# GitHub Copilot CLI Terraform: A Practical Project Guide

URL: https://agentvera.dev/en/blog/copilot-cli-for-terraform/ · Published: 2026-11-01

Practical guide to using GitHub Copilot CLI on Terraform projects: project instructions, safe plan and review loop, testing, and parallel agent work.

**In short:**

- Use a short project instruction file with exact Terraform commands so the agent follows your environment and module conventions.
- Work in small plan-validate-review steps and never let the agent apply Terraform changes without human approval.
- Keep state, backend, and provider changes under careful review, and use worktrees and checkpoints for parallel work.

[GitHub Copilot CLI](/en/agents/copilot-cli/) can be a productive pair for Terraform work once you give it the right project context and a review loop. Run `copilot` in the repository root, keep Terraform state and backends explicit, and treat every proposed change as a plan before apply. This guide covers a practical workflow: project instructions, plan-small-verify steps, Terraform-specific pitfalls, testing, and running multiple agents with AgentVera.

## Where Copilot CLI earns its keep in Terraform repos

Terraform repos are mostly HCL plus a small amount of shell for backend init and plan scripts. The structure is explicit: resources, data sources, variables, outputs, and modules. GitHub Copilot CLI works well here because most changes are localized edits with clear names and relationships. A well-scoped Terraform task is easy to verify with `terraform fmt`, `terraform validate`, and `terraform plan`; the agent can produce a diff and you can review it as you would a teammate’s change. The main value is not generating whole environments from scratch, but making safe, incremental module and configuration updates while preserving existing conventions.

## Start with a tight .github/copilot-instructions.md contract

Create `.github/copilot-instructions.md` at the repository root. If an `AGENTS.md` exists, GitHub Copilot CLI reads that as well. Write the file as an operational contract, not a tutorial: exact commands for init, format check, validation, plan, apply policy, and test; folder conventions for environments and modules; and Terraform-specific rules around state, providers, and plan files. Keep it short enough that the agent actually follows it.

```markdown
# Terraform project instructions

## Commands
- Initialize: `terraform init -backend-config=env/backend.hcl`
- Format check: `terraform fmt -check -recursive`
- Validate: `terraform validate`
- Plan: `terraform plan -out=plan.tfplan`
- Apply: only after human approval; never run apply automatically.
- Test: `terraform test`

## Layout
- `modules/<name>/` for reusable modules; each module has variables.tf, outputs.tf, main.tf.
- `environments/<env>/` for root configurations; one backend per environment.
- Shared provider configuration in `providers.tf` at the root only.

## Rules
- Never edit state files or lock files directly.
- Prefer small, typed variables and clear descriptions.
- Keep provider versions pinned in `versions.tf`.
- Use existing modules before creating new ones.
- Do not commit `.terraform/`, `*.tfplan`, or local backend files.
```

Update the file when you change environments, backend layout, or test commands. For a broader workflow outside Terraform specifics, see [How to use GitHub Copilot CLI: a step-by-step guide](/en/blog/how-to-use-copilot-cli/).

## Plan-small-verify: the Terraform loop that keeps state safe

The safest loop is: initialize the backend once, start `copilot` at the repository root, give it a narrow task with the expected files to touch, let it edit and run `terraform fmt -check` and `terraform validate`, then stop and show the diff. Do not ask for apply until you have reviewed the plan output. If the task needs a provider change or a state move, split that into a separate step and ask the agent to propose commands first.

Useful prompts:

- Add a new `staging` root module under `environments/` by copying `environments/dev`, switching the backend key, and reusing the existing network and application modules. Run `terraform fmt -check` and `terraform validate`, then show the diff.
- Refactor the `networking` module to accept a `subnet_cidrs` map variable instead of separate list variables. Update all callers in `environments/dev` and `environments/prod`, and run validation.
- Create a new `aws_iam_policy` resource in `modules/app` from the inline policy in `main.tf`. Add an output and wire it through the root module. Show `terraform plan` output for dev.
- Investigate why `terraform plan` in `environments/prod` shows an unexpected replacement for the database instance. Report only the changed attributes and propose a minimal fix without changing state manually.
- Write a `terraform test` for the `naming` module that verifies a valid name and rejects an invalid character.

