feat: integrate Claude Terraform Plan Review action into plan-terraform workflow

[Cali93]

Terraform Plan: Automated Summary, Alignment Check, and Diagnostics

Closes https://linear.app/reown/issue/ISAI-151/ai-claude-code-review-gha-to-analyse-terraform-plan-ci-runs
Example run: https://github.com/reown-com/infra-monitoring-grafana/pull/92#issuecomment-3456401594

Why

• Terraform plan outputs can be noisy/verbose and easy to misinterpret in reviews.
• Provide an automated summary and alignment check against PR code changes to quickly flag:
  • Unexpected create/destroy actions
  • Possible unplanned side effects vs the code diff
  • Warnings/errors indicating risk (provider/deprecation, drift, unknown values)

What’s changed

• actions/plan-terraform/action.yml
  • Added optional input anthropic_api_key (default: empty).
  • Captures human-readable plan via terraform show and exposes it as plan_content.
  • Captures raw terraform plan logs and exposes plan_log (for warnings/errors).
  • Conditionally runs the Claude review step only if anthropic_api_key is provided.
• claude/terraform-plan-review/action.yml
  • Uses PR context available to Claude Code Action to align plan changes with the PR diff (no manual diff needed).
  • Accepts optional terraform_plan_log to summarize warnings/errors.
  • Output structure includes: Plan Summary, Alignment Check, Potential Drift/Hidden Dependencies, Risky/Destructive Changes, Warnings/Errors, and Verdict.
• claude/terraform-plan-review/README.md
  • Documented alignment check behavior based on PR context and review output structure.

How it works

• If anthropic_api_key is empty: the review step is skipped, preserving existing behavior.
• If provided: the action posts a concise analysis that:
  • Summarizes adds/changes/destroys and cost impact.
  • Confirms expected vs unexpected changes relative to the PR diff.
  • Highlights potential drift/hidden dependencies and risky/destructive changes.
  • Surfaces warnings/errors from plan_log.

Backward compatibility

• Safe-by-default: no key => review step does not run.
• Existing outputs (plan-file, output-file, plan) are unchanged.
• terraform plan is piped through tee with set -o pipefail, preserving failure semantics.

Potential issues and mitigations

• Large outputs: GitHub step outputs have limits (~1 MB). Very large plan logs could exceed limits.
  • Mitigations (follow-up options):
    • Truncate logs before emitting (top N lines + “…truncated…” + last M lines).
    • Filter to Warning/Error lines only (e.g., provider deprecations, data source errors).
• Noise vs value:
  • Full logs help catch risk signals absent from terraform show.
  • Truncation/filtering balances signal vs size constraints.

Testing notes

• Without anthropic_api_key: verify plan generation remains unchanged and no review runs.
• With anthropic_api_key: verify the review includes:
  • Alignment Check referencing PR diff context.
  • Warnings/Errors summarized from plan_log.

Files touched

• actions/plan-terraform/action.yml
• claude/terraform-plan-review/action.yml
• claude/terraform-plan-review/README.md

References

• Claude Code Action — enhanced example with progress tracking: docs/solutions.md

[linear]

ISAI-151 [AI] Claude Code Review GHA to analyse `terraform plan` CI runs automatically

[bkrem]

Thanks for tackling this! 💯 LGTM generally, think some things may still be a bit implicit in terms of documenting needed config (raised in the review)

We should be able to test drive this by referencing via uses: WalletConnect/actions/claude/terraform-plan-review@chore/tf-plan-cc-review elsewhere

