Video tutorial coming soon.
🪶 Setup Woodpecker CI — Self-Hosted CI/CD Pipeline
Deploy Woodpecker CI on Ubuntu with Docker — a simple, powerful continuous integration and delivery engine with YAML-based pipeline definitions and Docker-native step execution. Integrates natively with Gitea, GitHub, and GitLab.
📦 Resources & Setup Scripts
Grab the automated bash script from GitHub to follow along with the video.
Quick Install:
wget https://raw.githubusercontent.com/mhmdali94/Docker/main/dev/woodpecker/woodpecker-ubuntu.sh
chmod +x woodpecker-ubuntu.sh
sudo bash woodpecker-ubuntu.shTutorial Steps
1 Download & Run the Script
The script installs Docker, prompts for your Gitea server URL and OAuth credentials, and starts both the Woodpecker server and agent. An agent secret is auto-generated and displayed at the end.
wget https://raw.githubusercontent.com/mhmdali94/Docker/main/dev/woodpecker/woodpecker-ubuntu.sh
chmod +x woodpecker-ubuntu.sh
sudo bash woodpecker-ubuntu.sh2 Login via OAuth
Open your browser and navigate to the Woodpecker dashboard. Click Login — you'll be redirected to your Gitea/GitHub/GitLab instance to authorize the OAuth app:
http://<your-server-ip>:80933 Activate a Repository
After login, your repositories are listed. Click the toggle next to a repo to activate it for CI/CD. Woodpecker will automatically configure a webhook in your Git provider to trigger pipelines on push events.
4 Create Your First Pipeline
Add a .woodpecker.yml file to the root of your repository. Each step runs inside a Docker container:
steps:
- name: build
image: node:20
commands:
- npm install
- npm run build
- name: test
image: node:20
commands:
- npm testPorts Used
| Port | Purpose |
|---|---|
| 8093 | Woodpecker Web UI & API |
| 9003 | Agent gRPC (internal) |
Overview
Woodpecker CI is a community-driven fork of Drone CI — a modern, lightweight CI/CD system that uses Docker containers for pipeline steps. Pipelines are defined in a .woodpecker.yml file at the repository root, with each step running in its own Docker container. It integrates natively with Gitea for webhook-triggered builds.
Why Use It
Woodpecker CI completes the self-hosted DevOps stack: Gitea handles code, Woodpecker handles CI/CD, Harbor stores images. Unlike Jenkins (JVM-heavy, XML configuration, plugin hell) or GitLab CI (requires GitLab), Woodpecker is a lightweight Go binary with Docker-native YAML pipelines that integrates natively with Gitea via OAuth. There are no agents to license, no cloud dependency, and pipeline definitions live in the repository alongside the code they build.
When You Need It
Who Should Use It
Real Use Cases
Main Features
How to Use After Installation
Security Best Practices
Ports and Firewall Notes
Woodpecker server runs on port 8000 (gRPC for agents) and port 8080 (web UI). Put the web UI behind Nginx Proxy Manager on HTTPS port 443. The gRPC port 8000 must be reachable by Woodpecker agents — if agents run on the same host, this is internal. Gitea sends webhooks to Woodpecker's public HTTPS URL on port 443 — ensure Gitea can reach Woodpecker's domain. No inbound ports beyond 443 are needed if agents are co-located.
Backup and Maintenance
Common Mistakes
Troubleshooting
Alternatives
Drone CI is Woodpecker's upstream origin — still maintained commercially by Harness. Jenkins is the most widely used CI system but requires significant maintenance, JVM resources, and plugin management. GitHub Actions is excellent if you're on GitHub but ties you to their platform and minutes quota. GitLab CI is deeply integrated with GitLab but requires the full GitLab stack. Tekton is Kubernetes-native CI but requires a Kubernetes cluster. For simplicity plus Gitea integration, Woodpecker is the cleanest choice.
When Not to Use It
Avoid Woodpecker if you need enterprise CI features like flaky test analytics, sophisticated caching layers, test parallelism across 50+ machines, or compliance audit trails — Jenkins or GitLab CI are better suited. Don't use it if your team's code is on GitHub and you want tight GitHub PR integration — GitHub Actions is simpler there. Woodpecker also has a smaller plugin ecosystem than Jenkins; if you rely on specific Jenkins plugins, check Woodpecker's plugin library first.
Need Help Setting Up Woodpecker CI?
PrismaTechWork provides end-to-end infrastructure services — from initial deployment and security hardening to ongoing monitoring, automated backups, and dedicated support. Whether you need a single-server setup or a multi-site network, our team ensures your infrastructure is built right, secured properly, and maintained reliably.
Frequently Asked Questions
What is the difference between Woodpecker CI and Drone CI?
Woodpecker CI is a community fork of Drone CI 0.8 (before Drone became commercialized). Woodpecker is MIT-licensed, actively maintained by the community, and free for any use. Drone CI is now owned by Harness and the enterprise edition is paid. Woodpecker has diverged with its own improvements and is the recommended choice for self-hosted deployments. Most Drone CI pipeline YAML files work in Woodpecker with minor adjustments.
How do I build and push a Docker image in a Woodpecker pipeline?
Use the woodpeckerci/plugin-docker-buildx plugin step: `image: woodpeckerci/plugin-docker-buildx` with settings for `repo`, `registry`, `username` (from secret), and `password` (from secret). Point the registry to your Harbor instance URL. The plugin builds the Dockerfile in your repository and pushes the image. Set `tags: latest,${CI_COMMIT_SHA}` to tag builds with both latest and the commit hash.
Can Woodpecker run on ARM (Raspberry Pi, Apple Silicon)?
Yes. Woodpecker publishes multi-arch Docker images for amd64 and arm64. You can run the Woodpecker server on x86 and connect ARM agents (Raspberry Pi, Oracle Ampere) for building ARM-native images. This is useful for cross-compilation or running native ARM tests in your CI pipeline. Set the agent's WOODPECKER_AGENT_TAGS to architecture labels to route specific pipeline steps to the right agent.
How do I pass secrets to a pipeline step?
In Woodpecker UI, go to the repository > Secrets > Add Secret. Create a secret with a name and value. In your .woodpecker.yml, reference it under environment: with the from_secret syntax: `DB_PASSWORD: from_secret: db_password`. The secret is injected as an environment variable in the step container — it never appears in the YAML file or repository.
Can I run Woodpecker agents on a different server from the Woodpecker server?
Yes. The Woodpecker server and agents communicate over gRPC (port 8000). Run agents on any server that can reach port 8000 on your Woodpecker server. Configure WOODPECKER_SERVER and WOODPECKER_AGENT_SECRET on each agent to connect. This lets you run builds on dedicated hardware — more powerful machines, ARM boards, or servers in a different network — while the UI and webhook handling stays on the main server.
How do I cache dependencies between pipeline runs?
Use the woodpeckerci/plugin-caching plugin or mount a named Docker volume in your pipeline step. For npm/pip/maven dependencies, mount a cache volume at the package manager's cache directory. Alternatively, build a custom Docker image that pre-installs your dependencies and use it as the pipeline step image — this is the simplest approach for stable dependency sets.
How do I deploy to a production server from a Woodpecker pipeline?
Use an SSH step: `image: appleboy/drone-ssh` (compatible with Woodpecker) with `host`, `username`, and `key` (from secret — the server's private SSH key). In the script, run docker compose pull && docker compose up -d on the target server. Add a `when: branch: main` condition to only deploy on merges to the main branch. Store the SSH private key as a Woodpecker secret.
Is there a web editor for .woodpecker.yml or do I always edit locally?
Woodpecker does not have a built-in pipeline YAML editor — you edit .woodpecker.yml in your repository and push to trigger changes. However, Gitea has a web editor for files, so you can edit .woodpecker.yml directly in the Gitea UI. Woodpecker does provide a CI Lint tool to validate your YAML syntax before running. The Woodpecker CLI (woodpecker-cli exec) lets you test pipelines locally without pushing.