Set up the workflow

There are two ways to add the workflow. Both produce a single file, .github/workflows/infragram.yml.

From the dashboard

In Repositories, click Set up workflow on an activated repository. The setup dialog:

• finds your root modules from the repository’s file paths. It doesn’t read their contents. Directories such as modules/, .terraform/ and test fixtures are skipped, because planning a child module gives either an error or a meaningless diagram. In a repository that publishes a module, the examples/ directories count as roots.
• suggests var files for each root. Files Terraform loads on its own (terraform.tfvars, *.auto.tfvars) are never offered, because passing them again could change their precedence.
• detects your Terraform version from .terraform-version, .tool-versions, or a required_version constraint.
• reads back an existing workflow. If infragram.yml already exists, running setup again starts from what it says. You can edit the file in either place.
• opens a pull request authored by you. The commit is yours, not a bot’s, and it lands on the infragram/setup-workflow branch. If the GitHub App hasn’t been granted permission to write workflows, you get a prefilled GitHub link or YAML to copy instead.

Keyboard shortcuts

Press ? in the setup dialog to see them all.

Shortcut	Action
A	Add a build
Alt 1–9	Focus a build
1–3	Choose the Gitleaks mode
Ctrl/⌘ ⇧ C	Copy the YAML
Ctrl/⌘ ⇧ G	Commit it yourself on GitHub
Ctrl/⌘ ↵	Open the pull request

By hand

.github/workflows/infragram.yml

name: Infrastructure diagram

on:
  pull_request:
    paths:
      - "infrastructure/**/*.tf"
      - "infrastructure/**/*.tfvars"
      - "infrastructure/**/.terraform.lock.hcl"

permissions:
  contents: read
  id-token: write

concurrency:
  group: infragram-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  diagram:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: hashicorp/setup-terraform@v4
        with:
          terraform_version: "1.9.8"
          terraform_wrapper: false
      - uses: actions/setup-go@v7
        with:
          go-version: stable
      - uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: arn:aws:iam::123456789012:role/infragram-plan
          aws-region: eu-west-1
      - uses: Tekchbila-Studios/infragram-action@v1
        with:
          working-directory: infrastructure
          var-files: |
            environments/common.tfvars
            environments/production.tfvars
          secret-scan: block

Why each line is there

Line	Why
on: pull_request + paths	Builds run only when infrastructure changes. Diagrams are tied to the pull request so the comment can find it.
id-token: write	Required. The Action authenticates with the workflow’s OIDC token. Without this permission it fails before planning.
contents: read	Lets actions/checkout read the code. Nothing in the workflow needs write access.
concurrency	A new push cancels the build still running for the previous one. Keep it at workflow level. See multiple environments.
runs-on: ubuntu-latest	Only Linux runners are supported, x64 or arm64.
terraform_version	Pin the version your team uses. setup-terraform takes an exact version here, not a constraint like ~> 1.9.
terraform_wrapper: false	The wrapper intercepts Terraform’s stdout. The Action pipes terraform show -json, and the wrapper would corrupt it.
setup-go	The collector is built from source on every run. Hosted Ubuntu images include Go, but containers and self-hosted runners may not.
configure-aws-credentials	Gives terraform plan read access to your account through OIDC. No stored keys. See AWS credentials.
secret-scan: block	This is the default, written out so a reviewer can see it. See Secret scanning.

Do not use pull_request_target

Infragr.am refuses builds triggered by pull_request_target. That event runs with the base repository’s secrets while checking out code from the pull request, which can expose privileged credentials to code from a fork.

Lock files

If the root has a .terraform.lock.hcl, terraform init honours it, and the Action installs exactly the provider versions it records. If there is no lock file, the Action resolves versions from your constraints and logs a notice. Lock files generated on macOS often lack Linux hashes, which is fine. To pin providers for the runner too, run:

terraform providers lock -platform=linux_amd64 -platform=darwin_arm64