Woodpecker CI: active Drone fork as the SME standard for Gitea and Forgejo

What is Woodpecker CI?

Woodpecker CI is a container-native continuous integration system, started in 2019 as a community fork of Drone after licence-policy ambiguity around Drone maintainer Brad Rydzewski. As of May 2026, Woodpecker is in version 3.x – an independent, very active project with clear community governance – the energy Drone lost under Harness ownership lives here.

Licence: Apache 2.0 for server and runner. No open-core clauses, no proprietary modules. Fully self-host, without footnotes – costs zero.

Architecture: server binary (Go) plus at least one agent (runner). Configuration via env vars or INI file. Pipelines defined in .woodpecker.yml in the repo. Container-native pipeline design: every step runs in its own Docker container. Runner types: Docker (default), Kubernetes, local exec, SSH.

Drone compatibility: deliberately maintained. .drone.yml files can be rewritten as .woodpecker.yml with minimal edits – same kind/type/steps schema, same logic. Drone plugins (Docker images with defined input schemas) work in Woodpecker directly, without adjustment. Migration from Drone to Woodpecker therefore typically takes half a day.

Git host integration: native support for Gitea, Forgejo, GitHub, GitLab, Bitbucket, Gogs. Webhook-based – push triggers pipeline run. OAuth integration via the respective host, standard setup.

May 2026 status: Woodpecker 3 stabilises the plugin interface, brings multi-pipeline workflows (several .woodpecker.yml files per repo for parallel builds), and improves the secrets vault integration (HashiCorp Vault, AWS Secrets Manager). The community is very active – daily commits, a clear release cadence, lively GitHub discussions.

SME default 2026: for self-host CI alongside Gitea or Forgejo, Woodpecker is the rational choice. Drone experience is transferable, learning curve is low, the community is alive.

Why it matters

Woodpecker solves the CI problem for SMEs with a self-host Git setup: lean, free, tightly integrated with Gitea and Forgejo.

SME suitability (May 2026): setup is a docker-compose file with server and one runner. Configuration via a few env vars, create an OAuth app in the Git host, done. Learning curve is gentle because pipeline syntax is close to Drone (and therefore close to what many DevOps engineers already know). Within half a day a production CI platform is up.

CH DSG fit: fully self-host on Hetzner Falkenstein. Apache 2.0 without lock-in. Code, pipelines, build artefacts, secrets – everything stays on-premise. For fiduciary or law-firm mandates Woodpecker is a compliant pick.

Licence and cost: Apache 2.0, zero per-user fees, zero per-build limits. GitHub Actions on gitlab.com free plan caps at 2000 minutes/month – quickly exhausted with active development. GitLab CI free tier caps at 400 minutes/month. Woodpecker self-host: unlimited, only hardware cost (Hetzner CX22 around CHF 6/month).

Community energy: arguably the most important argument in 2026. Anyone picking a CI platform for the next 3-5 years should pick an active project. Drone has lost speed under Harness – Woodpecker has picked it up. Security patches arrive quickly, new features arrive regularly (multi-pipeline workflows, improved secrets integration, OpenTelemetry support for pipeline tracing).

Migration path: anyone on Drone moves to Woodpecker with manageable effort. Anyone on Jenkins planning a container-native switch can evaluate Woodpecker as a modern successor – pipeline syntax is markedly clearer than Jenkinsfile (Groovy).

Integration with Gitea Actions: an important point. Since 2023 Gitea has its own Actions (GitHub-Actions-compatible). Woodpecker and Gitea Actions are complementary – many SMEs use Gitea Actions for simple workflows (build, test) and Woodpecker for more complex multi-stage pipelines. Both coexist technically without issue.

How it works

Woodpecker consists of server and agent. Server orchestrates, agent runs jobs.

docker-compose.yml example with Gitea as Git host:

```yaml services: woodpecker-server: image: woodpeckerci/woodpecker-server:v3 ports: ["8000:8000", "9000:9000"] volumes: - woodpecker-server-data:/var/lib/woodpecker environment: WOODPECKER_OPEN: false WOODPECKER_HOST: https://ci.firm.ch WOODPECKER_GITEA: true WOODPECKER_GITEA_URL: https://git.firm.ch WOODPECKER_GITEA_CLIENT: ${GITEA_OAUTH_CLIENT_ID} WOODPECKER_GITEA_SECRET: ${GITEA_OAUTH_CLIENT_SECRET} WOODPECKER_AGENT_SECRET: ${AGENT_SECRET} WOODPECKER_ADMIN: admin restart: unless-stopped woodpecker-agent: image: woodpeckerci/woodpecker-agent:v3 depends_on: [woodpecker-server] environment: WOODPECKER_SERVER: woodpecker-server:9000 WOODPECKER_AGENT_SECRET: ${AGENT_SECRET} WOODPECKER_MAX_WORKFLOWS: 4 volumes: - /var/run/docker.sock:/var/run/docker.sock - woodpecker-agent-data:/etc/woodpecker restart: unless-stopped volumes: woodpecker-server-data: woodpecker-agent-data: ```

