CI/CD agentów AI z DOCKUP_TOKEN

CI/CD agentów AI działa poprawnie tylko wtedy, gdy uwierzytelnianie i wdrażanie przebiegają bez udziału osoby przy terminalu. Logowanie w przeglądarce, przepisywanie jednorazowych kodów i komunikaty o stanie wyrażone wyłącznie opisowo nie pasują do unattended runnera. Dockup obsługuje nieinteraktywny proces za pomocą DOCKUP_TOKEN, strukturyzowanego JSON-a oraz poleceń wdrażania, które zwracają rzeczywisty kod wyjścia oznaczający błąd.

W tym poradniku zbudujemy kontrakt pipeline’u, z którego może korzystać Claude Code, Codex, skrypt powłoki lub standardowe zadanie CI. Zasady są takie same: wstrzykuj token w czasie działania, zweryfikuj tożsamość, wykryj lub jawnie wskaż dokładny target, zaczekaj na stan końcowy i zachowaj diagnostykę w razie błędu.

Dlaczego CI/CD agentów AI wymaga nieinteraktywnego uwierzytelniania?

Interaktywne dockup login otwiera stronę uwierzytelniania i czeka na token. Jest to odpowiednie na stacji roboczej dewelopera, ale runner uruchomiony w kontenerze może nie mieć przeglądarki, trwałego katalogu domowego ani osoby, która mogłaby coś wkleić.

DOCKUP_TOKEN rozwiązuje ten problem:

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

Zmienna środowiskowa ma pierwszeństwo przed ~/.dockup/config.json. whoami raportuje tokenSource, dzięki czemu pipeline może potwierdzić, że korzysta z zamierzonego poświadczenia wstrzykniętego w czasie działania, a nie ze starego pliku konfiguracyjnego pozostawionego na self-hosted runnerze.

W CI nie uruchamiaj dockup login -t "$DOCKUP_TOKEN", chyba że istnieje konkretny powód, aby utrwalać plik konfiguracyjny. Bezpośrednie przekazanie zmiennej środowiskowej ogranicza zakres poświadczenia do procesu i zapobiega zapisaniu go w katalogu domowym runnera.

Pipeline nigdy nie może wypisywać tokenu. Wyłącz śledzenie poleceń powłoki wokół poleceń zawierających sekrety, nie wyświetlaj całego środowiska i korzystaj z mechanizmu maskowania sekretów udostępnianego przez platformę CI.

Jak przechowywać i ograniczać zakres DOCKUP_TOKEN?

Przechowuj token jako zaszyfrowany sekret repozytorium, środowiska lub organizacji. W przypadku produkcji preferuj sekret na poziomie środowiska, ponieważ można go połączyć z ograniczeniami dotyczącymi gałęzi i ręcznymi akceptacjami udostępnianymi przez platformę CI.

Bezpieczna polityka tokenów powinna odpowiadać na pięć pytań:

Pytanie	Zalecana odpowiedź
Gdzie jest przechowywany token?	Zaszyfrowany magazyn sekretów CI
Kiedy jest udostępniany?	Wyłącznie w zadaniu wdrożeniowym
Które gałęzie mogą go używać?	Chronione gałęzie produkcyjne
Kto może zmieniać workflow?	Zweryfikowani maintainerzy
Jak użycie jest weryfikowane?	Dziennik audytowy Dockup oraz historia zadań CI

Dockup obsługuje również klucze API z uprawnieniami. Przed utworzeniem klucza o wąskim zakresie wyświetl dostępne nazwy uprawnień:

dockup keys permissions --json

Wybierz wyłącznie dokładne nazwy uprawnień zwrócone przez platformę, a następnie utwórz klucz za pomocą workflow klucza API z uprawnieniami. Bezpiecznie zapisz wygenerowany klucz podczas tworzenia i przechowaj go natychmiast; nie umieszczaj go w issue, pull requeście ani transkrypcji agenta. Zadanie wdrożeniowe nie powinno dziedziczyć szerokich uprawnień administracyjnych do konta tylko dlatego, że token dewelopera je posiada.

Artykuł Zabezpieczenia produkcyjne dla agentów AI przedstawia szerszą drabinę uprawnień.

Jak zbudować pipeline wdrożeniowy, który czeka na rzeczywisty wynik?

Zainstaluj CLI w zadaniu, zweryfikuj tożsamość, a następnie wykonaj wdrożenie z --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

Najważniejszy nie jest dostawca CI, lecz kontrakt polecenia. dockup deploy ... --wait --json kończy się kodem 0 tylko wtedy, gdy wdrożenie osiągnie stan powodzenia. Domyślny limit czasu wynosi 900 sekund. Nieudany build zwraca niezerowy kod wyjścia z deploy_failed, a operacja, która po upływie limitu nie osiągnęła stanu końcowego, zwraca deploy_timeout.

