docs(auto-pr): runbook voor end-to-end auto-PR flow
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) <noreply@anthropic.com>
This commit is contained in:
parent
f570f07d4a
commit
c15719164a
2 changed files with 188 additions and 0 deletions
|
|
@ -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 |
|
||||
|
|
|
|||
187
docs/runbooks/auto-pr-flow.md
Normal file
187
docs/runbooks/auto-pr-flow.md
Normal file
|
|
@ -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-<id>
|
||||
│
|
||||
▼
|
||||
Agent roept update_job_status('done', branch=feat/story-<n>)
|
||||
│
|
||||
▼ MCP-tool prepareDoneUpdate (scrum4me-mcp/src/tools/update-job-status.ts)
|
||||
│
|
||||
├─ pushBranchForJob → git push origin feat/story-<n>
|
||||
│ (no-op als HEAD === origin/main → status DONE zonder pushed_at)
|
||||
│
|
||||
├─ Job.pushed_at = now() Job.branch = feat/story-<n>
|
||||
│
|
||||
▼ 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/<branch>` | ✅ | 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 = '<product-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
|
||||
(<reason>): <stderr-snippet>"`. 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue