Plan Comment Bots and Atlantis-style Workflows

Bring plan review into the pull request

A Terraform plan bot can run plan for a pull request and post a formatted summary where reviewers already discuss the change. Tools such as Atlantis can also accept authorized pull-request commands to plan or apply a project in a selected directory. This shortens feedback loops, but it moves infrastructure authority into a code-hosting integration and must be secured as carefully as a deployment pipeline.

The bot should identify the repository, pull request, commit, Terraform project directory, workspace, and state backend associated with its run. A plan comment should distinguish create, update, delete, and replacement actions, link to detailed output with restricted access, and indicate when the result is stale. Do not post raw plans containing sensitive values to a public or broadly visible comment.

Control execution and locking

A lock prevents concurrent runs from racing on the same state. The lock scope should match the workspace or project, not block unrelated infrastructure changes. The bot should release locks after completion and provide an operator procedure for stale locks. A failed or canceled run may have partial effects during apply, so do not automatically unlock or retry without inspecting state and provider outcomes.

Plan commands can often run with scoped read privileges; apply needs mutation authority and should require a separate authorization. Restrict apply comments to trusted roles or teams using repository permissions and an explicit allowlist. Verify the actor and the pull request state at execution time, not only when the comment is created. A stale approval or a comment from a bot account should not grant broad production access.

Keep command scope explicit

In a monorepo, map each Terraform directory to a project and workspace. The command should select a known directory rather than accept arbitrary shell fragments from a comment. Validate labels, branch, and state mapping. Prevent path traversal and injection by using structured configuration instead of interpolating user text into shell commands. Run with a controlled working directory and pinned Terraform and provider versions.

Comment bots can expose results to many readers. Redact sensitive output, limit artifact retention, and prevent a malicious pull request from printing environment variables. Use short-lived cloud credentials and separate trust for untrusted forks. Protect the bot configuration and webhook secret, and audit command actor, commit, plan artifact, approval, and apply result.

Maintain the collaboration contract

Define how the bot reacts to new commits: cancel or mark the old plan stale, then create a plan for the current head. Do not leave an old green plan comment looking current. Make failures actionable and distinguish Terraform errors, policy denials, lock contention, and platform outages. Keep a manual recovery path for the bot itself, but apply the same approval and audit controls.

The automation should make review easier without hiding responsibility. Humans still review destructive actions and approve production changes. The bot provides consistent execution, formatting, and state coordination; it is not the architecture decision-maker or a security boundary by itself.

Treat webhook events as untrusted input. Verify the webhook signature, reject replayed or malformed events, and fetch authoritative pull-request state from the code host before running a command. Rate-limit repeated requests and record the actor and commit. This prevents a forged comment or stale event from triggering privileged work.

Map pull requests to Terraform projects

For a repository with infra/network and infra/app roots, define an explicit project map. Each entry names the working directory, workspace, backend, and allowed target environments. When a pull request changes files under one root, run a plan only for that project. If a shared module changes, identify dependent roots and plan each affected workspace. Do not infer a production workspace from arbitrary pull-request text.

On a pull request command, verify repository, branch, current commit, author permissions, and command allowlist. Run terraform fmt, init, validate, policy checks, and plan in a controlled runner. Post a comment that includes the commit sha, project, workspace, action counts, policy status, and timestamp. Keep full logs in restricted artifacts and redact values in the comment. When a new commit arrives, mark the earlier plan as stale and cancel or supersede its pending work.

Authorize apply carefully

Allow apply only on a protected branch and only for authorized reviewers. Require explicit approval associated with the current plan and commit. Verify the pull request has not changed since review. Lock the workspace before apply and serialize other mutations. If an apply fails or is canceled, preserve logs and state information; do not blindly retry or release a lock while Terraform may still be operating.

Use an identity scoped to the target environment and prefer a short-lived credential flow. Plan and apply identities can be separated. The bot should not expose credentials to forked pull requests or arbitrary workflow edits. Protect webhook secrets, runner configuration, and project mapping with code-owner review. Record the user who invoked apply and the credential identity used.

Test abuse and recovery cases

