Git Basics for Node Teams

A cookbook for trunk-based flow with release tags on Node.js backend teams - short-lived feature branches, semver tags, and hotfix lanes that match API and worker deploy order.

Recipe

Quick-reference recipe card - copy-paste ready.

# Daily feature work
git checkout main && git pull --ff-only
git checkout -b feat/API-412-add-refund-endpoint
# ... commits with conventional messages ...
git push -u origin feat/API-412-add-refund-endpoint
# Open PR → squash merge to main after CI green

# Release cut (when API + workers ship together)
git checkout main && git pull --ff-only
git checkout -b release/2.6.0
git push -u origin release/2.6.0
# Bugfixes only until tag; migrations coordinated in release notes

# Tag after staging sign-off
git checkout release/2.6.0
git tag -a v2.6.0 -m "Release 2.6.0 - orders-api + email-worker"
git push origin v2.6.0

Branch lanes (Node backends)
  main              ← integration; always green CI
  feat/*            ← days; squash merge
  release/X.Y       ← weeks; coordinated deploy train
  hotfix/X.Y.Z      ← hours; from tag vX.Y.(Z-1)

When to reach for this:

Multiple services (API + workers) share a release calendar
Database migrations must align with API deploy order
Production runs tagged images, not floating main SHA
Onboarding engineers from frontend Git who never tagged releases

Working Example

Step 1 - Repo hygiene

# Never gitignore lockfiles
git check-ignore package-lock.json && echo "BAD" || echo "OK"
 
# .gitignore must exclude
# node_modules/
# dist/
# .env
# coverage/

// package.json
{
  "engines": { "node": "24.18.0" }
}

Step 2 - Conventional commits

git commit -m "feat(orders): add refund endpoint [API-412]"
git commit -m "fix(worker): retry webhook on 429 [API-415]"
git commit -m "chore(deps): bump fastify to 5.x [API-420]"

Ticket ID in every commit enables git cherry-pick to release/* and hotfix/*
Squash merge features to main for one-commit-per-ticket history

Step 3 - Coordinated release with workers

## Release 2.6.0 checklist
- [ ] orders-api migration 20260709_refunds.sql merged to release/2.6.0
- [ ] email-worker compatible with new event schema
- [ ] Deploy order: migration → worker → API (document in runbook)
- [ ] Tag v2.6.0 triggers GitHub Actions release workflow

Step 4 - Hotfix from tag

git checkout -b hotfix/2.5.1 v2.5.0
# fix only production bug
git tag -a v2.5.1 -m "Hotfix: pool leak in webhook handler"
git push origin v2.5.1
# Cherry-pick fix SHA to main AND open release/2.6.0 if still active

Branch Policy Table

Branch	Lifetime	Merge policy
`main`	Permanent	Squash merge from PRs; always CI green
`feat/*`	1-3 days	Rebase or merge `main` daily
`release/X.Y`	Until tag shipped	Bugfixes only; no new features
`hotfix/*`	Hours	From production tag; backport to `main`

Node-Specific Hygiene

Commit package-lock.json - Docker and CI use npm ci
Do not commit dist/ - build in CI/CD pipeline
Commit .env.example, never .env
Migration files in db/migrations/ merge before code that depends on them

FAQs

GitFlow with long-lived develop?

Avoid for backend teams shipping weekly. Trunk + short release/* matches container tag deploys and reduces migration drift.

Monorepo: one tag or per service?

Either monorepo tag triggering matrix deploy of changed services, or per-service tags (orders-api-v2.6.0). Document one pattern in CONTRIBUTING.md.

When to hotfix from tag vs merge main?

Hotfix from tag when production runs v2.5.0 but main already has v2.6.0 features not yet released.

GitHub Actions Integration - required checks
Git & GitHub Best Practices - portable summary
CI/CD Basics - PR vs release pipelines
Package Managers Best Practices - lockfile policy

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.

Git Basics for Node Teams

A cookbook for trunk-based flow with release tags on Node.js backend teams - short-lived feature branches, semver tags, and hotfix lanes that match API and worker deploy order.

Recipe

Quick-reference recipe card - copy-paste ready.

# Daily feature work
git checkout main && git pull --ff-only
git checkout -b feat/API-412-add-refund-endpoint
# ... commits with conventional messages ...
git push -u origin feat/API-412-add-refund-endpoint
# Open PR → squash merge to main after CI green

# Release cut (when API + workers ship together)
git checkout main && git pull --ff-only
git checkout -b release/2.6.0
git push -u origin release/2.6.0
# Bugfixes only until tag; migrations coordinated in release notes

# Tag after staging sign-off
git checkout release/2.6.0
git tag -a v2.6.0 -m "Release 2.6.0 - orders-api + email-worker"
git push origin v2.6.0

Branch lanes (Node backends)
  main              ← integration; always green CI
  feat/*            ← days; squash merge
  release/X.Y       ← weeks; coordinated deploy train
  hotfix/X.Y.Z      ← hours; from tag vX.Y.(Z-1)

When to reach for this:

Multiple services (API + workers) share a release calendar
Database migrations must align with API deploy order
Production runs tagged images, not floating main SHA
Onboarding engineers from frontend Git who never tagged releases

Working Example

Step 1 - Repo hygiene

# Never gitignore lockfiles
git check-ignore package-lock.json && echo "BAD" || echo "OK"
 
# .gitignore must exclude
# node_modules/
# dist/
# .env
# coverage/

// package.json
{
  "engines": { "node": "24.18.0" }
}

Step 2 - Conventional commits

git commit -m "feat(orders): add refund endpoint [API-412]"
git commit -m "fix(worker): retry webhook on 429 [API-415]"
git commit -m "chore(deps): bump fastify to 5.x [API-420]"

Ticket ID in every commit enables git cherry-pick to release/* and hotfix/*
Squash merge features to main for one-commit-per-ticket history

Step 3 - Coordinated release with workers

## Release 2.6.0 checklist
- [ ] orders-api migration 20260709_refunds.sql merged to release/2.6.0
- [ ] email-worker compatible with new event schema
- [ ] Deploy order: migration → worker → API (document in runbook)
- [ ] Tag v2.6.0 triggers GitHub Actions release workflow

Step 4 - Hotfix from tag

git checkout -b hotfix/2.5.1 v2.5.0
# fix only production bug
git tag -a v2.5.1 -m "Hotfix: pool leak in webhook handler"
git push origin v2.5.1
# Cherry-pick fix SHA to main AND open release/2.6.0 if still active

Branch Policy Table

Branch	Lifetime	Merge policy
`main`	Permanent	Squash merge from PRs; always CI green
`feat/*`	1-3 days	Rebase or merge `main` daily
`release/X.Y`	Until tag shipped	Bugfixes only; no new features
`hotfix/*`	Hours	From production tag; backport to `main`

Node-Specific Hygiene

Commit package-lock.json - Docker and CI use npm ci
Do not commit dist/ - build in CI/CD pipeline
Commit .env.example, never .env
Migration files in db/migrations/ merge before code that depends on them

FAQs

GitFlow with long-lived develop?

Avoid for backend teams shipping weekly. Trunk + short release/* matches container tag deploys and reduces migration drift.

Monorepo: one tag or per service?

Either monorepo tag triggering matrix deploy of changed services, or per-service tags (orders-api-v2.6.0). Document one pattern in CONTRIBUTING.md.

When to hotfix from tag vs merge main?

Hotfix from tag when production runs v2.5.0 but main already has v2.6.0 features not yet released.

GitHub Actions Integration - required checks
Git & GitHub Best Practices - portable summary
CI/CD Basics - PR vs release pipelines
Package Managers Best Practices - lockfile policy

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.

Git Basics for Node Teams

Search Documentation

Git Basics for Node Teams