Build a Woodpecker CI Pipeline End-to-End

If you are using Gitea or Forgejo instead of GitHub, replace the WOODPECKER_GITHUB* variables with WOODPECKER_GITEA=true, WOODPECKER_GITEA_URL, WOODPECKER_GITEA_CLIENT, and WOODPECKER_GITEA_SECRET.

Step 3 — Configure a Reverse Proxy (Caddy Example)

Caddy is the fastest path to automatic TLS. Add a block to your Caddyfile:

ci.example.com {
    reverse_proxy localhost:8000
}

systemctl reload caddy

For nginx, proxy http://127.0.0.1:8000 and add the standard X-Forwarded-* headers. The gRPC port (9000) does not need to be exposed publicly unless you run agents on other hosts.

Step 4 — Start the Stack and Activate Your First Repo

docker compose up -d
docker compose logs -f

Navigate to https://ci.example.com. Log in with your forge account. Woodpecker redirects through the OAuth flow and drops you into the dashboard. Click + Add repository, find your repo, and enable it. Woodpecker installs a webhook automatically.

Step 5 — Write Your First Pipeline

Woodpecker looks for .woodpecker.yaml (or .woodpecker/ directory) at the repository root. Each step runs in its own container sequentially unless you set depends_on for parallelism.

cat > .woodpecker.yaml <<'EOF'
steps:
  - name: lint
    image: golangci/golangci-lint:v1.57
    commands:
      - golangci-lint run ./...

  - name: test
    image: golang:1.22-alpine
    commands:
      - go test -race ./...

  - name: build-image
    image: woodpeckerci/plugin-docker-buildx:latest
    settings:
      repo: ghcr.io/yourorg/yourapp
      tags: latest,${CI_COMMIT_SHA:0:8}
      registry: ghcr.io
      username:
        from_secret: ghcr_user
      password:
        from_secret: ghcr_token
      cache_from: ghcr.io/yourorg/yourapp:cache
      cache_to: ghcr.io/yourorg/yourapp:cache
    when:
      branch: main
EOF

The cache_from / cache_to pair pushes BuildKit layer cache to the registry so subsequent builds skip unchanged layers. On a cold cache the first build is normal speed; warm builds can cut image build time by 60–80% for typical Go or Node apps.

Step 6 — Add Pipeline Secrets

Secrets are stored encrypted in the Woodpecker database and injected at runtime. Never hard-code credentials in .woodpecker.yaml.

Add secrets via the UI: Repository → Settings → Secrets → Add secret, or use the CLI:

# Install the CLI (single binary)
curl -Lo woodpecker-cli https://github.com/woodpecker-ci/woodpecker/releases/latest/download/woodpecker-cli_linux_amd64
chmod +x woodpecker-cli && mv woodpecker-cli /usr/local/bin/woodpecker

export WOODPECKER_SERVER=https://ci.example.com
export WOODPECKER_TOKEN=

woodpecker secret add \
  --repository yourorg/yourapp \
  --name ghcr_user \
  --value yourorg

woodpecker secret add \
  --repository yourorg/yourapp \
  --name ghcr_token \
  --value ghp_xxx...

Secrets are available to pipeline steps by referencing from_secret: secret_name inside a settings block, or as environment variables with environment: MY_VAR: from_secret: my_secret. Woodpecker masks secret values in logs automatically.

Step 7 — Add a Deploy Step

A deploy step runs only on the main branch after a successful image build. This example SSHes into a remote host and runs a docker compose pull && docker compose up -d:

# Append to .woodpecker.yaml
cat >> .woodpecker.yaml <<'EOF'

  - name: deploy
    image: appleboy/drone-ssh:latest
    settings:
      host:
        from_secret: deploy_host
      username:
        from_secret: deploy_user
      key:
        from_secret: deploy_ssh_key
      script:
        - cd /opt/myapp
        - docker compose pull
        - docker compose up -d --remove-orphans
    when:
      branch: main
      event: push
EOF

Add the three secrets (deploy_host, deploy_user, deploy_ssh_key) via the CLI or UI as shown in Step 6. The appleboy/drone-ssh plugin is compatible with Woodpecker because Woodpecker is a Drone fork and shares the plugin protocol.

Step 8 — Verify the Pipeline

Push a commit to your repository. The forge fires a webhook, Woodpecker queues the pipeline, and the agent picks it up within seconds.

# Watch agent logs in real time
docker compose logs -f woodpecker-agent

You should see the agent claim the job, pull the step images, execute each step, and report back. In the UI, navigate to Pipelines and click the run to see per-step logs and timing.

Troubleshooting

Agent won't connect to server

Confirm both containers are on the same Docker network and the AGENT_SECRET value in .env matches exactly. Check docker compose logs woodpecker-server for gRPC handshake errors. If you changed the secret after first start, restart both services.

Webhook 400 or not firing

Woodpecker registers the webhook at the forge using the WOODPECKER_HOST value. If that URL is unreachable from the internet (or from Gitea on the same host), webhooks silently fail. Test reachability: curl -I https://ci.example.com/healthz.

Docker-in-Docker permission errors

The agent mounts /var/run/docker.sock. On SELinux hosts (Fedora, RHEL, Rocky) you may need to add the :z relabelling option to the volume mount, or run setsebool -P container_manage_cgroup on. On AppArmor systems (Ubuntu), the default Docker profile is usually sufficient.

Registry cache push fails

BuildKit cache requires the registry credentials to have write access. Confirm the ghcr_token secret has the write:packages scope. If the cache tag doesn't exist yet, the first push creates it automatically — this is expected and not an error.