9  Pull request review checklist

Use this checklist when reviewing a Terraform pull request. You do not need to work through it in order — use it to make sure you have not missed anything.

Not every item applies to every PR. Use your judgement about what is relevant to the change in front of you.

9.1 Before you start

• The PR description clearly explains what changed and why
• The target environment directory is correct for the stated change
• A terraform plan output is attached or linked (required for non-production, pre-production, and production; recommended for sandbox)
• CI checks have passed: terraform fmt, terraform validate, tflint, and checkov

9.2 Code structure and quality

• Provider and Terraform version constraints are declared in versions.tf and pinned to specific versions or tight ranges
• All variables have a description and a declared type
• Sensitive variables are marked sensitive = true
• All outputs have a description
• Sensitive outputs are marked sensitive = true
• Resource names are meaningful and consistent
• No hardcoded project IDs, region names, or resource identifiers that should be variables
• Any committed .tfvars files contain only non-sensitive configuration (project IDs, regions, feature flags) — no passwords, tokens, or API keys

9.3 Security

• No hardcoded secrets, passwords, tokens, or API keys anywhere in the code or variable files
• IAM bindings use the most specific role available — no roles/owner or roles/editor without strong justification
• google_project_iam_binding vs google_project_iam_member is used correctly (binding is authoritative; member adds without removing)
• Storage resources have public access explicitly configured (usually disabled)
• Encryption at rest is explicitly configured on data resources in non-sandbox environments
• Audit logging is enabled where expected for the target environment
• All checkov suppressions have an inline comment explaining the rationale

9.4 Lifecycle and state

• prevent_destroy = true is set on stateful resources (databases, storage buckets) in pre-production and production
• Any ignore_changes rules have a comment explaining why the attribute is being ignored
• count and for_each usage is correct — changing between them on existing resources causes destructive replacement
• The plan does not show unexpected resource replacements (-/+)

9.5 Modules

• Changes to shared modules in modules/ are understood to affect all environments that call them
• Module README is present and updated if the module interface has changed
• Module inputs are validated where appropriate (using validation blocks)

9.6 Documentation

• Non-obvious configuration choices have inline comments explaining why
• Module README is up to date (generated by terraform-docs or equivalent)
• An ADR has been raised if the PR makes a significant or hard-to-reverse architectural decision

9.7 Environment-specific checks

Sandbox (01_sandbox/)

• No references to production project IDs or live data sources
• terraform plan output is attached or linked (recommended)

Non-production (02_dev_nonprod/)

• terraform plan output is attached or linked
• Logging is configured on resources that will carry logging in production
• IAM follows least privilege

Pre-production (03_stg_prod/)

• terraform plan output is attached or linked
• Deletion protection is enabled on stateful resources
• Resource configuration matches production (instance types, network topology, encryption)
• Monitoring and alerting are configured

Production (04_prd_prod/)

• terraform plan output is attached or linked
• All destructive changes are expected and explained
• Change has been tested in pre-production first
• IAM changes have been reviewed with particular care
• Deletion protection is enabled on all stateful resources
• If you are not confident in any aspect of this change, you have escalated to a platform engineer before approving

9.8 Approval

A PR is ready to merge when:

1. All required CI checks pass
2. At least one reviewer has approved
3. All unresolved review comments have been addressed
4. No items in this checklist are outstanding without a clear justification

Do not approve a production PR if you have outstanding doubts about what the plan will do. Approve once you are confident, or escalate if you are not.