# Woodpecker CI

CI/CD engine with a server and agents that run pipeline steps in containers.

- Replaces: [CircleCI](https://openlogs.fyi/alternatives/circleci)
- Summary: Paid hosted CI/CD services, such as CircleCI.
- Stack: Go (language)
- Deployment: docker_compose
- License: Apache-2.0 (osi) [source](https://github.com/woodpecker-ci/woodpecker/blob/aca84ce05addae61c1cf24349d9636b2d396457a/LICENSE)
- Business model: unknown. The README at the pinned commit does not state a business model, so it stays unknown. ([source](https://github.com/woodpecker-ci/woodpecker/blob/aca84ce05addae61c1cf24349d9636b2d396457a/README.md), read 2026-10-22)
- Difficulty: medium. 2 services, 2 volume mounts, 4 env values to set, host access: docker_socket. Heuristic score 5 of 11: medium.
- Requirements: not stated
- Repository: [woodpecker-ci/woodpecker](https://github.com/woodpecker-ci/woodpecker)

## Install

1. Docker with the Compose plugin ([source](https://github.com/woodpecker-ci/woodpecker/blob/aca84ce05addae61c1cf24349d9636b2d396457a/docker-compose.example.yaml))

   ```text
   A host with Docker and the Docker Compose plugin. This entry runs from a compose file.
   ```

2. Save the compose file as compose.yaml ([source](https://github.com/woodpecker-ci/woodpecker/blob/aca84ce05addae61c1cf24349d9636b2d396457a/docker-compose.example.yaml))

   ```yaml
   version: '3'
   
   services:
     woodpecker-server:
       image: woodpeckerci/woodpecker-server:v3
       ports:
         - 8000:8000
       networks:
         - woodpecker
       volumes:
         - /var/lib/woodpecker:/var/lib/woodpecker/
       environment:
         - WOODPECKER_OPEN=true
         - WOODPECKER_ADMIN=laszlocph
         - WOODPECKER_HOST=${WOODPECKER_HOST}
         - WOODPECKER_GITHUB=true
         - WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
         - WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
         - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
     woodpecker-agent:
       depends_on:
         woodpecker-server:
           condition: service_healthy
       image: woodpeckerci/woodpecker-agent:v3
       networks:
         - woodpecker
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock
       environment:
         - WOODPECKER_SERVER=woodpecker-server:9000
         - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
         - WOODPECKER_MAX_WORKFLOWS=2
   
   networks:
     woodpecker:
   ```

3. Set the values the compose file needs ([source](https://github.com/woodpecker-ci/woodpecker/blob/aca84ce05addae61c1cf24349d9636b2d396457a/docker-compose.example.yaml))

   ```text
   These variables have no default in the compose file: WOODPECKER_AGENT_SECRET, WOODPECKER_GITHUB_CLIENT, WOODPECKER_GITHUB_SECRET, WOODPECKER_HOST. Compose reads them from the shell or from a .env file next to the compose file.
   ```

4. Start it ([source](https://github.com/woodpecker-ci/woodpecker/blob/aca84ce05addae61c1cf24349d9636b2d396457a/docker-compose.example.yaml))

   ```bash
   docker compose up -d
   ```

5. Open the app ([source](https://github.com/woodpecker-ci/woodpecker/blob/aca84ce05addae61c1cf24349d9636b2d396457a/docker-compose.example.yaml))

   ```text
   Open http://localhost:8000. The compose file publishes host port 8000 for the woodpecker-server service.
   ```

Compose file check: config_ok on 2026-10-22.

## Gotchas and maintenance

### Gotchas

- The compose file publishes host ports: Host ports: 8000 (woodpecker-server). A port without a host address listens on all host network interfaces. ([source](https://github.com/woodpecker-ci/woodpecker/blob/aca84ce05addae61c1cf24349d9636b2d396457a/docker-compose.example.yaml), checked 2026-10-22)
- The compose file mounts host folders: Host paths mounted into containers: /var/lib/woodpecker at /var/lib/woodpecker/ (woodpecker-server). ([source](https://github.com/woodpecker-ci/woodpecker/blob/aca84ce05addae61c1cf24349d9636b2d396457a/docker-compose.example.yaml), checked 2026-10-22)
- Some services get elevated host access: woodpecker-agent mounts the Docker socket, which gives it control of Docker on the host. ([source](https://github.com/woodpecker-ci/woodpecker/blob/aca84ce05addae61c1cf24349d9636b2d396457a/docker-compose.example.yaml), checked 2026-10-22)

### Signals

Computed from a GitHub snapshot taken 2026-10-22.

- Open issues and pull requests: 391
- Stars: 8031, forks: 718
- Last push: 2026-10-22 (0 days ago)
- Latest release: v3.19.0 on 2026-10-07 (14 days ago)

## Sources

- [Repository: https://github.com/woodpecker-ci/woodpecker](https://github.com/woodpecker-ci/woodpecker)
- [License: https://github.com/woodpecker-ci/woodpecker/blob/aca84ce05addae61c1cf24349d9636b2d396457a/LICENSE](https://github.com/woodpecker-ci/woodpecker/blob/aca84ce05addae61c1cf24349d9636b2d396457a/LICENSE)
- [Business model: https://github.com/woodpecker-ci/woodpecker/blob/aca84ce05addae61c1cf24349d9636b2d396457a/README.md](https://github.com/woodpecker-ci/woodpecker/blob/aca84ce05addae61c1cf24349d9636b2d396457a/README.md)
- [Compose file: https://github.com/woodpecker-ci/woodpecker/blob/aca84ce05addae61c1cf24349d9636b2d396457a/docker-compose.example.yaml](https://github.com/woodpecker-ci/woodpecker/blob/aca84ce05addae61c1cf24349d9636b2d396457a/docker-compose.example.yaml)

---
Canonical: https://openlogs.fyi/tools/woodpecker-ci  
Last updated: 2026-10-22