If the Terraform change is part of a larger feature, a spec-driven approach keeps the agent aligned; see [Spec-driven development with AI agents: a practical guide](/en/blog/spec-driven-development-with-ai/).

## Tasks Copilot CLI handles well and Terraform pitfalls to watch

Good fits include adding resources, data sources, and locals; renaming or retyping variables with all callers; splitting an inline block into a module; updating descriptions and validation rules; and formatting. Less safe are moving resources between modules or state, backend reconfiguration, provider version upgrades, and anything that requires `terraform state mv` or manual lock file edits.

The agent also tends to generate working HCL but can miss Terraform-specific consequences: hard-coded regions or environment names instead of variables, missing `depends_on` where ordering is real, or changes that break `terraform plan` because of unknown values. Watch for destructive replacement plans and sensitive outputs.

| Task type | Typical Copilot CLI use | Specific Terraform risk |
| --- | --- | --- |
| Add resources or data sources | Good: create resources, locals, and outputs in existing modules | Must use existing variables, providers, and aliases correctly |
| Refactor module variables | Good: rename or change type, update all callers | HCL type constraints can cause validate errors; check every environment |
| Split inline block into module | Good: move a resource block and wire inputs and outputs | State address changes; may need `terraform state mv` and import planning |
| Provider or backend changes | Risky: can generate correct syntax but wrong migration path | Lock file and backend init; never run apply or state commands without review |

Keep state, backend, and provider edits fully in the human review loop.

## Verification before apply: fmt, validate, plan, and tests

Verification for Terraform is mostly command output, not unit tests. After every agent edit, run the checks in this order: `terraform fmt -check -recursive`, `terraform validate`, then `terraform plan -out=plan.tfplan`. The agent can execute these, but you should read the plan summary yourself. For a module change, validate every environment that uses it; a variable rename that passes in dev may fail in prod because of different provider constraints or Terraform versions.

For drift investigation, `terraform plan -refresh-only` is useful; ask the agent to list only resource changes and avoid state writes. If the project defines `terraform test`, add explicit test cases for pure functions such as name generation and CIDR allocation, and have the agent run them after changes. Before apply, review the diff with `git diff` and check that no sensitive values are printed in plan output or `terraform output` calls.

## Parallel agents on one Terraform repo with AgentVera

AgentVera helps when you split Terraform work across several agents. Run one agent per environment or module in its own git worktree so changes to `main.tf` and `variables.tf` do not overwrite each other. When each agent’s turn ends, the automatic code review flags risky HCL or backend edits with file:line links, which is the right moment to catch a bad `terraform state` suggestion. Checkpoints let you undo a turn before it touches state or backend config. Token budgets keep plan-review loops from running away, especially when an agent repeatedly asks for approval on `terraform plan` output.

## Keep the review loop tight

GitHub Copilot CLI fits Terraform projects best when you treat it as a careful pair programmer: put the commands and module conventions in `.github/copilot-instructions.md`, keep tasks small, and always verify with `terraform fmt`, `terraform validate`, and `terraform plan` before apply. The agent is strong for repetitive module and variable edits; state, backend, and provider migrations should stay under your review. With those guardrails, it reduces the mechanical parts of Terraform work without taking control of your infrastructure.

## Frequently asked questions

**Can GitHub Copilot CLI write Terraform code and modules?** Yes. It can generate HCL for resources, data sources, variables, outputs, and modules. Review the output with terraform validate and terraform plan because the agent may not catch provider-specific constraints.

**How do I configure GitHub Copilot CLI for a Terraform repository?** Create a .github/copilot-instructions.md or AGENTS.md file at the repository root. Include exact commands for terraform init, fmt, validate, plan, and apply, plus environment and module folder conventions.

**Can GitHub Copilot CLI run terraform plan and apply?** It can run terraform plan and show the output, but you should not let it run terraform apply unattended. Review the plan diff and approve commands manually, especially for state or backend changes.

**How do I prevent GitHub Copilot CLI from breaking Terraform state?** Keep tasks small and ask it to stop after plan or validate. Never let it edit state files directly or run terraform state commands without explicit approval, and use a version control checkpoint before risky changes.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/