(I also just realised we're missing Claude auto-review on this repo, resolving in another PR)

[bkrem]

Would be good to have an explicit full workflow file example (similar to https://github.com/WalletConnect/actions/tree/master/claude/auto-review#quick-start) bc I think the needed permissions are currently implicit here.

E.g. if we want to have Claude write this back to the PR it will need pull-requests: write etc

[bkrem]

@claude review

[claude]

Claude finished @bkrem's task —— View job

---

Code Review: Claude Terraform Plan Review Integration

I've reviewed this PR which adds Claude-powered Terraform plan analysis. The implementation is generally solid, but I've identified several issues that need attention.

---

Critical Issues

Issue 1: Missing Required Permissions Documentation

File: claude/terraform-plan-review/README.md
Severity: High

The README lacks a complete workflow example showing required GitHub permissions. The reviewer (bkrem) correctly identified this gap. Users need explicit guidance on the permissions: block required for the action to post PR comments.

Required permissions:

permissions:
  contents: read
  pull-requests: write
  issues: write
  id-token: write

Recommendation: Add a "Quick Start" section similar to claude/auto-review/README.md:42-81 that includes a full workflow file example with proper trigger conditions and permissions.

---

Issue 2: Deprecated ::set-output Command

File: actions/plan-terraform/action.yml:150-152
Severity: Medium

echo "::set-output name=plan-file::/tmp/plan.tfplan"
...
echo "::set-output name=output-file::/tmp/plan.txt"

The ::set-output command is deprecated by GitHub Actions and will be removed in future runner versions. This is inconsistent with the correct usage of $GITHUB_OUTPUT elsewhere in the same file (lines 155-165).

Reference: https://github.blog/changelog/2022-10-11-github-actions-deprecating-save-state-and-set-output-commands/

Recommendation: Replace with the modern $GITHUB_OUTPUT syntax:

echo "plan-file=/tmp/plan.tfplan" >> $GITHUB_OUTPUT
echo "output-file=/tmp/plan.txt" >> $GITHUB_OUTPUT

---

Issue 3: Incorrect Action Reference in Integration

File: actions/plan-terraform/action.yml:169
Severity: High

uses: WalletConnect/actions/claude/terraform-plan-review@master

Per the repository's own conventions (stated in CLAUDE.md and throughout the codebase), actions should be pinned to full 40-character commit SHAs, not branch names like @master. Branch references are mutable and create unpredictable behavior.

Recommendation: This should use a commit SHA or be parameterized to use the same ref as the calling workflow. However, since this is internal integration within the same repository, consider using a relative path like:

uses: ./claude/terraform-plan-review

This ensures users always get the version they checked out.

---

Medium Issues

Issue 4: Large Output Size Risk Not Mitigated

File: actions/plan-terraform/action.yml:159-165
Severity: Medium

The PR description acknowledges that GitHub step outputs have ~1MB limits and that "very large plan logs could exceed limits," but no mitigation is implemented. The code captures full plan logs without truncation or filtering:

PLAN_LOG=$(cat /tmp/plan.log)
echo "plan_log<<EOF" >> $GITHUB_OUTPUT
echo "$PLAN_LOG" >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT

For large infrastructure plans, this will silently fail or cause unexpected behavior when outputs are truncated.

Recommendation: Implement at least basic safeguards:

• Add a size check and truncate if necessary with a clear marker
• Or filter to Warning/Error lines only when size exceeds threshold
• Document the limitation in the README

Example:

if [ -f /tmp/plan.log ]; then
  PLAN_LOG=$(cat /tmp/plan.log)
  LOG_SIZE=${#PLAN_LOG}
  MAX_SIZE=900000  # Leave buffer under 1MB
  if [ $LOG_SIZE -gt $MAX_SIZE ]; then
    echo "⚠️ Plan log truncated (${LOG_SIZE} bytes)" >> /tmp/plan.log
    PLAN_LOG=$(head -c $MAX_SIZE /tmp/plan.log)
  fi
  echo "plan_log<<EOF" >> $GITHUB_OUTPUT
  echo "$PLAN_LOG" >> $GITHUB_OUTPUT
  echo "EOF" >> $GITHUB_OUTPUT
fi

---

Issue 5: Inconsistent Parameter Naming Convention

File: actions/plan-terraform/action.yml:52-55, claude/terraform-plan-review/action.yml:6-8
Severity: Low

The codebase uses kebab-case for input names (e.g., aws-access-key-id, app-name), but the new inputs use snake_case:

• anthropic_api_key (line 52)
• tfc_token (line 56)

And the terraform-plan-review action uses snake_case throughout:

• anthropic_api_key
• terraform_plan
• terraform_plan_log

Recommendation: For consistency with existing codebase conventions, rename to kebab-case:

• anthropic-api-key
• tfc-token
• terraform-plan
• terraform-plan-log

---

Minor Issues

Issue 6: Unhelpful Default in README Example

File: claude/terraform-plan-review/README.md:28
Severity: Low

The standalone example shows:

uses: WalletConnect/actions/claude/terraform-plan-review@master

This violates the repository's convention of pinning to commit SHAs. While this may be acceptable for documentation brevity, it sets a bad example.

Recommendation: Either:

1. Use @<commit-sha> with a note explaining it should be updated
2. Add a comment: # Pin to a specific commit SHA in production

---

Issue 7: Missing Input Documentation

File: claude/terraform-plan-review/README.md:46-51

The inputs table is missing the terraform_plan_log input that's defined in the action and mentioned in the PR description as a key feature.

Recommendation: Add to the inputs table:

| `terraform_plan_log` | ❌ | - | Optional raw plan logs for warning/error diagnostics |

---

Positive Observations

✅ Good secret handling: API key properly passed as input and marked as secret, never logged
✅ Backward compatible: Safe-by-default with empty anthropic_api_key skipping review
✅ Proper pipefail usage: set -o pipefail correctly preserves terraform plan exit codes
✅ Comprehensive prompt: The review prompt structure is well-designed with clear sections
✅ Progress tracking: Uses track_progress: true per Claude Code Action best practices

---

Summary

This is a valuable addition that brings AI-powered Terraform plan analysis to the repository. The core implementation is sound, but needs:

1. Documentation improvements (permissions example, missing input)
2. Deprecation fixes (::set-output replacement)
3. Convention alignment (commit SHA pinning, naming consistency)
4. Risk mitigation (output size handling)

The reviewer's feedback about missing permissions documentation is spot-on and should be addressed before merge. Consider also implementing output size safeguards given the acknowledged risk.

---

[bkrem]

UX thought: the full output is useful but I think it would be best to have Verdict up top and then have a Click to expand section underneath with the detailed report, similar to what the plan output step is currently doing.

I'm a bit worried that PRs will become super long if there's more than a couple of plans that happen.