Przejdź do głównej zawartości

Deploy: recenzuj w obie strony, bramkuj produkcję

Etap deploy uruchamia recenzję agenta na każdym pull requeście, pozwala agentowi-autorowi poprawić własne uwagi z review i trzyma merge oraz produkcję za kontrolami, które działają poza modelem: ochroną gałęzi z code ownerem, środowiskiem wdrożeniowym z wymaganymi zatwierdzającymi i poświadczeniami do wdrożenia, których agent nigdy nie dostaje. Hooki agenta tylko wcześnie wyłapują pomyłki.

W zeszłym tygodniu twoi agenci otworzyli więcej pull requestów, niż zespół był w stanie przeczytać. Dwa czekały trzy dni na recenzenta, a jeden trafił do maina po pobieżnym przejrzeniu i w sobotę obudził kogoś alertem. Ta strona jest dla dewelopera, który wpina recenzję agenta w repozytorium, i dla tech leada, który odpowiada za bramki merge’a i wydania.

„Recenzja w obie strony” oznacza dwie pętle. Przychodząca: agent recenzujący sprawdza każdy PR w ten sam sposób i szereguje to, co znalazł. Wychodząca: agent, który napisał PR, przechodzi przez wątki review, aż zostaje wyłącznie decyzja człowieka. Uwaga ludzi przesuwa się poziom wyżej: czy zmiana robi to, co zakładał spec.md, i czy ryzyko jest akceptowalne?

  • Recenzję agenta na każdym PR-ze, z uwagami szeregowanymi według tego samego REVIEW.md w każdym przebiegu zarządzanym lub w CI.
  • Krok CI, który blokuje merge, gdy recenzja zgłosi uwagę Important.
  • Dwa prompty do skopiowania: jeden recenzuje gałąź względem specyfikacji przed pushem, drugi przechodzi przez nierozwiązane wątki review na własnym PR-ze agenta.
  • Bramkę produkcyjną zbudowaną z ochrony gałęzi, środowiska wdrożeniowego i zawężonych poświadczeń, w której hooki agenta są wczesnym ostrzeżeniem, a nie zamkiem.
  • Tabelę dla każdego środowiska, która mówi, jak daleko agent może się posunąć lokalnie, na stagingu i na produkcji.
  • Dowody z testów z etapu Test. Recenzja szereguje uwagi; nie zastępuje pętli testów, która zamyka się przy błędzie.
  • Pakiet dowodów na każdym PR-ze agenta: link do specyfikacji, wynik testów, klasa ryzyka i dotknięte wrażliwe ścieżki. Zarówno recenzent, jak i człowiek czytają pakiet przed diffem.
  • Ochronę domyślnej gałęzi, która wymaga pull requesta, zielonych checków i akceptacji code ownera wpisanego w CODEOWNERS.
  • Imiennie wskazanego właściciela wydania na produkcję oraz klasy ryzyka z polityki governance, które rozstrzygają, które zmiany wymagają człowieka poza code ownerem.

Zacznij od jednego recenzenta na repozytorium: z naszego doświadczenia drugi recenzent na tym samym PR-ze dokłada wątki szybciej niż nowe, odrębne znaleziska.

Zarządzany Code Review to najszybszy start: Owner włącza go dla organizacji, a każde repozytorium wybiera wyzwalacz (raz po utworzeniu PR-a, po każdym pushu albo ręcznie). To research preview dla planów Team i Enterprise, niedostępne dla organizacji z Zero Data Retention, a dokumentacja Anthropic podaje, że każda recenzja „averages $15-25” w kredytach użycia (sprawdzone 2026-09-26). Komentarz @claude review na PR-ze zleca jedną recenzję na żądanie, a @claude review always subskrybuje PR do recenzji przy kolejnych pushach.

Code Review publikuje komentarze inline oznaczone jako Important lub Nit i wypełnia check run o nazwie Claude Code Review. Ten check zawsze kończy się wynikiem neutralnym, więc sam z siebie nigdy nie blokuje merge’a. Następna sekcja zamienia go w bramkę.

