The trunk

Left to right is time. The thick line is main (the only long-lived Git branch). A ticket is a short feature branch: it leaves main, gets a Preview site, then squash-merges back. GitHub Actions then updates Dev. Staging and Production are tags on one commit, later. New to this? Start on Normal way. Developer commands: Commands.

save on main save on a feature branch squash-merge onto the trunk Dev (newest main) Staging sticker Production sticker

Preview lives on the short spur. After squash-merge, GitHub’s robot puts that save on Dev. Later the Release owner names the same save for Staging (v1.5.0-rc.1), then Production (v1.5.0 + Approve). Dev keeps following newest main. Staging stays still. There is no Git branch called develop or staging. Hotfix, rollback, and Git errors are under Exceptions.

Git vs servers

How we ship code

Pick the role that matches the job. Developer loop is in the green box. Copy-paste Git is on Commands. Stuck? FAQ. Something weird? Exceptions.

Developer makes a branch → Senior developer merges it → Dev updates.
Later, Release owner sends that same code to Staging (QA), then Production (users).

Words in this guide

Who does what

Every ticket

1. Developer Feature branch

   Developer edits files here. Never on main.

2. Developer Preview

   A website for this PR. Open the link on the PR.

3. Senior developer Squash and merge

   The only merge button we use.

4. Dev

   Always the newest main. Happens by itself.

When we ship to users

1. Release owner The version on Dev

   Release owner writes down the short ID, like a1b2c3d.

2. Release owner Staging · v1.5.0-rc.1

   This copy stays still. New tickets still go to Dev.

3. Release owner Production · v1.5.0

   Must be the Staging version. Release owner waits for Approve.

Preview, Dev, Staging, and Production are servers, not Git branches. There is no branch called develop or staging.

Commands for each role

Developer: the daily loop is first. Copy the block that matches the numbered step. Happy path is here. Production shipped mid-ticket is the extra Developer block. Hotfix, QA bugs, and Git errors: Exceptions.

Developer Daily loop — every ticket

1. First time on this computer: clone the repo git status should say On branch main.
2. Get latest main, then make a feature branch Name: feature/JIRA-101-short-name. Do not save while still on main.
3. Edit → git add the file path → git commit → git push Type the path. Do not use git add . (secrets can sneak in).
4. Open a Pull Request. Base must be main Use the Preview link on the PR. Then stop and wait for a Senior developer.

Step 1 — first time onlygit clone https://github.com/YOUR-ORG/YOUR-REPO.git
cd YOUR-REPO
git status

Steps 2–4 — every ticketgit checkout main
git pull origin main
git checkout -b feature/JIRA-101-user-authentication

git add src/auth/login.ts
git commit -m "feat(auth): implement JWT token generation"
git push -u origin feature/JIRA-101-user-authentication

gh pr create --base main --title "feat(auth): JWT token generation"
# Or GitHub → Compare & pull request → base = main

Developer Production shipped, branch still open

Users just got a tag (example: v1.5.0). The Developer is still on feature/JIRA-101-…. That commit is already in Git. Stay on the feature branch. Rebase or merge newest main into it. If Production was a hotfix, wait until that fix is on main first (Exception 5).

1. Stay on the feature branch. Finish or stash unsaved edits git status must say the feature branch name. Do not git checkout v1.5.0 — that leaves the ticket.
2. Download tags and newest main. Confirm the Production save Do not copy files from the Production server.
3. Put newest main into this feature branch, then keep working No PR comments yet: git rebase origin/main. Comments already exist: git merge origin/main. Same rule as Exception 3.

Step 1 — still on the unfinished feature branchgit status

Sample for step 1 — git statusOn branch feature/JIRA-101-user-authentication
Your branch is up to date with 'origin/feature/JIRA-101-user-authentication'.

nothing to commit, working tree clean
# If Git lists unsaved files: git add path + git commit, or git stash -u, then continue.

Step 2 — fetch. Confirm what users just gotgit fetch origin --tags
git log -1 --oneline v1.5.0

Sample for step 2 — git log -1 --oneline v1.5.0a1b2c3d feat(auth): implement JWT token generation
# That save is the Production sticker. It is already in Git. Do not copy from the server.

Step 3 — no PR comments yet: rebase onto newest maingit rebase origin/main
git push --force-with-lease
# force-with-lease updates the feature branch only — never main

Step 3 — PR already has comments: merge main in. Do not replaygit merge origin/main
git push

Then keep working on the same feature branchgit log --oneline -5
# Should show the Developer’s saves on top of a1b2c3d (and any other main work).
# Next edit: git add path → git commit → git push. Still not on main.

Senior developer Review and merge

1. Open the PR. Base must say main If it does not, send it back. Do not merge.
2. Wait for a green check, then read the code Checks tab, or gh pr checks 123.
3. Click Squash and merge. Delete the branch Not Merge. Not Rebase.
4. Open Dev and click the ticket Actions job Deploy to EC2 (dev) is green. Do not use Staging for this ticket.

Steps 1–4 — reviewgh pr checkout 123
gh pr checks 123
# GitHub: review → Squash and merge → delete branch

Release owner Staging, then Production

1. On Dev, pick the version QA should test git log --oneline -5. Copy the first short ID (left column). Sample below.
2. Name it v1.5.0-rc.1 and publish as a pre-release GitHub → Releases → tick Set as a pre-release. Staging updates.
3. When QA says yes, name that same version v1.5.0 Do not pick newest main. Publish (no pre-release tick). A required reviewer clicks Approve.

