Woodpecker CI: Lightweight Self-Hosted CI

By Khimananda Oli | Last reviewed: August 2026

Teams needing full control over their build environment often hit a wall with SaaS runners: high costs, data residency concerns, and network latency. Woodpecker CI: Lightweight Self-Hosted CI solves this by providing a container-native automation platform that runs entirely on your own infrastructure. If you are evaluating self-hosted CI runners for compliance or performance, Woodpecker offers a streamlined alternative to heavier orchestrators.

How does Woodpecker CI: Lightweight Self-Hosted CI work?

Woodpecker operates on a decoupled server-agent model that prioritizes isolation and scalability. The server component handles webhooks from your Git provider (Gitea, GitHub, GitLab), manages the UI, stores configuration, and schedules builds. It does not execute any code itself. This separation is critical for security; your build logic never runs on the same host as your scheduling logic or database.

The agent component connects to the server via gRPC and polls for work. When a pipeline is triggered, the server assigns it to an available agent based on labels and capacity. The agent then translates the YAML pipeline definition into backend-specific operations. By default, this means spinning up ephemeral Docker containers for each step, ensuring no state leaks between builds. For teams already running Kubernetes clusters, Woodpecker can also schedule pods directly, making it truly cloud-native.

Understanding the execution lifecycle

1. Webhook Receipt: The server receives a push or pull request event and validates the signature.
2. Pipeline Parsing: The .woodpecker.yml file is parsed, and secrets are injected securely from the datastore.
3. Scheduling: The server matches the pipeline's required labels (e.g., platform: linux/amd64) against registered agents.
4. Execution: The assigned agent creates isolated containers for each step, streaming logs back to the server in real-time.
5. Cleanup: Upon completion (success or failure), all containers and temporary volumes are destroyed automatically.

How do you install and configure Woodpecker CI?

Deployment is straightforward because Woodpecker ships as two small Go binaries or container images. For most production environments, I recommend running both the server and agent as containers via Docker Compose or Helm. Below is a battle-tested Docker Compose configuration that sets up a secure, persistent instance.

version: '3.8'

services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:v2.7.0
    ports:
      - "8000:8000"   # HTTP API and UI
      - "9000:9000"   # gRPC for agents
    volumes:
      - woodpecker-data:/var/lib/woodpecker/
    environment:
      - WOODPECKER_HOST=https://ci.example.com
      - WOODPECKER_GITEA=true
      - WOODPECKER_GITEA_URL=https://git.example.com
      - WOODPECKER_GITEA_CLIENT=your-oauth-client-id
      - WOODPECKER_GITEA_SECRET=your-oauth-secret
      - WOODPECKER_AGENT_SECRET=generate-a-strong-random-string-here
      - WOODPECKER_DATABASE_DRIVER=postgres
      - WOODPECKER_DATABASE_DATASOURCE=postgres://user:pass@db:5432/woodpecker?sslmode=disable

  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:v2.7.0
    command: --server woodpecker-server:9000
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WOODPECKER_SERVER=woodpecker-server:9000
      - WOODPECKER_AGENT_SECRET=generate-a-strong-random-string-here
      - WOODPECKER_MAX_PROCS=4
    depends_on:
      - woodpecker-server

volumes:
  woodpecker-data:

Critical security configuration notes

A common mistake in self-hosted CI setups is leaving the agent secret weak or exposing the Docker socket unnecessarily. Always generate a cryptographically strong WOODPECKER_AGENT_SECRET; this token authenticates agents to the server. If compromised, an attacker could inject malicious pipelines. For Kubernetes deployments, avoid mounting the Docker socket entirely; use the native Kubernetes backend instead to maintain pod-level isolation. Refer to Ubuntu security hardening best practices if hosting agents on bare metal VMs.

How does Woodpecker CI compare to Drone and Jenkins?

Choosing the right tool requires understanding trade-offs. Woodpecker forked from Drone CI in 2021 after Drone's acquisition introduced licensing changes that restricted certain self-hosted use cases. While Jenkins remains the industry veteran, its JVM-based architecture and plugin complexity make it heavy for modern container workflows. Woodpecker occupies a specific niche: true open-source, container-first simplicity.

In practice, if you are starting fresh in 2026 and want a CI/CD solution for small teams, Woodpecker’s lower maintenance burden wins. Jenkins still makes sense if you have complex legacy integrations or require non-container build steps that cannot be easily containerized. Drone users should evaluate migration to Woodpecker if licensing restrictions become a blocker; the YAML syntax is nearly identical, making migration typically a find-and-replace operation.

What are the best practices for securing Woodpecker CI pipelines?

Self-hosting gives you control, but it also transfers security responsibility to you. After auditing numerous CI systems for SOC 2 compliance, I’ve found that most breaches stem from misconfigured secrets or overly permissive agents. Treat your CI infrastructure with the same rigor as production application servers.

• Never hardcode secrets: Use Woodpecker’s built-in secrets manager or integrate with HashiCorp Vault. Secrets should be scoped to specific repositories and events (e.g., only available on push, not pull_request).
• Isolate untrusted builds: If you accept external contributions, run fork PRs on dedicated agents with no access to deployment credentials or internal networks. Use agent labels like trust: untrusted to route these safely.
• Pin plugin versions: Avoid using latest tags in pipeline steps. Always pin to specific SHA256 digests or semantic versions to prevent supply chain attacks via compromised upstream images.
• Enable audit logging: Configure structured logging and forward agent/server logs to your observability stack. Understanding structured logging best practices helps trace exactly who triggered what and when.
• Restrict Docker socket access: On Linux agents, consider using rootless Docker or Podman to reduce the blast radius if a build container escapes isolation.

When should you choose Woodpecker CI over other options?

Woodpecker excels when you need predictable performance without cloud bills scaling linearly with commit frequency. It is ideal for organizations with existing on-premise hardware, edge deployments, or strict data residency requirements where code cannot leave a specific jurisdiction. In Nepal, where international bandwidth can be expensive and latency-sensitive, running Woodpecker locally eliminates round-trips to US/EU SaaS endpoints entirely.

However, it is not a universal replacement. If your team lacks container expertise or needs deep integration with proprietary enterprise tools (like mainframe testing), Jenkins or Azure DevOps may still be more pragmatic. Woodpecker assumes comfort with containers as the fundamental unit of work. Evaluate your team’s maturity honestly before migrating. For those ready to adopt it, start with a single agent on existing infrastructure, validate the workflow, then scale horizontally as demand grows.

Next steps for adopting Woodpecker CI

Adopting Woodpecker CI: Lightweight Self-Hosted CI is a strategic move toward infrastructure sovereignty and cost predictability. Begin by deploying a test instance alongside your current CI system, migrate one low-risk repository, and measure the difference in feedback loop time and operational overhead. Ensure your monitoring covers agent health and queue depth from day one. If you need help designing a secure, compliant CI architecture tailored to your environment, reach out to discuss your DevOps infrastructure needs.