We własnym CI (potrzebne przy Amazon Bedrock, Agent Platform w Google Cloud (dawniej Vertex AI), Microsoft Foundry albo w organizacji z ZDR) uruchom plugin code-review przez anthropics/claude-code-action@v1:

.github/workflows/claude-review.yml
name: Code Review
on:
pull_request:
types: [opened, synchronize, ready_for_review, reopened]
jobs:
review:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: read
issues: read
id-token: write
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
fetch-depth: 1
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
plugins: "code-review@claude-code-plugins"
prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

Zostaw linię claude_args: akcja uruchamia serwer komentarzy inline tylko wtedy, gdy --allowedTools go wymienia. U dostawcy chmurowego ustaw use_bedrock, use_vertex albo use_foundry na "true" zamiast klucza API. Plugin pomija PR, na którym Claude już zostawił komentarz, więc kolejne pushe nie dostają ponownej recenzji; jeśli jej potrzebujesz, użyj zarządzanego Code Review z wyzwalaczem po każdym pushu. Przed pushem uruchom poniższy prompt recenzji, który czyta REVIEW.md; lokalne /code-review go nie czyta (sprawdzone w v2.1.283).

Strony poszczególnych narzędzi wchodzą głębiej: automatyzacja recenzji w Claude Code, code review w Codeksie i Bugbot.

Napisz REVIEW.md, żeby każdy przebieg szeregował uwagi tak samo

Dział zatytułowany „Napisz REVIEW.md, żeby każdy przebieg szeregował uwagi tak samo”

Agent recenzujący bez spisanej polityki zgłasza to, co preferują jego ustawienia domyślne, więc dwa przebiegi na podobnych PR-ach nie zgadzają się co do tego, co ważne. Zapisz politykę w jednym pliku w katalogu głównym repozytorium. Zarządzany Code Review w Claude Code czyta REVIEW.md bezpośrednio; workflow Codeksa powyżej wskazuje go w prompcie; dla @codex review skopiuj reguły do AGENTS.md.

# Review instructions
## Passes
Run three passes and tag each finding with its pass:
- Bugs: logic errors, broken edge cases, subtle regressions
- Security: injection, authentication and authorization gaps, secrets or PII in logs
- Compliance: the change matches spec.md and plan.md for this PR; flag any
behaviour the spec does not mention
## What Important means here
Reserve Important for findings that would break behaviour, leak data,
or breach a policy. Style, naming and refactoring suggestions are Nit at most.
## Cap the nits
Report at most five nits per review; mention the rest as a count in the summary.
## Re-reviews
After the first review of a PR, report Important findings only.
## Do not report
Generated files under src/gen/, lockfiles, and anything CI already enforces
(formatting, lint, type errors).

Reguła ponownych recenzji zaczyna mieć znaczenie, gdy agent-autor wypycha poprawki: bez niej każdy commit z poprawką zaprasza nową rundę nitów i PR nigdy się nie domyka.

Uwagi z recenzji same niczego nie zatwierdzają ani nie blokują. Akceptacją pozostaje ludzki code owner. Dodaj wymagany check, który nie przechodzi, gdy recenzja zgłosi uwagę Important, żeby code owner nigdy nie dostał PR-a z otwartym błędem, który recenzent już znalazł.

W zarządzanym review Claude Code ostatnia linia wyniku check runu zawiera liczniki według ważności w formacie do odczytu maszynowego. Ten skrypt odczytuje je dla jednego commita i kończy się błędem, gdy otwarta jest choć jedna uwaga Important:

