Skip to content

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 staging and are squash-merged. Every merge to staging triggers CI and, when green, an automatic staging deploy.
  • main is human-merged and only receives staging→main promotion PRs (or release/* hot-fix branches). The Enforce PR base workflow (check-base) blocks any other PR against main; Dependabot Retarget moves such PRs to staging instead.
  • Production deploys run from a tag on main, never from a branch. Promoting to main does not deploy anything by itself; scripts/deploy-production.sh does (see below). Production is v1.60 (2026-11-06).

Promotion: scripts/release.sh

Promotion staging→main runs exclusively via:

scripts/release.sh --promote-only

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-test instead of e2e-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:

  1. 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)
  2. TypeScript check - tsc --noEmit
  3. CodeRabbit review - AI code review (non-blocking)
  4. 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:

  1. 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 except ci-gate, and set no tested-tree marker. Every tested PR run stores a tested-tree-<tree> artifact; a later push to staging with the same git tree (the usual squash-merge) skips the test jobs and goes straight to build and deploy
  2. backend-test - flake8, migration checks (makemigrations --check, check_migrations --ci), full pytest suite (parallel, coverage ≥75%)
  3. frontend-test - TypeScript check, ESLint, full Jest suite
  4. frontend-build - Next.js production build (artifact reused by the E2E jobs)
  5. e2e-smoke-test - Playwright @smoke tests (plus pdp-hydration.spec.ts in Mobile Safari)
  6. e2e-visual-test - Visual regression tests
  7. 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
  8. 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.py and intake-ready.sh (scripts/tests/)
  9. 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)
  10. deploy - Only on pushes to staging: calls deploy-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 starts staging-perf-gate.yml (k6 on the homepage) afterwards
  11. notify-staging - Always on a staging push: Discord message with the deploy result, also when the deploy was skipped because a test failed
  12. 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):

  1. e2e-full-test - Full Playwright suite (run_full_e2e)
  2. e2e-admin-test - Admin + multi-zone E2E (Playwright chromium-admin project: admin login via TOTP storageState + designer/multi-zone fixtures) (run_full_e2e)
  3. security-scan-dependencies - pip-audit, npm audit, Snyk (run_security_scan)
  4. docker-build - Validates Docker images build + Trivy scans (run_docker_build)
  5. 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 to ready (status dagplanning-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 line Dagplanning: YYYY-MM-DD): enables auto-merge (squash) with AUTOMERGE_TOKEN when the item (Ref: or Feedback:) 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 on staging is 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 label wacht-op-ivar, a comment, a Discord message, and Ivar merges it himself. Adding wacht-op-ivar by hand switches auto-merge off.
  • Staging red: when a CI run on a staging push fails, auto-merge is switched off on every open build PR, with a comment. When only e2e-smoke-test and/or e2e-visual-test failed 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

  1. Go to Settings → Branches → Branch protection rules
  2. Click Edit on main
  3. 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

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)