Git & GitHub Best Practices

These are the habits that keep an AWS SDK repository safe and reviewable by default, not just fast to commit to.

Walk the list once now, then treat it as a review checklist before opening or approving any PR that touches AWS-facing code.

How to Use This List

Each item is a rule stated positively, with a one-line rationale.
Groups run roughly in order of impact: what never belongs in Git first, then branching, review, and history hygiene.
Check the boxes against your own repo as a quick audit.
Revisit when you add a new service integration or onboard a new contributor.

A - What Never Belongs in a Commit

Never commit AWS access keys, secrets, or tokens. Use the SDK's default credential chain or a secrets manager; a committed key is compromised the moment it's pushed.
Never commit .env files. Add them to .gitignore before the first commit, since untracking a file after the fact does not remove it from history.
Never commit generated or dependency artifacts. __pycache__/, node_modules/, and build output are regenerated, not authored, and only bloat the repo.
Never commit Terraform or CDK state files. .tfstate can contain resource attributes and sometimes secrets; keep state in a remote backend, not Git.

Let .gitignore do this work automatically, before you ever run git add.

cat > .gitignore <<'EOF'
.env
*.tfstate
*.tfstate.backup
__pycache__/
node_modules/
.aws-sam/
EOF

B - Scanning & Prevention

Install a pre-commit secret scanner. git-secrets (AWS Labs) or gitleaks catches an AWS key pattern before it leaves your machine.
Enable GitHub secret scanning and push protection. This server-side layer catches leaks even when a local hook was skipped or never installed.
Run a secrets scan in CI too, not only pre-commit. CI catches contributors who bypassed or never set up the local hook.
Allowlist known-fake example keys explicitly. Use the scanner's ignore file for values like AKIAIOSFODNN7EXAMPLE rather than disabling scanning entirely.

C - Branching & Workflow

Default to short-lived branches. Trunk-based development with fast merges keeps main close to what's actually deployed.
Keep PRs small and single-purpose. A focused diff reviews faster and reverts cleanly; don't mix a refactor with an infra change.
Name branches by intent. fix/, feature/, chore/ prefixes make a PR's purpose clear before anyone opens the diff.
Pull before you branch, and merge main in periodically on longer-lived work. This keeps conflicts small and frequent instead of one large one at the end.

D - Review & Branch Protection

Protect main with required reviews and status checks. No one, including admins, should be able to push directly to it.
Require a specific reviewer for infra-touching paths. A CODEOWNERS entry for iam/, infra/, and cloudformation/ routes the riskiest changes to someone who owns that risk.
Block force-push and branch deletion on protected branches. This preserves the audit trail of exactly what was reviewed and when.
Require a passing policy-linting check for IAM changes. Catch overly broad Action or Resource wildcards automatically, before a human review even starts.

E - Commit & History Hygiene

Write commit messages that say why, not just what. "Fix retry backoff for throttled DynamoDB writes" tells a future reader more than "fix bug".
Review your own diff before committing. git diff --staged catches a stray print statement or an accidental credential before it's ever recorded.
Rotate first, clean history second. If a credential does leak, deactivate it in IAM immediately; only afterward is rewriting history worth doing, and only for hygiene.
Squash noisy work-in-progress commits before merge. A clean history helps git blame and git log stay useful for the next person debugging an issue.

FAQs

What's the single highest-priority habit on this list?

Never committing credentials in the first place. Everything else - scanning, protected branches, rotation - exists to catch or contain the cases where that first line of defense fails.

Is a pre-commit hook enough on its own?

No. It only runs on machines where it's installed, so pair it with GitHub secret scanning/push protection and a CI scan so a bypassed or missing local hook isn't the only defense.

Why does .tfstate belong on the never-commit list?

Terraform state files can include resource attributes and occasionally secrets in plaintext, and they're meant to live in a remote backend with locking, not in Git history.

Should every PR require the same reviewer?

No. Route the mandatory extra reviewer only at infra-touching paths via CODEOWNERS; application-only PRs should merge under the general review requirement without added friction.

If I rewrite history to remove a leaked key, is the incident closed?

Not by itself. Rotate (deactivate) the key in IAM first - that's what actually closes the exposure. History cleanup afterward is good hygiene but doesn't undo a leak already scraped.

Why keep PRs small?

Small, single-purpose PRs review faster and revert cleanly. A PR that mixes a refactor with an infra change makes both harder to review and harder to safely undo if something's wrong.

Is blocking force-push overkill for a small team?

No - it costs nothing to configure and it preserves the review history, which matters the moment you need to reconstruct exactly what changed and when, regardless of team size.

What should a commit message actually include?

The reason for the change, not just a restatement of the diff. "Fix retry backoff for throttled DynamoDB writes" is far more useful later than "fix bug" or "update code".

Git Workflows for AWS SDK Teams - the branching model behind groups C and D.
Preventing Leaked AWS Credentials in Commits - the full detail behind groups A and B.
Protected Branches & Review Requirements for Infra-Touching PRs - the full detail behind group D.
Git & GitHub Basics - the underlying commands these habits apply to.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Git & GitHub Best Practices

