Недавно я опубликовал на Хабре разбор архитектуры своего open-source инструмента cd (Dmitry-Fedotov-Dev/cd) — легковесной self-hosted системы доставки кода на свой VPS через OpenID Connect (OIDC). Вместо приватных SSH-ключей и статических токенов в настройках репозитория система использует одноразовые подписанные JWT от самой CI-платформы.
Сегодня практическое продолжение цикла: клиентская часть оформлена в официальный GitHub Action cd deploy (uses: Dmitry-Fedotov-Dev/cd@v1) в GitHub Marketplace. Под катом — воспроизводимая инструкция без лишней теории: паспорт экшена, быстрый старт (в одну команду или за 3 шага), требования к контейнеру, три готовых сценария (bundle со сборкой в CI, монорепозиторий и ручной откат через workflow_dispatch), а также таблица диагностики кодов CD-RESULT.
Паспорт инструмента и совместимость (TL;DR)
Параметр | Значение / Спецификация |
|---|---|
Инструмент и репозиторий |
|
GitHub Action (Marketplace) |
|
Серверные компоненты | Демон |
Протокол авторизации |
|
Типы проектов ( |
|
Другие поддерживаемые CI | GitLab CI ( |
Требования к серверу (VPS) | Linux с Docker, |
Предусловия: что должно быть готово на VPS и в приложении
Большинство ошибок первого запуска связано не с YAML в GitHub Actions, а с невыполнением контракта серверной части cdd и песочницы контейнера.
Установка демона cdd на сервер
Если управляющий демон cdd ещё не развёрнут на вашем VPS, установите cdd и cdctl от имени root (установщик проверяет контрольные суммы checksums.txt и затрагивает только /usr/local/bin/cd*, /etc/cdd и /var/lib/cdd):
curl -fsSLO https://raw.githubusercontent.com/Dmitry-Fedotov-Dev/cd/v1/install.sh
sudo bash install.sh --public-url https://deploy.example.com
Значение --public-url (и будущая переменная CD_SERVER в GitHub) обязательно должно использовать HTTPS и записываться строго без завершающего слеша (https://deploy.example.com, а не https://deploy.example.com/). Сервер проверяет совпадение aud внутри OIDC-токена по точному строковому равенству.
Контракт запускаемого приложения в песочнице cdd
Демон cdd запускает каждый релиз в изолированном Docker-контейнере. Чтобы контейнер прошёл проверку здоровья и не откатился к предыдущему релизу, приложение должно соблюдать пять правил:
Процесс слушает порт из переменной окружения
$PORT(по умолчанию3000).Приложение отвечает HTTP
200на запрос к/healthzв течение90секунд (health_timeout_sec).Контейнер выполняется от непривилегированного пользователя
UID 10001(все Linux capabilities сброшены, включёнno-new-privileges, swap отключён, порт привязан только к127.0.0.1).Корневая файловая система смонтирована в режиме read-only. Запись разрешена только в
/tmp(tmpfsв памяти) и в постоянный каталог данных проекта/var/lib/cdd/projects/<name>/data(задаётся флагом--data).Секреты времени выполнения (строки подключения к БД, API-ключи) никогда не хранятся в репозитории или GitHub Secrets — они размещаются только на VPS в
env_fileпроекта.
Быстрый старт: в одну команду или за 3 шага
Вариант А: подключение репозитория в одну команду через init.sh
Если проект уже зарегистрирован на сервере (см. Шаг 1 ниже), а локально в папке репозитория у вас авторизован GitHub CLI (gh), настроить .github/workflows/deploy.yml и переменную CD_SERVER можно одним скриптом:
curl -fsSLO https://raw.githubusercontent.com/Dmitry-Fedotov-Dev/cd/v1/init.sh
bash init.sh my-app https://deploy.example.com
Скрипт init.sh проверит доступность сервера через GET /v1/healthz, создаст workflow-файл для проекта my-app, запишет переменную CD_SERVER, закоммитит изменения и выполнит git push, сразу запустив первый деплой.
Вариант Б, Шаг 1: регистрация проекта на VPS через cdctl project add
Создайте проект на сервере и привяжите его к конкретному репозиторию, ветке и окружению (обратите внимание на обязательную подкоманду project):
sudo cdctl project add my-app \
--repo Dmitry-Fedotov-Dev/my-app \
--branch main \
--environment production \
--type node \
--domain app.example.com
С этого момента демон cdd будет принимать запросы для my-app только при наличии валидного OIDC-токена GitHub Actions, выпущенного именно для ветки main и окружения production репозитория Dmitry-Fedotov-Dev/my-app.
Если на сервере заранее настроена связка с Porkbun DNS (sudo cdctl domain setup --zone example.com --ip 203.0.113.10), утилита предложит создать DNS-запись и сгенерирует HTTPS-конфигурацию Caddy в /etc/caddy/cd/my-app.caddy. Если домен уже направлен на сервер вручную (например, wildcard-записью), будет создан только сайт Caddy.
Вариант Б, Шаг 2: создание переменной CD_SERVER в GitHub
В настройках репозитория на GitHub откройте Settings → Secrets and variables → Actions → вкладка Variables (именно Variables, а не Secrets, поскольку URL деплой-сервера не является секретом) и создайте одну переменную:
Name:
CD_SERVERValue:
https://deploy.example.com(строго без завершающего слеша)
Вариант Б, Шаг 3: создание workflow .github/workflows/deploy.yml
Добавьте в репозиторий файл .github/workflows/deploy.yml:
name: Deploy to Production
on:
push:
branches:
- main
permissions:
contents: read
id-token: write
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Deploy via cd
uses: Dmitry-Fedotov-Dev/cd@v1
with:
server: ${{ vars.CD_SERVER }}
project: my-app
Обязательные требования к конфигурации workflow:
Строка
id-token: writeвpermissionsобязательна — без неё раннер не сможет получить одноразовый OIDC JWT от GitHub.Значение
environment: productionдолжно совпадать с флагом--environmentна сервере (если при вызовеcdctl project addокружение не задавалось, блокenvironmentможно убрать, однако для продакшена его рекомендуется сохранять как дополнительный контур защиты).
Вариант Б, Шаг 4: верификация первого деплоя
После git push origin main перейдите во вкладку Actions вашего репозитория. Экшен Dmitry-Fedotov-Dev/cd@v1 выполнит четыре последовательных шага:
Запросит у GitHub временный OIDC-токен с полем
aud, равнымvars.CD_SERVER.Упакует текущий коммит с помощью
git archive.Передаст
tar.gzпо HTTPS и начнёт в реальном времени стримить лог сборки (в отдельном BuildKit-контейнере с лимитами по умолчанию1 GBRAM,1CPU и15минут) и старта контейнера в консоль GitHub Actions.Завершит вывод статусной строкой
CD-RESULT: 0 ok, а при сбое сборки или провале/healthzавтоматически вернёт предыдущий контейнерcd-my-app-old.
Для проверки состояния с сервера используйте cdctl project list и cdctl top, а доступность самого демона без авторизации можно проверить запросом curl -fsS https://deploy.example.com/v1/healthz (ожидаемый ответ: {"ok":true,"version":"..."}).
Спецификация входных параметров GitHub Action Dmitry-Fedotov-Dev/cd@v1
Параметр ( | Обязательный | По умолчанию | Назначение и допустимые значения |
|---|---|---|---|
| Да | — | Публичный HTTPS URL сервера |
| Да | — | Имя проекта, зарегистрированное на сервере командой |
| Нет |
| Действие протокола |
| Нет | — | Путь к готовому архиву |
| Нет | — | Список директорий или файлов через пробел для сужения архивации исходников |
| Нет | — | Число строк журнала для |
Боевые рецепты для повседневных задач
Рецепт 1. Сборка артефактов в CI и отправка готового бандла (bundle)
В комментариях к первой статье справедливо отмечалось, что сборка кода на самом продакшен-VPS нагружает слабый сервер и повышает риски при работе с тяжёлыми или недоверенными зависимостями. Вынос компиляции в раннер GitHub Actions с передачей готового архива через bundle решает обе задачи: на сервер попадает только собранный бинарник без исходников и компиляторов.
Предусловие на сервере: поскольку в бандле передаётся собственный Dockerfile, проект на сервере нужно зарегистрировать с флагом --type dockerfile (включайте этот тип только для доверенных проектов):
sudo cdctl project add my-app \
--repo Dmitry-Fedotov-Dev/my-app \
--branch main \
--environment production \
--type dockerfile \
--domain app.example.com
Workflow со сборкой бинарника Go в CI:
name: Build and Deploy Bundle
on:
push:
branches:
- main
permissions:
contents: read
id-token: write
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Go
uses: actions/setup-go@v5
with:
go-version-file: go.mod
- name: Build binary and pack bundle
run: |
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o server ./cmd/app
tar -czf bundle.tar.gz server Dockerfile
- name: Deploy pre-built bundle
uses: Dmitry-Fedotov-Dev/cd@v1
with:
server: ${{ vars.CD_SERVER }}
project: my-app
bundle: bundle.tar.gz
Требования к bundle.tar.gz и Dockerfile: архив не должен содержать симлинков, жёстких ссылок, файлов устройств, абсолютных путей или сегментов ... По умолчанию допустимый размер — до 50 МБ в сжатом виде (max_bundle_mb) и до 300 МБ / 20 000 файлов после распаковки. Внутри контейнера процесс будет запущен от UID 10001 с корневой файловой системой в режиме read-only, поэтому скомпилированный бинарник должен иметь права на чтение и выполнение для всех пользователей, слушать $PORT и отвечать на /healthz.
Рецепт 2. Выборочный деплой из монорепозитория (paths)
Чтобы не передавать весь монорепозиторий и запускать деплой только при изменениях конкретного сервиса, скомбинируйте фильтр on.push.paths в триггере GitHub Actions со входом paths в Dmitry-Fedotov-Dev/cd@v1:
name: Deploy API Service (Monorepo)
on:
push:
branches:
- main
paths:
- "services/api/**"
- "deploy/Dockerfile"
permissions:
contents: read
id-token: write
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Deploy API service
uses: Dmitry-Fedotov-Dev/cd@v1
with:
server: ${{ vars.CD_SERVER }}
project: api-service
paths: "services/api deploy/Dockerfile"
Учитывайте правила распаковки: параметр paths ограничивает список файлов, попадающих в архив, при этом по спецификации cd protocol v1 сервер срезает только один общий каталог верхнего уровня (префикс вида app/). Убедитесь, что пути внутри архива (services/api/..., deploy/Dockerfile) совпадают со структурой, которую ожидает ваш Dockerfile или конфигурация проекта.
Рецепт 3. Откат, логи и статус без захода по SSH (workflow_dispatch)
Для ручного просмотра статуса, логов или отката релиза прямо из браузера или мобильного приложения GitHub добавьте отдельный workflow. Шаг actions/checkout для этих операций не требуется:
name: Prod Control
on:
workflow_dispatch:
inputs:
action:
description: "Команда управления релизом"
type: choice
required: true
options:
- status
- logs
- rollback
default: status
lines:
description: "Количество строк лога (для logs, 1–1000)"
type: string
required: false
default: "150"
permissions:
id-token: write
jobs:
control:
runs-on: ubuntu-latest
environment: production
steps:
- name: Run cd control action
uses: Dmitry-Fedotov-Dev/cd@v1
with:
server: ${{ vars.CD_SERVER }}
project: my-app
action: ${{ inputs.action }}
lines: ${{ inputs.lines }}
Два обязательных условия срабатывания: во-первых, при ручном запуске (Run workflow) выбирайте именно ту ветку (main), которая разрешена в cdctl project add, иначе GitHub запишет в OIDC-токен другую ветку в поле ref и cdd вернёт отказ 5. Во-вторых, если для проекта настроен флаг --environment production, секция environment: production в Prod Control также обязательна.
Диагностика ошибок и коды ответа CD-RESULT
Ошибки до старта потоковой отдачи логов возвращаются стандартными HTTP-статусами (400, 401, 403, 404, 413). После начала стриминга text/plain HTTP-статус всегда 200, а итог операции определяет финальная строка CD-RESULT: <код> <сообщение>. Если соединение оборвалось до появления CD-RESULT, это расценивается как код 3 — состояние нужно перепроверить командой status.
Код | Значение | Типичная причина | Решение |
|---|---|---|---|
| Успех ( | Новый релиз ответил на | Действий не требуется |
| Ошибка сборки или старта | Исчерпаны лимиты сборки ( | Проверить |
| Архив отклонён | Симлинки, | Проверить содержимое |
| Сервер занят или обрыв связи | На этом VPS уже идёт другой деплой/откат (лимит | Дождаться завершения активной задачи и проверить статус ( |
| Некорректный запрос | Неверные параметры экшена, формат SHA коммита (требуется | Исправить блок |
| Доступ запрещён | Нет | Проверить |
При необходимости журнал самого демона на VPS читается командой journalctl -u cdd, аварийная остановка и запуск выполняются через sudo cdctl stop my-app / sudo cdctl start my-app, а для тиражирования одного билда на несколько доменов и БД предусмотрено клонирование (sudo cdctl project clone).
Частые вопросы (FAQ)
Куда складывать переменные окружения и секреты приложения, если не использовать GitHub Secrets?
Секреты приложения (DATABASE_URL, токены внешних API, ключи шифрования) хранятся исключительно на VPS в env_file конкретного проекта. Они передаются контейнеру при запуске на сервере и никогда не попадают в репозиторий, GitHub Actions или архив бандла.
Поддерживает ли сервер cdd деплой из GitLab CI или обычного shell-скрипта?
Да. В том же репозитории Dmitry-Fedotov-Dev/cd есть готовый шаблон gitlab/deploy.yml (подключается через include: remote и extends: .cd-deploy с нативными id_tokens GitLab CI) и автономный клиент deploy.sh, принимающий токен через переменную окружения CD_ID_TOKEN или CD_TOKEN.
Что происходит с работающим сервисом во время деплоя и отката?
На время распаковки и сборки образа прежний контейнер продолжает обслуживать запросы. Для переключения версии cdd останавливает действующий контейнер (сохраняя его как cd-<project>-old), запускает новый и ждёт ответа от /healthz. Если проверка не пройдена в пределах таймаута, демон выводит хвост логов упавшего контейнера, удаляет его, снова запускает cd-<project>-old и завершает задачу с кодом 1.
Как зафиксировать версию GitHub Action и проверить подлинность бинарников сервера?
Тег Dmitry-Fedotov-Dev/cd@v1 автоматически подтягивает совместимые обновления первой мажорной ветки. Для жёсткой фиксации версии используйте конкретный тег патч-релиза Dmitry-Fedotov-Dev/cd@vX.Y.Z, а архивы релизов cdd и cdctl можно дополнительно проверять через криптографическую аттестацию происхождения GitHub (gh attestation verify).
Полезные ссылки
GitHub Action в Marketplace: cd deploy (
Dmitry-Fedotov-Dev/cd)Исходный код, шаблоны и спецификация протокола: github.com/Dmitry-Fedotov-Dev/cd
Первая часть цикла (теория OIDC, архитектура и сравнение подходов): Деплой на VPS по push без SSH-ключей в CI: архитектура cd, механика OIDC и границы применимости
Если вы уже пробовали cd в своих проектах, расскажите в комментариях: где вы предпочитаете собирать тяжёлые артефакты — в раннере CI через bundle или прямо на сервере — и каких сценариев не хватает в следующей версии экшена? Буду рад обратной связи и баг-репортам в Issues на GitHub.

Комментарии 0