Skip to content

Release Worktree Checklist

Last audited: 2026-06-25.

Use this before pushing to integration, before promoting another branch into integration, and before any user-controlled production rollout.

Repositories To Check

Run the checklist in every repository that can affect a release:

  • backend
  • architecture
  • docs
  • mobile-frontend
  • web-admin

Worktree And Branch Check

From each repository root:

git fetch --all --prune
git status --short --branch
git branch --show-current
git pull --ff-only

Expected result:

  • Worktree is clean before switching branches, promoting branches, or pushing.
  • Current branch is the intended release branch.
  • Backend and architecture agent work is on integration.
  • Backend and architecture long-lived branches are only integration and production.
  • Detached HEAD is only acceptable for read-only audit work. Before pushing, check out the target branch and repeat the clean-worktree check.

If git pull --ff-only fails, stop and report the divergence. Do not create a merge commit and do not force-push unless the user explicitly approves a history rewrite plan.

Integration And Production Ancestry

Before any production rollout, verify that production has no production-only commits and that production is already contained in integration:

git rev-list --count origin/integration..origin/production
git merge-base --is-ancestor origin/production origin/integration

The rev-list count must be 0, and merge-base must exit 0. If either check fails, production-only commits exist or branch ancestry is unsafe. Stop and report the divergence before any rollout planning continues.

Keep release history linear:

git rev-list --merges --count origin/production..origin/integration

The merge count must be 0 for the promotion range. If merge commits appear in the release range, stop and report them before promoting.

Fast-Forward Promotion Path

When promoting a completed source branch into integration, update integration only by fast-forward:

git checkout integration
git pull --ff-only origin integration
git merge --ff-only <source-branch-or-commit>
git push origin integration

If git merge --ff-only fails, stop and report the divergence. Do not run a plain git merge, do not use --no-ff, and do not force-push.

Production rollout is manual and user-controlled. The only allowed production movement is a fast-forward to the already verified integration commit:

git checkout production
git pull --ff-only origin production
git merge --ff-only origin/integration

Never push directly to production from an agent or automation workflow.

After Every Push

After every push, monitor the GitLab pipeline to a terminal state.

If the pipeline fails:

  • Identify the failing job.
  • Classify the failure as application, test, contract, security, deploy, or infrastructure.
  • Report the next required action before continuing release work.

After a successful integration CI/CD pipeline, verify the affected integration environment with agent-browser. Exercise the workflow or screen affected by the change. If browser verification is blocked, capture the blocker and report it with the pipeline result.