#!/bin/bash
# .github/scripts/claude-review-gate.sh HEAD_SHA (needs gh and jq; GH_TOKEN set)
set -euo pipefail
SHA="$1"
ID=$(gh api "repos/$GITHUB_REPOSITORY/commits/$SHA/check-runs" \
--jq '.check_runs[] | select(.name == "Claude Code Review") | .id' | head -n1)
[ -n "$ID" ] || { echo "No Claude Code Review check run for $SHA" >&2; exit 1; }
COUNTS=$(gh api "repos/$GITHUB_REPOSITORY/check-runs/$ID" \
--jq '.output.text | split("bughunter-severity: ")[1] | split(" -->")[0] | fromjson') \
|| { echo "No severity counts: the review failed or timed out. Comment '@claude review' to re-run it." >&2; exit 1; }
IMPORTANT=$(echo "$COUNTS" | jq '.normal')
echo "Review severity counts: $COUNTS"
if [ "$IMPORTANT" -gt 0 ]; then
echo "Blocked: $IMPORTANT Important finding(s). Fix them or record why each one is wrong." >&2
exit 1
fi

Klucz normal to liczba uwag Important; nit i pre_existing nigdy nie zatrzymują bramki.

Uruchamiaj go z workflow, który startuje po zakończeniu check runu Claude Code Review. Workflow check_run działa na gałęzi domyślnej, więc jego własny job nigdy nie trafia na head commit PR-a. Dlatego job publikuje status commita na zrecenzowanym SHA:

.github/workflows/claude-review-gate.yml
name: Claude review gate
on:
check_run:
types: [completed]
jobs:
gate:
if: github.event.check_run.name == 'Claude Code Review'
runs-on: ubuntu-latest
permissions:
contents: read
checks: read
statuses: write
steps:
- uses: actions/checkout@v7 # default branch: the gate script never comes from the PR
with:
persist-credentials: false
- env:
GH_TOKEN: ${{ github.token }}
SHA: ${{ github.event.check_run.head_sha }}
run: |
if bash .github/scripts/claude-review-gate.sh "$SHA"; then STATE=success; else STATE=failure; fi
gh api "repos/$GITHUB_REPOSITORY/statuses/$SHA" \
-f state="$STATE" -f context=claude-review-gate \
-f description="Important findings from Claude Code Review"

W ochronie gałęzi ustaw claude-review-gate jako wymagany status check. Bramka potrzebuje recenzji każdego head commita, więc ustaw w repozytorium wyzwalacz After every push albo skomentuj PR poleceniem @claude review always. Przy Once after PR creation lub Manual commity z poprawkami od agenta-autora nie dostają recenzji i wymagany status nigdy się nie pojawia. PR-y z forków nigdy nie są recenzowane ponownie po pushu, więc każdy nowy head commit na PR-ze z forka potrzebuje świeżego komentarza @claude review, zanim bramka przepuści zmianę. Nieudana lub przerwana po limicie czasu recenzja nie ma linii z licznikami, więc bramka zamyka się bezpiecznie (fail closed); skomentuj @claude review, żeby uruchomić recenzję ponownie (dokumentacja Code Review Anthropic, sprawdzone 2026-09-26).

W Codeksie niech recenzja zwraca werdykt do odczytu maszynowego w tym samym duchu (na przykład codex exec --output-schema ze schematem JSON zawierającym licznik important) i bramkuj na nim. Dla Bugbota użyj bramki z code ownerem opisanej w zakładce Cursor powyżej.

Pozwól agentowi-autorowi zamknąć własne wątki review

Dział zatytułowany „Pozwól agentowi-autorowi zamknąć własne wątki review”

Pętla wychodząca zabiera ludziom czas przy każdym PR-ze: recenzent zostawia sześć komentarzy, a autor spędza nad nimi popołudnie. Przekaż to agentowi, który napisał PR, z twardą regułą: może wypychać commity, ale nigdy nie zatwierdza, nie merguje i nie odrzuca recenzji.

Z zainstalowanym workflow wzmianek anthropics/claude-code-action@v1 (konfiguruje go /install-github-app) skomentuj PR, wpisując @claude i prośbę; Claude odpowiada w wątku i może wypchnąć commit z poprawką. Odpowiedź na komentarz zarządzanego Code Review niczego nie uruchamia: wypchnij poprawkę, a recenzja wyzwalana pushem rozwiąże wątek. Lokalnie uruchom poniższy prompt w worktree PR-a.

Jeśli agent ma czytać wątki przez API, a nie przez gh, GitHub MCP Server udostępnia wątki review w pull requestach, odpowiedzi i rozwiązywanie wątków jako narzędzia. Załaduj tylko jego toolset pull_requests przez ścieżkę URL:

