# Add Conftest Policies to a Terraform Repository

Yes. An agent writes Rego policies for the rules your team states, tests them with conftest verify, runs them over every example in CI and names what fails, in a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-conftest-policies/terraform/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the repository's conventions before it writes a rule. In a module like terraform-aws-modules/terraform-aws-vpc, `versions.tf` requires Terraform at or above 1.0 and the AWS provider at or above 6.28, `variables.tf` declares two hundred and thirty-six inputs, among them `enable_flow_log` defaulting to `false`, `map_public_ip_on_launch` defaulting to `false`, `manage_default_security_group` defaulting to `true` and `enable_dns_hostnames` defaulting to `true`, and `examples/` holds thirteen directories from `simple` to `complete`, each a `main.tf` that calls the module with `source = "../../"` and a `tags` local carrying `Example`, `GithubRepo` and `GithubOrg`. `examples/complete/main.tf` sets `manage_default_security_group = true`, `map_public_ip_on_launch = false` and `enable_nat_gateway = true`; `examples/simple/main.tf` passes only `name`, `cidr`, `azs`, `private_subnets` and `tags`. `.pre-commit-config.yaml` runs `terraform_fmt`, `terraform_docs`, `terraform_tflint` with a fixed rule list, and `terraform_validate` through `pre-commit-terraform`, and `.github/workflows/pre-commit.yml` runs that configuration at the minimum and maximum Terraform versions through the `clowdhaus` composite actions. Nothing evaluates a policy, and there is no `policy/` directory.

It writes policies against HCL, not against a plan, because the examples need AWS credentials to plan and CI has none. Conftest's HCL parser turns each `main.tf` into a document where a module call appears under `module.vpc`, so the agent writes `policy/vpc.rego` with a `deny` rule for each statement in the prompt: a module call that sets `map_public_ip_on_launch` to `true`, one that does not set `enable_flow_log` to `true`, one whose `tags` lack a required key, and a `warn` for a call that leaves `manage_default_security_group` at the default without saying so. Each rule's message names the file, the module block and the fix, so a failing check reads like a review comment. The package name, the input shape and the `--parser hcl2` flag are documented in a short `policy/README.md`.

The policies get tests of their own. `policy/vpc_test.rego` holds a `test_` rule per deny with a small inline input that should pass and one that should fail, run with `conftest verify`, so a later edit to a rule cannot silently stop denying. The agent then runs `conftest test --parser hcl2 --policy policy examples/*/main.tf` and reads the result: with `enable_flow_log` off by default, the `simple` example and others fail the flow-log rule today, which is the point, and the pull request lists them as the current state rather than editing the examples, since `examples/README.md` says they show configurations and are not best practice.

Then it puts the check where the repository already runs checks. A `conftest` job joins `.github/workflows/pre-commit.yml` beside the existing ones, installing the conftest release binary with a pinned version and running `verify` and then `test` over `examples/`, and a `repo: local` hook in `.pre-commit-config.yaml` runs the same `test` command on changed `.tf` files so a developer sees a denial before pushing. The workflow is linted with `actionlint`, `pre-commit run --all-files` is run to confirm the new hook does not fight `terraform_fmt`, and the pull request opens with the failing examples named so the team can decide whether to flip the rule to `warn` or fix the examples.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add conftest policies to this Terraform repository. Read versions.tf, variables.tf, examples/README.md, every examples/*/main.tf, .pre-commit-config.yaml and .github/workflows/pre-commit.yml first. Write policy/vpc.rego against the HCL parser input with deny rules for a module call that sets map_public_ip_on_launch to true, one that does not set enable_flow_log to true, and one whose tags lack the Example, GithubRepo and GithubOrg keys, plus a warn for a call that leaves manage_default_security_group unset; make every message name the file, the block and the fix. Write policy/vpc_test.rego with a passing and a failing case per rule and a policy/README.md with the command to run. Run conftest verify and conftest test --parser hcl2 over examples/*/main.tf and record which examples fail today; do not edit the examples. Add a conftest job to .github/workflows/pre-commit.yml with a pinned binary version and a repo local pre-commit hook that runs the same test on changed .tf files. Run actionlint and pre-commit run --all-files, then open a pull request that lists each rule, its test cases and the examples that currently fail.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that adds `policy/vpc.rego`, `policy/vpc_test.rego` and `policy/README.md`, adds a job to `.github/workflows/pre-commit.yml`, and adds a local hook to `.pre-commit-config.yaml`. The description holds a table of rule, severity, message and the two test cases behind it, then a list of the examples that fail each rule today with the line that triggers it, and a note that the examples were left unchanged on purpose.

