| name | woodpecker-ci |
| description | Operate Woodpecker CI from installation through production troubleshooting: configure servers and agents, connect Forgejo/Gitea or another forge, write and validate pipelines, manage secrets and plugins, use Docker or Kubernetes backends, run the CLI, and diagnose failed builds. Use when setting up, administering, or debugging Woodpecker CI. |
| license | MIT |
| compatibility | Requires access to a Woodpecker instance for administration; Docker Compose, Kubernetes, or woodpecker-cli are optional depending on the backend. |
| metadata | {"source":"https://woodpecker-ci.org/docs","research":"GroktoCrawl plus official Woodpecker documentation and repository sources"} |
Woodpecker CI
Use this skill as an operating playbook, not as a substitute for checking the documentation for the installed major version. Prefer explicit SemVer image tags, verify the resolved configuration before starting services, and verify runtime health after every change.
Scope boundary: This skill configures and operates Woodpecker CI (the server, agents, workflows, and integrations). It does not install or administer Forgejo/Gitea itself, and it does not configure Forgejo Actions runners. When a task mentions Forgejo, treat it as the forge Woodpecker connects to unless forge administration is explicitly requested.
Operating loop
- Identify the Woodpecker major version, forge, backend, deployment files, database, public URL, and whether the task is a setup, pipeline, or incident.
- Read the matching reference below before changing configuration.
- Render and lint configuration before starting the server or agent.
- Make the smallest change at the layer that owns the problem: forge/OAuth, server, agent/backend, or repository workflow.
- Verify the result at the next boundary: server health, agent connected state, repository webhook, pipeline scheduling, step logs, and external deployment endpoint.
- Record the exact version and relevant environment variables without recording secret values.
Choose the entry point
| If the task is... | Start here |
|---|
| New server/agent or forge connection | references/setup.md |
| Workflow YAML, services, conditions, secrets, or plugins | references/pipeline-syntax.md |
| Upgrade, backup, metrics, CLI, or capacity | references/operations.md and references/advanced-patterns.md |
| A failed login, queued pipeline, clone, step, or backend | references/troubleshooting.md and references/failure-signatures.md |
| A trust or multi-tenant decision | references/security.md and the backend section of references/setup.md |
| Local lint/exec or CLI installation | references/cli.md |
Then load references/source-index.md when a version-sensitive command or variable needs confirmation.
Quick command card
openssl rand -hex 32
cp templates/docker-compose.yml compose.yaml
cp templates/forgejo.env.example .env
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs -f --tail=100 woodpecker-server woodpecker-agent
woodpecker-cli lint .woodpecker.yml
woodpecker-cli exec .woodpecker.yml
woodpecker-cli repo info --repository OWNER/REPO
woodpecker-cli repo secret add --repository OWNER/REPO --name NAME --value @/path/to/value
woodpecker-cli exec is useful for local command and metadata checks, but it is not a complete substitute for a server run: server-managed secrets and forge events may not be available locally.
Core defaults
- Use the Docker backend for isolated container steps. The Docker socket is powerful: treat an agent host as a CI trust boundary.
- Use the Kubernetes backend for pod-per-step isolation and cluster scheduling; review service accounts, namespace boundaries, pull secrets, PVC/storage, and resource requests before allowing repository authors to set backend options.
Multi-tenant default: For untrusted repositories, prefer Kubernetes with namespace/RBAC/ServiceAccount controls when the cluster is already operated as a security boundary. Docker is a viable simpler default only with dedicated agents and trust-tier separation because the Docker socket controls the host daemon. Never use the Local backend for untrusted repositories.
- The agent needs
WOODPECKER_SERVER and the same WOODPECKER_AGENT_SECRET as the server. The server registers an agent on first contact; persist the agent config file so its generated identity survives restarts.
- Keep
WOODPECKER_OPEN=false unless open registration is intentional. Grant admin access explicitly and protect the OAuth client secret and agent secret.
- Do not expose secrets to untrusted pull requests by default. If a secret must be available there, restrict its events and plugin images and document the threat model.
depends_on is for workflow ordering and parallelism; it is not a readiness check for service containers. Add a real wait/backoff or health probe for databases and caches.- A step's
when list is OR across entries and AND within one entry. Branch filters also affect pull-request target branches; combine event and branch when you mean pushes to a branch only.
- A passing
docker compose config or CLI lint proves syntax/model validity, not that the agent can reach the forge, the image can pull, or the pipeline is safe.
Reference routing
| Load when | Reference |
|---|
| Installing with Docker Compose, configuring Forgejo/Gitea, or choosing a backend | references/setup.md |
| Writing workflow YAML, events, conditions, matrices, services, plugins, or multi-workflow projects | references/pipeline-syntax.md |
| Designing parallel workflows, concurrency, caching, registries, reusable YAML, or autoscaling | references/advanced-patterns.md |
| Managing secrets, registries, CLI operations, upgrades, backups, and metrics | references/operations.md |
| A pipeline, clone, agent, OAuth, Docker, or Kubernetes run is failing | references/troubleshooting.md |
| You need a compact symptom-to-evidence map during an incident | references/failure-signatures.md |
| Reviewing trust boundaries, pull requests, plugins, local backend, or Kubernetes permissions | references/security.md |
Using or installing woodpecker-cli | references/cli.md |
| Checking source URLs and version-sensitive claims | references/source-index.md |
Included artifacts
templates/docker-compose.yml — minimal server plus Docker agent deployment.templates/woodpecker.yml — conservative build/test/deploy workflow skeleton.templates/forgejo.env.example — placeholder environment contract for Forgejo.assets/troubleshooting-checklist.md — incident handoff checklist.scripts/woodpecker-doctor.py — dependency-free connectivity/configuration probe with text or JSON output.
Available Scripts
| Script | Purpose | Invocation |
|---|
scripts/woodpecker-doctor.py | Dependency-free connectivity/configuration probe for a Woodpecker deployment: checks the server HTTP URL and the agent gRPC endpoint, with text or JSON output. Run it as step one of any "is it the CI or is it me" diagnosis, after deployment changes to verify health, and before deeper troubleshooting. | python3 scripts/woodpecker-doctor.py --url https://ci.example.com --server agent-host:9000 --json |
Prerequisites
- Network reachability from where you run the probe to the Woodpecker server URL and, when checking agents, the agent's gRPC host:port.
- Python 3 only — the probe uses the standard library and no third-party packages; it never mutates the Woodpecker instance.
- For actual administration beyond probing (per
compatibility): access to the Woodpecker instance, and Docker Compose, Kubernetes, or woodpecker-cli depending on the backend in use — see references/setup.md and references/cli.md.
Limitations
- The doctor probe reports connectivity and configuration signals only; a green probe does not prove forge OAuth works, pipelines schedule, or steps can pull images — verify at those boundaries separately (see Common failure boundaries).
- It reads nothing about repository-level state (webhooks, secrets, queue depth); use the server API/UI and references/troubleshooting.md for that.
- The skill documents operating patterns, not a pinned version: always confirm version-sensitive commands and variables against the installed major version via references/source-index.md.
Common failure boundaries
- Server starts but repositories do not appear: inspect forge OAuth URL, callback URL, scopes, and server logs before changing pipeline YAML. For a push with no pipeline, inspect the Forgejo repository's Settings → Webhooks → Recent Deliveries first and record the delivery status.
- Agent is connected but never picks up work: compare labels/backend, maximum workflows, repository visibility/trust, and agent logs.
- A clone fails: first test network/DNS and credentials from an intentionally paused step; do not debug application commands until checkout works.
- A service is running but tests fail to connect: use the service hostname and container port, then add readiness handling.
- A secret is empty: check secret scope, event filters, plugin-image filters, and expression escaping (
$${NAME} when Woodpecker must pass the variable to the shell).
When not to use
Use a forge-specific skill for installing or administering Forgejo/Gitea itself, a Kubernetes operations skill for cluster lifecycle, and a Docker security skill for host hardening. This skill covers Woodpecker's integration points and CI behavior.
