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

---
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