Replace GitHub Actions with Woodpecker CI on a VPS

Until 2025, private repositories included a monthly quota of free minutes. On December 16, 2025, GitHub announced per-minute pricing for runner usage — including self-hosted runners running on your own machines. GitHub Discussion #182089 (opened that same month, 72 upvotes) captured the community's concern: teams would be paying GitHub to orchestrate a job running on their own infrastructure, at $0.002 per minute.

Faced with a massive community backlash, GitHub suspended the pricing within 48 hours. As of September 1, 2026, self-hosted runners on private repositories remain free — the measure was never enforced. But the announcement exposed a structural dependency: GitHub can change its terms at any time. Moving the entire CI/CD chain to a self-hosted forge is how you remove that uncertainty. Woodpecker CI is built precisely for this: a lightweight, open source (Apache 2.0) pipeline engine that installs alongside Gitea or Forgejo and has no minute counter.

To deploy Woodpecker CI comfortably, check the following requirements.

VPS: 1 vCPU and 1 GB of RAM are sufficient for the Woodpecker server, one agent and a lightweight Gitea or Forgejo forge. Plan for 2 GB if you run several builds in parallel or if your jobs build Docker images.

Software: Docker and Docker Compose must be installed. If you are starting from a bare VPS, the guide Getting started with Docker on a VPS covers this step.

Git forge: Woodpecker CI relies on OAuth2 for authentication. You need a Gitea or Forgejo instance already running and accessible via HTTPS (for example at git.your-domain.com). The guides Hosting Gitea and Hosting Forgejo detail this setup.

Domain: prepare a dedicated subdomain for Woodpecker — for example ci.your-domain.com — pointing to your VPS IP, with port 443 open. This subdomain serves as WOODPECKER_HOST and as the OAuth2 redirect URL.

Woodpecker CI has its own YAML syntax — it is not compatible with GitHub Actions. The good news: it is shorter. Here is the migration of a classic Node.js workflow.

Before — .github/workflows/ci.yml:

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm test

After — .woodpecker.yml:

steps:
  - name: test
    image: node:20
    commands:
      - npm ci
      - npm test

Key differences: Woodpecker uses a Docker image directly as the runtime (no setup-node needed), and each step is a container service. The checkout action is implicit — Woodpecker automatically clones the repository into the shared workspace between steps.

The agent does not appear in the dashboard. Check that WOODPECKER_AGENT_SECRET is identical in both services of docker-compose.yml. If you modified the .env after the first start, restart with docker compose down && docker compose up -d.

OAuth2 login fails. The redirect URL registered in Gitea must match exactly https://ci.your-domain.com/authorize. A trailing slash, a typo or HTTP instead of HTTPS are enough to block the OAuth2 flow. Also check that WOODPECKER_GITEA_URL in docker-compose.yml points to the public URL of your Gitea — the Woodpecker container must be able to resolve it from inside the Docker network.

The webhook does not trigger. Open the repository in Gitea → Settings → Webhooks and check that the Woodpecker webhook is present and that recent deliveries have no 4xx error. If the webhook URL points to http:// instead of https://, Gitea may refuse to call it. Reconfigure WOODPECKER_HOST with the full HTTPS URL and reactivate the repository in Woodpecker to force the webhook update.

Builds fail due to out of memory. The Woodpecker server and agent use under 50 MB at idle — but each build step launches an additional Docker container. On a 1 GB VPS, limit concurrent builds by adding WOODPECKER_MAX_PROCS=2 to the woodpecker-agent service environment.

Once the base pipeline is working, several optimisations are worth exploring.

Multi-runner. Add a second woodpecker-agent service to your docker-compose.yml (same image, same WOODPECKER_AGENT_SECRET) to parallelise builds. Each agent is independent and can run on a separate VPS if your workload requires it.

Docker cache between builds. Mount a Docker volume in the agent and enable Docker layer caching to avoid re-downloading images on each build. Woodpecker supports native pipeline caching via the woodpecker-ci/cache plugin — add it as a dedicated step in your .woodpecker.yml.

Notifications. Woodpecker can notify a messaging channel on each build. Community plugins cover Matrix, Slack, Telegram and Mattermost — look for woodpecker-ci/notify-matrix or appleboy/drone-telegram in the official documentation.

Conditional pipelines. Woodpecker syntax lets you restrict a step to a specific branch or event:

steps:
  - name: deploy
    image: alpine
    when:
      branch: main
      event: push
    commands:
      - ./deploy.sh

To go deeper into pipeline setup, the guide Woodpecker CI and Forgejo: CI/CD pipeline on a VPS details advanced steps including Forgejo integration and multi-stage pipelines. The guide Docker Compose production checklist covers best practices for securing your Docker stacks in production.