Gate your CI pipeline.

Basic setup

Add this step to any GitHub Actions workflow that has a Terraform plan:

- name: Analyze Terraform plan
  id: rtp
  uses: readtheplan/readtheplan@v1
  with:
    plan-file: plan.json
    fail-on-threshold: dangerous

The action reads plan-file, runs the full analysis, writes outputs such as summary-json and risk-counts, and fails only when the configured threshold is met. Leave fail-on-threshold empty for report-only mode.

Full workflow example

name: Terraform plan review
on:
  pull_request:
    paths:
      - '**.tf'
      - '**.tfvars'

jobs:
  plan-and-analyze:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      actions: read
    steps:
      - uses: actions/checkout@v4

      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: "1.6"

      - name: Terraform plan
        run: |
          terraform init -input=false
          terraform plan -out=tfplan -input=false
          terraform show -json tfplan > plan.json

      - name: Analyze plan
        id: rtp
        uses: readtheplan/readtheplan@v1
        with:
          plan-file: plan.json
          fail-on-threshold: dangerous

      - name: Save summary JSON
        run: echo '${{ steps.rtp.outputs.summary-json }}' > readtheplan-summary.json

Agent gate for AI-driven PRs

If an AI agent opens a PR with Terraform changes, use agent-gate to enforce a human-approval gate on dangerous changes:

- name: Agent gate check
  run: |
    pip install readtheplan
    readtheplan agent-gate plan.json > agent-gate.json
    DECISION="$(jq -r .decision agent-gate.json)"
    echo "::notice::Agent gate decision: $DECISION"
    if [ "$DECISION" = "block" ]; then
      exit 1
    fi

- name: Block dangerous changes
  if: failure()
  run: |
    echo "## Agent gate blocked this plan" >> $GITHUB_STEP_SUMMARY
    jq -r '.pr_comment' agent-gate.json >> $GITHUB_STEP_SUMMARY
    exit 1

The agent gate enforces these rules:

Compliance framework gating

Use the CLI in a workflow step when you need SOC 2, ISO 27001, or HIPAA control IDs:

- name: SOC 2 compliance gate
  run: |
    python -m pip install readtheplan
    readtheplan analyze --framework soc2 --format json plan.json > readtheplan-summary.json

Each change is annotated with the relevant control (e.g. CC6.1, CC7.1 for SOC 2). The evidence output is audit-ready.

Evidence envelopes

Generate a signed evidence envelope for compliance audits with the optional signing extra:

- name: Generate SOC 2 evidence
  run: |
    python -m pip install "readtheplan[sign]"
    readtheplan analyze --framework soc2 --evidence evidence.json --sign plan.json

The envelope follows rtp-evidence-v1 schema — timestamped, signed, with full change-to-control mappings. Upload it as a CI artifact for your auditor.

Next steps