CI/CD для AI-агентов с DOCKUP_TOKEN

CI/CD для AI-агентов работает надёжно только тогда, когда аутентификация и деплой корректно выполняются без человека за терминалом. Вход через браузер, копирование одноразовых кодов и сообщения о статусе только в виде текста несовместимы с unattended runner. Dockup поддерживает неинтерактивный сценарий через DOCKUP_TOKEN, структурированный JSON и команды деплоя, возвращающие настоящий ненулевой код завершения при ошибке.

В этом руководстве мы создадим контракт pipeline, которым смогут пользоваться Claude Code, Codex, shell-скрипт или обычная CI-задача. Правила одинаковы: передавать токен во время выполнения, проверять идентичность, находить или явно указывать точную цель, дожидаться терминального результата и сохранять диагностические данные при ошибке.

Зачем CI/CD для AI-агентов нужна неинтерактивная аутентификация?

Интерактивная команда dockup login открывает страницу аутентификации и ожидает токен. Это удобно на рабочей станции разработчика, но у контейнеризированного runner может не быть браузера, постоянного домашнего каталога или человека, который сможет что-либо вставить.

DOCKUP_TOKEN решает эту проблему:

export DOCKUP_TOKEN="<TOKEN>"
dockup whoami --json

Переменная окружения имеет приоритет над ~/.dockup/config.json. Команда whoami выводит tokenSource, поэтому pipeline может подтвердить, что используется именно переданная учётная информация, а не старый конфигурационный файл, оставшийся на self-hosted runner.

Не запускайте dockup login -t "$DOCKUP_TOKEN" в CI, если нет особой причины сохранять конфигурационный файл. Прямая передача переменной окружения ограничивает область действия учётных данных текущим процессом и не позволяет записывать их в домашний каталог runner.

Pipeline ни в коем случае не должен выводить токен. Отключайте трассировку shell-команд вокруг команд, использующих секреты, не выводите всё окружение и используйте механизм маскирования секретов, предоставляемый CI-платформой.

Как хранить и ограничивать область действия DOCKUP_TOKEN?

Храните токен в зашифрованном хранилище секретов репозитория, окружения или организации. Для production предпочтительнее секрет уровня окружения: его можно дополнительно связать с ограничениями по веткам и ручными подтверждениями, которые предоставляет CI-платформа.

Безопасная политика работы с токеном должна отвечать на пять вопросов:

Вопрос	Рекомендуемый ответ
Где хранится токен?	Зашифрованное хранилище секретов CI
Когда он доступен?	Только в задаче деплоя
Какие ветки могут его использовать?	Защищённые production-ветки
Кто может изменять workflow?	Мейнтейнеры, чьи изменения проходят review
Как проверяется использование?	Audit log Dockup и история CI-задач

Dockup также поддерживает API-ключи с разрешениями. Перед созданием ключа с узкой областью доступа выведите список доступных разрешений:

dockup keys permissions --json

Выбирайте только точные имена разрешений, возвращённые платформой, а затем создайте ключ через workflow для API-ключей с разрешениями. Надёжно сохраните сгенерированный ключ во время создания и сразу поместите его в хранилище; не добавляйте его в issue, pull request или transcript агента. Задача деплоя не должна получать широкие права администрирования аккаунта только потому, что они уже есть у токена разработчика.

В статье Защитные меры для AI-агентов в production описана более подробная лестница разрешений.

Как создать deployment pipeline, который дожидается достоверного результата?

Установите CLI в задаче, проверьте идентичность, а затем выполните деплой с --wait:

name: production-deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      DOCKUP_TOKEN: ${{ secrets.DOCKUP_TOKEN }}
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install Dockup CLI
        run: npm install -g dockup-cli

      - name: Verify Dockup identity
        run: dockup whoami --json

      - name: Deploy and wait
        run: dockup deploy production/api --wait --json

Важно не то, какого CI-провайдера вы используете, а контракт команды. dockup deploy ... --wait --json завершается с кодом 0 только после успешного завершения деплоя. Тайм-аут по умолчанию составляет 900 секунд. Ошибка сборки возвращает ненулевой код с deploy_failed, а операция, не достигшая терминального состояния до истечения тайм-аута, — deploy_timeout.

