# Quick start

Build your first Terraform pipeline in Buddy: plan with OpenTofu, approve the diff, and apply it, with state kept in a Buddy artifact.

This guide builds a pipeline that plans an infrastructure change, waits for approval, and applies it. It uses OpenTofu and keeps the state in a Buddy artifact, so you don't need a bucket or any other external storage.

## Before you start

- A project with your Terraform code in its repository. The guide assumes the code is in `infra/`.
- The code **does not declare a `backend` block**. Buddy adds one for the artifact backend. Use the `CUSTOM` backend if you want to keep your own. See [State backends](/docs/terraform/state.md).
- Credentials for the providers your code uses, for example an [AWS integration](/docs/integrations/amazon-web-services/amazon.md) or variables. See [Credentials and variables](/docs/terraform/credentials-and-variables.md).

## 1. Create an artifact for the state

The artifact backend stores the state in an existing artifact. Buddy doesn't create it for you.

1. Add an artifact of type **Bucket**, for example `infra-state`.
2. In **Initial version name**, enter `prod`. One version holds one state file.
3. Set **Access control** to **Buddy Auth**. The pipeline authenticates to the artifact with its run token. Don't use **Public** - the state can contain secrets.

![New Bucket artifact for the Terraform state](/docs/terraform/artifact-bucket-create.png 640x205)

## 2. Create the pipeline

1. Create a pipeline. In the **Workflow** tab, set the **Git** context to the branch the plan should run on, for example `main`.
2. Choose how runs start: add the **Git: Push** trigger to plan on every push to the branch, or leave the triggers empty and run the pipeline manually.
3. Open the **Permissions** tab of the `infra-state` artifact and give the pipeline **read-write** access.

![Pipeline Workflow tab with the main branch and Git: Push trigger](/docs/terraform/terraform-pipeline-workflow.png 640x188)

## 3. Add the Terraform Plan action

1. Add the **Terraform Plan** action to the pipeline.
2. Set **Tool** to OpenTofu and **Version** to a specific release, for example `1.12.6`.
3. Set **Working directory** to `infra`.
4. In the **Backend** tab, select **Buddy Artifact** and choose the `infra-state` artifact and its `prod` version.

![Terraform Plan action settings in the Run tab](/docs/terraform/terraform-plan-config.png 640x445)

## 4. Add Approve Run

Add the **Approve Run** action after the plan. The run stops there until someone with permission approves it. Before approving, they can open the Plan action and review the diff.

To skip the approval when nothing changes, see [Conditional apply](/docs/terraform/plan-and-apply.md#conditional-apply).

## 5. Add the Terraform Apply action

Add **Terraform Apply** after Approve Run. Use the **same** tool, version, working directory, workspace, and backend as in the Plan action. You don't have to set a plan file: Apply picks up the one from the Plan action automatically.

![Pipeline with Terraform Plan, Approve Plan, and Terraform Apply](/docs/terraform/terraform-pipeline-actions.png 640x551)

## 6. Run it

Run the pipeline. When it stops at Approve Run, open the Plan action to see the resource diff, then approve.

![Run paused at Approve Run with the plan diff above](/docs/terraform/terraform-run-overview.png 640x746)

## The same pipeline in YAML

```yaml
- pipeline: Infrastructure
  events:
    - type: PUSH
      refs:
        - refs/heads/main
  actions:
    - action: Plan
      type: TERRAFORM_PLAN
      tool: OPENTOFU
      version: 1.12.6
      working_directory: infra
      backend:
        type: ARTIFACT
        artifact: infra-state
        artifact_version: prod
    - action: Approve
      type: WAIT_FOR_APPLY
      description: Review the plan before applying it.
    - action: Apply
      type: TERRAFORM_APPLY
      tool: OPENTOFU
      version: 1.12.6
      working_directory: infra
      backend:
        type: ARTIFACT
        artifact: infra-state
        artifact_version: prod
```

## Next steps

- [Plan and Apply](/docs/terraform/plan-and-apply.md): how the plan file reaches Apply, `additional_args`, and conditional apply.
- [State backends](/docs/terraform/state.md): S3, GCS, or your own backend.
- [Drift detection](/docs/terraform/drift-detection.md): a scheduled check for changes made outside of Terraform.


---
Original source: https://buddy.works/docs/terraform/quickstart