Ponieważ proces kończy się kodem niezerowym, runner oznacza krok i zadanie jako nieudane. Nie trzeba analizować logów.

W przypadku połączonego repozytorium, które powinno wypchnąć bieżącą gałąź i wykonać wdrożenie, dockup push --json domyślnie czeka na zakończenie. W zadaniu CI, które otrzymało już zdarzenie Git push, jawne dockup deploy <target> jest często czytelniejsze, ponieważ pozwala uniknąć wypychania zmian z runnera.

Jak pipeline powinien przechwytywać logi i kody błędów?

Zachowaj wynik wdrożenia w formacie JSON jako artefakt lub output zadania, ale nie dopuść do tego, aby przekierowanie ukryło kod wyjścia. W powłoce można przechwycić oba elementy:

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 kończy się pierwotnym statusem wdrożenia. Logi buildu są zbierane dopiero po wystąpieniu błędu. Logi runtime należy zbierać wtedy, gdy obraz został zbudowany, ale aplikacja później ulega awarii:

dockup logs production/api --json

Aby obserwować build na żywo, użyj trybu follow, który emituje NDJSON:

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

Strumień kończy się wraz z wdrożeniem, a błąd nadal skutkuje niezerowym wynikiem procesu. Szczegółowa sekwencja diagnostyczna została opisana w artykule debugowanie logów buildu i runtime.

Pipeline powinien reagować na kody, a nie fragmenty komunikatów:

Kod	Reakcja pipeline’u
not_logged_in	Natychmiast przerwij; wstrzykiwanie sekretu nie działa
no_target	Przerwij; konfiguracja targetu jest nieprawidłowa
deploy_trigger_failed	Przerwij przed oczekiwaniem; sprawdź zwrócony błąd
deploy_failed	Prześlij logi buildu i przerwij z błędem
deploy_timeout	Oznacz stan jako niepewny; przed ponowieniem sprawdź status
needs_confirm	Zatrzymaj proces; operacja destrukcyjna nie ma akceptacji

Jak agent może uczestniczyć w procesie bez osłabiania bezpieczeństwa CI?

Agent może przygotować kod, zaktualizować zweryfikowany workflow, interpretować JSON i podsumować nieudany build. Nie potrzebuje jednak nieograniczonego dostępu do tokenu produkcyjnego podczas każdej sesji programistycznej.

Rozdziel role:

1. Agent deweloperski: lokalnie edytuje kod i uruchamia testy.
2. Proces przeglądu: weryfikuje zmiany w konfiguracji wdrożenia.
3. Runner CI: otrzymuje DOCKUP_TOKEN dopiero po zatwierdzonym wyzwoleniu.
4. Dockup: wykonuje wdrożenie i rejestruje zdarzenia audytowe.
5. Agent lub operator: interpretuje wynik i proponuje sposób przywrócenia działania.

Taki układ uniemożliwia prompt injection w niezwiązanym zadaniu uzyskanie poświadczeń produkcyjnych. Agent nadal może rozumieć pipeline, ponieważ polecenia i oczekiwany JSON są zapisane w repozytorium, a wartość sekretu pozostaje poza nim.

W przypadku wdrożeń uruchamianych bezpośrednio przez agenta wstrzyknij token do konkretnego procesu Claude Code lub Codex i zainstaluj dołączony skill:

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

Skill instruuje obu agentów, aby korzystali z nieinteraktywnego uwierzytelniania, JSON-a, dokładnego wykrywania targetu, oczekiwania na stan końcowy oraz bramek potwierdzeń.

Co sprawia, że CI/CD agentów AI jest powtarzalne i możliwe do audytowania?

Powtarzalność zaczyna się od jawnie określonego targetu. Przechowuj production/api jako chronioną zmienną pipeline’u lub zweryfikowaną wartość zapisaną w konfiguracji, a nie jako nazwę wyprowadzaną przez agenta w czasie działania. Zweryfikuj konto przed pierwszą operacją zapisu.

Idempotencja wymaga różnego podejścia zależnie od operacji:

• Odczytywanie tożsamości, statusu, logów i historii można bezpiecznie powtarzać.
• Tworzenie usługi musi zaczynać się od wykrycia targetu, aby ponowienia nie tworzyły duplikatu.
• Ponowne wdrożenie tworzy kolejne zdarzenie produkcyjne i powinno zostać zarejestrowane.
• Zmiany środowiska są mutacjami i wymagają ponownego wdrożenia.
• Niszczenie zasobów i pruning nie mogą być automatycznymi celami ponawiania.

Po wdrożeniu zbierz dowody z platformy:

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

Uptime jest mierzony co minutę i obejmuje średni czas odpowiedzi oraz p95. Dane audytowe łączą mutację wykonaną przez CI z późniejszym przeglądem. Zużycie CPU, RAM-u i miejsca na dysku również jest mierzone co minutę względem salda konta; zalecany plan Pro kosztuje 20 USD miesięcznie i obejmuje 20 USD kredytu na użycie.

