Skip to main content

Set the Woodpecker CI token

The Woodpecker CI token is the personal token of an account on your Woodpecker CI server. With it, peckaboo.com reads every run in detail: each workflow and step, why a run failed, and the end of the log of a failed step. peckaboo.com is an independent service and not a project of Woodpecker CI.

What the token reaches

Woodpecker CI has no tokens that can only read: a token can do whatever its account can do. Which account you take decides what peckaboo.com sees.

Token of peckaboo.com reads
your own account, or any other account the runs of the repositories that account works on
an administrator of the server every repository of the server, and its agents and its queue as well

peckaboo.com only ever reads with the token. It sends nothing but read requests, keeps the token encrypted and never shows it again. Keep the token of an administrator as carefully as the password of that account, since it reaches the whole server. Every change of the token reaches the owners of your account by mail.

Before you start: two-factor authentication

Only somebody whose password alone does not open their account sets a token. Until you have turned on two-factor authentication, the field stays locked.

  1. Open the account menu at the bottom of the sidebar and choose Two-factor authentication under Security.
  2. Scan the code with an authenticator app on your phone, or type the setup key below it into the app, and enter the six-digit code the app shows.
  3. Keep the recovery codes somewhere safe. They open your account if the phone is lost.

Step 1: copy the token in Woodpecker CI

  1. Sign in to your Woodpecker CI server with the account whose token peckaboo.com should use.
  2. Select your picture at the top right and open the page CLI & API in your user settings. Its address is https://ci.example.com/user/cli-and-api, where ci.example.com stands for the address of your server.
  3. Copy the Personal Access Token. It is a long string of letters, digits, dots and dashes, and usually starts with eyJ.

Step 2: give the token to peckaboo.com

  1. Open the Instance settings and find the instance.
  2. Paste the token into Woodpecker CI token, in the right column next to the metrics, and select Set the token.
  3. peckaboo.com asks your server once whether it accepts the token. It then shows Set beside the field, and Administrator where the token belongs to an administrator.

Within a minute, the view Repositories and steps of the instance shows its latest runs. With the token of an administrator, the view Queue shows the agents and the tasks waiting for one as well.

Choose the repositories

Once the token has listed the repositories it reaches, Repositories it watches appears below its field.

  • All repositories watches every repository the token reaches, and every one that comes later. A new instance starts with it.
  • A selection watches only the repositories you tick. Find one by its name, or tick all or none at once, and select Keep the choice. A repository that comes later is not ticked until you tick it.

The runs read of a repository you untick stay.

When the field refuses the token

The field says What to do
Woodpecker CI refused this token Copy the token again, as in step 1.
The token contains a control character Copy the token again, without the characters around it.
Turn on two-factor authentication first See the start of this page.
We cannot reach the API of this server Try again in a minute. If it stays, check that the server answers from the internet.
The API of this server took longer than … to answer Try again in a minute, when the server is less busy.
The API of this server answers with a redirect Something in front of Woodpecker CI, such as a proxy or a sign-in page, redirects /api/. Let /api/ through to Woodpecker CI.
No API of Woodpecker CI 3 answers at this address A proxy in front of the server does not pass /api/ on. Let it through to Woodpecker CI.
This token may not read what peckaboo.com asks of it The server, or a proxy in front of it, forbids /api/user to this token. Let /api/ through to Woodpecker CI, then copy the token again, as in step 1.
An answer of the API is larger than peckaboo.com reads Something other than Woodpecker CI answers at /api/user, such as a proxy or a sign-in page. Let /api/ through to Woodpecker CI.

Servers in a private network lists every path under /api/ that peckaboo.com reads, for a proxy that lets only those through.

When a later read is refused

peckaboo.com reads with the token at every poll. When the server refuses a read, the Instance settings say why, and Refused stands beside the field instead of Set. The view Repositories and steps shows the same note with the latest runs, and the view Queue the one about the agents and the queue. The runs read before stay.

The note says What to do
Woodpecker CI refused this token The token no longer works, for example because a new one was created on the page CLI & API or its account was deleted. peckaboo.com reads nothing with it until you copy a new one, as in step 1, and select Replace the token.
This token no longer belongs to an administrator of the server The runs of its own account are still read, but no longer the agents, the queue or the repositories of other accounts. Once the account is an administrator again, enter its token again and select Replace the token, or take the token of another administrator.
The server could not give the runs of these repositories Nothing. The other repositories are read, and these are asked again in a later read.
Any other reason Nothing. The next poll asks again, and the note goes once the server answers. If it stays, the table above says what it means.

Replace or remove the token

Replace the token takes a new one in place of the old. Remove the token takes it away; the runs read with it stay. Removing never needs two-factor authentication.

So that the old token no longer works anywhere, create a new one on the page CLI & API of Woodpecker CI as well.