How to Add Architecture Diagrams to Terraform Pull Requests

You're reviewing a pull request that adds three subnets, a NAT gateway, and shifts an RDS instance into a private zone. The diff is 240 lines of HCL across four files. Somewhere in there is the question that actually matters: does this change expose anything new to the public internet?

You can read every line carefully, build a mental model of the resulting topology, and answer the question. Or you can look at a diagram.

This guide walks through three ways to put that diagram into the pull request itself — manually, with a self-hosted CI step, and with a hosted GitHub App.

Why The Pull Request Is The Right Place#

Three reasons.

Timing. The reviewer is already there. Asking them to open a separate tool, paste in the Terraform, and study the output is a workflow that nobody sustains.

Comparison. A diagram of the merged result is useful. A diagram of the delta — what changed between the base branch and the PR — is more useful. PRs are the only context where both states are cheap to access.

Audit trail. A diagram posted on the PR becomes part of the permanent record of why this change merged. Six months later, when someone asks why the architecture looks the way it does, the PR comment is the answer.

For the broader argument about why visual review beats text diffs, see Cognitive Debt: The Hidden Cost of Infrastructure as Code.

Approach 1: Manual Export#

The simplest approach is to generate the diagram locally and paste it into the PR.

How:

1. Check out the PR branch
2. Run a diagram tool against it (any of the ones in our tools comparison)
3. Export PNG or SVG
4. Drag the image into the PR comment box

When this works: small teams, infrequent infra changes, no strong need for the diagram to stay current after merge.

When it breaks: any team with more than a few PRs a week. Someone forgets, the diagram goes stale, the workflow dies. Manual steps in code review never survive contact with a busy sprint.

Approach 2: Self-Hosted CI Step#

The next step up is automating it in your existing CI.

How:

1. Add a GitHub Actions workflow that triggers on pull_request events affecting .tf files
2. In the workflow, install a CLI (inframap or terravision) and generate the diagram
3. Use a sticky-comment action (peter-evans/create-or-update-comment) to post or update a single PR comment with the diagram image
4. Store the image in the workflow's artifact bucket or push it to a branch

Strengths: stays in your infra, no external vendor, full control over the output format.

Trade-offs:

• You own the maintenance. The CI step breaks when the CLI updates, when GitHub Actions changes, when someone moves the artifact bucket.
• The diagram quality is whatever the underlying CLI produces. For most teams that means a flat graph, not a layered architecture view.
• You build the diff logic yourself. Showing "what changed since base" means generating two diagrams and comparing them — every team that goes down this road ends up writing that comparison code, and it's harder than it looks.

This approach is right when you have a hard policy against sending Terraform to a vendor, or when the maintenance cost is genuinely lower than the alternative for your team. It's wrong if you're choosing it just to avoid a procurement conversation.

Approach 3: A Hosted GitHub App#

The hosted option installs as a GitHub App on the repo and handles the PR commenting automatically.

How (with Infragr.am):

1. Install the Infragr.am GitHub App on your repository
2. Grant read access to pull request content
3. Optionally add an infragr.yml config file at the repo root
4. Open a PR that touches .tf files — the bot comments within a minute

What the comment contains:

• The updated architecture diagram, embedded as an image
• A summary line: "3 resources added, 1 zone changed, 1 public-facing endpoint added"
• A link to download the draw.io file for detailed review
• A link to the layered view (Network, Security, Compute, Data) for reviewers who want to inspect one concern at a time

If the PR gets new commits, the bot updates the existing comment instead of posting a new one. No noise.

Example infragr.yml#

Most setups don't need configuration — sensible defaults work for a single-environment Terraform repo. For monorepos or multi-environment setups, the config file gives you control:

The config supports filtering by directory (only watch infra/, ignore terraform/test-fixtures/), choosing which lenses to include (skip the Data lens if your repo has no data resources), and setting per-environment defaults (use prod.tfvars when commenting on PRs targeting main).

The config lives at the repo root and is read on every PR event. Changes to it take effect on the next PR.

What Reviewers See#

The reviewer's experience is the actual product. A few details that matter:

The image is the first thing in the comment. Reviewers scroll PRs fast — anything below the fold doesn't get seen. Diagram at top, summary line, then the link to the layered view for anyone who wants more detail.

Determinism means the diagram is diffable. Because Infragr.am renders deterministically, the diagram in this PR is visually comparable to the diagram in last month's PR. The same Terraform always produces the same output. This is what makes architectural drift tracking possible — if a resource moves, you can see it move.

Public-facing changes get called out. The summary line surfaces the specific class of change reviewers care about most: anything that changes the public-internet boundary. New ingress rules, new public IPs, security group changes that open ports — the things you want to be sure about before approving.

Security Considerations#

Terraform files often contain sensitive material — backend state references, provider configurations, occasionally hardcoded values that should not be hardcoded. Any approach that processes Terraform outside your perimeter needs scrutiny.

For hosted tools, the things to verify:

• Storage policy. Does the vendor store your Terraform after rendering, or process it in memory and discard? Infragr.am processes in memory; verify the same for any vendor you evaluate.
• Variable redaction. Are sensitive variable values redacted from the rendered output? Most reasonable tools do this; confirm.
• Permissions scope. The GitHub App should request the minimum permissions needed — read access to PR content, write access to issue comments. Anything more is a yellow flag.
• Self-hosted option. For regulated industries, the vendor should offer a self-hosted or in-VPC deployment. Infragr.am offers this on enterprise plans.

FAQ#

Does this work on monorepos with multiple Terraform roots?#

Yes, but you'll want an infragr.yml config that lists which directories to watch. Without it, the bot diagrams every .tf file it finds, which gets noisy in large repos.

What about Terragrunt?#

Supported by some tools, not others. Infragr.am supports Terragrunt with module resolution; verify with other vendors before adopting. CLIs typically need you to render the Terraform first via terragrunt run-all init.

Does the comment update or repost on new commits?#

It should update. If a tool reposts on every push, that's a bug — say so and switch tools. The PR conversation should not be cluttered by diagram updates.

Can I get a diagram of just the diff, not the full architecture?#

Yes. Infragr.am surfaces both — the full updated diagram for context, and a delta view that highlights only what changed. Other tools vary in how clearly they separate the two.

How long does the bot take to comment?#

Under a minute for small-to-medium repos. Large monorepos with hundreds of resources can take a few minutes. If it's slower than that, the rendering pipeline is doing something it shouldn't be.

What about GitLab or Bitbucket?#

The GitHub App is what's available today. GitLab support is on the roadmap; reach out if it's a blocker for you.

Closing#

The shortest path between "infrastructure changed" and "the right person reviewed it" runs through the pull request. A diagram in the PR comment is the single highest-leverage change you can make to a Terraform review workflow. Whether you build it yourself or install a GitHub App is a smaller decision than the decision to put the diagram there at all.