From c15719164a4c0144dfc6af76c5a4ac66d379f872 Mon Sep 17 00:00:00 2001 From: Madhura68 Date: Wed, 6 May 2026 00:37:18 +0200 Subject: [PATCH] docs(auto-pr): runbook voor end-to-end auto-PR flow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Beschrijft hoe agent-jobs met Product.auto_pr=true automatisch commit → push → PR → auto-merge → deploy doorlopen. Documenteert welke laag wat doet (worker, scrum4me-mcp, GitHub Actions, Vercel), setup-vereisten per product, foutpaden en wanneer auto_pr UIT laten. Onderdeel van PBI-36 ST-1220. De auto-PR-implementatie zelf zit in scrum4me-mcp; deze runbook documenteert de bestaande flow plus de nieuwe auto-merge-stap (scrum4me-mcp PR #23). Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/INDEX.md | 1 + docs/runbooks/auto-pr-flow.md | 187 ++++++++++++++++++++++++++++++++++ 2 files changed, 188 insertions(+) create mode 100644 docs/runbooks/auto-pr-flow.md diff --git a/docs/INDEX.md b/docs/INDEX.md index b541fcc..9dd6afc 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -110,6 +110,7 @@ Auto-generated on 2026-05-05 from front-matter and headings. | [Scrum4Me — API Test Plan](./qa/api-test-plan.md) | `qa/api-test-plan.md` | active | 2026-05-03 | | [Realtime smoke-checklist — PBI / Story / Task](./realtime-smoke.md) | `realtime-smoke.md` | active | 2026-05-03 | | [Agent-flow: open issues & decision log](./runbooks/agent-flow-pitfalls.md) | `runbooks/agent-flow-pitfalls.md` | active | 2026-05-03 | +| [Auto-PR flow: van story-DONE naar gemergde PR](./runbooks/auto-pr-flow.md) | `runbooks/auto-pr-flow.md` | active | 2026-05-06 | | [Branch, PR & Commit Strategy](./runbooks/branch-and-commit.md) | `runbooks/branch-and-commit.md` | active | 2026-05-03 | | [Deploy-controle: triggers, labels, path-filter](./runbooks/deploy-control.md) | `runbooks/deploy-control.md` | active | 2026-05-05 | | [Vercel Deployment](./runbooks/deploy-vercel.md) | `runbooks/deploy-vercel.md` | active | 2026-05-03 | diff --git a/docs/runbooks/auto-pr-flow.md b/docs/runbooks/auto-pr-flow.md new file mode 100644 index 0000000..710965f --- /dev/null +++ b/docs/runbooks/auto-pr-flow.md @@ -0,0 +1,187 @@ +--- +title: "Auto-PR flow: van story-DONE naar gemergde PR" +status: active +audience: [contributor, ai-agent] +language: nl +last_updated: 2026-05-06 +when_to_read: "Vóór het aanzetten van auto_pr op een product, of bij debugging van uitblijvende PR's na agent-jobs." +--- + +# Auto-PR flow + +Wanneer een Scrum4Me-agent een TASK_IMPLEMENTATION-job afrondt, kan de +hele keten **commit → push → PR → auto-merge → deploy** zonder +handmatige actie verlopen — mits het bijbehorende product `auto_pr=true` +heeft staan en de repo + tokens correct geconfigureerd zijn. + +--- + +## Volledige keten + +``` +Agent voltooit task in /tmp/job- + │ + ▼ +Agent roept update_job_status('done', branch=feat/story-) + │ + ▼ MCP-tool prepareDoneUpdate (scrum4me-mcp/src/tools/update-job-status.ts) + │ + ├─ pushBranchForJob → git push origin feat/story- + │ (no-op als HEAD === origin/main → status DONE zonder pushed_at) + │ + ├─ Job.pushed_at = now() Job.branch = feat/story- + │ + ▼ maybeCreateAutoPr (scrum4me-mcp/src/tools/update-job-status.ts:203) + │ + ├─ Product.auto_pr === false → STOP (niets meer) + │ + ├─ Product.auto_pr === true: + │ ├─ sibling-job in story heeft al pr_url → hergebruik + │ └─ eerste DONE-task in story: + │ ├─ gh pr create → Job.pr_url + │ └─ gh pr merge --auto --squash → CI groen → squash-merged + │ + ▼ +Push naar main → ci.yml deploy-production → Vercel +``` + +--- + +## Wat is wel/niet automatisch? + +| Stap | Automatisch? | Door wie | +|---|---|---| +| Commit op feature-branch | ✅ | Worker (Claude-CLI in container) | +| Push naar `origin/` | ✅ | scrum4me-mcp `pushBranchForJob` | +| `gh pr create` | ✅ (als `auto_pr=true`) | scrum4me-mcp `maybeCreateAutoPr` | +| `gh pr merge --auto --squash` | ✅ (als `auto_pr=true`) | scrum4me-mcp `createPullRequest` | +| CI groen | n.v.t. | GitHub Actions `ci.yml` | +| Squash-merge | ✅ (als CI groen + auto-merge actief) | GitHub | +| Productie-deploy na merge | ✅ (mits path-filter "code") | `ci.yml` deploy-production — zie [deploy-control.md](./deploy-control.md) | +| Sluiten van feature-branch | ✅ (na merge) | GitHub | + +--- + +## Setup-vereisten per product + +### 1. Toggle aanzetten + +In de webapp: **Product → Settings → Automatisch PR aanmaken na +succesvolle agent-job** → toggle aan. + +Equivalent op DB-niveau: +```sql +UPDATE products SET auto_pr = true WHERE id = ''; +``` + +Per product. Standaard staat hij **uit** zodat nieuwe producten geen +verrassende auto-PR's produceren. + +### 2. GitHub repo-instellingen + +- Settings → General → **Allow auto-merge** → aanvinken. Zonder dit + weigert `gh pr merge --auto` met fout, maar de PR is al wel + aangemaakt — auto-merge moet je dan handmatig aanzetten. +- Settings → General → **Automatically delete head branches** → + aanbevolen aan zodat gemergde feature-branches opgeruimd worden. +- Settings → Branches → branch protection op `main`: + - **Required status checks**: minimaal `ci` (lint, typecheck, test, build) + - `deploy-preview` is **niet** required (mag skipped zijn door labels — + zie [deploy-control.md](./deploy-control.md)) + +### 3. Tokens op de scrum4me-mcp host + +`gh` CLI moet ingelogd zijn als een user/token met `repo`-scope (private) +of `public_repo` (public). De MCP-host (typisch een NAS-container) draait: + +```bash +gh auth login # of: +gh auth login --with-token < /path/to/token +``` + +### 4. Worker (scrum4me-docker) + +De agent-runner container heeft de relevante MCP-tools al in zijn +`ALLOWED_TOOLS`-lijst. Geen aanpassing nodig. + +--- + +## Wat zie je in de UI + +- **/admin/jobs** (admin): elke ClaudeJob toont `branch`, `pr_url`, + `error`. Status-badge: SKIPPED bij no-op (zie + [worker-idempotency.md](./worker-idempotency.md)). +- **Idea-detail Sync-tab** (PBI-36 ST-1219): per Story toont de PR-URL + en gemerged-status van de gekoppelde PBI. +- **Notifications**: SSE-stream vuurt op `claude_job_status`-event + zodat dashboard en bel-icoon real-time bijwerken. + +--- + +## Branch-strategie + +`feat/story-<8-char-suffix>` per Story. Sibling-tasks in dezelfde Story +hergebruiken zelfde branch + zelfde PR (zie `maybeCreateAutoPr` regel +229-239 in `scrum4me-mcp/src/tools/update-job-status.ts`). Eén PR per +Story, niet per Task. + +PBI-niveau aggregatie is **niet** geïmplementeerd: er is geen +`check_pbi_complete`-MCP-tool en geen "samengestelde" PR die alle +stories van een PBI bundelt. Eén story = één PR. + +--- + +## Foutpaden + +### Push faalt +`prepareDoneUpdate` zet `Job.status=FAILED` met `error: "push failed +(): "`. Mogelijke `reason`: + +- `no-credentials` — `gh auth login` ontbreekt op MCP-host +- `conflict` — non-fast-forward; meestal omdat een sibling-job de + branch al aanpaste. Worker maakt geen retry — gebruiker moet handmatig + rebasen of nieuwe job aanmaken. +- `unknown` — netwerkfout / andere git-fout. Stderr in `error`-veld. + +### `gh pr create` faalt +Worktree blijft bestaan voor handmatige inspectie. `Job.pr_url` blijft +null. Gebruiker kan handmatig PR aanmaken vanuit de gepushte branch. + +### Auto-merge faalt +Best-effort: als `gh pr merge --auto` faalt (repo zonder "Allow +auto-merge", of token-scope ontoereikend) wordt alleen een warning +gelogd. PR-URL blijft teruggegeven, gebruiker kan handmatig auto-merge +aanzetten of mergen. + +### CI rood +PR blijft open. Auto-merge wacht eindeloos. Gebruiker moet ofwel CI +fixen (extra commit op zelfde branch — pakt MCP niet automatisch op, +worker is per-job) ofwel auto-merge uitzetten en handmatig sluiten. + +--- + +## Wanneer auto_pr UIT laten + +- **Tijdens initial-development** van een nieuw product — wil je elke PR + zelf reviewen. +- **Code-reviews vereist** door org-policy — auto-merge kan branch + protection rules omzeilen die niet als "required check" staan. +- **Externe contributors** — auto-PR met SQUASH-merge schrijft de agent + als author. Voor contributor-PRs wil je dat niet. + +--- + +## Referenties + +- Tool-implementatie: `scrum4me-mcp/src/tools/update-job-status.ts` + (`prepareDoneUpdate`, `maybeCreateAutoPr`) +- Push-implementatie: `scrum4me-mcp/src/git/push.ts` +- PR-implementatie: `scrum4me-mcp/src/git/pr.ts` (createPullRequest + + auto-merge) +- UI-toggle: `components/products/auto-pr-toggle.tsx` +- Server-action: `actions/products.ts` (`updateAutoPrAction`) +- Schema: `prisma/schema.prisma` → `Product.auto_pr` +- Gerelateerde runbooks: + - [deploy-control.md](./deploy-control.md) — wat gebeurt er na merge + - [worker-idempotency.md](./worker-idempotency.md) — JobStatus protocol + - [branch-and-commit.md](./branch-and-commit.md) — branch-strategie