Woodpecker CI, без жодного SaaS у ланцюжку

Як встановити Woodpecker CI з Docker Compose

Сервер і агент на одному хості, у цьому прикладі під'єднані до GitHub. Замініть блок кузні на змінні Gitea, Forgejo, GitLab чи Bitbucket, якщо ваша кузня одна з них.

1. 1

   Встановіть Docker і Compose

   sudo apt install docker.io docker-compose-v2
   sudo systemctl enable --now docker

   Обидва контейнери й кожен крок конвеєра працюють на цьому демоні, тож це єдина залежність, потрібна хосту.

2. 2

   Зареєструйте застосунок OAuth у вашій кузні

   # GitHub: Settings -> Developer settings -> OAuth Apps -> New OAuth App
   # Homepage URL:     https://ci.example.com
   # Authorization callback: https://ci.example.com/authorize

   Woodpecker автентифікує користувачів через кузню і з цим дозволом читає репозиторії, тож ідентифікатор клієнта й секрет, які вона повертає, - це те, що потрібне серверу. Кожна підтримувана кузня має відповідну форму.

3. 3

   Згенеруйте спільний секрет агента

   openssl rand -hex 32

   Сервер і агенти автентифікують одне одного цим рядком, а документація Woodpecker називає саме цю команду для його створення. Тримайте його поза файлом compose - покладіть у файл .env поруч.

4. 4

   Напишіть файл compose

   services:
     woodpecker-server:
       image: woodpeckerci/woodpecker-server:v3
       ports:
         - 8000:8000
       volumes:
         - woodpecker-server-data:/var/lib/woodpecker/
       environment:
         - WOODPECKER_OPEN=true
         - 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:
       image: woodpeckerci/woodpecker-agent:v3
       command: agent
       restart: always
       depends_on:
         - woodpecker-server
       volumes:
         - woodpecker-agent-config:/etc/woodpecker
         - /var/run/docker.sock:/var/run/docker.sock
       environment:
         - WOODPECKER_SERVER=woodpecker-server:9000
         - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
   volumes:
     woodpecker-server-data:
     woodpecker-agent-config:

   Це приклад від розробників. WOODPECKER_HOST - публічна URL-адреса, до якої звертаються користувачі й вебхуки, порт 8000 - вебінтерфейс, а 9000 - порт gRPC, до якого під'єднуються агенти. WOODPECKER_OPEN=true впускає будь-кого з обліковим записом у кузні - вимкніть це, щойно ваша команда зареєструється.

5. 5

   Запустіть

   docker compose up -d
   docker compose logs -f woodpecker-agent

   Агент під'єднується до сервера зі спільним секретом і сам реєструється при першому контакті. Якщо він зациклюється на помилці автентифікації, два секрети не збігаються - найчастіше тому, що файл .env не було прочитано.

6. 6

   Додайте конвеєр

   when:
     - event: push
   
   steps:
     - name: smoke
       image: alpine:latest
       commands:
         - cat /etc/os-release
         - echo "built on $CI_MACHINE"

   Закомітьте це як .woodpecker.yaml, увімкніть репозиторій у вебінтерфейсі, щоб створився вебхук, і запуште. Кожен крок - це контейнер, і саме тому агенту потрібен сокет Docker.

Звірено з офіційною документацією 2026-08-15 — читати першоджерело