Woodpecker
@thomas/woodpeckerv2026.10.11.1
01README
Administration of a Woodpecker CI server over its REST API, authenticated with a personal access token. Onboard and configure repositories (enable, mark trusted, set timeout/visibility/approval), copy shared CI credentials into org- or repo-scoped secrets (idempotent), inspect recent pipelines, and trigger runs. Changes are additive or reversible: re-running enable or set undoes a disable or a secret or cron delete. Secret values are write-only: supplied via a vault reference, sent once, and never read back or output.
02Behaviors
@thomas/woodpeckerv2026.10.11.1woodpecker.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| apiUrl | string | Woodpecker server base URL, e.g. https://woodpecker.example.com |
| token | string | Woodpecker personal access token (Settings → CLI and API). Supply via |
fn repo_list()
List enabled repositories with their CI settings (factory). Read-only.
fn repo_get(repo: string)
Get one enabled repository and its settings. Read-only.
| Argument | Type | Description |
|---|---|---|
| repo | string | Repo reference: numeric id or "owner/name" (e.g. octo-org/web). |
fn forge_list()
List the forges registered on the server, flagging the one the
fn repo_available(match?: string)
List repos on the token's own forge, with whether each is already
| Argument | Type | Description |
|---|---|---|
| match? | string | Case-insensitive substring filter on the repo full name. |
fn org_get(owner: string)
Look up an org / user by login or numeric id. Read-only.
| Argument | Type | Description |
|---|---|---|
| owner | string | Org / user login or numeric org id. |
fn org_secret_list(owner: string)
List an org's secrets (names/events/images only — never values;
| Argument | Type | Description |
|---|---|---|
| owner | string | Org / user login or numeric org id. |
fn repo_secret_list(repo: string)
List a repo's secrets (names/events/images only — never values;
| Argument | Type | Description |
|---|---|---|
| repo | string | Repo reference: numeric id or "owner/name" (e.g. octo-org/web). |
fn pipeline_list(repo: string)
List recent pipelines for a repo (factory). Read-only.
| Argument | Type | Description |
|---|---|---|
| repo | string | Repo reference: numeric id or "owner/name". |
fn pipeline_last(repo: string)
Get the most recent pipeline for a repo, of any event (incl. tags).
| Argument | Type | Description |
|---|---|---|
| repo | string | Repo reference: numeric id or "owner/name" (e.g. octo-org/web). |
fn pipeline_steps(repo: string)
List a pipeline's steps and their states (factory; defaults to the
| Argument | Type | Description |
|---|---|---|
| repo | string | Repo reference: numeric id or "owner/name". |
fn pipeline_logs()
Fetch and decode the logs for one pipeline step (by step name or id;
fn pipeline_wait()
Poll a pipeline until it reaches a terminal state (success/failure/…),
fn status_all(match?: string)
Fleet dashboard: the latest pipeline status for every enabled repo
| Argument | Type | Description |
|---|---|---|
| match? | string | Case-insensitive substring filter on the repo full name. |
fn repo_enable(repo: string)
Onboard a repo: activate it from the forge if needed, then converge
| Argument | Type | Description |
|---|---|---|
| repo | string | Repo to enable, as "owner/name". |
fn repo_update(repo: string)
Update settings on an already-enabled repo (trusted/timeout/
| Argument | Type | Description |
|---|---|---|
| repo | string | Repo reference: numeric id or "owner/name". |
fn repo_repair(repo: string)
Repair a repo's forge webhook + deploy key (idempotent; fixes a stale
| Argument | Type | Description |
|---|---|---|
| repo | string | Repo reference: numeric id or "owner/name" (e.g. octo-org/web). |
fn org_secret_set(owner: string)
Create-or-update an org-level secret (inherited by all the org's
| Argument | Type | Description |
|---|---|---|
| owner | string | Org / user login or numeric org id. |
fn repo_secret_set(repo: string)
Create-or-update a repo-scoped secret. The value is write-only —
| Argument | Type | Description |
|---|---|---|
| repo | string | Repo reference: numeric id or "owner/name". |
fn repo_disable(repo: string)
Deactivate a repo (stops its CI; removes the webhook). REVERSIBLE —
| Argument | Type | Description |
|---|---|---|
| repo | string | Repo reference: numeric id or "owner/name" (e.g. octo-org/web). |
fn org_secret_delete(owner: string, name: string)
Delete an org-level secret. REVERSIBLE — re-create with org_secret_set.
| Argument | Type | Description |
|---|---|---|
| owner | string | Org / user login or numeric org id. |
| name | string | Secret name to delete (reversible: re-create). |
fn repo_secret_delete(repo: string, name: string)
Delete a repo-scoped secret. REVERSIBLE — re-create with
| Argument | Type | Description |
|---|---|---|
| repo | string | Repo reference: numeric id or "owner/name". |
| name | string | Secret name to delete (reversible: re-create). |
fn pipeline_trigger(repo: string, branch?: string)
Trigger a new pipeline for a repo on the given branch (defaults to the
| Argument | Type | Description |
|---|---|---|
| repo | string | Repo reference: numeric id or "owner/name". |
| branch? | string | Branch to run (defaults to the repo's default branch). |
fn pipeline_restart(repo: string)
Restart (re-run) a pipeline — e.g. after fixing infra, instead of an
| Argument | Type | Description |
|---|---|---|
| repo | string | Repo reference: numeric id or "owner/name". |
fn pipeline_cancel(repo: string)
Cancel a running pipeline (defaults to the repo's latest). Verifies it
| Argument | Type | Description |
|---|---|---|
| repo | string | Repo reference: numeric id or "owner/name". |
fn pipeline_approve(repo: string)
Approve a pipeline blocked pending approval (require_approval).
| Argument | Type | Description |
|---|---|---|
| repo | string | Repo reference: numeric id or "owner/name". |
fn pipeline_decline(repo: string)
Decline a pipeline blocked pending approval. Without `number`,
| Argument | Type | Description |
|---|---|---|
| repo | string | Repo reference: numeric id or "owner/name". |
fn agent_list()
List the server's build agents and their health (last contact, version,
fn queue_info()
Server build-queue statistics (pending/running/worker counts; paused).
fn server_info()
Server version and health (GET /version + /healthz). Read-only.
fn cron_list(repo: string)
List a repo's scheduled-pipeline (cron) jobs (factory). Read-only.
| Argument | Type | Description |
|---|---|---|
| repo | string | Repo reference: numeric id or "owner/name" (e.g. octo-org/web). |
fn cron_set(repo: string, name: string, schedule: string, branch?: string, enabled?: boolean)
Create-or-update a scheduled-pipeline (cron) job by name, enabled
| Argument | Type | Description |
|---|---|---|
| repo | string | Repo reference: numeric id or "owner/name". |
| name | string | Cron job name (unique within the repo). |
| schedule | string | Schedule: a cron expression or an @hourly/@daily/@weekly/… macro. |
| branch? | string | Branch to run (defaults to the repo's default branch). |
| enabled? | boolean | Whether the scheduler runs this cron. The default true re-enables a |
fn cron_delete(repo: string, name: string)
Delete a scheduled-pipeline (cron) job by name. REVERSIBLE — re-create
| Argument | Type | Description |
|---|---|---|
| repo | string | Repo reference: numeric id or "owner/name". |
| name | string | Cron job name to delete (reversible: re-create). |
Resources
repo(infinite)— An enabled repository and its CI settings.
available-repo(infinite)— A forge repo the token can access (enabled or not).
forge(infinite)— A forge registered on the server.
org(infinite)— An organization / user record.
secret(infinite)— A secret's metadata (name/events/images) — never its value. A delete
pipeline(infinite)— A pipeline run's status.
pipeline-step(infinite)— One step of a pipeline run and its state.
pipeline-log(infinite)— Decoded logs for one pipeline step.
repo-status(infinite)— A repo's latest pipeline status (the fleet dashboard).
agent(infinite)— A Woodpecker build agent and its health.
queue(infinite)— Server build-queue statistics.
server(infinite)— Server version and health.
cron(infinite)— A repo's scheduled-pipeline (cron) job. A delete of a
03Previous Versions
2026.09.08.1
2026.06.04.1
04Stats
A
93 / 100
Downloads
29
Archive size
39.5 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License1/2partial
no SPDX license declared
- Verified public repository2/2earned
05Platforms
06Labels