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, включите репозиторий в веб-интерфейсе, чтобы создался вебхук, и сделайте push. Каждый шаг - это контейнер, и именно поэтому агенту нужен сокет Docker.

Сверено с официальной документацией 2026-08-15 — читать первоисточник