The run's record keeps the `conftest verify` and `conftest test` output, the `actionlint` result and the `pre-commit run --all-files` output, so a reviewer can see every policy test passed and read the real denials for `simple` and the other examples before deciding what to do with them.

Before merging, a reviewer decides per failing example whether to set `enable_flow_log = true` there or turn that rule into a `warn`, and confirms the pinned conftest version in the workflow matches the one the local hook installs.

## Run it on every Linear issue labelled policy

In the console, add an automation to the Project with this prompt and a `linear` trigger on `linear.issue.labeled`, filtered to the `policy` label and the platform team. When someone labels an issue such as "every VPC must ship flow logs and the three cost tags", the trigger puts the issue after the prompt and the run turns the rules it states into deny rules with tests. Only label changes made by a person in your Rush org fire the trigger, and the automation starts at most `max_runs_per_hour` runs in an hour.

From your own server, the same body goes to `POST /o/{org}/sessions` with the repository in `resources` and the issue URL beside it, read through your Linear connection, and a `request_id` that is a UUID v5 of the issue id, so a retried call returns the run already started rather than opening a second pull request.

## Why run it on Rush?

Policy code is where a typo passes silently: a Rego rule that never matches because the HCL input nests `module.vpc` one level deeper than the author assumed denies nothing and the check stays green. The agent runs `conftest verify` with a failing case per rule and then runs the policies over the repository's own thirteen examples in its sandbox, so a rule that denies nothing is caught before it reaches CI.

The commands and their output stay with the run, so the pull request can quote the exact denials the examples produce today, and the team's only decision is what to do about them.

## Frequently asked questions

### Why test the HCL instead of a terraform plan?

Planning the examples needs AWS credentials, which the pre-commit workflow does not have and should not need for a policy check. Conftest's HCL parser reads `main.tf` directly, so the rules run on every push without touching an account; a plan-based check can be added later for resource-level rules.

### Will the check fail CI as soon as it is merged?

Yes, for the examples the pull request names, because `enable_flow_log` defaults to `false` and several examples do not set it. The agent leaves the examples alone and lists the failures so the team chooses between fixing them and softening the rule to `warn` before merging.

### How are the policies kept correct over time?

`policy/vpc_test.rego` has a passing and a failing input per rule, and the CI job runs `conftest verify` before `conftest test`. A rule edit that stops denying its failing case breaks the build.

### Does this replace tflint or checkov?

No. `terraform_tflint` keeps its rule list in `.pre-commit-config.yaml`; conftest adds rules specific to this team, such as required tag keys and flow logs, that a generic linter does not know. The two run side by side in the same workflow.

## More Terraform jobs

- [Add Terraform Drift Detection to an EKS Configuration](https://getrush.ai/run/add-drift-detection/terraform/)
- [Set Up GitHub Actions CI for a Terraform Repository](https://getrush.ai/run/add-github-actions-ci/terraform/)
- [Add Infracost to CI for a Terraform Module](https://getrush.ai/run/add-infracost-to-ci/terraform/)

## More jobs like this: Turn a Linear label into a PR

- [Add a Context Menu Item to a Chrome Extension from a Linear Issue](https://getrush.ai/run/add-context-menu/chrome-extension/)
- [Trim Long Chats to the Model's Context Window with the AI SDK](https://getrush.ai/run/add-context-window-trimming/ai-sdk/)
- [Add CORS to a Flask API](https://getrush.ai/run/add-cors/flask/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
