Wdrożenie Codex: kompleksowy workflow w Dockup

Wdrożenie Codex powinno kończyć się dowodami, a nie założeniem, że wszystko się udało. Praktyczne wyzwanie nie polega na poproszeniu Codex o uruchomienie komendy wdrożeniowej, lecz na zapewnieniu agentowi interfejsu, który jednoznacznie identyfikuje docelową usługę, czeka na stan końcowy, zwraca rzeczywiste kody wyjścia i udostępnia szczegóły błędów bez użycia przeglądarki.

Dockup jest warstwą wdrożeniową dla tego workflow. Jego CLI zwraca Codex ustrukturyzowany JSON dla każdej obsługiwanej komendy, a dołączony skill uczy agenta, jak się uwierzytelniać, wyszukiwać usługi, wdrażać, diagnozować problemy i zatrzymywać się przed operacjami destrukcyjnymi.

Jak zainstalować skill Codex CLI?

Zainstaluj CLI globalnie, a następnie uruchom pojedynczy instalator skilla. Zapisze on kanoniczny skill i utworzy do niego linki zarówno w Claude Code, jak i Codex:

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

Kanoniczny skill znajduje się w ~/.agents/skills/dockup/, a jego link symboliczny jest tworzony w ~/.codex/skills/. Skill jest dostarczany wraz z dockup-cli, więc zwykła aktualizacja zmienia jednocześnie plik wykonywalny i instrukcje:

dockup update

Takie powiązanie wersji ma znaczenie przy dużej liczbie komend. Agent nigdy nie powinien wykonywać zapamiętanej flagi tylko dlatego, że pojawiła się w starym promptcie. Codex powinien korzystać z dołączonego skilla oraz aktualnej dokumentacji Dockup CLI jako źródła informacji o dostępnych komendach.

Uzasadnienie projektowe dotyczące skilli znajdziesz w artykule skills agentów a MCP.

Jak Codex uwierzytelnia się bez interaktywnego terminala?

Sandbox lub zadanie CI może nie mieć możliwości ukończenia logowania przez przeglądarkę. Ustaw token w środowisku procesu:

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

DOCKUP_TOKEN ma pierwszeństwo przed lokalnym plikiem konfiguracyjnym. Odpowiedź whoami informuje, czy aktywne dane uwierzytelniające pochodzą ze środowiska, czy z konfiguracji. Ułatwia to Codex diagnozowanie częstego przypadku, w którym współistnieją nieaktualny lokalny token i token CI.

Traktuj token jak sekret infrastruktury. Nie umieszczaj go w AGENTS.md, SKILL.md, systemie kontroli wersji, przykładach komend zatwierdzanych w repozytorium ani w końcowym transkrypcie agenta. W CI korzystaj z szyfrowanego magazynu sekretów platformy i udostępniaj wartość wyłącznie krokowi wdrożeniowemu. Pełny wzorzec trybu nieinteraktywnego opisano w artykule CI/CD z DOCKUP_TOKEN.

Zanim przyznasz Codex uprawnienia do zapisu, określ zakres jego uprawnień. Rozsądny początkowy zakres obejmuje wyszukiwanie usług, wdrażanie, odczyt logów i sprawdzanie statusu. Usuwanie baz danych, niszczenie usług, zmiany zespołu i czyszczenie konfiguracji powinny nadal wymagać zatwierdzenia.

Jak Codex znajduje lub tworzy właściwą usługę?

Wyszukiwanie powinno być pierwszą operacją. Nie proś Codex o przekształcenie nazwy „Payments API” w odgadnięty slug:

dockup services --json

Każdy wynik zawiera dokładne pole target w formacie project/service. Codex powinien kopiować tę wartość do kolejnych komend i zwracać ją w podsumowaniu.

Jeśli usługa nie istnieje, utwórz ją z repozytorium Git:

