Skip to content

Add a GitHub workflow

This section shows you how to add a workflow to your infrastructure repository that runs Terraform whenever your team make changes to a specific stack directory.

Step 1: Add the workflow to your repository

Navigate to the root your infrastructure repository (like pirates-iac) and run:

mkdir -p .github/workflows && cd .github/workflows
ok workflows

Choose terraform_on_changed_dirs.yml from the list.

Step 2: Configure when the workflow should run

Open terraform_on_changed_dirs.yml. Configure the on event to match your setup. For example:

      - 'dev/**.tf'
      - 'dev/**.yml'
      - main

      - 'dev/**.tf'

Step 3: Configure paths and environments

Edit the attribute jobs.changes.outputs.stack_paths_environments.

It should like this:

stack_paths_environments: >
  "dev/app-treasures": "pirates-dev-app-treasures",
  "prod/app-treasures": "pirates-prod-app-treasures",


  • dev/app-treasures with the path to the application stack
  • pirates-dev-app-treasures with the name of the GitHub environment you created in the previous section.

Step 4: Path filters

Since GitHub Actions workflows doesn't provide information about which paths changed, you need to use a third party action to get this information.

- name: Get changed files
  uses: dorny/paths-filter@main
  id: filter
    filters: |
        - dev/app-treasures/*.tf
        - dev/app-treasures/*.yml
        - prod/app-treasures/*.tf
        - prod/app-treasures/*.yml

Replace the filters block with the stacks for one or more applications.

Spend some time to reflect on structure this. Different files for different paths/environments/strategies etc.

Step 5: Customize the workflow variables

Change the role session name to <iac_env>-<stack_name>-${{ github.run_id }}. Example:

role_session_name: pirates-dev-app-treasures-${{ github.run_id }}

The next sections shows you how to set up secrets and IAM roles for the workflow.