docs: guide for adding custom policy checks to Terraform stack pipelines

[devin-ai-integration]

Summary

New guide guides/terraform-policy-checks covering the full path platform teams have to walk today: copy a system stack pipeline, insert a policy custom step between plan and approve, and point stacks at the copy via the change_pipeline_id / destroy_pipeline_id default values at org, project, or environment scope.

The load-bearing details, all verified against shared-go/services/default_pipeline and shared-go/services/stackrun:

• Enforcement is just exit codes — a custom step exiting nonzero before approve means nothing reaches terraform:apply.
• The copy must keep the system inputs, the standard variant (resolveStackRunVariantAndInputs fails if the stack's requested variant is missing), plan_file_uri: << steps.plan.output.plan_file_uri >>, and the autoapprove input (addAutoapproveInputIfSupported only injects it when the pipeline declares it).
• Existing stacks pick up a new default on their next run; no module config change (stale pipeline IDs are refreshed at run prep).
• The primary example checks the checked-out config, not the plan: plan_file_uri is an S3 URI to a binary plan, so plan-based rules additionally need the same tool/version, an initialized dir, and bucket read access via infrastructure.permissions.attach. The guide says so rather than implying the URI is a local path.

Two accuracy fixes fell out of the research:

• modules/stack.mdx documented system pipeline IDs pipe_system_tf_change_pipeline / pipe_system_tf_destroy_pipeline, which don't exist. System pipelines are seeded with generated pipe_... IDs; only the given IDs tf-change-pipeline / tf-destroy-pipeline are stable, so the table now lists names + given IDs and tells you to read the ID from ravion pipeline list.
• pipelines/templating.mdx claimed "there are no operators", but expressions are evaluated with expr-lang and the system pipelines themselves use <<steps.plan.output.has_changes && !pipeline.input.autoapprove>>. Now documents boolean/comparison operators, with a destroy_count > 0 approval-gate example.

mint validate, mint broken-links, and the OG-image check all pass.

Link to Devin session: https://app.devin.ai/sessions/539c3dd601e7481090f600e108e81ff5
Requested by: @flybayer

Greptile Summary

The PR adds a guide for extending Ravion’s Terraform stack pipelines with custom policy checks and corrects related system-pipeline identifiers and templating documentation.

• Adds the policy-check workflow, configuration example, scoped rollout instructions, and destroy-pipeline guidance.
• Registers the guide in the documentation navigation.
• Replaces nonexistent fixed system-pipeline IDs with stable given IDs and discovery instructions.
• Documents boolean and comparison operators in pipeline expressions.

Confidence Score: 4/5

The PR appears safe to merge, with a non-blocking reproducibility concern in the policy-step example.

The documentation flow and command contracts are coherent, but installing an unconstrained Checkov release during every run allows policy behavior or availability to change without a pipeline-config change.

Files Needing Attention: guides/terraform-policy-checks.mdx

Important Files Changed

Filename	Overview
guides/terraform-policy-checks.mdx	Adds the end-to-end policy-check guide; the example’s unpinned runtime installation makes enforcement behavior non-reproducible.
modules/stack.mdx	Corrects system-pipeline identification and links readers to the new customization guide.
pipelines/templating.mdx	Documents supported boolean and comparison expressions and adds a conditional approval example.
docs.json	Adds the new Terraform policy-check guide to the Guides navigation.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Copy[Copy system pipeline] --> Insert[Insert custom policy step]
  Insert --> Configure[Apply custom pipeline config]
  Configure --> Default[Set scoped pipeline default]
  Default --> Plan[Terraform plan]
  Plan --> Policy[Policy check]
  Policy -->|exit 0| Approval[Approval]
  Policy -->|nonzero exit| Failed[Run failed]
  Approval --> Apply[Terraform apply]

Loading

Prompt To Fix All With AI

### Issue 1
guides/terraform-policy-checks.mdx:101
**Unpinned policy-tool installation**

Installing the latest Checkov release on every run makes enforcement non-reproducible: a package release or registry outage can change policy results or block stack changes without any pipeline configuration change. Pin a tested version or otherwise use a controlled tool artifact.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "docs: guide for adding custom policy che..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Ravion	🟢 Ready	View Preview	Aug 15, 2026, 2:39 PM

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[greptile-apps]

Unpinned policy-tool installation

Installing the latest Checkov release on every run makes enforcement non-reproducible: a package release or registry outage can change policy results or block stack changes without any pipeline configuration change. Pin a tested version or otherwise use a controlled tool artifact.

Prompt To Fix With AI

This is a comment left during a code review.
Path: guides/terraform-policy-checks.mdx
Line: 101

Comment:
**Unpinned policy-tool installation**

Installing the latest Checkov release on every run makes enforcement non-reproducible: a package release or registry outage can change policy results or block stack changes without any pipeline configuration change. Pin a tested version or otherwise use a controlled tool artifact.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[devin-ai-integration]

Fair point — fixed in 47a1842. The example now installs checkov==3.3.11, and the notes below it call out pinning explicitly, so readers don't copy an unpinned install into an enforcement path.

[devin-ai-integration]

Runtime verification in local Mintlify preview ✅

Tested on devin/1786804702-tf-policy-checks with npx mint dev (localhost:3000), all interactions done by clicking in a real browser.

New guide: /guides/terraform-policy-checks

Sidebar entry Terraform policy checks appears in the Guides group and is highlighted; title/description render; the Mermaid flow renders as an SVG; <Steps>, <Warning>, <Note> and <CodeGroup> all render as components with no raw MDX; every bash/YAML block is syntax highlighted.

<CodeGroup> tabs switch correctly — Project shows --parent-type project, Environment shows --parent-type environment:

In-page anchors (4/4 jump to the right heading)

#step-1-copy-the-system-pipeline-config, #step-2-create-your-own-pipeline, #step-3-add-the-policy-check-step, #step-4-make-your-pipeline-the-default all scroll to their Step heading.

Cross-links (7/7 load real pages)

/modules/stack#system-pipelines-and-customization, /pipelines/step-types#custom, /pipelines/templating, /pipelines/variants, /config-as-code/pipeline-config-file, /cli/reference/default-value, /module-definitions/definition-schema.

Edited pages still render (regression)

/modules/stack: new 3-column system-pipeline table with tf-change-pipeline / tf-destroy-pipeline, the ravion pipeline list sentence, the updated pipeline config pull command, and the new link to the guide (verified it navigates). Its own Mermaid diagram and Steps still render.

/pipelines/templating: operators wording lists &&, ||, !, ==, >, and the new approve_deletions example shows if: << steps.plan.output.change_summary.destroy_count > 0 >> literally (no HTML escaping).

Tested by Devin — session