Поскольку процесс завершается с ненулевым кодом, runner помечает шаг и задачу как неуспешные. Анализировать логи вручную не требуется.

Для связанного репозитория, который должен отправить текущую ветку и выполнить деплой, команда dockup push --json по умолчанию ожидает завершения. В CI-задаче, уже получившей событие Git push, явная команда dockup deploy <target> часто понятнее, поскольку не отправляет изменения с runner.

Как pipeline должен сохранять логи и коды ошибок?

Сохраняйте результат деплоя в JSON как artifact или output задачи, но не допускайте, чтобы перенаправление вывода скрывало код завершения. Shell-паттерн позволяет получить и результат, и код:

set +e
dockup deploy production/api --wait --json > deploy-result.json
status=$?
set -e

if [ "$status" -ne 0 ]; then
  dockup logs production/api --build --json > build-logs.json || true
  cat deploy-result.json
  exit "$status"
fi

dockup status production/api --json

Pipeline завершается с исходным кодом деплоя. Логи сборки собираются только после ошибки. Runtime-логи следует собирать, если образ успешно собрался, но приложение впоследствии завершилось с ошибкой:

dockup logs production/api --json

Для наблюдения за сборкой в реальном времени режим follow выводит NDJSON:

dockup logs production/api --build -f --json

Поток завершается одновременно с деплоем, а при ошибке процесс по-прежнему возвращает ненулевой код. Подробная последовательность диагностики описана в статье Отладка логов сборки и runtime.

Pipeline должен обрабатывать коды, а не фрагменты сообщений:

Код	Действие pipeline
not_logged_in	Немедленно завершить работу с ошибкой: передача секрета нарушена
no_target	Завершить работу с ошибкой: конфигурация цели недействительна
deploy_trigger_failed	Завершить работу до ожидания; изучить возвращённую ошибку
deploy_failed	Загрузить логи сборки и завершить работу с ошибкой
deploy_timeout	Пометить результат как неопределённый; проверить статус перед повтором
needs_confirm	Остановиться: для деструктивного шага нет подтверждения

Как агент может участвовать, не ослабляя безопасность CI?

Агент может подготовить код, обновить прошедший review workflow, интерпретировать JSON и обобщить причины неудачной сборки. При этом ему не нужен неограниченный доступ к production-токену во время каждой сессии разработки.

Разделите роли:

1. Агент разработки: локально изменяет код и запускает тесты.
2. Процесс review: проверяет изменения конфигурации деплоя.
3. CI runner: получает DOCKUP_TOKEN только после одобренного триггера.
4. Dockup: выполняет деплой и записывает события аудита.
5. Агент или оператор: интерпретирует результат и предлагает восстановление.

Такая схема не позволяет prompt injection в несвязанной задаче получить production-учётные данные. Агент по-прежнему может понимать pipeline, поскольку команды и ожидаемый JSON хранятся в репозитории, а значение секрета остаётся за его пределами.

Для деплоя, который агент запускает напрямую, передайте токен конкретному процессу Claude Code или Codex и установите bundled skill:

npm install -g dockup-cli
dockup skill install
dockup whoami --json

Skill инструктирует обоих агентов использовать неинтерактивную аутентификацию, JSON, точное определение цели, ожидание терминального состояния и этапы подтверждения.

Что делает CI/CD для AI-агентов воспроизводимым и проверяемым?

Воспроизводимость начинается с явной цели. Храните production/api как защищённую переменную pipeline или проверенный review литерал, а не как имя, которое агент определяет во время выполнения. Проверьте аккаунт до первой операции записи.

Идемпотентность требует разного подхода к разным операциям:

• Повторять чтение идентичности, статуса, логов и истории безопасно.
• Создание сервиса должно начинаться с поиска цели, чтобы повторная попытка не создала дубликат.
• Повторный деплой создаёт ещё одно production-событие и должен быть зафиксирован.
• Изменение окружения является мутацией и требует повторного деплоя.
• Уничтожение и pruning не должны быть автоматическими целями для повторной попытки.

После деплоя соберите данные платформы:

dockup status production/api --json
dockup uptime production/api --hours 24 --json
dockup audit --writes --json