Kompletny rekord pipeline’u zawiera commit Git, target Dockup, identyfikator wdrożenia, znaczniki czasu rozpoczęcia i zakończenia, kod wyjścia, status końcowy oraz odnośniki do artefaktów buildu. Dzięki temu wydanie CI/CD agentów AI można odtworzyć nawet wtedy, gdy pierwotna sesja agenta już nie istnieje.

Dokumentację Dockup CLI należy traktować jako źródło prawdy dotyczące poleceń. Aby utworzyć repozytorium przed włączeniem CI, postępuj zgodnie z poradnikiem Od repozytorium Git do produkcji.

Kontroluj współbieżność i promocję między środowiskami

Dwa udane pipeline’y mogą mimo wszystko utworzyć niebezpieczne wydanie, jeśli będą działać jednocześnie na tym samym targecie. Użyj mechanizmów kontroli współbieżności platformy CI, aby nowsze zadanie produkcyjne czekało na starsze albo celowo je zastępowało. Dockup zgodnie z prawdą zarejestruje każde wdrożenie, ale workflow repozytorium musi zdecydować, w jakiej kolejności traktować nakładające się commity.

Promuj między środowiskami ten sam zweryfikowany commit zamiast ponownie budować nieśledzony stan lokalny. Zadanie stagingowe może wdrożyć staging/api, uruchomić kontrole aplikacji, a następnie umożliwić chronionemu zadaniu produkcyjnemu wdrożenie production/api. Utrzymuj oddzielne tokeny i targety, aby agent stagingowy nie mógł przypadkowo przekroczyć tej granicy.

Zdefiniuj politykę ponawiania po przekroczeniu limitu czasu

deploy_timeout nie oznacza ani błędu, ani powodzenia. Oznacza, że operacja nadal trwała po upływie 900-sekundowego oczekiwania. Przed ponowieniem sprawdź:

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

Jeśli pierwotne wdrożenie zakończy się później powodzeniem, bezrefleksyjne ponowienie utworzy kolejne wydanie. Jeśli zakończyło się błędem, zbierz log buildu. Jeśli nadal nie osiągnęło stanu końcowego, a build jest uzasadnienie długi, ponów obserwację z większym, udokumentowanym limitem czasu zamiast tworzyć drugie wdrożenie.

To rozróżnienie zapobiega przekształcaniu przez CI/CD agentów AI niepewności związanej z siecią lub czasem w duplikaty zmian produkcyjnych.

Rejestruj tożsamość wdrożenia

W podsumowaniu CI umieść tożsamość konta Dockup, target, SHA commita, identyfikator wdrożenia i status końcowy. Ten niewielki rekord pozwala później połączyć wykonanie pipeline’u ze zdarzeniami audytowymi Dockup bez ujawniania tokenu.

Wprowadź workflow na produkcję

Zainstaluj CLI na runnerze, zweryfikuj wstrzykniętą tożsamość i spraw, aby bramką pipeline’u był końcowy status procesu, a nie log wyglądający na pomyślny.

npm install -g dockup-cli
dockup skill install

Pierwsze polecenie instaluje CLI. Drugie instaluje zgodny skill Dockup dla Claude Code i Codex. Zacznij bezpłatnie na stronie app.dockup.ai.

FAQ

Czym jest DOCKUP_TOKEN?

DOCKUP_TOKEN to oparte na zmiennej środowiskowej uwierzytelnianie dla sesji Dockup CLI, które nie mogą ukończyć interaktywnego logowania w przeglądarce, w tym dla runnerów CI, kontenerów i agentów AI.

Czy DOCKUP_TOKEN zastępuje lokalny plik konfiguracyjny Dockup?

Tak. Token ze zmiennej środowiskowej ma pierwszeństwo, a dockup whoami --json raportuje aktywne źródło tokenu.

Skąd zadanie CI wie, że wdrożenie Dockup zakończyło się błędem?

Uruchom dockup deploy z opcjami --wait i --json. Polecenie kończy się niezerowym kodem wyjścia oraz strukturyzowanym kodem błędu, gdy wdrożenie zakończy się niepowodzeniem lub przekroczy limit czasu.

Czy workflow CI powinien wypisywać token wdrożeniowy na potrzeby debugowania?

Nie. Przechowuj go w magazynie sekretów CI, unikaj śledzenia poleceń powłoki i zrzutów środowiska oraz udostępniaj go wyłącznie krokowi wdrożeniowemu.

Czy Claude Code lub Codex mogą korzystać z tej samej ścieżki uwierzytelniania CI?

Tak. Oba narzędzia mogą korzystać z DOCKUP_TOKEN i dołączonego skilla Dockup, który uczy tych samych zasad dotyczących JSON-a, wykrywania targetu, oczekiwania i potwierdzeń.