AI Agent CI/CD із DOCKUP_TOKEN

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

У цьому посібнику ми створимо контракт pipeline, яким можуть користуватися Claude Code, Codex, shell-скрипт або звичайне CI-завдання. Правила однакові: передавати token під час виконання, перевіряти identity, знаходити або явно вказувати точний target, чекати на terminal result і зберігати діагностику в разі помилки.

Навіщо AI agent CI/CD потрібна неінтерактивна автентифікація?

Інтерактивна команда dockup login відкриває сторінку автентифікації та очікує на token. Для робочої станції розробника це нормально, але containerized runner може не мати браузера, постійної домашньої директорії або людини, яка вставить потрібне значення.

DOCKUP_TOKEN усуває цю проблему:

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

Змінна середовища має пріоритет над ~/.dockup/config.json. whoami повідомляє tokenSource, тож pipeline може підтвердити, що використовує потрібні injected credentials, а не старий config file, який випадково залишився на self-hosted runner.

Не запускайте dockup login -t "$DOCKUP_TOKEN" у CI, якщо немає конкретної причини зберігати config file. Безпосередня передача змінної середовища обмежує credential межами процесу й не дає записати його до домашньої директорії runner.

Pipeline ніколи не повинен виводити token. Вимикайте shell tracing навколо команд, що працюють із секретами, не друкуйте все середовище та використовуйте функцію маскування секретів, яку надає CI-платформа.

Як зберігати та обмежувати DOCKUP_TOKEN?

Зберігайте token як encrypted repository, environment або organization secret. Для production краще використовувати environment-level secret, оскільки його можна поєднати з обмеженнями для branch і ручними approvals, які надає CI-платформа.

Безпечна політика роботи з token має відповідати на п’ять запитань:

Запитання	Рекомендована відповідь
Де зберігається token?	CI encrypted secret store
Коли він доступний?	Лише в deployment job
Які branch можуть його використовувати?	Protected production branches
Хто може змінювати workflow?	Maintainers, чиї зміни пройшли review
Як перевіряється його використання?	Dockup audit log і CI job history

Dockup також підтримує permissioned API keys. Перед створенням key з обмеженими правами перегляньте доступні назви permissions:

dockup keys permissions --json

Вибирайте лише точні назви permissions, які повертає платформа, а потім створюйте key через permissioned API-key workflow. Надійно перехопіть згенерований key під час створення та негайно збережіть його; не додавайте його в issue, pull request або transcript агента. Deployment job не повинен автоматично отримувати широкі права адміністрування account лише тому, що їх уже має token розробника.

У статті AI agent production guardrails описано ширшу ladder permissions.

Як побудувати deployment pipeline, який очікує на фактичний результат?

Встановіть CLI у job, перевірте identity, а потім виконайте деплой із --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 vendor, а контракт команд. dockup deploy ... --wait --json завершується з кодом 0 лише тоді, коли deployment досягає успішного результату. Timeout за замовчуванням становить 900 секунд. Невдалий build повертає ненульовий код завершення з deploy_failed, а non-terminal operation після timeout — deploy_timeout.

Оскільки процес завершується з ненульовим кодом, runner позначає step і job як failed. Аналізувати логи не потрібно.

Для linked repository, який має виконати push поточної branch і деплой, dockup push --json за замовчуванням очікує на завершення. У CI job, що вже отримав подію Git push, явний dockup deploy <target> часто зрозуміліший, оскільки runner не виконує push.

Як pipeline має зберігати логи та коди помилок?

Зберігайте JSON-результат deployment як artifact або job output, але не допускайте, щоб перенаправлення приховало exit status. 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 завершується з початковим deploy status. Build logs збираються лише після помилки. Runtime logs потрібно збирати, коли image успішно зібрано, але застосунок згодом аварійно завершується:

dockup logs production/api --json

Для перегляду build у реальному часі follow mode виводить NDJSON:

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

Stream завершується разом із deployment, а помилка й надалі призводить до ненульового результату процесу. Детальну послідовність діагностики описано в матеріалі debugging build and runtime logs.

Pipeline має приймати рішення на основі codes, а не фрагментів повідомлень:

Code	Реакція pipeline
not_logged_in	Негайно завершити з помилкою; injection secret зламано
no_target	Завершити з помилкою; конфігурація target недійсна
deploy_trigger_failed	Завершити до очікування; перевірити повернуту помилку
deploy_failed	Завантажити build logs і завершити з помилкою
deploy_timeout	Позначити результат як невизначений; перевірити status перед повторною спробою
needs_confirm	Зупинитися; destructive step не має approval

Як агент може брати участь у роботі, не послаблюючи безпеку CI?

Агент може підготувати code, оновити workflow, який пройшов review, інтерпретувати JSON і підсумувати failed build. Йому не потрібен необмежений доступ до production token під час кожної coding session.

