How it works

A build has two halves. Everything that touches your Terraform runs on your GitHub Actions runner. Infragr.am receives only the result: a sanitized, scanned description of your resources and how they connect.

 Your GitHub Actions runner                                 Infragr.am
┌──────────────────────────────────────────────────────┐
│ 1  preflight     am I eligible to build? ────────────┼──▶ yes / skip (reason)
│ 2  terraform     init + plan, with your credentials  │
│ 3  collect       plan JSON → sanitized bundle        │
│ 4  gitleaks      independent scan of the bundle      │
│ 5  upload        bundle only, over HTTPS ────────────┼──▶ 6  render four lenses
└──────────────────────────────────────────────────────┘    7  comment on the PR

1. Preflight

Before it does anything expensive, the Action asks Infragr.am whether this repository can build right now. It authenticates with the workflow’s GitHub OIDC token, which is short-lived, signed by GitHub, and names the exact repository and event. You don’t store an API key anywhere.

If the repository isn’t activated, or the account has used its monthly builds, the step ends green with a notice and nothing is planned. A runner never spends ten minutes planning a build that would be refused.

2. Plan

The Action runs terraform init and terraform plan in working-directory, with your var-files and vars. Terraform receives cloud credentials from your workflow, for example from aws-actions/configure-aws-credentials. The Action never reads or forwards those credentials.

To skip this step, pass a plan you already have with plan-path.

3. Collect

infragram-collect is a small Go program built from source on the runner at every run. It reads terraform show -json and writes a bundle with:

each resource’s address, type, planned actions, and non-secret attributes, such as names, CIDRs, ports and regions;
the references between resources, as your configuration writes them;
for module-heavy code, the names that locals blocks refer to, but never their values.

It drops every value Terraform marks sensitive, and any attribute whose name looks like a credential. The sanitization rules list them exactly.

4. Scan

Gitleaks v8.28.0, downloaded and checksum-verified, scans the exact bytes about to be uploaded. In the default block mode, a finding fails the step and nothing is sent. The scan is a second opinion that doesn’t depend on the collector’s own rules.

5. Upload

The bundle is sent over HTTPS, with the same OIDC token as identity. Infragr.am accepts it only if it matches the bundle schema exactly. Unknown fields are rejected, and so is any attribute whose name looks like a credential, checked again on the server.

6. Render

Infragr.am resolves the references into connections, places every resource in a trust zone, and renders each lens as its own diagram. Rendering is deterministic: the same plan always produces the same diagram. So a push that leaves the plan unchanged reuses the earlier render and doesn’t use quota.

7. Comment

On a pull request, Infragr.am posts one comment per environment, or updates the one already there, with a link to the diagrams. The comment mode controls when this happens.