Недавно я опубликовал на Хабре разбор архитектуры своего 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)
Параметр
Значение / Спецификация
Инструмент и репозиторий
cd — github.com/Dmitry-Fedotov-Dev/cd (лицензия MIT)
GitHub Action (Marketplace)
Dmitry-Fedotov-Dev/cd@v1 (cd deploy); для фиксации версии используйте тег @vX.Y.Z
Серверные компоненты
Демон cdd (systemd, слушает 127.0.0.1 за reverse proxy) и CLI cdctl (Go, без внешних зависимостей)
Протокол авторизации
cd protocol v1 поверх HTTPS: OIDC JWT (RS256), проверка aud (CD_SERVER), repository, ref, environment
Типы проектов (--type)
node, static, dockerfile
Другие поддерживаемые CI
GitLab CI (gitlab/deploy.yml с id_tokens), любой shell-клиент (deploy.sh)
Требования к серверу (VPS)
Linux с Docker, systemd и reverse proxy (из коробки поддержаны Caddy и автоматизация DNS через Porkbun)
Предусловия: что должно быть готово на 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.shsudo 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//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.shbash 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_SERVER -
Value:
https://deploy.example.com(строго без завершающего слеша)
Вариант Б, Шаг 3: создание workflow .github/workflows/deploy.yml
Добавьте в репозиторий файл .github/workflows/deploy.yml:
name: Deploy to Productionon: push: branches: - mainpermissions: contents: read id-token: writejobs: 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
Параметр (with:)
Обязательный
По умолчанию
Назначение и допустимые значения
server
Да
—
Публичный HTTPS URL сервера cdd без слеша на конце (обычно ${{ vars.CD_SERVER }})
project
Да
—
Имя проекта, зарегистрированное на сервере командой cdctl project add
action
Нет
deploy
Действие протокола cd protocol v1: deploy, status, logs, rollback
bundle
Нет
—
Путь к готовому архиву .tar.gz (отменяет вызов git archive)
paths
Нет
—
Список директорий или файлов через пробел для сужения архивации исходников
lines
Нет
—
Число строк журнала для action: logs (передаётся в протокольный параметр &n={lines}, диапазон 1–1000)
Боевые рецепты для повседневных задач
Рецепт 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 Bundleon: push: branches: - mainpermissions: contents: read id-token: writejobs: 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: writejobs: 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 Controlon: 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: writejobs: 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.
Код CD-RESULT
Значение
Типичная причина
Решение
0
Успех (ok)
Новый релиз ответил на /healthz и обслуживает трафик; прежний контейнер удалён
Действий не требуется
1
Ошибка сборки или старта
Исчерпаны лимиты сборки (1 GB / 1 CPU / 15 мин), сбой старта или таймаут /healthz (90 с)
Проверить $PORT, /healthz, запись только в /tmp/--data; прежний релиз продолжает работать
2
Архив отклонён
Симлинки, .., абсолютный путь в bundle.tar.gz, либо превышены 50 МБ / 300 МБ / 20 000 файлов
Проверить содержимое tar -tzf bundle.tar.gz и размер архива
3
Сервер занят или обрыв связи
На этом VPS уже идёт другой деплой/откат (лимит 1 операция одновременно) или превышены 6 операций в час (deploys_per_hour)
Дождаться завершения активной задачи и проверить статус (action: status)
4
Некорректный запрос
Неверные параметры экшена, формат SHA коммита (требуется 7–64 hex-символа) или некорректное значение lines
Исправить блок with: в workflow
5
Доступ запрещён
Нет id-token: write, лишний / в CD_SERVER, запуск не с той ветки/environment или проект не зарегистрирован
Проверить CD_SERVER, permissions, ветку запуска и cdctl project list
При необходимости журнал самого демона на 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--old), запускает новый и ждёт ответа от /healthz. Если проверка не пройдена в пределах таймаута, демон выводит хвост логов упавшего контейнера, удаляет его, снова запускает cd--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.
Источник: habr.com