Uptime измеряется каждую минуту и включает среднее время ответа и p95. Данные аудита связывают изменение, выполненное CI, с последующим review. Потребление CPU, RAM и диска также измеряется каждую минуту относительно баланса аккаунта; рекомендуемый Pro-план стоит $20 в месяц и включает кредит на использование в размере $20.

Полная запись pipeline включает Git-коммит, цель Dockup, ID деплоя, время начала и окончания, код завершения, терминальный статус и ссылки на build artifacts. Благодаря этому релиз CI/CD для AI-агентов остаётся воспроизводимым, даже если исходная сессия агента уже завершилась.

Справочник Dockup CLI следует считать главным источником информации о командах. Чтобы создать репозиторий до включения CI, следуйте руководству От Git-репозитория к production.

Управляйте параллельностью и продвижением между окружениями

Даже два успешных pipeline могут создать небезопасный релиз, если они одновременно работают с одной целью. Используйте средства управления concurrency в CI-платформе, чтобы новая production-задача либо ожидала завершения старой, либо намеренно заменяла её. Dockup достоверно зафиксирует каждый деплой, но именно workflow репозитория должен определить порядок обработки пересекающихся коммитов.

Продвигайте между окружениями один и тот же прошедший review коммит, а не пересобирайте незафиксированное локальное состояние. Задача staging может выполнить деплой staging/api, запустить проверки приложения, а затем передать управление защищённой production-задаче, которая выполнит деплой production/api. Используйте разные токены и цели, чтобы staging-агент случайно не пересёк границу окружений.

Определите политику повторных попыток при тайм-ауте

deploy_timeout не означает ни ошибку, ни успех. Это означает, что операция всё ещё выполнялась, когда завершилось 900-секундное ожидание. Перед повторной попыткой проверьте:

dockup status production/api --json
dockup deployments production/api -n 5 --json

Если исходный деплой позднее завершился успешно, слепая повторная попытка создаст ещё один релиз. Если он завершился ошибкой, соберите лог сборки. Если операция всё ещё не достигла терминального состояния, а сборка действительно длительная, повторите наблюдение с увеличенным задокументированным тайм-аутом вместо создания второго деплоя.

Это различие не позволяет CI/CD для AI-агентов превращать неопределённость, связанную с сетью или временем выполнения, в дублирующие изменения production.

Фиксируйте идентификатор деплоя

Включайте в summary CI идентичность аккаунта Dockup, цель, SHA коммита, ID деплоя и терминальный статус. Эта небольшая запись позволяет оператору впоследствии связать запуск pipeline с событиями аудита Dockup, не раскрывая токен.

Переведите workflow в production

Установите CLI на runner, проверьте переданную идентичность и используйте терминальный код завершения, а не похожую на успешную строку лога, в качестве условия успешности pipeline.

npm install -g dockup-cli
dockup skill install

Первая команда устанавливает CLI. Вторая устанавливает соответствующий Dockup skill для Claude Code и Codex. Начните бесплатно на app.dockup.ai.

FAQ

Что такое DOCKUP_TOKEN?

DOCKUP_TOKEN — это способ аутентификации на основе переменной окружения для сессий Dockup CLI, в которых невозможно завершить интерактивный вход через браузер, включая CI runner, контейнеры и AI-агентов.

Имеет ли DOCKUP_TOKEN приоритет над локальным конфигурационным файлом Dockup?

Да. Токен из окружения имеет приоритет, а dockup whoami --json выводит активный источник токена.

Как CI-задача узнаёт, что деплой Dockup завершился ошибкой?

Запустите dockup deploy с --wait и --json. При ошибке или тайм-ауте команда завершается с ненулевым кодом и структурированным кодом ошибки.

Следует ли CI workflow выводить токен деплоя для отладки?

Нет. Храните его в хранилище секретов CI, отключайте трассировку shell-команд и вывод окружения и предоставляйте токен только шагу деплоя.

Могут ли Claude Code или Codex использовать тот же способ аутентификации CI?

Да. Оба могут использовать DOCKUP_TOKEN и bundled Dockup skill, который обучает тем же правилам работы с JSON, определения цели, ожидания и подтверждений.