# Set Up GitHub Actions CI for a Terraform Repository

Yes. An agent adds a workflow that runs terraform fmt, init, validate and tflint on every pull request of your Terraform repo, with no cloud credentials needed.

[Run this on Rush](https://cloud.getrush.ai/run/add-github-actions-ci/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 configuration before writing YAML. In a repository like hashicorp-education/learn-terraform-provision-eks-cluster there is no `.github/` directory at all. `terraform.tf` sets `required_version` to `~> 1.3` and pins the `aws` provider at `~> 5.47.0`, `random` at `~> 3.6.1`, `tls` at `~> 4.0.5` and `cloudinit` at `~> 2.3.4`; `.terraform.lock.hcl` is committed and records `aws` 5.47.0, `cloudinit` 2.3.4, `null` 3.2.2, `random` 3.6.1, `time` 0.11.1 and `tls` 4.0.5. `main.tf` wires the `terraform-aws-modules/vpc/aws` module at 5.8.1, `terraform-aws-modules/eks/aws` at 20.8.5 with `cluster_version` 1.36 and two managed node groups, and the `iam-assumable-role-with-oidc` submodule at 5.39.0 for the EBS CSI driver; `variables.tf` has one variable, `region`, defaulting to `us-east-2`, and `.gitignore` already excludes `.terraform/`, state files and `*.tfvars`.

From that it writes `.github/workflows/terraform.yml` with two jobs that need no AWS account. The `validate` job checks out the code, installs Terraform with `hashicorp/setup-terraform` at a version inside the `~> 1.3` constraint, runs `terraform fmt -check -recursive -diff`, then `terraform init -backend=false -input=false` and `terraform validate`. Init without a backend still downloads the three registry modules and the six locked providers, which is what makes `validate` meaningful for a configuration built from modules, and the job caches `TF_PLUGIN_CACHE_DIR` keyed on the lock file so the provider download is paid once. The `lint` job installs `tflint` with `terraform-linters/setup-tflint`, adds a `.tflint.hcl` that enables the `aws` ruleset plugin, runs `tflint --init` and then `tflint` over the root module, so a deprecated argument or an invalid instance type in the node groups fails the check.

Two things in this repository need checking rather than assuming. The lock file carries provider hashes for the platform it was generated on; if it lacks `linux_amd64` entries, `terraform init` on the runner refuses the providers, so the agent runs `terraform providers lock -platform=linux_amd64 -platform=darwin_arm64` and commits the widened lock file in the same pull request, saying so. And `terraform plan` needs AWS credentials and a backend, so the agent writes a commented `plan` job that would use `aws-actions/configure-aws-credentials` with an OIDC role, with the one variable `region` passed through, and explains in the pull request which repository settings make it live.

The proof is the same commands run in the sandbox first: `terraform fmt -check`, `init -backend=false`, `validate` and `tflint` all pass locally before the branch is pushed, and then the workflow runs on the pull request itself. If `fmt` reports a file, the agent formats it in the same pull request and lists it, since otherwise the first CI run would fail on code it did not write.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add GitHub Actions CI to this Terraform repository. Read terraform.tf, main.tf, variables.tf, outputs.tf, .terraform.lock.hcl and .gitignore first. Write .github/workflows/terraform.yml that runs on pull requests and pushes to the default branch with two jobs: one that installs Terraform at a version inside required_version, runs terraform fmt -check -recursive -diff, terraform init -backend=false -input=false with a plugin cache keyed on the lock file, and terraform validate; and one that installs tflint, adds a .tflint.hcl enabling the aws ruleset, runs tflint --init and tflint. Check whether the lock file has linux_amd64 hashes and widen it with terraform providers lock if it does not. Add a commented plan job that uses OIDC credentials and explain what it needs. Run every command in the sandbox first; if fmt reports files, format them and list them. Open a pull request and make the workflow pass on it.",
  "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 on its own branch adding `.github/workflows/terraform.yml` and `.tflint.hcl`, plus `.terraform.lock.hcl` when the lock needed Linux hashes and any `.tf` file `fmt` reformatted. No resource, module version or variable changes.

The description lists each job and its steps, the Terraform version chosen and the constraint it satisfies, the ruleset `tflint` loaded, whether the lock file was widened and why, and the local output of the four commands. The workflow's own run on the pull request is the second proof, and the commands are in the transcript at `GET /o/{org}/sessions/{id}/messages`.

Before merging, a reviewer checks the Actions tab for the green run, decides whether to enable the commented `plan` job by creating the OIDC role and repository variable it names, and whether the workflow should also run on a schedule to catch provider deprecations between pull requests.

## Run it on every Terraform repository without CI

Start one run per repository from your own server: `POST /o/{org}/sessions` with this prompt and that repository in `resources`, one call each. `GET /o/{org}/github` lists every repository the Rush GitHub App installation can reach, so a script can find the ones with `.tf` files and no `.github/workflows/` directory and start a run for each. Each run has its own sandbox and its own branch.

Give the key a `webhook_url` and each run POSTs `run.completed` with its `session_url` when the turn finishes, so the pull request links collect on your side without polling. A key may have at most `max_concurrent` runs in progress at once, 4 by default, and a request past that answers `202` with `status: "queued"`, so a script over many Terraform repositories sends them all together and Rush feeds the queued runs in as slots free.

## Why run it on Rush?

Terraform CI fails for reasons that only show on the runner: a lock file without Linux hashes, a provider download that times out without a cache, a `validate` that needs modules `init` never fetched. On a laptop each is a push, a wait and a log read. In a Rush sandbox the agent runs the real `terraform init` against the registry, reads the lock file and fixes the cause before pushing, so the first run on the pull request is the one you see.

The result is a workflow with its own green run attached, and the step left out, `plan`, is written down with the credentials and settings it needs rather than silently skipped. Several repositories can be onboarded at once, each in its own sandbox and pull request.

## Frequently asked questions

### Does the workflow need AWS credentials?

No. `fmt`, `init -backend=false`, `validate` and `tflint` all run without a cloud account; `init` only talks to the Terraform registry for modules and providers. The `plan` job, which does need credentials, is included commented out with the OIDC setup it requires described in the pull request.

### Why might the lock file change?

`.terraform.lock.hcl` records provider hashes per platform. If it was generated on a Mac and holds only `darwin` hashes, `terraform init` on an Ubuntu runner refuses the providers. The agent checks the file and, if needed, runs `terraform providers lock` for both platforms and commits the result, with a note in the description.

### Which Terraform version does CI use?

One that satisfies the `required_version` constraint in `terraform.tf`, `~> 1.3` here, pinned explicitly in the workflow so a new release cannot change the result between runs. The pull request names the version and the constraint side by side.

### What does tflint add over validate?

`validate` checks syntax and types; `tflint` with the `aws` ruleset checks provider-specific facts, such as an instance type that does not exist or an argument the provider deprecated. On this configuration that covers the node group instance types in `main.tf` and the module inputs.

## More Terraform jobs

- [Add Infracost to CI for a Terraform Module](https://getrush.ai/run/add-infracost-to-ci/terraform/)
- [Make a Terraform Module's CI Run on OpenTofu Too](https://getrush.ai/run/add-opentofu-support/terraform/)
- [Post Terraform Plan Comments on Pull Requests](https://getrush.ai/run/add-plan-comments-to-pr/terraform/)

## The same job on other stacks

- [Add GitHub Actions CI to a Textual App](https://getrush.ai/run/add-github-actions-ci/textual/)
- [Set Up GitHub Actions CI for a Vapor App](https://getrush.ai/run/add-github-actions-ci/vapor/)
- [Set Up GitHub Actions CI for a VS Code Extension](https://getrush.ai/run/add-github-actions-ci/vscode-extension/)

## 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/)