These are the habits that keep an AWS SDK repository safe and reviewable by default, not just fast to commit to.

Walk the list once now, then treat it as a review checklist before opening or approving any PR that touches AWS-facing code.

How to Use This List

Each item is a rule stated positively, with a one-line rationale.
Groups run roughly in order of impact: what never belongs in Git first, then branching, review, and history hygiene.
Check the boxes against your own repo as a quick audit.
Revisit when you add a new service integration or onboard a new contributor.

A - What Never Belongs in a Commit

Never commit AWS access keys, secrets, or tokens. Use the SDK's default credential chain or a secrets manager; a committed key is compromised the moment it's pushed.
Never commit .env files. Add them to .gitignore before the first commit, since untracking a file after the fact does not remove it from history.
Never commit generated or dependency artifacts. __pycache__/, node_modules/, and build output are regenerated, not authored, and only bloat the repo.
Never commit Terraform or CDK state files. .tfstate can contain resource attributes and sometimes secrets; keep state in a remote backend, not Git.

Let .gitignore do this work automatically, before you ever run git add.

cat > .gitignore <<'EOF'
.env
*.tfstate
*.tfstate.backup
__pycache__/
node_modules/
.aws-sam/
EOF

B - Scanning & Prevention

Install a pre-commit secret scanner. git-secrets (AWS Labs) or gitleaks catches an AWS key pattern before it leaves your machine.
Enable GitHub secret scanning and push protection. This server-side layer catches leaks even when a local hook was skipped or never installed.
Run a secrets scan in CI too, not only pre-commit. CI catches contributors who bypassed or never set up the local hook.
Allowlist known-fake example keys explicitly. Use the scanner's ignore file for values like AKIAIOSFODNN7EXAMPLE rather than disabling scanning entirely.

C - Branching & Workflow

Default to short-lived branches. Trunk-based development with fast merges keeps main close to what's actually deployed.
Keep PRs small and single-purpose. A focused diff reviews faster and reverts cleanly; don't mix a refactor with an infra change.
Name branches by intent. fix/, feature/, chore/ prefixes make a PR's purpose clear before anyone opens the diff.
Pull before you branch, and merge main in periodically on longer-lived work. This keeps conflicts small and frequent instead of one large one at the end.

D - Review & Branch Protection

Protect main with required reviews and status checks. No one, including admins, should be able to push directly to it.
Require a specific reviewer for infra-touching paths. A CODEOWNERS entry for iam/, infra/, and cloudformation/ routes the riskiest changes to someone who owns that risk.
Block force-push and branch deletion on protected branches. This preserves the audit trail of exactly what was reviewed and when.
Require a passing policy-linting check for IAM changes. Catch overly broad Action or Resource wildcards automatically, before a human review even starts.

E - Commit & History Hygiene

Write commit messages that say why, not just what. "Fix retry backoff for throttled DynamoDB writes" tells a future reader more than "fix bug".
Review your own diff before committing. git diff --staged catches a stray print statement or an accidental credential before it's ever recorded.
Rotate first, clean history second. If a credential does leak, deactivate it in IAM immediately; only afterward is rewriting history worth doing, and only for hygiene.
Squash noisy work-in-progress commits before merge. A clean history helps git blame and git log stay useful for the next person debugging an issue.

FAQs

What's the single highest-priority habit on this list?

Never committing credentials in the first place. Everything else - scanning, protected branches, rotation - exists to catch or contain the cases where that first line of defense fails.

Is a pre-commit hook enough on its own?

No. It only runs on machines where it's installed, so pair it with GitHub secret scanning/push protection and a CI scan so a bypassed or missing local hook isn't the only defense.

Why does .tfstate belong on the never-commit list?

Terraform state files can include resource attributes and occasionally secrets in plaintext, and they're meant to live in a remote backend with locking, not in Git history.

Should every PR require the same reviewer?

No. Route the mandatory extra reviewer only at infra-touching paths via CODEOWNERS; application-only PRs should merge under the general review requirement without added friction.

If I rewrite history to remove a leaked key, is the incident closed?

Not by itself. Rotate (deactivate) the key in IAM first - that's what actually closes the exposure. History cleanup afterward is good hygiene but doesn't undo a leak already scraped.

Why keep PRs small?

Small, single-purpose PRs review faster and revert cleanly. A PR that mixes a refactor with an infra change makes both harder to review and harder to safely undo if something's wrong.

Is blocking force-push overkill for a small team?

No - it costs nothing to configure and it preserves the review history, which matters the moment you need to reconstruct exactly what changed and when, regardless of team size.

What should a commit message actually include?

The reason for the change, not just a restatement of the diff. "Fix retry backoff for throttled DynamoDB writes" is far more useful later than "fix bug" or "update code".

Git Workflows for AWS SDK Teams - the branching model behind groups C and D.
Preventing Leaked AWS Credentials in Commits - the full detail behind groups A and B.
Protected Branches & Review Requirements for Infra-Touching PRs - the full detail behind group D.
Git & GitHub Basics - the underlying commands these habits apply to.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Git & GitHub Best Practices

Buscar en la documentación

Git & GitHub Best Practices