Gitea side: create OAuth app in user settings > applications, paste client ID and secret into Woodpecker .env. Woodpecker fetches the repository list via the Gitea API, users activate repos by click.

Pipeline example (.woodpecker.yml):

```yaml steps: build: image: node:20 commands: - npm ci - npm run build test: image: node:20 commands: - npm test deploy: image: alpine/git environment: SSH_KEY: from_secret: deploy_key commands: - apk add openssh - mkdir -p ~/.ssh && echo "$SSH_KEY" > ~/.ssh/id_rsa && chmod 600 ~/.ssh/id_rsa - ssh -o StrictHostKeyChecking=no deploy@server "cd /app && git pull && pm2 restart all" when: branch: main ```

Secrets management: defined in the Woodpecker UI per repo. Access via from_secret in YAML. Alternatively HashiCorp Vault plugin for central secrets management in larger setups.

Multi-pipeline workflows (v3 feature): multiple .woodpecker.yml files in one repo (for example .woodpecker/build.yml, .woodpecker/test.yml, .woodpecker/deploy.yml) – run parallel or with dependencies. Lets you structure complex pipelines cleanly instead of one giant file.

Agent scaling: per agent WOODPECKER_MAX_WORKFLOWS=N – N parallel jobs. Multiple agent containers can register with the server for horizontal scaling. At Fairlane one agent runs with Max 4 – enough for 20+ pipelines/day.

Setup in 5 steps

1. 01docker-compose with woodpeckerci/woodpecker-server:v3 and woodpeckerci/woodpecker-agent:v3, generate agent secret.
2. 02Create OAuth app in Gitea/Forgejo/GitHub, paste client ID + secret into Woodpecker .env, start the server.
3. 03nginx reverse proxy at ci.firm.ch with Lets-Encrypt cert, protect gRPC port 9000 between server and agent via Docker network as needed.
4. 04Activate first repository in the Woodpecker UI, write .woodpecker.yml with build step, trigger push, verify logs in the UI.
5. 05Define secrets in the UI per repo (deploy_key, registry_password, api_token), enable pipeline deploy on main branch.

When to use Woodpecker

Woodpecker is the right choice when (a) the setup has self-host Git with Gitea or Forgejo, (b) CI pipelines should be container-native, (c) a lean system is desired (no GitLab complexity), (d) Drone experience exists in the team or is easy to transfer.

Concrete SME cases: a fiduciary platform with Gitea for code and Woodpecker for build/deploy of Bexio integrations. A law firm with a self-built client platform – Gitea hosts code, Woodpecker builds containers and deploys on push to main. A SaaS boutique with 5-15 developers – Gitea plus Woodpecker plus Gitea-native container registry covers the entire software supply chain.

Migration from Drone: typical case in May 2026. Rewrite .drone.yml as .woodpecker.yml (very similar schema), recreate secrets in the Woodpecker UI, redirect webhooks in the Git host. Half a day of work for 20-50 pipelines.

Also useful as CI for open-source projects that want to avoid GitHub Actions – Codeberg projects for instance use Woodpecker as default CI.

When not to use

Woodpecker is the wrong choice when (a) the setup already uses GitLab CE/EE – integrated GitLab CI is tighter, (b) GitHub Actions marketplace plugins are central – Woodpecker has no marketplace, (c) very complex multi-cloud deployments are needed – Jenkins or specialised tools like ArgoCD fit better, (d) the team hopes for a complete DevOps platform (issues+CI+registry+security) – Woodpecker is CI only.

Pitfalls: running the Woodpecker agent without resource limits – a misconfigured build can fill the host. Set memory and CPU limits per agent. Writing secrets in plain text into .woodpecker.yml – always go through UI secrets or the Vault plugin. Mounting the Docker socket without awareness – gives the runner root-equivalent rights on the host. Isolate via Docker-in-Docker or rootless Docker in multi-tenant setups.

Anti-patterns: running Woodpecker and Drone in parallel – both do the same job, two UIs are configuration pain. Exposing Woodpecker without a TLS reverse proxy directly to the internet – brute-force on /login. Treating pipeline YAML as a secret – it should be versioned and reviewable in the repo.

Trade-offs

FAQ

Related topics

Sources

1. Woodpecker CI – Documentation · 2026-05
2. Woodpecker CI – GitHub repository · 2026-04
3. Woodpecker 3 – Multi-pipeline workflows · 2026-03
4. Codeberg – Woodpecker as default CI · 2026-04