Git staging bridge workflow

Versioned bridge branches carry targeted fixes from origin/main into staging for pre-UAT / staging deployment—without merging feature work through main first.

First use: v1.0.2 on [[Projects/anabatic-claim/anabatic-claim|Claim]] backend (backend-claim-dev) — approver list scope fix (exclude finance steps from approver/list).

Flow overview

Version naming (APP_VERSION)

Bridge branch name = APP_VERSION in config/staging.env (same string, including the v prefix, e.g. v1.0.2).

• Authoritative for the next bridge: read APP_VERSION from config/staging.env before git checkout -b ….
• Claim backend today: config/staging.env and config/development.env both set APP_VERSION='v1.0.2' — they must stay identical across dev and staging config.
• Do not invent a branch tag that does not match APP_VERSION; do not leave env version behind after a bridge is promoted.

After bridge lands on ready-prod — bump env and create next bridge

When the current bridge has been pushed / merged to ready-prod, do all of the following in one pass (do not bump env without creating the matching branch):

1. Choose the next version (e.g. v1.0.2 → v1.0.3).
2. Set APP_VERSION to that value in both files (keep them identical):

1. Create the new bridge branch from origin/main using that exact name.
2. Commit the env bump on the new bridge branch and push it.

git fetch origin main
git checkout -b v1.0.3 origin/main          # branch name = new APP_VERSION

# Edit config/staging.env and config/development.env → APP_VERSION='v1.0.3'

git add config/staging.env config/development.env
git commit -m "chore: bump APP_VERSION to v1.0.3 and open staging bridge"
git push -u origin v1.0.3

The next fixes ship on v1.0.3; merge that branch → staging when ready (see §3 below). Do not commit the version bump only on staging or main without creating origin/v1.0.3.

Branch roles

Environment progression (see [[Areas/Anabatic/Tech stack|Tech stack]]): dev → staging → UAT → production.

Standard procedure

1. Open or create the bridge branch

A — Previous bridge already on ready-prod

Use the After bridge lands on ready-prod section above (bump + git checkout -b + commit env on the new branch + push). Skip to §2 on that branch.

B — Bridge for this version already exists (e.g. v1.0.2 in env and on remote)

1. Confirm APP_VERSION in config/staging.env matches config/development.env.
2. Check out the existing bridge:

git fetch origin
git checkout v1.0.2    # must match APP_VERSION
git pull origin v1.0.2

C — First bridge for a repo / greenfield

Set APP_VERSION in both env files, then create the branch from origin/main with the same name and commit the env files on that branch (same commands as section After bridge lands on ready-prod).

2. Apply and commit on the bridge

• Implement or cherry-pick the fix on v1.0.2 only.
• Commit code + docs (including docs/ submodule pointer if the repo uses one).
• Do not commit unrelated local work (migrations, env files, WIP).

git add <paths>
git commit -m "fix(scope): short description"
git push -u origin v1.0.2

3. Merge bridge → staging

git fetch origin staging
git checkout staging
git pull origin staging
git merge v1.0.2 -m "Merge branch 'v1.0.2' into staging"

• If merge conflicts: stop, resolve on a human branch or rebase the bridge—do not force-push staging.
• If clean:

git push origin staging

4. Verify on staging

• Deploy / restart staging API per project runbook.
• Smoke-test the behaviour that motivated the bridge (e.g. approver/list?tab=history vs finance-approver/list).

Hard rules (agents and humans)

Do not touch production git surfaces unless explicitly requested—and then only after a deliberate warning.

If a task appears to require main, origin/main, or prod:

1. Stop and state why it might be needed.
2. Show a clear warning that prod/main will be affected.
3. Proceed only after explicit human confirmation.

Submodule note (Claim backend)

backend-claim-dev mounts docs/ as submodule (documentation-claim). When docs change:

1. Commit inside docs/ on its repo (main or agreed docs branch).
2. Push docs remote.
3. Bump submodule pointer in parent repo on the bridge branch, then merge bridge → staging.

Example: v1.0.2 (2026-05-22)

Related

• [[Areas/Anabatic/Workflow/Workflow]]
• [[Areas/Anabatic/Rules/Rules#Git and remotes]]
• [[Projects/anabatic-claim/anabatic-claim]]