Pull Request Workflow Gates

Make infrastructure change visible before merge

An infrastructure pull request should show the planned resource actions, run policy checks, and collect approval before merge. A Terraform plan is the review artifact that explains whether resources will be created, changed, or destroyed. Branch protection can require successful validation and plan checks so an author cannot merge around a failed gate. The goal is to move review earlier, while the configuration and plan are still easy to change.

The plan should be tied to a commit and a workspace. A pull request that spans multiple roots or environments may need separate plans so reviewers know which state each change affects. Label the environment, workspace, and backend identity in the summary. Avoid posting full secret-bearing output; show resource addresses and action summaries while redacting sensitive values. Preserve the full plan only in controlled storage if apply requires it.

Run complementary checks

Formatting, initialization, validation, and static analysis catch inexpensive errors before a cloud-backed plan. Policy checks evaluate organizational rules such as encryption, approved regions, or public exposure. A plan can reveal drift and provider-computed changes that static scans cannot see. These checks complement one another; passing one does not imply all risks are addressed.

Make status checks required and stable. A check should report success only after its command has completed and its artifact is published. Avoid optional jobs whose failure can be ignored when they protect production. If a policy exception is necessary, require a reason, an owner, and an expiry or review date rather than a blanket suppression.

Separate review from apply

The pull-request plan is a proposal, not permission to mutate shared infrastructure. Apply should run from a protected branch after merge and approval, with a controlled identity. Where possible, apply the exact reviewed plan. If state changed and a new plan is needed, publish it and require review again. A merge approval does not authorize a different set of resource actions generated later.

Protect workflow configuration and branch rules as carefully as Terraform code. An author who can change the workflow may otherwise remove the check or expand credentials. Require code-owner review for changes to trust conditions, deployment environments, policy gates, and artifact access. Do not provide production credentials to arbitrary pull-request code, especially from forks.

Handle competing proposals

Two pull requests may plan changes against the same state. Plans can become stale when another change applies first. Use state locking during plan/apply and serialize applies per workspace. Re-plan after a conflicting change and review the updated result. A status comment should clearly indicate that the old plan is no longer current; keeping a green check on a stale artifact is misleading.

The pipeline should preserve audit evidence: commit, plan summary, policy results, reviewers, approval, applying identity, and apply output. Define retention and access so evidence remains useful without exposing secrets. A good PR gate makes dangerous actions visible, blocks unreviewed mutation, and gives the author actionable feedback.

Make destructive actions easy to spot. Replacements and deletes should receive stronger review than an in-place tag update, and policy can require an additional owner for high-impact resources. A plan comment should show whether actions are expected from the pull request or caused by drift. The reviewer needs the target state and workspace, not just a count of changed resources.

Configure required checks

For a Terraform repository, require a workflow that runs formatting, initialization, validation, static scanning, plan, and policy evaluation on a pull request. The job should publish a concise plan summary with create, update, and destroy counts, resource addresses, environment, and workspace. Require the workflow status in branch protection and require at least one infrastructure owner approval for production roots. An empty plan should still be a successful, visible result rather than a skipped check.

If one pull request changes several root modules, generate a separate plan per root and show each result. Do not mix state files or reuse an artifact name across workspaces. Include the source commit and provider lock hash. Keep binary plans in restricted artifacts because values can remain present even when text output is redacted.

Gate policy and exceptions

Run policy checks alongside the plan so reviewers see both proposed actions and rule violations. A policy that blocks a public storage resource should identify the resource address and the required remediation. For an approved exception, require a documented reason and expiration or follow-up. Do not let an inline comment silently suppress a critical policy without review.

Use branch protection to prevent merging when plan or policy status is missing. Protect workflow files with code owners and restrict who can change environment protection rules. Confirm that forks can run safe checks without receiving deployment credentials. If cloud-backed planning is necessary, run it only for trusted contributors or in an isolated account with minimal access.

Keep approval attached to the plan

After merge, apply from a protected branch with a production environment approval. Verify that the plan artifact corresponds to the reviewed commit and target workspace. If the plan is stale, rerun it and publish a new review status; do not treat the old approval as approval for changed actions. Serialize applies for each state and make cancellation behavior explicit.

