Scrum4Me/docs/runbooks/deploy-control.md

---
title: "Deploy-controle: triggers, labels, path-filter"
status: active
audience: [contributor, ai-agent]
language: nl
last_updated: 2026-05-07
when_to_read: "Vóór een PR mergen, vóór doc-only changes pushen, of bij troubleshooting van Vercel-deployments."
---

# Deploy-controle

Selectieve controle over wanneer Vercel-deployments worden uitgevoerd
vanuit de GitHub Actions workflow `.github/workflows/ci.yml`. Vercel's
eigen Git-integratie staat **uit** (`vercel.json: git.deploymentEnabled:
false`) — de workflow is de enige bron van deploy-truth.

> **Auto-deploy staat momenteel UIT.** Zowel PR-preview als
> push-naar-main-productie deploys zijn afhankelijk van repo-variable
> `AUTO_DEPLOY_ENABLED=true`. Default ontbreekt die variable → beide
> auto-deploy-jobs worden overgeslagen om Actions-minuten te besparen.
> **Handmatig deployen blijft werken** via `workflow_dispatch` (zie
> onderaan). Aanzetten: *Settings → Secrets and variables → Actions →
> Variables → New repository variable → `AUTO_DEPLOY_ENABLED` = `true`*.

---

## Triggers en defaults

| Event | Default-deploy |
|---|---|
| `push` naar `main` | Productie (`vercel deploy --prod`) — alleen als path-filter zegt "code" **en** `AUTO_DEPLOY_ENABLED=true` |
| `pull_request` naar `main` | Preview (`vercel deploy`) — alleen als path-filter zegt "code", geen `skip-deploy` label **en** `AUTO_DEPLOY_ENABLED=true` |
| `workflow_dispatch` | Handmatig — kies `target: preview \| production` in Actions-tab. Werkt altijd, ongeacht `AUTO_DEPLOY_ENABLED`. |

CI (lint, typecheck, test, build) draait **altijd** op push/PR — ook
voor doc-only changes. Alleen de deploy-jobs respecteren path-filter,
labels, en de `AUTO_DEPLOY_ENABLED` flag.

---

## Path-filter

Job `changes` (dorny/paths-filter@v3) zet output `code=true` als
één van deze paden gewijzigd is:

```
app/**
components/**
lib/**
actions/**
stores/**
prisma/**
public/**
package.json
package-lock.json
next.config.ts
tsconfig.json
vercel.json
proxy.ts
middleware.ts
.github/workflows/**
```

Wijzigingen aan `docs/`, `CLAUDE.md`, `README.md`, `.vscode/**`, etc.
zetten `code=false` → **geen deploy** (zelfs niet preview).

---

## Labels (alleen op PRs)

| Label | Effect |
|---|---|
| `skip-deploy` | Preview-deploy overslaan, ook als path-filter "code" zegt |
| `force-deploy` | Preview-deploy forceren, ook als path-filter "geen code" zegt |

Beide labels werken alleen op **PR's**. Op pushes naar `main` heeft
alleen path-filter invloed (productie-gate).

---

## Beslismatrix per scenario

| Trigger | Path-filter | Labels | Resultaat |
|---|---|---|---|
| PR met code-change | `code=true` | (geen) | ✅ Preview-deploy |
| PR met code-change | `code=true` | `skip-deploy` | ❌ Preview overgeslagen |
| PR met doc-only | `code=false` | (geen) | ❌ Geen deploy |
| PR met doc-only | `code=false` | `force-deploy` | ✅ Preview-deploy |
| PR met code-change | `code=true` | `skip-deploy` + `force-deploy` | ✅ `force-deploy` wint |
| Push main code | `code=true` | n.v.t. | ✅ Productie-deploy + migrate |
| Push main doc-only | `code=false` | n.v.t. | ❌ Geen deploy |
| `workflow_dispatch` `target=preview` | n.v.t. | n.v.t. | ✅ Manuele preview |
| `workflow_dispatch` `target=production` | n.v.t. | n.v.t. | ✅ Manuele prod + migrate |

---

## Voorbeelden

**Doc-only PR die je niet wil deployen** (default):

```bash
git checkout -b docs/fix-typo
# alleen docs/foo.md aanpassen
git commit -am "docs: typo"
gh pr create
# → CI runt, deploy-preview = SKIPPED
```

**Doc-only PR die je wél visueel wil checken**:

```bash
gh pr create
gh pr edit --add-label force-deploy
# → CI runt, deploy-preview RUNT
```

**Code-PR die je niet wil deployen** (bv. WIP):

```bash
gh pr create
gh pr edit --add-label skip-deploy
# → CI runt, deploy-preview SKIPPED
```

**Manuele productie-redeploy zonder push**:

1. GitHub repo → Actions → CI workflow → "Run workflow" knop
2. `target: production` → Run
3. → `deploy-manual` job draait `prisma migrate deploy` + `vercel deploy --prod`

---

## Troubleshooting

**Probleem**: Twee deploys verschijnen op Vercel-dashboard per push.

→ Check `vercel.json` bevat `"git": { "deploymentEnabled": false }`. Zo
niet: Vercel's eigen Git-integratie deployt parallel naast de workflow.

**Probleem**: Mijn PR met code-change deployt geen preview.

→ Check labels: heb je `skip-deploy` aangezet? Verwijder het label of
voeg `force-deploy` toe.
→ Check `changes`-job output in Actions-tab: zegt het `code=false`?
Mogelijk staat je wijziging buiten de path-filter (bv. een nieuw
top-level bestand). Pas filter aan in `ci.yml` als nodig.

**Probleem**: Push naar main triggert geen prod-deploy.

→ Check Actions-tab `changes`-job output. `code=false` betekent geen
deploy.
→ Forceer via `workflow_dispatch` met `target=production`.

**Probleem**: `workflow_dispatch` toont geen "Run workflow" knop.

→ Workflow moet minstens één keer op de default branch (main) hebben
gedraaid voordat de knop verschijnt. Eerste keer: merge naar main of
push direct naar main.

---

## Referenties

- Workflow: `.github/workflows/ci.yml`
- Vercel-config: `vercel.json`
- Plan: `docs/old/plans/auto-pr-deploy-sync.md` Deel A
- Branch- & commit-strategie: [`docs/runbooks/branch-and-commit.md`](./branch-and-commit.md)
- Auto-PR-flow (toekomstig): `docs/old/plans/auto-pr-deploy-sync.md` Deel B