Test a command from an authorized maintainer, an unauthorized contributor, and a fork. Try an unknown directory name, a stale commit, and a second apply while the workspace is locked. The bot should reject each unsafe case without executing a shell command from user text. Simulate a runner crash and verify the stale-lock procedure requires checking backend state and active operations.

Review comments for leakage. Use a plan with a sensitive output and verify the comment and logs do not reveal it to unauthorized users. Confirm detailed artifacts expire on schedule. Make the bot's output explain replacement and destroy actions clearly so reviewers do not have to parse a raw binary plan to understand risk.

Keep the workflow maintainable

Assign an owner to the bot and its project map. Update mappings when a root or workspace is added, and test that a shared module change triggers the intended plans. Version the bot and Terraform CLI, pin providers, and maintain a rollback path for bot upgrades. A comment bot is a production integration with credentials, state locks, and audit records; treat it like one rather than a convenience script.

A lock is not only a backend detail; it is user-facing coordination. Tell contributors which workspace is held, which run owns the lock, and how to wait or request safe recovery. Do not automatically force-unlock after a timeout: a slow runner may still be applying. An operator should confirm the process ended and inspect state before removing a lock.

Convenience expands the trust boundary

A bot that accepts commands from pull-request comments can trigger operations with repository and cloud authority. Authenticate the actor, restrict allowed commands, bind execution to a reviewed commit, and scope credentials by environment. Never interpolate comment text into a shell command. A safe command selects a configured project; it does not accept arbitrary paths, flags, or expressions from a user.

Plan output is visible collaboration data but may contain secrets. Redact summaries, restrict detailed logs, and expire artifacts. A bot should indicate when a plan is stale after new commits or state changes. Lock state per workspace and handle canceled applies carefully; the bot cannot infer that a canceled process made no changes.

Decide whether a bot is worthwhile

Comment-based workflows can reduce context switching and standardize plans for teams that work heavily in pull requests. They add webhook maintenance, runner security, command authorization, lock recovery, output formatting, and upgrade work. A hosted platform or a simple protected CI workflow may be easier for a small team. Compare total operational ownership, not only the convenience of a plan comment.

Avoid treating a bot as approval. A successful plan status is not a human review, and an authorized comment is not necessarily approval for every environment. Separate plan generation from apply authorization. Keep branch protection and environment rules as the enforcement layer, and audit the person and commit associated with each operation.

In an interview, explain how the bot maps repositories to workspaces, secures commands, prevents concurrent runs, redacts output, and gates apply. Discuss stale plans and partial-apply recovery. Then state when a simpler CI workflow is preferable. This frames the bot as controlled automation that improves collaboration while expanding the system's trust boundary.

The bot's identity should be narrowly scoped. Separate repository read access, pull-request comment permissions, and cloud permissions when the platform allows it. Plan jobs should use only the access required to read state and provider data; apply should use a distinct protected environment. Rotate webhook secrets, pin runner images, patch dependencies, and isolate jobs so one malicious configuration cannot read another job's credentials.

Model the bot as a small control plane. Its configuration maps a repository and changed paths to approved roots, workspaces, and environments. Review that map like production code. A pull-request author must not be able to add a root that points to a more privileged backend or change the map without the required owners. Prefer fixed commands such as plan and apply over free-form arguments. Validate command syntax and ensure the executable, working directory, and environment are controlled by the runner.

Comment output is part of the review record. Include the exact commit, run identifier, workspace, Terraform version, plan freshness, and action summary. Update or supersede comments when new commits arrive. Use a link to a protected artifact for detailed output, and avoid posting state values, secret-bearing outputs, or full environment information. Apply commands should reference a current plan and require a permission check at execution time, even if the comment was previously authorized.

Recovery needs ownership. Document how to identify an abandoned run, confirm no apply process is active, inspect state, release a stale lock, and regenerate a plan. Preserve the failed run's logs for authorized operators. A canceled apply may have completed provider operations before the runner stopped, so reconciliation comes before retry. Alert on repeated lock contention, webhook failures, stale plans, and unauthorized command attempts.

The bot should not be the only way to operate infrastructure. Maintain a protected manual path for platform incidents, but apply equivalent identity, review, state-lock, and audit controls. Periodically test both the bot path and the recovery path. This prevents a convenient integration from becoming a single unmaintained point of failure.