dockup create payments-api \
  --repo https://github.com/acme/payments-api \
  --project production \
  --branch main \
  --deploy \
  --wait \
  --link \
  --json

Komenda tworzy usługę, wdraża ją, czeka na rozstrzygnięcie wdrożenia i zapisuje link .dockup w katalogu roboczym. Jeśli w repozytorium znajduje się Dockerfile, zostanie on użyty; w przeciwnym razie Nixpacks automatycznie wykryje sposób budowania.

Gdy Codex utraci stan sesji lub workflow zostanie uruchomiony ponownie po przerwaniu połączenia sieciowego, powinien ponownie wyszukać usługi i sprawdzić dokładny target przed wykonaniem jakichkolwiek modyfikacji. Jeśli target już istnieje, należy kontynuować na podstawie jego statusu i historii wdrożeń, zamiast wysyłać kolejne żądanie utworzenia.

Pełna sekwencja zaczynająca się od repozytorium jest dostępna w artykule Od repozytorium Git do produkcji.

Jak Codex powinien przygotować konfigurację przed wdrożeniem?

Poproś Codex o sprawdzenie metadanych bieżącej usługi przed wprowadzeniem zmian:

dockup info production/payments-api --json
dockup env list -s production/payments-api --json

Odpowiedź dotycząca środowiska zawiera klucze i oznaczenia isSecret, a wartości sekretów pozostają zamaskowane. Codex może dodawać zwykłe zmienne i sekrety osobno:

dockup env set NODE_ENV=production \
  -s production/payments-api \
  --json

dockup env set STRIPE_SECRET_KEY="$STRIPE_SECRET_KEY" \
  --secret \
  -s production/payments-api \
  --json

Nigdy nie umieszczaj sekretu produkcyjnego w dockup.yaml; manifest nadaje się do przechowywania konfiguracji w postaci jawnej, którą można przeglądać, ale nie danych uwierzytelniających. Istniejące zmienne będące sekretami nie są nadpisywane ani usuwane przez workflow configuration-as-code.

Skonfiguruj port nasłuchiwania usługi i readiness check, gdy są znane:

dockup set production/payments-api --port 3000 --json
dockup health production/payments-api \
  --path /health \
  --interval 5 \
  --retries 5 \
  --json

Bramka gotowości sprawia, że weryfikacja produkcji ma rzeczywistą wartość. Platforma wykonuje wdrożenie blue-green i kieruje ruch do nowej wersji dopiero po spełnieniu przez nią wymagań bramki.

W jaki sposób weryfikacja produkcji potwierdza stan końcowy?

W przypadku istniejącej usługi użyj jednej komendy:

dockup deploy production/payments-api \
  --wait \
  --timeout 900 \
  --json

Jawnie określony timeout odpowiada domyślnej wartości 900 sekund i pokazuje intencję workflow. Kod wyjścia 0 oznacza powodzenie wdrożenia. Wynik różny od zera wraz ze statusem deploy_failed oznacza, że build lub wdrożenie zakończyły się niepowodzeniem. deploy_timeout oznacza, że po zakończeniu okresu oczekiwania operacja nadal nie osiągnęła stanu końcowego.

Prawidłowa logika rozgałęziania Codex powinna opierać się na statusie procesu:

Wynik	Działanie Codex
Kod wyjścia 0, status:"success"	Przejdź do weryfikacji health, uptime i security
deploy_failed	Odczytaj logi builda i znajdź pierwszy błąd, na podstawie którego można podjąć działanie
deploy_timeout	Zgłoś niepewność; sprawdź status lub ponów próbę z uzasadnionym timeoutem
not_logged_in	Zatrzymaj się i poproś o prawidłowy token
needs_confirm	Zatrzymaj się i poproś człowieka o zatwierdzenie

Po udanym wdrożeniu Codex zbierz obserwowalne dowody:

dockup status production/payments-api --json
dockup uptime production/payments-api --hours 24 --json
dockup security production/payments-api --json

