GitHub Workflow & Branch Protection¶
This document describes how a change travels from a branch to production, which checks gate it, and what the GitHub Actions workflows in .github/workflows/ do. The rules for agents (which issues and todos may be picked up, PR template, labels) are in .claude/CLAUDE.md; this page describes the mechanics.
Branch Model¶
flowchart LR
F["feature/* · fix/*<br/>dependabot/* · claude/*"] -->|"PR (squash)<br/>ci-gate + check-base"| S[staging]
S -. "ci.yml: deploy job" .-> Stg["staging.freezedesign.nl"]
Stg -. "feedback-retest-comment.yml" .-> FB["feedback issue:<br/>status:retest-pending"]
S -->|"release.sh --promote-only<br/>promotion PR, fast-forward"| M[main]
M -->|"deploy-production.sh<br/>tag vX.Y → Deploy to Production"| P["www.freezedesign.nl"]
One path only: every change is squash-merged into staging, deployed there automatically, promoted to main by fast-forward after the retest, and deployed to production from a tag on main.
- Feature PRs always target
stagingand are squash-merged. Every merge tostagingtriggers CI and, when green, an automatic staging deploy. mainis human-merged and only receives staging→main promotion PRs (orrelease/*hot-fix branches). TheEnforce PR baseworkflow (check-base) blocks any other PR againstmain;Dependabot Retargetmoves such PRs tostaginginstead.- Production deploys run from a tag on
main, never from a branch. Promoting tomaindoes not deploy anything by itself;scripts/deploy-production.shdoes (see below). Production is v1.60 (2026-11-06).
Promotion: scripts/release.sh¶
Promotion staging→main runs exclusively via:
Promote only after Eefje has retested her feedback issues on staging and closed them, and Ivar has checked the todos on staging. The script finds the green CI run with a successful deploy job for the staging HEAD, then pauses for UAT and asks for confirmation. Only after that confirmation does it open the promotion PR (base=main, head=staging), waits for its checks, and then fast-forwards main to the PR's head SHA with a direct push. GitHub marks the PR as merged once main contains that commit. No commits are rewritten, so main and staging keep the same SHAs. The script refuses if main has something staging lacks (e.g. a hotfix): merge main into staging via a PR first. It still recreates staging if GitHub's delete_branch_on_merge removed it, and retargets open PRs back to staging. Promotion PRs skip the heavy CI jobs (the precheck job in ci.yml detects them); check-base is the only required check.
Other forms: scripts/release.sh <pr-number> merges that PR first and then promotes (--no-uat skips the pause, --dry-run prints what would happen, --allow-missing-staging-deploy continues when no deploy run is found within 15 minutes). If the script stops after the promotion PR exists, rerun the same command: step 4 picks the existing PR up.
Production deploy: scripts/deploy-production.sh¶
scripts/deploy-production.sh # next version: highest vX.Y tag + 1
scripts/deploy-production.sh --tag v1.27 # this version; reused if it already sits on main
The script tags origin/main (never the local HEAD, which usually sits on staging and runs ahead of main), shows the commits and new migrations since the previous tag, asks for confirmation, pushes the tag, starts Deploy to Production (deploy-production.yml, workflow_dispatch with the tag input) with that tag, and follows the run until it finishes. It refuses if main already carries the latest tag (nothing new), if the requested tag exists on another commit, or if main is not an ancestor of staging. If the tag was pushed but the workflow did not start, rerun with --tag to resume. --dry-run shows what would happen; --no-wait starts the deploy without following it. Afterwards rename the [Unreleased] section of CHANGELOG.md to the new version.
Branch Protection Rules¶
Verified against the live settings on 2026-11-01 (gh api repos/Voorman/webshop_freeze_design/branches/<branch>/protection).
main¶
| Rule | Setting | Purpose |
|---|---|---|
| Required status checks | check-base (Enforce PR base workflow) |
Blocks PRs to main that don't come from staging or release/* |
| Strict status checks | Enabled | Branch must be up-to-date with main |
| Required signatures | Disabled | Removes GPG signing friction for solo dev |
| Enforce admins | Disabled | Owner can bypass rules when needed |
| Required PR reviews | Disabled | No approval needed for solo dev |
| Required conversation resolution | Enabled | Open review threads must be resolved |
| Linear history | Disabled | main contains older Merge main into staging commits. Promotions now fast-forward squash-merged staging commits, so this could be re-enabled |
| Force pushes | Disabled | Protects commit history |
| Deletions | Disabled | Prevents accidental branch deletion |
staging¶
| Rule | Setting | Purpose |
|---|---|---|
| Required status checks | ci-gate and check-base, not strict (set 2026-10-07; see Auto-merge on staging) |
Makes auto-merge wait for green CI; not strict, so open PRs need no update after every merge |
| Force pushes | Disabled | Protects deploy history |
| Deletions | Disabled | Prevents delete_branch_on_merge from removing staging after a promotion merge (staging-auto-recreate.yml recreates it from main if it happens anyway) |
| Require a pull request | Enabled, 0 approvals | Every change reaches staging through a PR; nobody pushes to it directly |
| Enforce admins ("Do not allow bypassing the above settings") | Enabled (set for the daily planning, see docs/PLAN-dagplanning-uitvoering.md, task 13) |
The rules also apply to the owner and to the tokens of agents and the guard (AUTOMERGE_TOKEN): no merge without a green ci-gate and check-base |
| Required conversation resolution | Disabled | — |
Repository settings: allow_auto_merge: true and delete_branch_on_merge: true, so feature branches are cleaned up automatically after merge.
When GitHub Actions cannot run
With enforce admins on, nothing merges into staging while ci-gate cannot run, not even a PR with only a todo. That happened on 2026-10-12, when the Actions budget was used up. If a merge cannot wait, switch enforce admins off for that merge and back on right after:
gh api -X DELETE repos/Voorman/webshop_freeze_design/branches/staging/protection/enforce_admins
# merge the PR
gh api -X POST repos/Voorman/webshop_freeze_design/branches/staging/protection/enforce_admins
Step 6b of scripts/release.sh (recreate staging with a direct push) would also be refused. It is only needed when staging has been deleted, which "Deletions: Disabled" prevents.
Auto-merge on staging¶
Auto-merge (allow_auto_merge is on for the repository) only waits for required checks. Without required checks on staging, GitHub would merge at once, so it refuses while checks run ("unstable status").
Requiring the individual CI jobs does not work:
- A PR that only touches docs, Markdown or todo's used to get no CI run at all (
paths-ignore), so a required job would wait forever. - A skipped reusable E2E job reports as
e2e-smoke-testinstead ofe2e-smoke-test / e2e, so a required check on the long name would wait forever too.
That is why CI has one fixed gate, ci-gate. It runs on every PR, including docs-only PRs, and is green when every PR job succeeded or was skipped. The required checks on staging are ci-gate and check-base (set on 2026-10-07; see Changing Branch Protection for the command).
A PR that was opened on an older base (before ci-gate existed) has no ci-gate until its branch is updated with staging.
Standard Workflow¶
# Create feature branch
git checkout staging && git pull
git checkout -b feature/new-feature
# Make changes and push (pre-push hook runs local tests)
git add .
git commit -m "feat: add new feature"
git push -u origin feature/new-feature
# Create PR against staging — CI starts automatically on the PR
# (fill in the template: Feedback:/Ref: line, Verify on staging, Voor Ivar)
gh pr create --base staging --title "feat: add new feature" --body "Description"
# After CI is green, squash-merge
gh pr merge --squash
# CI on the staging push runs the tests again (or skips them when the same
# tree was already green in the PR) and deploys to staging
# After the retest on staging, promote staging → main (pauses for UAT):
scripts/release.sh --promote-only
# Then deploy main to production from a new tag:
scripts/deploy-production.sh
main only moves when scripts/release.sh fast-forwards it to a tested staging SHA after the promotion PR's checks pass. Other direct pushes to main are not part of the workflow. In cloud sessions gh pr and gh issue do not work (GraphQL is blocked); use gh api repos/... (REST) there.
Quality Gates¶
Local (Pre-push Hook)¶
Located at .githooks/pre-push, runs before every push:
- Backend tests - pytest, the same runner as CI, on a subset for speed (requires local PostgreSQL on 5432 and Redis on 6379, e.g. via
docker-compose.dev.yml) - TypeScript check -
tsc --noEmit - CodeRabbit review - AI code review (non-blocking)
- Frontend tests - Jest with coverage
A push that only touches docs, Markdown or todo's (docs/**, **/*.md, .github/workflows/docs.yml, .planning/**, the same paths CI ignores) skips these checks.
Never bypass the hook with --no-verify.
Remote (GitHub Actions CI)¶
.github/workflows/ci.yml runs on every push to main and staging, and on every PR against main or staging:
- precheck - Detects staging→main promotion PRs and skips the heavy jobs for them (the code was already fully tested on staging). Also detects PRs that only touch docs, Markdown or todo's (
docs/**,**/*.md,.github/workflows/docs.yml,.planning/**): those skip all jobs below exceptci-gate, and set no tested-tree marker. Every tested PR run stores atested-tree-<tree>artifact; a later push tostagingwith the same git tree (the usual squash-merge) skips the test jobs and goes straight to build and deploy - backend-test - flake8, migration checks (
makemigrations --check,check_migrations --ci), full pytest suite (parallel, coverage ≥75%) - frontend-test - TypeScript check, ESLint, full Jest suite
- frontend-build - Next.js production build (artifact reused by the E2E jobs)
- e2e-smoke-test - Playwright
@smoketests (pluspdp-hydration.spec.tsin Mobile Safari) - e2e-visual-test - Visual regression tests
- api-types-drift ("API types drift check") - Regenerates the frontend API types from the backend OpenAPI schema and fails if the committed types are out of date
- nginx-config - Only on PRs: starts the nginx configs and checks the security headers, and runs the script tests for
restart-unhealthy.sh,notify-ntfy.sh,deploy-rolling.sh,werkoverzicht.py,werkbord.pyandintake-ready.sh(scripts/tests/) - build-images / build-production-frontend - Only on pushes to
staging: build the Docker images for the commit in parallel with the tests (build-images.yml) - deploy - Only on pushes to
staging: callsdeploy-staging.yml(workflow_call) after build-images, backend-test, frontend-test, frontend-build, e2e-smoke-test, and e2e-visual-test are green (or skipped by precheck). The deploy itself health-checks the containers, rolls back on failure, and startsstaging-perf-gate.yml(k6 on the homepage) afterwards - notify-staging - Always on a staging push: Discord message with the deploy result, also when the deploy was skipped because a test failed
- ci-gate - Only on PRs: green when jobs 1–8 all succeeded or were skipped. The required check on
staging(see Auto-merge on staging)
A push to main or staging that only touches those docs paths still skips CI entirely (paths-ignore on the push trigger), so it does not deploy.
Runs only on schedule (Monday 03:00 UTC) or manual dispatch (workflow_dispatch inputs in brackets):
- e2e-full-test - Full Playwright suite (
run_full_e2e) - e2e-admin-test - Admin + multi-zone E2E (Playwright
chromium-adminproject: admin login via TOTPstorageState+ designer/multi-zone fixtures) (run_full_e2e) - security-scan-dependencies - pip-audit, npm audit, Snyk (
run_security_scan) - docker-build - Validates Docker images build + Trivy scans (
run_docker_build) - Seed data export/import round-trip inside backend-test (
run_extended_checks)
See the Testing Guide for what each test job runs.
Automation Around Pull Requests¶
Enforce PR base (enforce-pr-base.yml)¶
Runs on every PR (opened, edited, reopened, synchronize) as the check-base job. PRs against anything but main pass. PRs against main pass only from staging or release/*; anything else fails with instructions to reopen against staging.
Dependabot (dependabot.yml, dependabot-retarget.yml)¶
Dependabot runs monthly (first day of the month, 06:00 Europe/Amsterdam) for npm (/frontend), pip (/backend), GitHub Actions and the two Dockerfiles, with target-branch: staging; it reads the configuration from main, so a change only takes effect after promotion. Every ecosystem has a cooldown: npm and pip wait 30 days after a major release, 7 after a minor and 3 after a patch; GitHub Actions and Docker wait 7 days for everything (no semver cooldown there). Security updates ignore both the schedule and the cooldown. Patch and minor updates are grouped per ecosystem (frontend-patch-and-minor, backend-patch-and-minor, actions-all, plus react-pair for react/react-dom), and so are the majors (frontend-major, backend-major); fabric, next, react, react-dom and @next/* are excluded from both frontend groups and django from backend-major, so they always get their own PR. At most 5 open version-update PRs per ecosystem. Every third-party action in .github/workflows/ is pinned to a full commit SHA with the version as a comment (actions/checkout@<sha> # v7.0.1); Dependabot updates the SHA and the comment together. Labels: dependencies plus frontend, backend, github-actions or docker.
Dependabot Retarget (pull_request_target, on opened, reopened, edited) moves any PR that was opened against main from a branch other than staging or release/* to staging and leaves a comment. Triage of the Dependabot PRs is a weekly cloud routine described in .github/dependabot-triage.md: low-risk (patch/minor, non-Docker) PRs with the five required checks green are squash-merged after an independent verification; everything else lands in the triage issue (label dependabot-triage).
Daily build PRs (dagbouw-bewaker.yml)¶
The guard for the daily planning (docs/PLAN-dagplanning.md §4.7). It runs on pull_request_target for PRs against staging and on completed CI runs on staging, always with the version of the workflow on main, and never checks out PR code.
- Plan PRs (branch
claude/dagplanning-<date>): checks that the PR only touches.planning/and sets no todo toready(statusdagplanning-paden), and posts to Discord when the PR is opened and when Ivar merges it (the merge is the go for/dagstart). - Build PRs (opened by
Voorman, body contains a lineDagplanning: YYYY-MM-DD): enables auto-merge (squash) withAUTOMERGE_TOKENwhen the item (Ref:orFeedback:) is in the merged plan of that date under Vandaag or Reserve, the date is at most one working day old, the PR touches no sensitive path and the latest CI run onstagingis green. An item that is not in the plan gets a comment and Ivar merges it himself. Sensitive paths (scripts/dagplanning.py):.github/,.claude/,.githooks/, migrations,package.json/package-lock.json/pyproject.toml/uv.lock,backend/apps/payments/,backend/apps/users/, the checkout and login routes and components, and the guard script itself. Such a PR gets the labelwacht-op-ivar, a comment, a Discord message, and Ivar merges it himself. Addingwacht-op-ivarby hand switches auto-merge off. - Staging red: when a CI run on a
stagingpush fails, auto-merge is switched off on every open build PR, with a comment. When onlye2e-smoke-testand/ore2e-visual-testfailed on the first attempt, the guard first reruns those jobs once and waits; auto-merge goes off only when the rerun is red too or not finished in time. Re-run the guard or push a new commit once staging is green again.
Never enable auto-merge on a build PR yourself; the guard decides.
Feedback retest comment (feedback-retest-comment.yml)¶
Runs after every successful CI run on a staging push. scripts/resolve-deployed-prs.sh lists the PRs merged in that deploy; for each PR body with Feedback: Voorman/freezedesign-feedback#<N> it posts a comment on that issue ("Klaar op staging", the staging SHA, and the checklist extracted from the PR's Verify on staging section by scripts/extract-verify-steps.sh), removes all other status:* labels and sets status:retest-pending. Eefje closes the issue after a successful retest.
"Voor Ivar" list (voor-ivar-lijst.yml)¶
Runs when a PR against staging is merged. scripts/dagplanning.py voor-ivar pr copies the checkboxes under the PR's Voor Ivar section into the open issue with label voor-ivar (dated, with the PR number). Nothing happens when the section is empty or the lines are already there. See the Voor Ivar runbook.
Other workflows¶
| Workflow | Trigger | What it does |
|---|---|---|
deploy-staging.yml |
workflow_call from ci.yml; workflow_dispatch |
Deploys the images to staging (one deploy at a time; skips itself when a newer commit already runs), health-checks, rolls back on failure, starts the k6 gate and the E2E smoke (e2e-staging.yml) |
staging-perf-gate.yml |
workflow_dispatch (started by the staging deploy with the deployed sha) |
k6 loadtests/homepage-load.js against staging; Discord on failure |
deploy-production.yml |
workflow_dispatch with tag (via scripts/deploy-production.sh) |
Builds or reuses the images for the tag and deploys to production |
build-images.yml |
workflow_call |
Builds and pushes the Docker images with SHA tags |
staging-auto-recreate.yml |
branch delete |
Recreates staging from main if auto-delete removed it |
update-snapshots.yml |
workflow_dispatch (branch) |
Regenerates the visual baselines and opens a vrt/update-baselines-* PR |
e2e-staging.yml |
workflow_dispatch (spec, optional sha); started by deploy-staging.yml after every deploy with staging-smoke.spec.ts |
Runs one Playwright spec against staging with the basic-auth secret; with a sha it posts to Discord on failure |
intake-ready.yml |
issue_comment on an open issue with label intake, by Voorman |
/ready sets status:ready on the linked feedback issue and closes the intake issue; another answer restarts the intake assistant (scripts/intake-ready.sh) |
load-tests.yml |
workflow_dispatch (test_suite, base_url, frontend_url) |
Full k6 suite, manual re-baselining |
docs.yml |
push to main (docs/backend/frontend paths); PRs against main (no preview for Dependabot) |
Builds and deploys this documentation site; see Documentation |
dagplanning-waakhond.yml |
Mon–Fri 04:17 UTC | Discord alert when the nightly planner opened no plan PR |
websitecheck-discord.yml |
PR against staging |
Posts the "Voor Eefje" summary of a claude/websitecheck-* PR to Discord |
report-zone-cm-conflicts.yml |
push, workflow_dispatch |
Report on print-zone cm conflicts |
backup-test.yml |
Sunday 05:00 UTC | Tests the database backup/restore path |
todo-done-check.yml |
PR against staging |
scripts/check-done-todos.sh: a todo moved to .planning/todos/done/ needs status: done, resolved_date, resolved_pr and resolved_commit, and that commit must be in the last successful production deploy |
ssl-renewal.yml |
Wednesday 04:00 UTC | Renews the SSL certificates; each matrix leg runs in the GitHub environment staging or production and reads the SSH secrets from there (#1025) |
Scheduled and pull_request_target/workflow_run workflows run the version on main, so a change to one of them only takes effect after the next promotion.
Changing Branch Protection¶
Via GitHub CLI¶
# View current settings
gh api repos/Voorman/webshop_freeze_design/branches/main/protection
# Update settings (current config: check-base is the only required check)
gh api repos/Voorman/webshop_freeze_design/branches/main/protection -X PUT \
--input - << 'EOF'
{
"required_status_checks": {
"strict": true,
"checks": [
{"context": "check-base"}
]
},
"enforce_admins": false,
"required_pull_request_reviews": null,
"restrictions": null,
"required_linear_history": false,
"required_conversation_resolution": true,
"allow_force_pushes": false,
"allow_deletions": false
}
EOF
# staging: ci-gate + check-base, not strict (only after ci-gate has run on staging once),
# a PR with 0 approvals, and enforce admins on.
# The other fields keep the current staging settings.
gh api repos/Voorman/webshop_freeze_design/branches/staging/protection -X PUT \
--input - << 'EOF'
{
"required_status_checks": {
"strict": false,
"checks": [
{"context": "ci-gate"},
{"context": "check-base"}
]
},
"enforce_admins": true,
"required_pull_request_reviews": {
"required_approving_review_count": 0,
"dismiss_stale_reviews": false,
"require_code_owner_reviews": false
},
"restrictions": null,
"required_linear_history": false,
"allow_force_pushes": false,
"allow_deletions": false
}
EOF
# Enable/disable signature requirement
gh api repos/OWNER/REPO/branches/main/protection/required_signatures -X POST # Enable
gh api repos/OWNER/REPO/branches/main/protection/required_signatures -X DELETE # Disable
Warning
The required-status-checks config has been observed to silently revert to an older set of checks (May 2026, cause unknown). If a promotion PR fails with "base branch policy prohibits the merge", verify the current config with gh api .../branches/main/protection/required_status_checks and re-apply check-base via the API — not via the UI.
Via GitHub UI¶
- Go to Settings → Branches → Branch protection rules
- Click Edit on
main - Modify settings as needed
Future Considerations¶
When to Add PR Requirements¶
Consider enabling required PR reviews if:
- You add team members
- You want enforced code review
- Compliance requirements change
When to Add GPG Signing¶
Consider enabling required signatures if:
- Working on security-sensitive features
- Contributing to open source
- Corporate compliance requires it
To setup GPG signing:
# Generate GPG key
gpg --full-generate-key
# Get key ID
gpg --list-secret-keys --keyid-format=long
# Configure Git
git config --global user.signingkey YOUR_KEY_ID
git config --global commit.gpgsign true
# Add public key to GitHub
gpg --armor --export YOUR_KEY_ID | pbcopy
# Paste at: GitHub → Settings → SSH and GPG keys → New GPG key
Related Documentation¶
- Deployment Guide
- Testing Guide
- Seed Data & Catalog Management
- Dagplanning runbook
- Eefje Intake Process
Architecture Decisions¶
Task Queue: Celery (Decision: January 2026)¶
Decision: Keep Celery + Redis instead of migrating to Django 6.0 Tasks.
Reasons: - Django Tasks backend still in beta (not production guaranteed) - Celery is battle-tested (10+ years) - Current setup works reliably - Low task volume (~50/day) doesn't justify migration risk - €20-40/mo savings not worth beta risk for e-commerce
Revisit when: - Django Tasks backends reach v1.0 stable - Django 6.1+ released with matured ecosystem - Task volume significantly increases
Alternatives considered: - Django Tasks + django-tasks (too new) - Django-Q2 (viable alternative if Celery issues arise)