# Woodpecker CI

> Woodpecker CI is a free, open-source (Apache-2.0) continuous integration and delivery engine, forked from Drone 0.8 after Drone relicensed away from Apache-2.0. It is self-hosted: an operator runs a Woodpecker server plus one or more agents against a Git forge (GitHub, GitLab, Gitea, Forgejo, Bitbucket). Pipelines are declared in `.woodpecker/` YAML workflow files. Every server exposes a Swagger 2.0 REST API under `/api`, Server-Sent Event streams for pipeline events and step logs, and a gRPC contract for server-to-agent communication.

This file was generated by API Evangelist from Woodpecker CI's own public documentation and published specifications on 2026-08-27. Woodpecker CI does not publish an llms.txt of its own (https://woodpecker-ci.org/llms.txt returned 404 when probed on 2026-08-27).

## What an agent needs to know first

- There is no hosted Woodpecker service and no signup. The base URL is whatever host the operator runs. `https://ci.woodpecker-ci.org/api` is the project's own public instance and the source of the reference Swagger document; it is not a service you can sign up for.
- Authentication is a personal access token sent as `Authorization: Bearer <personal access token>`. Get it from your profile page on your own Woodpecker server (click the user icon, top right).
- The API is not versioned. It ships with the server, so the surface you meet is whatever release the operator installed. Current release: 3.18.0 (2026-08-24).
- Errors are `text/plain` strings or empty bodies. There is no error code, no problem+json, and 118 operations declare exactly one non-2xx response between them. Branch on the HTTP status and nothing else.
- There is no idempotency key. Retrying `POST /repos/{repo_id}/pipelines` starts another pipeline.
- There are no rate limits and no rate-limit headers. Pace yourself.

## API