Okno terminala
claude mcp add -s project --transport http github https://api.githubcopilot.com/mcp/x/pull_requests \
-H 'Authorization: Bearer ${GITHUB_PAT}'

Każda konfiguracja czyta token ze zmiennej środowiskowej GITHUB_PAT, zamiast trzymać go w pliku; dokumentacja MCP Cursora opisuje zapis ${env:NAME}, więc sprawdź, czy rozwija się w twojej wersji. Koszt kontekstu: każde narzędzie z załadowanego toolsetu dodaje swoją definicję do sesji, więc jeden toolset utrzymuje go na niskim poziomie, a gh z powłoki kosztuje jeszcze mniej tokenów. O tym, co serwer może zrobić, decyduje token, więc zawęź go do tego jednego repozytorium, a prawo zapisu do pull requestów daj tylko sesji, która musi odpowiadać w wątkach.

Dwa ustawienia utrzymują tę pętlę w ryzach. Na GitHubie wyłącz Allow GitHub Actions to create and approve pull requests, żeby token workflow nie mógł niczego zatwierdzić. I daj agentowi własną tożsamość, żeby historia PR-a pokazywała, które commity wypchnął agent, a które człowiek: zobacz tożsamość agenta i sekrety.

Gdy recenzja drugi raz wskazuje ten sam błąd, poprawka obejmuje też linię w CLAUDE.md, AGENTS.md albo w Cursor Rules, żeby następna sesja budowania go nie powtórzyła. To krawędź sprzężenia zwrotnego z powrotem do etapu Build.

Agent może działać aż do bramki produkcji i nie może jej przejść. Trzyma ta bramka, której agent nie może edytować, przeformułować ani obejść perswazją. Zbuduj ją warstwami, od najsilniejszej:

WarstwaCo wymuszaDlaczego agent jej nie przejdzie
Ochrona gałęzi i CODEOWNERSKażda zmiana przychodzi jako PR; zatwierdza ją ludzki code ownerToken agenta nie ma prawa akceptacji, a wymagane checki działają w CI
Środowisko wdrożeniowe z wymaganymi zatwierdzającymiImiennie wskazany właściciel wydania zatwierdza każde uruchomienie na produkcjiAkceptacja odbywa się na platformie CI, poza jakąkolwiek sesją agenta
Poświadczenia do wdrożenia przypisane do środowiskaWdrożyć może tylko zatwierdzony job produkcyjnyJoby i sesje agenta nigdy nie dostają tego poświadczenia
Hooki agenta i ustawienia zarządzanePolecenie wdrożenia wpisane w sesji zostaje odrzucone z uzasadnieniemTylko wczesne ostrzeżenie: dopasowuje tekst polecenia, nie intencję

W GitHub Actions bramkę niesie środowisko. Skonfiguruj wymaganych zatwierdzających i Prevent self-review w Settings › Environments › production, a token do wdrożenia zapisz jako sekret środowiska, który job dostaje dopiero po akceptacji:

# .github/workflows/deploy.yml (excerpt)
jobs:
deploy-production:
needs: [build, test]
runs-on: ubuntu-latest
environment: production # required reviewers approve here
permissions:
contents: read
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
- run: ./scripts/deploy.sh production
env:
DEPLOY_TOKEN: ${{ secrets.PROD_DEPLOY_TOKEN }} # environment secret, not a repository secret

Hook dołóż na końcu jako wczesne ostrzeżenie. Odrzuca wdrożenie produkcyjne wpisane w sesji i podpowiada agentowi drogę, która działa:

Zarejestruj skrypt jako hook PreToolUse z matcherem Bash w .claude/settings.json, tak jak na stronie Build, albo w ustawieniach zarządzanych, żeby inżynierowie nie mogli go wyłączyć (allowManagedHooksOnly ogranicza maszynę do hooków zarządzanych).

