Gate your CI pipeline.

Basic setup

Scan a whole checked-out repository without choosing adapters file by file:

- name: Gate infrastructure project
  id: rtp
  uses: readtheplan/[email protected]
  with:
    tool: scan
    input-file: .
    framework: soc2
    fail-on-threshold: dangerous

Or set tool and input-file for one supported infrastructure artifact. Terraform remains the default for backward compatibility:

- name: Analyze Terraform plan
  id: rtp
  uses: readtheplan/[email protected]
  with:
    tool: terraform
    input-file: plan.json
    fail-on-threshold: dangerous

The action writes summary-json, change-count, risk-counts, and action-counts, then fails only when the configured threshold is met. Leave fail-on-threshold empty for report-only mode. The old plan-file and resource-change-count names remain compatibility aliases.

By default the action installs the CLI bundled at the same tag or commit, preventing action/package version skew. Set install-source: readtheplan only when you intentionally want the latest PyPI package instead.

Cross-tool gates

Use the same action step for structured plans and conservative configuration scanners:

- uses: readtheplan/readtheplan@<release-tag-or-commit-sha>
  with:
    tool: pulumi
    input-file: infra/preview.json
    framework: soc2
    fail-on-threshold: dangerous

# Other tool values:
# scan, terraform-config, terraform-lock, terraform-state, terragrunt, terramate, spacelift, cloudformation, cdk, bicep, azure, kubernetes, helmfile, skaffold, devspace, tilt, cue, jsonnet, tanka, ytt, vendir, kbld, imgpkg, kapp, pulumi-project, ansible, ansible-project, salt, salt-project, nix, dsc, cfengine, opa, sentinel, sops, jenkins, jenkins-jcasc, jenkins-project, teamcity, concourse, bamboo, codebuild, cloud-build, codepipeline, chef, chef-project, puppet, puppet-project

Generate structured plans or rendered manifests with their upstream tools first. For example, run helm template or kubectl kustomize before the action, then select tool: kubernetes. The action never executes infrastructure source code itself.

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/[email protected]
        with:
          input-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 and signed, with resource-specific control annotations separated from generic heuristic signals. The signature protects artifact integrity; the mappings do not by themselves establish control satisfaction.

Next steps