Недавно я опубликовал на Хабре разбор архитектуры своего 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.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_SERVER

  • Value: 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 выполнит четыре последовательных шага:

  1. Запросит у GitHub временный OIDC-токен с полем aud, равным vars.CD_SERVER.

  2. Упакует текущий коммит с помощью git archive.

  3. Передаст tar.gz по HTTPS и начнёт в реальном времени стримить лог сборки (в отдельном BuildKit-контейнере с лимитами по умолчанию 1 GB RAM, 1 CPU и 15 минут) и старта контейнера в консоль GitHub Actions.

  4. Завершит вывод статусной строкой 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 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.

Код 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-<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).


Полезные ссылки

Если вы уже пробовали cd в своих проектах, расскажите в комментариях: где вы предпочитаете собирать тяжёлые артефакты — в раннере CI через bundle или прямо на сервере — и каких сценариев не хватает в следующей версии экшена? Буду рад обратной связи и баг-репортам в Issues на GitHub.