Checki uptime są wykonywane co minutę i zawierają statystyki czasu odpowiedzi, takie jak p95. Wyniki security obejmują CVE obrazów i sprawdzenia konfiguracji. Sygnały te nie dowodzą poprawności biznesowej, dlatego Codex powinien również uruchomić własne smoke testy repozytorium, jeśli są dostępne.

Jak Codex powinien diagnozować i odzyskiwać działanie po nieudanym release?

Błędy builda i błędy środowiska uruchomieniowego wymagają różnych logów. Użyj najnowszego outputu builda, gdy wdrożenie nie doprowadziło jeszcze do uruchomienia kontenera:

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

Użyj logów środowiska uruchomieniowego, gdy obraz został zbudowany, ale aplikacja się zawiesza, nasłuchuje na niewłaściwym porcie lub kończy działanie po uruchomieniu:

dockup logs production/payments-api --json

Tryb follow jest przydatny podczas długiego builda:

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

W trybie JSON output trybu follow ma format NDJSON, dzięki czemu Codex może przetwarzać każdą partię w miarę jej napływania. Strumień kończy się po osiągnięciu terminalnego stanu wdrożenia i zachowuje rzeczywisty kod wyjścia błędu.

Odzyskiwanie działania należy rozpocząć od historii, a nie od zgadywania celu rollbacku:

dockup deployments production/payments-api -n 20 --json
dockup rollback <deploymentId> production/payments-api --json

Codex powinien wskazać znane udane wdrożenie, podać wybrane ID i zachować dowody błędu przed ponownym uruchomieniem. Nigdy nie powinien wybierać „drugiego elementu” bez sprawdzenia statusu i znaczników czasu.

Przydatny raport końcowy zawiera siedem pól: target, branch lub commit, ID wdrożenia, kod wyjścia, status końcowy, URL produkcyjny oraz kolejne działania. Taki format sprawia, że każde wdrożenie Codex można przeanalizować ręcznie lub w kolejnym kroku automatyzacji.

Zwięzły skrypt weryfikacyjny

Ten wzorzec shell utrzymuje wdrożenie i diagnozowanie w jednym przejrzystym przepływie sterowania:

if dockup deploy production/payments-api --wait --json > deploy-result.json; then
  dockup status production/payments-api --json
  dockup uptime production/payments-api --hours 24 --json
else
  dockup logs production/payments-api --build --json
  exit 1
fi

Skrypt nie wyszukuje komunikatu o powodzeniu za pomocą grep. Ufa kodowi wyjścia CLI, zachowuje JSON wdrożenia i kończy się błędem dla wywołującego zadania, gdy produkcja nie osiągnęła stanu powodzenia.

Spraw, aby ponowienia były obserwowalne, a nie niewidoczne

Sesje agentów mogą zostać przerwane po rozpoczęciu operacji, ale przed dotarciem wyniku do transkryptu. Kolejne uruchomienie Codex nie powinno bezrefleksyjnie powtarzać każdej mutacji. Powinno ponownie wyszukać usługę, sprawdzić najnowsze wdrożenie i ustalić, czy poprzednia operacja osiągnęła stan końcowy.

Runbook wdrożenia Codex powinien klasyfikować komendy jako bezpieczne do powtórzenia, bezpieczne dopiero po sprawdzeniu albo wymagające zatwierdzenia. Odczyty można bezpiecznie powtarzać. Utworzenie usługi wymaga wcześniejszego wyszukania. Nowe wdrożenie jest nowym zdarzeniem produkcyjnym i powinno zostać zapisane jako takie. Czyszczenie oraz inne działania destrukcyjne nadal pozostają decyzjami człowieka.

Oddziel weryfikację platformy od weryfikacji aplikacji

