Why move away from cloud CI to a pipeline on your VPS
Cloud CI offerings bill by the build minute and impose shared queues whose wait time grows with volume. As repositories grow or tests multiply, the bill quickly exceeds the cost of a dedicated VPS. Hosting Forgejo and Woodpecker CI on the same server eliminates that network latency: the runner reads the code locally, without transit through a third-party infrastructure. You also choose when each pipeline update happens, and no integration secret leaves your machine.
What Woodpecker CI brings to a VPS
- Docker isolation per step — each step runs in its own container, with no shared state between jobs.
- Small memory footprint — the Woodpecker server and agent start up using less than 50 MB of RAM combined.
- Minimal YAML configuration — a single
.woodpecker.yamlfile at the root of the repository is enough to describe the full pipeline. - Native Forgejo integration — Forgejo's OAuth2 is the only authentication mechanism required, with no extra plugin.
- Apache 2.0 licence — the source code is auditable, the community fork is active, with no dependency on a proprietary vendor.
Prerequisites: a VPS with Forgejo already running
Woodpecker CI can be installed on the same VPS as Forgejo or on a dedicated server. For both services combined, plan for 1 GB of RAM as a minimum and 2 GB for comfortable use with several active repositories. On the software side: Docker and Docker Compose, a dedicated subdomain for Woodpecker (for example ci.your-domain.com) pointing to the VPS IP, port 443 open for HTTPS, and SSH access. Forgejo must be reachable from the Woodpecker container via the internal Docker network or its public URL.
Deploy Woodpecker CI on your VPS
Create an OAuth App in Forgejo
In Forgejo, go to Settings → Applications → Manage OAuth2 Applications. Give the application a name (for example woodpecker) and enter the redirect URL: https://ci.your-domain.com/authorize. Note the generated Client ID and Client Secret.
Write the Woodpecker docker-compose.yml
Create /opt/woodpecker/docker-compose.yml with two services: woodpecker-server (image woodpeckerci/woodpecker-server) and woodpecker-agent (image woodpeckerci/woodpecker-agent). On the server, set WOODPECKER_GITEA_URL, WOODPECKER_GITEA_CLIENT, WOODPECKER_GITEA_SECRET (the OAuth2 values you copied), WOODPECKER_AGENT_SECRET (a random string shared between server and agent), and WOODPECKER_HOST=https://ci.your-domain.com. The agent receives WOODPECKER_SERVER=woodpecker-server:9000 and the same WOODPECKER_AGENT_SECRET.
Start the stack
In /opt/woodpecker, run docker compose up -d. Check the logs with docker compose logs -f woodpecker-server until you see the server ready. The service listens internally on port 8000 (UI) and 9000 (gRPC agent).
Activate the repository in Woodpecker
Open https://ci.your-domain.com (behind your reverse proxy) and sign in with your Forgejo account via OAuth2. In the dashboard, click "Add repository" and select the project to activate. Woodpecker automatically registers a webhook in Forgejo to trigger builds.
Add a .woodpecker.yaml file to the repository
At the root of the repository, create .woodpecker.yaml. A minimal example: a lint step running npm run lint in the node:20 image, a test step (npm test), and a deploy step conditional on the main branch that runs ssh [email protected] ./deploy.sh. Push the file: a build triggers immediately in Woodpecker.
Place the Woodpecker server behind Traefik or Caddy with HTTPS and never expose it directly on port 8000. Store all pipeline secrets (SSH tokens, deployment API keys) in the repository secrets section of the Woodpecker dashboard — they are injected as environment variables during the build without appearing in the versioned .woodpecker.yaml.
From git forge to continuous deployment: a complete sovereign stack
Forgejo manages code, issues and pull request reviews; Woodpecker CI orchestrates the test and deployment pipelines. Both communicate through OAuth2 and webhooks on your own network, with no dependency on GitHub, GitLab or a cloud integration service. This self-hosted stack meets the sovereignty requirements of agencies and technical teams who do not want their intellectual property or integration secrets to pass through external platforms.
