Add Terraform to an agent

Terraform is a skill you add to an agent. With it, the agent plans changes from a folder of a GitHub repository, using a connected cloud account’s credentials, and applies a plan only after a person approves that exact plan. You set it up from the agent builder with a repository, a folder and a cloud account.

Before you start

• A cloud account connected on Infrastructure. Terraform runs with this account’s credentials. To apply, they must be allowed to make changes; read-only credentials can only plan. See Connect a cloud account.
• A runner. Terraform runs on the runner the cloud account signs in from. If there is none, add one under Connections → Runners.
• A GitHub repository that holds the Terraform code. For a private repository, add a GitHub access token under Connections → Vault first.
• A state backend declared in the code. The state stays where your Terraform code keeps it: Polo uses the backend the repository declares.

Add the skill

1. Open Agents. Choose Create agent and the Infrastructure agent template, or choose Edit on an existing agent.

2. Go to Review and create.

3. Under Tools it may use, find Skills and choose Add a Terraform skill.

4. Fill in the form:

   Field	What to enter
   Skill name	A name for this stack, such as “Network infrastructure”.
   GitHub repository	owner/name, such as acme/infrastructure.
   Folder	The folder inside the repository, such as envs/production. Leave empty for the root.
   Branch	The branch to plan from. The default is main.
   Environment it changes	For example production. Approval rules apply by environment.
   Cloud account	The connected account whose credentials Terraform uses.
   Repository access	The repository is public, or the vault secret that holds the token for a private one.

5. Decide what the skill may do:

   • Let it apply, after a person approves the plan is ticked by default. Untick it for an agent that only plans.
   • Let approved plans remove or replace resources is off by default. Tick it only if this agent should be able to propose destructive plans.

6. Choose Add skill.

The skill joins the agent’s tools, already ticked: Plan Terraform and, if you allowed it, Apply a saved Terraform plan. Then choose Create agent, or Save changes on an agent you are editing.

Plan

Give the agent a task, for example: “Plan the network stack for production and tell me what would change.”

Polo plans the head of the skill’s branch. The task shows a Saved Terraform plan card with:

• the stack, the repository and the directory;
• the commit that was planned and its branch;
• the changes, counted by kind, or No changes;
• when the plan expires.

If no plan could be made, the card reads Terraform plan not made and gives the reason.

Approve the exact plan

When the task calls for an apply, Polo proposes applying that saved plan and waits.

1. Open Approvals. The change is titled in plain words, such as “Apply the Terraform plan for checkout (production)”.
2. Review the plan summary, why Polo asks, what it checks afterwards, the rule that applies and when the request expires.
3. Choose Approve and execute, or Reject change with a reason.

What you approve is exactly what runs:

• The approval is bound to that one saved plan. A different plan needs a new approval.
• Once the plan has expired it can no longer be approved, only rejected. Ask Polo to plan again.
• Your approval rules decide who may approve. A rule for production can require an approver other than the person who asked. In that case the button reads Record approval until enough approvals are in.

See Approvals and guardrails.

After the apply

The runner applies the plan. Polo then verifies the result with a refreshed plan, which must show no changes, and records the outcome on the task. If the apply fails, the request’s history says whether it never ran, failed, or failed and left the stack needing recovery.

Limits to know

• Plans are made from the branch head. Polo cannot run a credentialed plan of a change that is not merged yet. For new code, Polo validates offline, opens a draft pull request, and plans after the merge. See Create infrastructure for a service.
• No cost estimate is attached to a plan.
• Planned, not built: OpenTofu and Pulumi, drift reports, resource import and state operations. The only drift check is the refreshed plan after an apply.

Note

Polo’s capability record lists Terraform plan and apply as verified locally: a real runner and the Terraform CLI on local state. It records no run against a live cloud account. Start with a non-production stack, and check Settings → What Polo can do for the current level.