#!/bin/bash
# .claude/hooks/production-gate.sh (chmod +x; needs jq)
CMD=$(jq -r '.tool_input.command // empty')
if echo "$CMD" | grep -Eqi '(deploy|release|promote).*(prod|production)'; then
jq -n '{hookSpecificOutput: {
hookEventName: "PreToolUse",
permissionDecision: "deny",
permissionDecisionReason: "Production deploys run only through the release pipeline. Update the PR and its evidence bundle; the release owner promotes it."
}}'
fi
exit 0

deny pokazuje uzasadnienie Claude’owi, więc zmienia on kurs, zamiast ponawiać próbę. Na stagingu zwróć zamiast tego "ask": wymusza to prośbę o potwierdzenie nawet w trybie auto. Pamiętaj jednak, kto na nią odpowiada: deweloper przy klawiaturze, a nie właściciel wydania. W przebiegach claude -p nikt nie odpowie, więc ask w praktyce staje się odmową.

Bramka akceptacji produkcji szczegółowo opisuje konfigurację środowiska, a uprawnienia i sandboksy omawiają kontrole po stronie sesji we wszystkich trzech narzędziach.

  1. Zacznij od kroków, które tylko oceniają i niczego nie zapisują. Diagnoza nieudanego builda, podsumowanie niestabilnego testu, szkic release notes. Przekaż dowody na wejście; agent nie potrzebuje narzędzi, żeby je przeczytać:

    Okno terminala
    # CI, after a failed run
    gh run view "$RUN_ID" --log-failed | claude -p --bare --setting-sources "" --strict-mcp-config "Triage this failed build: root cause, the file to change, and whether it is flaky. Do not propose a retry unless the log proves a transient failure." --output-format json
    gh run view "$RUN_ID" --log-failed | codex exec -c default_permissions=":read-only" "Triage this failed build: root cause, the file to change, and whether it is flaky."

    Codex dołącza wejście z potoku do promptu jako blok <stdin>. Nieudany przebieg mógł budować gałąź kontrybutora, więc wywołanie claude nie ładuje z checkoutu żadnych ustawień projektu, hooków ani serwerów MCP (--bare --setting-sources "" --strict-mcp-config), a żadne z wywołań nie dostaje tokenu z prawem zapisu.

  2. Dodawaj kroki zapisujące za istniejącymi bramkami. Poprawki lintera, regenerowanie dokumentacji i odpowiedzi na uwagi z review kończą się commitami na gałęzi PR-a. Agent nie ma drogi do pushowania na domyślną gałąź.

  3. Izoluj każdy job agenta. Kontenery, polityka sieciowa, krótkotrwałe tokeny zawężone do jednego repozytorium i żadnych stałych poświadczeń produkcyjnych. W openai/codex-action zostaw domyślne safety-strategy: drop-sudo i wybieraj profil uprawnień zamiast starszego wejścia sandbox.

  4. Udostępnij wdrożenie, status i rollback jako zawężone narzędzia. Gdy agent musi działać na środowisku, daj mu serwer MCP albo nakładkę CLI dla każdego środowiska osobno, żeby możliwość wdrażania była allowlistą, a nie powłoką. Gdy wdrożenia działają jako workflowy GitHub Actions, toolset actions serwera GitHub MCP w trybie tylko do odczytu (https://api.githubcopilot.com/mcp/x/actions/readonly) pozwala agentowi czytać status i logi uruchomień bez możliwości startowania nowych.

  5. Ćwicz rollback na stagingu, aż stanie się jednym poleceniem. Etap Maintain wywołuje tę ścieżkę, gdy przekroczony zostanie próg kontrolny, a pipeline rollbacku pokazuje, jak ją zbudować. Wdrażaj etapami dzięki progressive delivery, żeby zła zmiana najpierw trafiła do części ruchu.

To, jak daleko agent może się posunąć, zależy od środowiska:

ŚrodowiskoAgent możeBramka
Lokalne lub sandbox na zadanieWykonać całą procedurę wdrożenia z zawężonymi, krótkotrwałymi poświadczeniamiGranica sandboksa
StagingUruchomić wdrożenie przez pipeline i smoke testyChecki pipeline’u; ask z hooka w sesjach interaktywnych
ProdukcjaPrzygotować dowody, otworzyć PR wydania, napisać szkic changeloguAkceptacja środowiska przez właściciela wydania; poświadczenia tylko w zatwierdzonym jobie

Skąd wiesz, że etap deploy działa, bez czytania każdego diffa?

Dział zatytułowany „Skąd wiesz, że etap deploy działa, bez czytania każdego diffa?”

Testuj bramki tak, jak włamywacz testuje zamek: raz, celowo, i ponownie po każdej zmianie w pipelinie:

  • Otwórz PR z gałęzi agenta. Pojawia się check run recenzji, a uwagi przychodzą jako komentarze inline.
  • Podrzuć znany błąd (niezabezpieczony null, brak sprawdzenia autoryzacji). Recenzja zgłasza go jako Important, a bramka merge’a nie przechodzi.
  • Spróbuj zmergować bez akceptacji code ownera. Ochrona gałęzi odmawia.
  • Poproś agenta o wdrożenie na produkcję. Hook odmawia z uzasadnieniem, a joby agenta i tak nie mają poświadczenia produkcyjnego.
  • Uruchom job produkcyjny samodzielnie. Czeka na właściciela wydania, a osoba, która go uruchomiła, nie może go zatwierdzić.

Potem obserwuj pętlę w czasie. Wskaźniki wyprzedzające: czas do pierwszej recenzji i odsetek wątków review, które agent-autor zamknął bez commita człowieka. Wskaźniki opóźnione: defekty i podatności złapane przed merge’em w porównaniu z tymi, które uciekły na produkcję, oraz change failure rate i czas przywrócenia usługi, które twoje CI i narzędzia do incydentów już rejestrują. Metryki AI-native SDLC definiują je dla każdego etapu.

Co psuje się w recenzji agentów i bramkach wydania — i jak to naprawić

Dział zatytułowany „Co psuje się w recenzji agentów i bramkach wydania — i jak to naprawić”
ObjawPrzyczynaNaprawa
Recenzje zasypują zespół nitamiBrak polityki ważności, brak limituDodaj do REVIEW.md definicję Important, limit nitów i regułę ponownych recenzji; wyklucz generowane ścieżki
PR został zmergowany z otwartą uwagą ImportantCheck recenzji jest neutralny i nikt na nim nie bramkowałZrób z bramki ważności wymagany check
PR-y z forków nie dostają recenzjiSekrety nie trafiają do przebiegów z forków; zarządzany Code Review recenzuje forki tylko po @claude reviewKomentuj @claude review na PR-ach z forków albo recenzuj je w zaufanym workflow, który nigdy nie uruchamia kodu z forka z dostępem do sekretów
Recenzja wykonuje instrukcje ukryte w PR-zeTytuł, opis albo komentarze w kodzie PR-a trafiły do promptu recenzentaPrzekazuj w prompcie tylko numery i SHA, a recenzenta trzymaj w trybie tylko do odczytu
Agent-autor przepycha checki na zielono, osłabiając testyTesty leżą w diffie, który kontroluje agentZablokuj ścieżki testów przez CODEOWNERS i checki należące do CI: zobacz ochronę wyroczni
Pętla recenzji nigdy się nie domykaKażda poprawka wyzwala nową rundę uwagReguła ponownych recenzji w REVIEW.md, limit trzech rund w prompcie, potem eskalacja do człowieka
Wdrożenie prześlizgnęło się obok hookaPolecenie było zapisane inaczejW hooku nie ma czego łatać; sprawdź, czy poświadczenia faktycznie brakowało i czy akceptacja środowiska zadziałała, i napraw tę warstwę, która zawiodła
Zarządzany Code Review jest niedostępnyOrganizacja z ZDR albo ruch musi pozostać w Amazon Bedrock, Agent Platform w Google Cloud lub Microsoft FoundryUruchom claude-code-action we własnym CI z odpowiednim wejściem use_*

Konfiguracja poszczególnych narzędzi: Claude Code, Codex i Cursor.