Step 1 — list saves on Devgit checkout main
git pull origin main
git log --oneline -5

Sample for step 1 — git log --oneline -5 (newest first)a1b2c3d feat(auth): implement JWT token generation
7c8d9e0 fix(auth): handle expired refresh tokens
b2c3d4e feat(settings): add timezone picker
e1f2a3b chore: update composer.lock
4d5e6f7 feat(dashboard): show last login
# Copy the first ID. Here that is a1b2c3d — that is the version on Dev.

Step 2 — tag for Staginggit tag -a v1.5.0-rc.1 a1b2c3d -m "Staging candidate v1.5.0"
git push origin v1.5.0-rc.1
# GitHub → Releases → this tag → tick Pre-release → Publish

Step 3 — check the Staging savegit fetch origin --tags
git checkout v1.5.0-rc.1
git log --oneline -1

Sample for step 3 — must match Staginga1b2c3d feat(auth): implement JWT token generation
# If this ID is not a1b2c3d, stop. Do not tag Production.

Step 3 — tag for Productiongit tag -a v1.5.0 a1b2c3d -m "Production release v1.5.0"
git push origin v1.5.0
# GitHub → Releases → publish v1.5.0 (do not tick Pre-release) → Approve

QA found a bug, Production is down, or Production must go back to the last version? That is not this page — go to Exceptions.

Do not use the normal way when…

Stay on Commands unless one of these is true. Each box is: when it happens, what to do, what not to do.

Exception 4 — Release owner after the fix is on maingit checkout main
git pull origin main
git log --oneline -5

Sample: git log --oneline -5 (newest first)9f8e7d6 fix(auth): correct expiration offset
a1b2c3d feat(auth): implement JWT token generation
7c8d9e0 fix(auth): handle expired refresh tokens
b2c3d4e feat(settings): add timezone picker
e1f2a3b chore: update composer.lock
# Copy the first ID. Here that is 9f8e7d6 — the QA fix. Do not reuse a1b2c3d (rc.1).

Name the new ID for Staginggit tag -a v1.5.0-rc.2 9f8e7d6 -m "Staging candidate v1.5.0 rc.2"
git push origin v1.5.0-rc.2
# GitHub Release from v1.5.0-rc.2, tick Pre-release. Later Production uses rc.2, not rc.1.

Paste blocks for exception 5 are under Fixes.

Paste blocks for exception 7 are under Fixes.

Hotfix, rollback, and Git errors

Production users broken? Use the chooser, then paste. A Git error? Use the table. If anyone is lost, stop and ping a Senior developer — do not guess with --force on main.

If a command fails

Developer Exception 3 — replay the branch

Only if nobody has commented on the PR yet.

Developer: replay the feature branch on top of newest maingit fetch origin
git rebase origin/main
git push --force-with-lease
# force-with-lease updates the feature branch only — never main

If people already commented: git fetch origin && git merge origin/main && git push. Do not replay.

Conflict while replaying (Senior developer helps)git status
# Edit files, remove <<<<<<< markers, then:
git add path/to/file
git rebase --continue
git push --force-with-lease

Senior developer Exception 5 — Production hotfix

Start from the live version. Example: Production v1.4.3 → patch v1.4.4.

Senior developer — write the fix from the live versiongit fetch origin --tags
git checkout -b hotfix/JIRA-999-db-leak v1.4.3
git add src/db/pool.ts
git commit -m "fix(db): resolve connection pool leak"
git push -u origin hotfix/JIRA-999-db-leak
gh pr create --base main --title "fix(db): resolve connection pool leak"
# Squash and merge into main so Dev also has the fix
# Copy the fix save ID and send it to the Release owner

Release owner — copy that one fix onto the live version, then usersgit fetch origin --tags
git checkout v1.4.3
git cherry-pick PASTE_THE_FIX_COMMIT_ID
# cherry-pick = copy that one save, without unfinished tickets
git tag -a v1.4.4 -m "Hotfix v1.4.4"
git push origin v1.4.4
# GitHub → Releases → publish v1.4.4 → Approve production

Release owner Exception 7 — Rollback to last version

Example: bad Production is v1.5.0. Last good Production is v1.4.4. Skip names with -rc — those are Staging only.

Release owner — find the last good Production stickergit fetch origin --tags
git tag --list "v*" --sort=-v:refname

Sample: git tag --list (newest name first)v1.5.0
v1.5.0-rc.1
v1.4.4
v1.4.3
v1.4.2
# Bad live sticker: v1.5.0. Last good Production: v1.4.4 (not the rc).

Confirm that sticker’s save IDgit log -1 --oneline v1.4.4

Sample: git log -1 --oneline v1.4.4c0ffee1 fix(db): resolve connection pool leak
# Users must get this save again — not newest main.

First choice — no new sticker. Re-run the last good Production deploy# GitHub → Actions
# Find the last green job: Deploy to EC2 (prod) for v1.4.4
# Re-run jobs → Approve the production environment

If Re-run is gone — new sticker on the same save as v1.4.4git fetch origin --tags
git log -1 --oneline v1.4.4
git tag -a v1.4.5 c0ffee1 -m "Rollback: restore v1.4.4"
git push origin v1.4.5
# GitHub → Releases → publish v1.4.5 (do not tick Pre-release) → Approve
# Staging can stay on v1.5.0-rc.1. Senior developer still fixes v1.5.0 on main.

FAQ by role

Find the role heading. Open the question. Paste blocks are under Commands. Unusual cases are under Exceptions.

Developer

Senior developer

Release owner