Розділіть ролі:

1. Development agent: редагує code і локально запускає tests.
2. Review process: перевіряє зміни в deployment configuration.
3. CI runner: отримує DOCKUP_TOKEN лише після approved trigger.
4. Dockup: виконує deployment і записує audit events.
5. Agent або operator: інтерпретує результат і пропонує відновлення.

Такий підхід не дає prompt injection у сторонньому завданні отримати production credentials. Агент усе одно може розуміти pipeline, оскільки commands і очікуваний JSON зберігаються в repository, а значення secret залишається за його межами.

Для deployment, який безпосередньо запускає агент, передайте token конкретному процесу Claude Code або Codex і встановіть bundled skill:

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

Skill вказує обом агентам використовувати non-interactive authentication, JSON, exact target discovery, terminal-state waiting і confirmation gates.

Що робить AI agent CI/CD повторюваним і придатним до аудиту?

Повторюваність починається з explicit target. Зберігайте production/api як protected pipeline variable або literal, що пройшов review, а не як name, який агент визначає під час виконання. Перевірте account до першого write operation.

Idempotency потребує різного підходу до різних операцій:

• Повторювати читання identity, status, logs і history безпечно.
• Створення service має починатися з target discovery, щоб retry не створив duplicate.
• Повторний deploy створює ще одну production event, і це має бути записано.
• Зміни environment є mutations і потребують redeploy.
• Destruction і pruning не повинні бути цілями для automatic retry.

Після deployment збирайте platform evidence:

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

Uptime вимірюється щохвилини та містить average і p95 response time. Audit output пов’язує CI mutation із подальшим review. CPU, RAM і disk consumption також вимірюються щохвилини та враховуються в балансі account; рекомендований Pro plan коштує $20 на місяць і містить $20 usage credit.

Повний запис pipeline містить Git commit, Dockup target, deployment ID, час початку й завершення, exit code, terminal status і links на build artifacts. Завдяки цьому реліз AI agent CI/CD залишається відтворюваним, навіть якщо початкова сесія агента вже завершилася.

Dockup CLI reference слід вважати авторитетним джерелом щодо команд. Щоб створити repository до ввімкнення CI, скористайтеся посібником Git repository to production.

Керуйте concurrency і promotion між environment

Навіть два успішні pipeline можуть створити небезпечний реліз, якщо вони одночасно працюють з одним target. Використовуйте concurrency controls CI-платформи, щоб новий production job або очікував на завершення старого, або навмисно замінював його. Dockup правдиво повідомить про кожен deployment, але workflow repository має визначити порядок обробки commit, що перетинаються.

Переміщуйте між environment той самий reviewed commit, а не перебудову непідконтрольного local state. Staging job може виконати deploy staging/api, запустити application checks, а потім дозволити protected production job виконати deploy production/api. Розділяйте tokens і targets, щоб staging agent випадково не перетнув цю межу.

Визначте політику retry для timeout

deploy_timeout не означає ані failure, ані success. Це означає, що operation усе ще виконувалася після завершення 900-секундного очікування. Перед retry перевірте:

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

Якщо початковий deployment згодом досяг success, blind retry створить ще один release. Якщо він failed, зберіть build log. Якщо operation залишається non-terminal, а build справді тривалий, повторіть observation із більшим задокументованим timeout, а не створюйте другий deployment.

Ця відмінність не дає AI agent CI/CD перетворити мережеву або часову невизначеність на дублікати production changes.

Записуйте identity deployment

Додавайте до CI summary account identity Dockup, target, commit SHA, deployment ID і terminal status. Цього невеликого запису достатньо, щоб пізніше пов’язати pipeline run з audit events у Dockup, не розкриваючи token.

Виведіть workflow у production

Встановіть CLI на runner, перевірте injected identity і зробіть terminal exit status — а не рядок у логах, що виглядає як повідомлення про успіх — gate для 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 runners, containers і AI agents.

Чи має DOCKUP_TOKEN пріоритет над локальним config file Dockup?

Так. Environment token має пріоритет, а dockup whoami --json повідомляє активне джерело token.

Як CI job дізнається, що deployment Dockup завершився помилкою?

Запустіть dockup deploy з --wait і --json. Команда завершується з ненульовим кодом і structured failure code, якщо deploy завершився помилкою або timeout.

Чи повинен CI workflow виводити deployment token для debugging?

Ні. Зберігайте його в CI secret store, не використовуйте shell tracing і environment dumps та надавайте його доступ лише deployment step.

Чи можуть Claude Code або Codex використовувати той самий шлях автентифікації CI?

Так. Обидва можуть використовувати DOCKUP_TOKEN і bundled Dockup skill, який навчає тих самих правил щодо JSON, target discovery, wait і confirmation.