Woodpecker CI

Turns on Woodpecker for a repository that exists in the forge, which installs the webhook and makes pipelines run. Takes the forge-side id, NOT an owner/name pair and not a Woodpecker id — call list_repositories with include_inactive=true and read forge_remote_id from the entry.

Releases a pipeline that is waiting for approval (status "blocked") and lets it run. Read what you are approving first: pipelines are usually blocked because they come from a fork, and approving one runs code from that fork with this repository's secrets.

Stops a pipeline that is pending or running. Its steps are killed where they are, so anything half-written stays half-written. The pipeline can be restarted afterwards.

Makes the authenticated account the repository's owner in Woodpecker. The owner's forge token is what Woodpecker uses to read the repository and report build status, so this is the fix when the previous owner left. Asks a person first; where the client cannot show a dialog, call once to receive a token and again with it.

Registers a new build agent and returns its token. THE TOKEN IS A CREDENTIAL: whoever holds it can attach a machine to this server, receive pipeline workloads and read every secret those pipelines use. It is part of this answer because it is the only way to get it — put it straight into the agent's configuration and do not paste it anywhere else.

Schedules a pipeline run. The pipeline runs with event "cron", so steps and secrets restricted to other events do not apply to it — a cron job whose steps all have "when: event: push" runs and does nothing.

Registers an additional forge. Admin only, and two-step: a forge is a way to sign in, and Woodpecker grants administrator rights by login name alone, so an account on the new forge spelled like an admin is one. The OAuth application has to exist on the forge side first, with this Woodpecker as its callback.

Stores credentials for a container registry so pipelines can pull private images from it. The address is the identifier — there is no separate name — so "docker.io" and "index.docker.io" are two different entries.

Creates a secret at the chosen level. The value is write-only: it is never readable again through the API, so store it somewhere else too. At least one event is required — the API has no defaults, and a secret without pull_request is invisible to pull-request builds.

Registers an account ahead of its first login. Admin only. This does not create anything in the forge and grants no access there — the person still signs in through the forge; this only pre-creates the Woodpecker record, which is how you make someone an admin before they first log in. Passing admin=true asks a person first.

Refuses a pipeline that is waiting for approval. It ends as "declined" and never runs; the pipeline entry and its metadata stay.

Removes an agent and invalidates its token. Anything it was running is lost and has to be restarted. Drain it first with update_agent no_schedule=true. Two-step.

Removes a scheduled run. If you only want it to stop for now, update_cron with enabled=false keeps the definition. Two-step.

Removes a forge from Woodpecker. Admin only. Everyone who signs in through it loses access, and its repositories can no longer be read. Two-step.

Removes an organization from Woodpecker together with its org-level secrets, registries and agents. Admin only. It does not touch the forge, and it does not delete the repositories — but anything of theirs that relied on an org-level secret stops working. Two-step.

Removes a pipeline and everything attached to it, including its logs. A running pipeline cannot be deleted — cancel it first. Two-step.

Deletes the stored output of every step of a pipeline. The pipeline and its step results stay, so it still shows which step failed — just not why. Two-step.

Removes stored credentials for a registry. Pipelines that pull private images from it start failing at the pull step. Two-step.

Removes a repository from Woodpecker: the webhook, every pipeline, all logs, secrets, registries and cron jobs of that repository. The forge repository itself is untouched. Two-step.

Deletes a secret. Any pipeline that reads it starts failing — or worse, keeps running with an empty value. Two-step.

Deletes the stored output of a single step. The step and the pipeline stay, their logs do not. This is what you use when a step printed a secret. Two-step. Rotate the leaked credential as well — the log was readable until now, and deleting it does not un-read it.

Removes an account from Woodpecker. Admin only. Repositories the account owned keep running on a token that no longer exists, which shows up later as pipelines that stop starting — chown_repository moves ownership to someone else, and doing that first is the point. Two-step.

Returns one agent. Admin only. Its token is redacted; an agent that lost its token needs a new one, which means delete_agent and create_agent.

Returns one cron job, including the variables it passes.

Returns the account WOODPECKER_TOKEN belongs to, including whether it is an instance administrator. This is the first thing to call when a tool answers 403: the admin-only tools need admin=true here.

Returns one forge configuration. Admin only. The OAuth client secret is not part of the read model and is never returned.

Returns the current log level of the Woodpecker server. Admin only.

Returns one organization by its numeric id.

What the authenticated account may do in this organization: member and admin. Org-level secrets and agents need admin here.

Returns one pipeline with its workflows and steps, including each step id — which is what get_step_logs needs. Step state and exit_code say which step to look at.

Returns the pipeline YAML files this run was built from, as they were at that commit. This is the config that actually ran, not the one currently in the branch.

The activity feed of the authenticated account: the latest pipeline of every repository it can see, newest first. This is the "what is the state of everything" call — one request instead of list_pipelines per repository.

Returns the metadata Woodpecker exposes to the pipeline itself — the CI_* environment a step sees, plus the previous pipeline of the same workflow. Useful when a step behaves differently than its config suggests.

The server-side build queue: what is pending, running and waiting on an agent, plus the agent statistics. Admin only. Together with list_queued_pipelines this is the whole answer to "why is my build not starting".

Returns one registry entry — its address and username. The password is stripped by Woodpecker (Registry.Copy), so it is never in the answer.

Returns the full Woodpecker configuration of one repository: trusted flags, timeout, approval mode, config file path and the extension endpoints.

What the authenticated account may do with this repository: pull, push and admin. Woodpecker inherits these from the forge, so this answers "why was that 403" without guessing.

Returns one secret's metadata: which events and images it applies to, and its note. The value is not part of the answer — Woodpecker strips it from every response, including the one right after creating it.

Returns the Woodpecker version and whether the server reports itself healthy. Works without a token, which makes it the call to use when nothing else does: if this answers, WOODPECKER_URL is right and the problem is WOODPECKER_TOKEN.

Returns the output of one pipeline step as text, newest end first by default — a failing step almost always explains itself in its last lines. The step id comes from get_pipeline (workflows[].steps[].id). Woodpecker returns these lines base64-encoded; this tool decodes and reassembles them.

Returns one account by its login. Admin only. forge_id is required — see list_users for the value.

The work an agent is currently running. Admin only. This is how you find out what is occupying a busy agent, and which pipeline to cancel.

Lists the build agents, with their platform, capacity, version and last contact — the call that answers "why is nothing being built". Without org_id this is the instance-wide list and needs an administrator. Agent tokens are redacted.

Lists the scheduled pipeline runs of a repository, with the next execution time of each.

Lists the forges this Woodpecker authenticates against. Admin only. The forge_id shown here is what get_user and delete_user require.

Lists the organizations known to this Woodpecker instance. Admin only. Note that an entry with is_user=true is a personal account, not a real organization — Woodpecker models both the same way, and org-level secrets work for both.

Lists a repository's pipelines, newest first, summarised to what a list needs. Filters are applied by the server. Note that "number" — not the pipeline id — is what every other pipeline tool takes.

Lists the open pull requests of a repository, with the index a pipeline ref like "refs/pull/42/head" refers to.

Lists the pipelines waiting in the server queue across all repositories. This is the instance-wide view: what is stuck, and behind what. get_queue_info adds the agent side of the same picture.

Lists the container registry credentials at one level. These are what let a pipeline pull private images. Passwords are never returned.