- [API reference (rendered)](https://woodpecker-ci.org/api): All 118 operations across 74 paths, rendered from the Swagger 2.0 document.
- [Swagger 2.0 document](https://ci.woodpecker-ci.org/swagger/doc.json): The machine-readable contract, served by every Woodpecker server at `/swagger/doc.json`.
- [Swagger UI](https://ci.woodpecker-ci.org/swagger/index.html): Interactive try-it console, bundled with every server.
- [How the spec is generated](https://woodpecker-ci.org/docs/development/openapi): gin-swagger/swaggo annotations; explains the `page`/`perPage` pagination convention and the `Authorization` header parameter.

### Operation groups

- Repositories: `/repos`, `/repos/{repo_id}`, `/repos/lookup/{repo_full_name}`, branches, pull_requests, permissions, repair, chown, move
- Pipelines: `/repos/{repo_id}/pipelines`, `/repos/{repo_id}/pipelines/{pipeline_number}` and its `approve`, `decline`, `cancel`, `config`, `metadata` sub-resources
- Pipeline logs: `/repos/{repo_id}/logs/{pipeline_number}/{step_id}` and its `/download` variant
- Secrets and registries at three scopes: global (`/secrets`, `/registries`), organization (`/orgs/{org_id}/...`), repository (`/repos/{repo_id}/...`)
- Cron jobs: `/repos/{repo_id}/cron`
- Agents: `/agents`, `/orgs/{org_id}/agents`
- Forges: `/forges`
- Orgs and users: `/orgs`, `/users`, `/user`, `/user/feed`, `/user/token`
- Queue administration: `/queue/info`, `/queue/pause`, `/queue/resume`, `/queue/norunningpipelines`, `/pipelines`
- System: `/version`, `/healthz`, `/log-level`, `/signature/public-key`
- Badges: `/badges/{repo_id}/status.svg`, `/badges/{repo_id}/cc.xml` (CCTray/CCMenu format)
- Streams (Server-Sent Events): `/stream/events`, `/stream/logs/{repo_id}/{pipeline}/{step_id}`
- Profiling: `/debug/pprof/*`

Note: `/version` and `/healthz` are served at the server ROOT, not under the declared `/api` basePath. Verified live 2026-08-27.

## Other machine-readable contracts

- [Pipeline JSON Schema (draft-07)](https://raw.githubusercontent.com/woodpecker-ci/woodpecker/main/pipeline/frontend/yaml/linter/schema/schema.json): The normative schema for `.woodpecker/` workflow files. This is what `woodpecker-cli lint` validates against.
- [gRPC protobuf contract](https://github.com/woodpecker-ci/woodpecker/blob/main/rpc/proto/woodpecker.proto): proto3, service `Woodpecker`, 11 RPCs (Version, Next, Init, Wait, Done, Extend, Update, Log, RegisterAgent, UnregisterAgent, ReportHealth). Server-to-agent only.

## Docs

- [Introduction](https://woodpecker-ci.org/docs/intro)
- [Usage: getting started](https://woodpecker-ci.org/docs/usage/intro)
- [Workflow syntax](https://woodpecker-ci.org/docs/usage/workflow-syntax)
- [Workflows](https://woodpecker-ci.org/docs/usage/workflows)
- [Secrets](https://woodpecker-ci.org/docs/usage/secrets)
- [Registries](https://woodpecker-ci.org/docs/usage/registries)
- [Cron jobs](https://woodpecker-ci.org/docs/usage/cron)
- [Environment variables](https://woodpecker-ci.org/docs/usage/environment)
- [Matrix workflows](https://woodpecker-ci.org/docs/usage/matrix-workflows)
- [Project settings](https://woodpecker-ci.org/docs/usage/project-settings)
- [Terminology](https://woodpecker-ci.org/docs/usage/terminology)
- [Troubleshooting](https://woodpecker-ci.org/docs/usage/troubleshooting)
- [Local pipeline execution](https://woodpecker-ci.org/docs/usage/local-execution): `woodpecker-cli exec` runs a workflow from a checkout with no server.
- [Linter](https://woodpecker-ci.org/docs/usage/linter)
- [Extensions](https://woodpecker-ci.org/docs/usage/extensions): configuration, registry and secret extensions.
- [Plugins](https://woodpecker-ci.org/docs/usage/plugins/overview) and the [plugin index](https://woodpecker-ci.org/plugins)
- [CLI reference](https://woodpecker-ci.org/docs/cli)

## Administration

- [General administration](https://woodpecker-ci.org/docs/administration/general)
- [Server configuration](https://woodpecker-ci.org/docs/administration/configuration/server): every `WOODPECKER_*` environment variable, including `WOODPECKER_PROMETHEUS_AUTH_TOKEN`, which enables the token-gated `/metrics` endpoint.
- [Agent configuration](https://woodpecker-ci.org/docs/administration/configuration/agent)
- [Forges](https://woodpecker-ci.org/docs/administration/configuration/forges/overview): GitHub, GitLab, Gitea, Forgejo, Bitbucket, Bitbucket Data Center
- [Backends](https://woodpecker-ci.org/docs/administration/configuration/backends/docker): Docker, Kubernetes, local, custom
- [Install with docker-compose](https://woodpecker-ci.org/docs/administration/installation/docker-compose)
- [Install with the Helm chart](https://woodpecker-ci.org/docs/administration/installation/helm-chart)
- [Distribution packages](https://woodpecker-ci.org/docs/administration/installation/packages): official DEB and RPM, plus community packages the project does not maintain.
- [Supported platforms](https://woodpecker-ci.org/docs/administration/installation/supported-platforms)

## Versioning and change

- [Deprecation policy](https://woodpecker-ci.org/docs/development/deprecations): warning in minor N.x, error in major (N+1).0, code removed in minor (N+1).x. A full major cycle of runway.
- [Migrations](https://woodpecker-ci.org/migrations): where breaking API model changes are announced. The Pipeline model is currently moving to nested event-grouped objects; `title`, `message`, `is_prerelease` and ref-derived tags are deprecated in favour of `release.title`, `tag_title` and `release.is_prerelease`.
- [Changelog](https://github.com/woodpecker-ci/woodpecker/blob/main/CHANGELOG.md)
- [Releases](https://github.com/woodpecker-ci/woodpecker/releases)

## SDKs and tooling

- [Go client library](https://pkg.go.dev/go.woodpecker-ci.org/woodpecker/v3/woodpecker-go/woodpecker): the only first-party SDK, versioned with the server (v3.18.0, 2026-08-24).
- [woodpecker-cli](https://woodpecker-ci.org/docs/cli): first-party command line client. Tokens are stored in the OS keyring, never in the config file.
- [@woodpecker-ci/plugin](https://www.npmjs.com/package/@woodpecker-ci/plugin): TypeScript utilities for authoring a pipeline plugin. Not a REST client.
- [Autoscaler](https://github.com/woodpecker-ci/autoscaler): scales agent capacity to queue load.
- No Python, JavaScript, Java, Ruby or .NET client is published.

## Project

- [Website](https://woodpecker-ci.org/)
- [GitHub organization](https://github.com/woodpecker-ci)
- [Blog](https://woodpecker-ci.org/blog)
- [About and history](https://woodpecker-ci.org/about)
- [Awesome Woodpecker](https://woodpecker-ci.org/awesome): community tooling, including the MCP server the project links.
- [Support](https://github.com/woodpecker-ci/.github/blob/main/SUPPORT.md): GitHub Discussions and the Matrix space `#woodpecker:matrix.org`.
- [Governance](https://github.com/woodpecker-ci/.github/blob/main/GOVERNANCE.md)
- [Security policy](https://github.com/woodpecker-ci/.github/blob/main/SECURITY.md): report privately to security@woodpecker-ci.org, never as a public issue.

## Not available

- No hosted service, no pricing, no plans, no signup, no terms of service and no privacy policy — the product is software you run yourself.
- No status page and no SLA.
- No OpenAPI 3.x (the contract is Swagger 2.0), no operationIds, no declared securitySchemes.
- No `/.well-known/` documents on any host.
- No A2A agent card.
- No MCP server published by the project. The community server the project links is stdio-only and read-only.
- No outbound webhooks. `/hook` is INBOUND, from your Git forge.
- No AsyncAPI document for the SSE streams.