Scrum4Me/docs/runbooks/auto-pr-flow.md

title	status	audience	language	last_updated	when_to_read
Auto-PR flow: van story-DONE naar gemergde PR	active	contributor ai-agent	nl	2026-05-06	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
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:

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)

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:

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).
• 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 — wat gebeurt er na merge
  • worker-idempotency.md — JobStatus protocol
  • branch-and-commit.md — branch-strategie