Dockup może potwierdzić, że build został ukończony, kontener osiągnął stan gotowości, a sondy wykonywane co minutę obserwują publicznie dostępną usługę. Codex powinien jednak nadal uruchamiać kontrole specyficzne dla aplikacji: publiczny endpoint health, uwierzytelnione żądanie testowe lub smoke test dostarczony przez repozytorium, który nie modyfikuje danych klientów.

Wynik końcowy powinien przedstawiać obie warstwy. „Wdrożenie platformy zakończyło się powodzeniem” i „smoke test aplikacji zakończył się powodzeniem” to różne stwierdzenia. Gdy dostępna jest tylko pierwsza informacja, Codex powinien to wyraźnie zaznaczyć, zamiast zamykać niepewność w postaci zielonego znacznika.

Potwierdź zakres zainstalowanych komend przed automatyzacją

Zadanie Codex przeznaczone do wielokrotnego użycia powinno rozpoczynać się od sprawdzenia dockup skill status --json i otwarcia aktualnej dokumentacji CLI, jeśli korzysta z mniej znanej opcji. Zapobiega to sytuacji, w której sesja wykonuje przykład napisany dla innego wydania.

Sprawdzenie jest szczególnie przydatne w efemerycznych runnerach, gdzie świeża globalna instalacja npm może różnić się od tej na laptopie dewelopera. Codex może zgłosić stan skilla przed wykonaniem pierwszego zapisu w produkcji, dzięki czemu zapis wdrożenia będzie odtwarzalny.

Przekazanie

Zachowaj dowody.

Zachowaj widoczny target

Zwróć dokładny target usługi w raporcie końcowym.

Zachowaj informację o źródle

Zapisz, czy Dockup użył Dockerfile repozytorium, czy Nixpacks. Ta informacja pomoże kolejnej sesji Codex wybrać właściwy log builda i zapobiegnie pomyleniu zmiany układu źródeł z incydentem platformy.

Zapisz również, czy automatyczne wdrożenie po pushu jest włączone. W przeciwnym razie ręczny release agenta i release uruchomiony przez push mogą się na siebie nałożyć i utworzyć dwa zdarzenia produkcyjne w ramach tego samego dochodzenia.

Wprowadź workflow na produkcję

Pierwsze wdrożenie Codex wykonaj na usłudze tymczasowej lub o niskim ryzyku, a następnie przenieś ten sam zweryfikowany kontrakt komend na produkcję.

npm install -g dockup-cli
dockup skill install

Pierwsza komenda instaluje CLI. Druga instaluje pasujący skill Dockup dla Claude Code i Codex. Zacznij za darmo na app.dockup.ai.

FAQ

Czy Codex może wdrożyć nowe repozytorium Git za pomocą jednej komendy?

Tak. dockup create może utworzyć usługę, wdrożyć ją, zaczekać na wynik końcowy i utworzyć link do bieżącego katalogu, gdy użyje się jej z --deploy, --wait i --link.

Jak Codex powinien uwierzytelnić się w Dockup?

Użyj DOCKUP_TOKEN w środowisku procesu i zweryfikuj go za pomocą dockup whoami --json. Pozwala to uniknąć interaktywnego logowania przez przeglądarkę w sandboxach i CI.

Co potwierdza, że wdrożenie Codex zakończyło się powodzeniem?

Komenda deploy musi zakończyć się kodem 0 po uruchomieniu z --wait, a jej JSON musi zawierać pomyślny status końcowy. Następnie uruchom status, uptime i smoke testy aplikacji.

Czy Codex może odczytywać sekrety produkcyjne z Dockup?

Nie. Wartości sekretów są zamaskowane w output. Codex może ustawić lub zastąpić sekret, ale nie otrzymuje zapisanej wartości podczas wyświetlania konfiguracji.

Co Codex powinien zrobić ze statusem needs_confirm?

Powinien się zatrzymać i poprosić o wyraźne zatwierdzenie przez człowieka. Błąd oznacza, że podjęto próbę wykonania destrukcyjnej komendy bez wymaganego potwierdzenia --yes.