# Add plan workflow

Add the CI/CD foundation and a Terraform plan workflow to your infrastructure repository.

## Step 1: Create a branch

```bash title="repo-iac/"
git checkout -b add-plan-workflow
```

## Step 2: Set up CI/CD common

The `cicd-common` stack creates the IAM roles and resources needed for GitHub Actions to run Terraform in your AWS accounts. You need it in **every environment** that you want to run GitHub Actions workflows against.

<!-- prettier-ignore-start -->
!!! note
    The examples below use a `dev` environment. Change the directory paths to match your own environment and directory structure.
<!-- prettier-ignore-end -->

Install the stack in your environment directory:

```bash title="repo-iac/environments/dev/"
ok pkg add cicd-common
cd cicd-common
ok pkg install
```

Update `config_override.tf`:

```hcl title="repo-iac/environments/dev/cicd-common/config_override.tf"
locals {
  trusted_repositories = [
    {
      name = "<repo-name>"
      type = "infra"
    },
  ]
}
```

| Field         | Description                 | Example       |
| ------------- | --------------------------- | ------------- |
| `<repo-name>` | Name of your IaC repository | `pirates-iac` |

Apply the stack locally so the IAM roles are available before the workflow runs:

```bash title="repo-iac/environments/dev/cicd-common/"
terraform init
terraform apply
```

Repeat for each remaining environment, such as `prod`.

## Step 3: Add configuration files

### Step 3.1: Add `.gp.cicd.json`

Download [.gp.cicd.json](https://github.com/oslokommune/golden-path-templates/blob/main/templates/gh-terraform-iac/.gp.cicd.json){:target="_blank"} to the repository root:

```bash title="repo-iac/"
gh api repos/oslokommune/golden-path-templates/contents/templates/gh-terraform-iac/.gp.cicd.json \
  --jq '.content' | base64 -d > .gp.cicd.json
```

Update these values (you can find them in `common-config.yml` in each of your environment directories):

| Field                     | Description                         | Example        |
| ------------------------- | ----------------------------------- | -------------- |
| `<team-name>`             | Your team name                      | `pirates`      |
| `<dev-aws-account-id>`    | AWS account ID for `dev`            | `123456789012` |
| `<dev-environment-name>`  | Name of your `dev` AWS environment  | `pirates-dev`  |
| `<prod-aws-account-id>`   | AWS account ID for `prod`           | `987654321098` |
| `<prod-environment-name>` | Name of your `prod` AWS environment | `pirates-prod` |
| `<aws-region>`            | Your AWS region                     | `eu-west-1`    |

### Step 3.2: Add CODEOWNERS

Add a `CODEOWNERS` file to define who owns the repository and approves PRs:

```text title="repo-iac/.github/CODEOWNERS"
* @oslokommune/<github-team-name>
```

| Field                | Description                                                               | Example        |
| -------------------- | ------------------------------------------------------------------------- | -------------- |
| `<github-team-name>` | The name of your [GitHub team](https://github.com/orgs/oslokommune/teams) | `utviklerflyt` |

### Step 3.3: Add Renovate configuration

Download [renovate.json5](https://github.com/oslokommune/golden-path-templates/blob/main/templates/gh-terraform-iac/renovate.json5){:target="_blank"} to the repository root:

```bash title="repo-iac/"
gh api repos/oslokommune/golden-path-templates/contents/templates/gh-terraform-iac/renovate.json5 \
  --jq '.content' | base64 -d > renovate.json5
```

This overwrites any existing `renovate.json5`. If you have custom Renovate configuration, merge it into the downloaded file.

<!-- prettier-ignore-start -->
!!! info "What is Renovate?"
    Renovate automatically creates pull requests to keep your dependencies up to date. Think of it as a better Dependabot. Learn more in the [Renovate reference documentation](../renovate.md).
<!-- prettier-ignore-end -->

## Step 4: Add the plan workflow

Download [`terraform-pr.yml`](https://github.com/oslokommune/golden-path-templates/blob/main/templates/gh-terraform-iac/.github/workflows/terraform-pr.yml){:target="_blank"} to `.github/workflows/terraform-pr.yml`:

```bash title="repo-iac/"
mkdir -p .github/workflows
gh api repos/oslokommune/golden-path-templates/contents/templates/gh-terraform-iac/.github/workflows/terraform-pr.yml \
  --jq '.content' | base64 -d > .github/workflows/terraform-pr.yml
```

Update these values:

| Field                 | Description                                             | Example      |
| --------------------- | ------------------------------------------------------- | ------------ |
| `<dev-iac-directory>` | The directory containing IaC for your `dev` environment | `stacks/dev` |

## Step 5: Create a pull request

Push the branch and create a pull request.

## Step 6: Verify the plan workflow in the PR

The plan workflow should run automatically in the PR. Verify that the **Plan / Summarize** check runs and completes successfully.

## Step 7: Merge the pull request

Merge the pull request.

## Step 8: Verify the plan workflow against all stacks

Manually trigger the plan workflow against all stacks to detect any issues:

1. Go to **Actions > Terraform PR > Run workflow**
1. Input `**` as the stack pattern
1. Run the workflow

Once the run finishes, you'll get a summary of running `terraform plan` against all stacks in your repository. Review the results. Ideally all plans report _No changes_.

If any stacks have issues or unexpected drift, either fix them before continuing, or make a note of which stacks are affected — you add them to an ignore list in the next guide.

<!-- prettier-ignore-start -->
!!! tip
    See the [`terraform-pr.yml` reference](https://github.com/oslokommune/reusable-terraform-pr?tab=readme-ov-file#inputs) for available configuration options, including `ignored-stacks`.
<!-- prettier-ignore-end -->

## Next steps

[Add the apply workflow](add-apply-workflow.md) to enable automated Terraform apply on pushes to your default branch.