Skip to content
Infragr.amDocs

Quickstart

By the end of this page, every pull request that touches your Terraform will have a comment linking to its architecture diagrams.

Before you start

Section titled “Before you start”
  • A GitHub repository with a Terraform root module: a directory you can run terraform plan in.
  • AWS resources. AWS is the only provider drawn today; see supported resources.
  • Some way for the workflow to run terraform plan. Usually that is an AWS role the workflow can assume, covered in step 3. If another workflow already produces a plan, you can reuse it instead, and no cloud credentials are needed.

Set up

Section titled “Set up”

  1. Install the GitHub App

    Sign in at infragr.am/login with GitHub, then install the Infragr.am app on your user account or organization. You can grant it all repositories or only some.

    The app uses its access for two things only: posting the diagram comment on your Terraform pull requests, and, if you ask, opening one setup pull request that adds the workflow. You review and merge that pull request yourself.

  2. Activate the repository

    In the dashboard, open Repositories and click Activate on the repository. Activating is free. Builds count against your plan only when they run.

  3. Add the workflow

    Click Set up workflow. The dashboard finds the Terraform root modules in your repository and asks how the build gets a plan. Then it opens a pull request that adds .github/workflows/infragram.yml. The pull request is authored by you, not by a bot.

    If you would rather write it by hand, here is the smallest working workflow:

    .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_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

    No role yet? Create a read-only one with three AWS CLI commands.

  4. Open a pull request

    Change any .tf file under the working directory and open a pull request. The Action plans, sanitizes, scans and uploads. A few moments later this comment appears:

    Infragr.am architecture diagram

    Section titled “Infragr.am architecture diagram”

    View the diagram →

    Network, Compute, Data and Security views of what this pull request changes. Updated on every push; the link stays the same.

What the workflow log shows

Section titled “What the workflow log shows”

Each accepted build prints its run ID in three places: as a job annotation, in the plain log, and in the job summary.

Sanitization and independent Gitleaks scan passed. Diagram build submitted.
Infragr.am run ID: 3f0c9a4e-6d1b-4f7e-9a51-2a8c0e7d4b12
Infragr.am build URL: https://infragr.am/dashboard?section=diagrams&run=3f0c9a4e-…
Quote the run ID above when raising a support case.

The run ID is also exposed as the run-id output, so later steps can use it.

Next steps

Section titled “Next steps”