Git & GitHub Best Practices

A condensed summary of the 25 most important Git and GitHub practices for Node.js backend teams - shared portable content; customize per org conventions.

main is always integration truth: Every merged PR passes CI; never leave main broken overnight - production pipelines assume a green tip (Git Basics for Node Teams).
Commit the lockfile: package-lock.json (or pnpm-lock.yaml) required for reproducible npm ci - never gitignore it.
Ticket IDs in every commit: feat(orders): refund endpoint [API-412] - cherry-picks to release/* and hotfix/* depend on traceable messages.
Squash merge features to main: One ticket, one commit on integration branch - simplifies cherry-pick to release lanes.
Short-lived feature branches: Target 1-3 days; merge or rebase main daily to avoid migration and lockfile conflicts.
Cut release/X.Y for coordinated trains: API + worker + migration ship together; new features land on main only until tag.
Release branch accepts bugfixes only: Enforce with branch protection, not Slack reminders during freeze windows.
Cherry-pick to release/*, never merge main into release/*: Merging pulls unvetted features into the release candidate.
Tag from release/* after staging sign-off: v2.6.0 triggers release CI; tag message lists deployables.
Merge release/* back to main after rollout: Preserve train boundary; delete release branch when complete.
Hotfix branches from tags: git checkout -b hotfix/2.5.1 v2.5.0 - not from main when it is ahead of production.
Backport every hotfix: Cherry-pick fix SHA to main and open release/* if still active.
Never force-push shared branches: main, release/*, hotfix/* history is audit evidence.
Pre-commit hooks mirror CI: Husky runs typecheck, lint, test - same as pr-checks.yml (GitHub Actions Integration).
PR template requires migration note: Schema changes need rollback SQL or expand-contract plan.
Branch protection requires quality check: Policy beats honor system.
Never commit .env or secrets: .env.example only; production via platform inject.
Do not commit dist/ or node_modules/: Build artifacts belong in CI/CD, not git.
Conventional commits for changelog automation: Pair with semantic-release if adopted.
Tag creation restricted: Tags trigger production - rulesets or release manager role.
Monorepo: document tag strategy: One monorepo tag vs per-service tags - pick one.
Worker + API schema changes in one PR or linked PRs: Event contract drift breaks async flows.
Review lockfile diffs on dependency PRs: Unexpected postinstall scripts are red flags.
Document rollback in release tag message: Image digests, migration down plan, feature flag kill switch.
Interactive rebase on private feat/* only: --force-with-lease before PR review; never on shared branches.

FAQs

GitFlow develop branch or trunk + release?

Prefer trunk (main) + short release/* + hotfix/* for Node services on container tags. Long-lived develop diverges from production SHAs.

Minimum Git setup for a solo developer?

main + feature branches + squash merge + Husky + tag-driven deploy. Add release branches when staging QA joins.

How do Git practices connect to CI/CD?

Tags trigger release pipelines; PRs trigger quality gates; branch protection connects both. See CI/CD Best Practices.

Biggest Git mistake on Node teams?

Deploying main tip to production while release/2.6.0 freeze is in progress - use tags and branch lanes consistently.

Git Basics for Node Teams - trunk flow and tags
GitHub Actions Integration - required checks and templates
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 & GitHub Best Practices

A condensed summary of the 25 most important Git and GitHub practices for Node.js backend teams - shared portable content; customize per org conventions.

main is always integration truth: Every merged PR passes CI; never leave main broken overnight - production pipelines assume a green tip (Git Basics for Node Teams).

Commit the lockfile: package-lock.json (or pnpm-lock.yaml) required for reproducible npm ci - never gitignore it.

Ticket IDs in every commit: feat(orders): refund endpoint [API-412] - cherry-picks to release/* and hotfix/* depend on traceable messages.

Squash merge features to main: One ticket, one commit on integration branch - simplifies cherry-pick to release lanes.

Short-lived feature branches: Target 1-3 days; merge or rebase main daily to avoid migration and lockfile conflicts.

Cut release/X.Y for coordinated trains: API + worker + migration ship together; new features land on main only until tag.

Release branch accepts bugfixes only: Enforce with branch protection, not Slack reminders during freeze windows.

Cherry-pick to release/*, never merge main into release/*: Merging pulls unvetted features into the release candidate.

Tag from release/* after staging sign-off: v2.6.0 triggers release CI; tag message lists deployables.

Merge release/* back to main after rollout: Preserve train boundary; delete release branch when complete.

Hotfix branches from tags: git checkout -b hotfix/2.5.1 v2.5.0 - not from main when it is ahead of production.

Backport every hotfix: Cherry-pick fix SHA to main and open release/* if still active.

Never force-push shared branches: main, release/*, hotfix/* history is audit evidence.

Pre-commit hooks mirror CI: Husky runs typecheck, lint, test - same as pr-checks.yml (GitHub Actions Integration).

PR template requires migration note: Schema changes need rollback SQL or expand-contract plan.

Branch protection requires quality check: Policy beats honor system.

Never commit .env or secrets: .env.example only; production via platform inject.

Do not commit dist/ or node_modules/: Build artifacts belong in CI/CD, not git.

Conventional commits for changelog automation: Pair with semantic-release if adopted.

Tag creation restricted: Tags trigger production - rulesets or release manager role.

Monorepo: document tag strategy: One monorepo tag vs per-service tags - pick one.

Worker + API schema changes in one PR or linked PRs: Event contract drift breaks async flows.

Review lockfile diffs on dependency PRs: Unexpected postinstall scripts are red flags.

Document rollback in release tag message: Image digests, migration down plan, feature flag kill switch.

Interactive rebase on private feat/* only: --force-with-lease before PR review; never on shared branches.

FAQs

GitFlow develop branch or trunk + release?

Prefer trunk (main) + short release/* + hotfix/* for Node services on container tags. Long-lived develop diverges from production SHAs.

Minimum Git setup for a solo developer?

main + feature branches + squash merge + Husky + tag-driven deploy. Add release branches when staging QA joins.

How do Git practices connect to CI/CD?

Tags trigger release pipelines; PRs trigger quality gates; branch protection connects both. See CI/CD Best Practices.

Biggest Git mistake on Node teams?

Deploying main tip to production while release/2.6.0 freeze is in progress - use tags and branch lanes consistently.

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 & GitHub Best Practices

FAQs

Related

Buscar en la documentación

Git & GitHub Best Practices

FAQs

Related