Test the gate by opening a change that creates a resource, one that would destroy a resource, and one that violates policy. Confirm required checks block merge and the summary makes destructive actions conspicuous. Change the plan after approval and verify the apply job refuses the mismatched artifact. Test an unauthorized user and a forked pull request to prove credentials are withheld.

Improve reviewer signal

Plan output can be noisy. Group unchanged resources, highlight replacements and deletes, and link to a detailed secure artifact for authorized reviewers. Provide enough context to understand why a resource changes without dumping unrelated provider values. If a plan includes drift unrelated to the pull request, identify it as drift and decide whether to handle it separately; do not hide it in a large output block.

Review the workflow itself during security changes. Test branch protection, environment approvals, secrets scope, and artifact retention periodically. Record who approved and applied production changes. A useful PR workflow gives reviewers signal, prevents bypass, and ensures the post-merge operation still matches the reviewed proposal.

Policy rules should have a clear owner and a tested rollout path. Introduce a new blocking rule in report-only mode when existing repositories need remediation, then set an enforcement date and exception process. Keep policies deterministic and explainable so authors can reproduce failures locally. A policy failure should identify the violated requirement and a secure path to resolve it, not merely return a generic nonzero status.

Keep gates strong and actionable

An infrastructure gate that runs slowly or produces unreadable output encourages teams to bypass it. Run inexpensive checks first, scope plans to changed roots where safe, and report policy failures with resource addresses and remediation. Do not weaken a production gate merely to reduce wait time; improve caching, parallelize independent roots, or move static checks earlier while preserving the required controls.

A plan comment is not a substitute for branch protection. If the status is optional, a merge can proceed without it. A green status is also insufficient if it refers to a stale plan or the wrong workspace. Bind the artifact and approval to the commit and target state, and invalidate them when state changes materially.

Protect the workflow's own authority

The workflow can hold or request powerful credentials, so changes to its code are security-sensitive. Protect deployment definitions, trust policies, environment approvals, and branch rules with code-owner review. Do not execute arbitrary fork code with production secrets. Use short-lived credentials and separate plan from apply permission. Restrict access to plan artifacts and logs that may contain sensitive values.

Review exceptions as carefully as the rule. A suppression should identify its scope, rationale, approver, and expiry. A permanent broad exception turns a policy gate into documentation only. Keep the path for urgent changes explicit, auditable, and followed by retrospective review rather than inventing a hidden bypass.

In an interview, describe the required plan and policy statuses, branch protection, protected workflow changes, and separate apply approval. Explain how the exact plan is carried forward, how stale artifacts are invalidated, and how secrets are withheld from untrusted contributors. This frames a PR gate as both a review interface and an authorization boundary for infrastructure change.

A gate can become a bottleneck if every root is planned serially or a remote provider is unreliable. Parallelize independent workspaces while serializing operations against the same state. Cache provider plugins using the committed lock file, but never share mutable state or plan artifacts across roots. Show job duration and failure class so maintainers can improve reliability without weakening required review.

Branch protection should require the exact checks that matter and should apply to the protected target branch. Verify behavior for administrators, bot accounts, merge queues, and emergency changes; an undocumented bypass can invalidate the security model. Emergency paths should be narrow, auditable, and followed by a plan review and reconciliation. Workflow changes themselves need review because they can alter which checks run and which credentials are available.

Separate plan visibility from apply authority. Reviewers may need a readable summary, while only the protected apply environment needs the binary plan and write credentials. Restrict artifact access and expire it promptly. If a new commit changes the pull request, invalidate the previous result and require a new plan. If state changes after review, replan and make the changed proposal visible. Never present a stale green check as current approval.

Use explicit policy ownership for exceptions. A suppression should identify the resource, control, rationale, approver, and expiry date. When a rule changes, test it against representative plans and publish migration guidance. A gate that blocks without an appeal or remediation path encourages unsafe bypasses; a gate that always allows exceptions provides little protection. The balance is a clear default with time-bounded, reviewed exceptions.

Finally, evaluate the gate against real user flow. A contributor should be able to see a plan, understand a denial, revise the configuration, and receive a new result without manual administrator intervention. Measure cycle time and bypass rate alongside policy findings. The goal is a repeatable path to safe infrastructure change, not a collection of status checks whose failures no one can interpret.