Auto-Post Architecture Diagrams on Every IaC Pull Request

Every time your team opens a pull request that changes Terraform, Kubernetes, Bicep, or any other IaC file, reviewers face the same problem: they have to mentally simulate what the code change does to the actual infrastructure. The InfraSketch GitHub Action solves this by automatically posting a clickable architecture diagram link in the PR comment — no secrets, no paid plan, no setup beyond a single workflow file.

What the action does

When a contributor opens or updates a pull request, the action:

1. Reads the list of changed files from the GitHub API
2. Filters for IaC files — .tf, .bicep, terragrunt.hcl, Kubernetes YAML, CloudFormation templates, Pulumi TypeScript/Python, and Docker Compose files
3. Reads each file's content and auto-detects its format
4. Encodes the content into a shareable infrasketch.cloud URL
5. Posts a PR comment with a table of diagram links — one per IaC file
6. Updates the existing comment on subsequent pushes rather than spamming new ones

The PR comment looks like this:

## 🗺️ InfraSketch — Architecture Diagrams

Found 2 infrastructure files in this PR.

| File              | Format     | Status      | Diagram         |
|-------------------|------------|-------------|-----------------|
| infra/main.tf     | Terraform  | ✏️ modified | View diagram →  |
| k8s/deploy.yaml   | Kubernetes | 🆕 added    | View diagram →  |

Clicking "View diagram →" opens InfraSketch in the browser with the file content pre-loaded. The diagram renders immediately — no login, no account, nothing to install.

Setup: 2 minutes

Create the following file in your repository at .github/workflows/infrasketch.yml:

name: Architecture Diagram

on:
  pull_request:
    types: [opened, synchronize, reopened]
    paths:
      - '**/*.tf'
      - '**/*.tfvars'
      - '**/*.bicep'
      - '**/terragrunt.hcl'
      - '**/docker-compose*.yml'
      - '**/docker-compose*.yaml'
      - '**/__main__.py'
      - '**/index.ts'
      - '**/*.yaml'
      - '**/*.yml'

jobs:
  diagram:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4

      - uses: pandey-raghvendra/infrasketch@v4
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

That's it. Open a PR that touches a .tf file and the action posts the comment automatically.

Supported formats

The action auto-detects format from file extension and content — you don't need to configure anything per-format:

• Terraform — *.tf, *.tfvars
• Terragrunt — terragrunt.hcl
• Bicep / ARM — *.bicep, ARM JSON templates (detected by schema URL)
• Kubernetes — *.yaml / *.yml files containing apiVersion: and kind:
• CloudFormation — YAML/JSON containing AWSTemplateFormatVersion
• CDK — synthesized CloudFormation JSON with Resources key
• Pulumi — __main__.py or index.ts with @pulumi/ imports
• Docker Compose — docker-compose*.yml, compose.yml

How it differs from other diagram PR tools

Several tools post infrastructure-related comments on PRs, but they all have meaningful trade-offs:

• Pluralith — purpose-built for Terraform visualization with a beautiful diff view. Excellent tool, but the CI integration starts at $250/month per workspace. Free tier is local-only.
• Infracost — posts cost estimates as text tables. Doesn't generate architecture diagrams.
• Holori — generates diagrams and posts PR comments. Requires signup and a connected cloud account for full functionality.
• InfraSketch GitHub Action — fully free, no account, no secrets beyond the automatic GITHUB_TOKEN. Diagram links open instantly in any browser. Supports 8 IaC formats without per-format configuration.

The trade-off: InfraSketch does static analysis of the changed files rather than running terraform plan. This means it works without cloud credentials and without Terraform being initialized, but it won't show resources created by count or for_each expressions that depend on variable values.

Customizing which files trigger the action

The paths filter in the workflow controls which file changes trigger the action. You can narrow it to specific directories:

on:
  pull_request:
    paths:
      - 'infra/**/*.tf'
      - 'k8s/**/*.yaml'
      - 'deployments/**'

Or broaden it to catch all YAML files in a monorepo:

on:
  pull_request:
    paths:
      - '**/*.tf'
      - '**/*.yaml'
      - '**/*.yml'

Using it with a monorepo

InfraSketch works well in monorepos where infrastructure lives alongside application code. The action only processes files listed as changed in the PR — it won't scan the entire repository. A PR that changes services/api/main.go and infra/api/main.tf will post a diagram link only for infra/api/main.tf.

If you have multiple Terraform root modules in a monorepo (e.g. infra/vpc/, infra/eks/, infra/rds/), changes to any of them generate separate diagram links in the same PR comment table.

Combining with Checkov and Infracost

InfraSketch pairs naturally with other IaC PR tools. A common setup combines three GitHub Actions on the same PR:

• InfraSketch — architecture diagram links for visual review
• Checkov — security scan results as a text comment
• Infracost — cost estimate diff as a text comment

Beyond the PR comment, InfraSketch lets you paste the Checkov or Infracost JSON output directly into the diagram tool to overlay security findings or cost estimates visually on the architecture nodes. See the Checkov overlay guide and Infracost overlay guide for details.

# .github/workflows/iac-checks.yml — combine all three
name: IaC Checks

on:
  pull_request:
    paths: ['**/*.tf', '**/*.yaml']

jobs:
  diagram:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: pandey-raghvendra/infrasketch@v4
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

  cost:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: infracost/actions/setup@v3
        with:
          api-key: ${{ secrets.INFRACOST_API_KEY }}
      - run: infracost diff --path . --format json --out-file infracost.json
      - uses: infracost/actions/comment@v3
        with:
          path: infracost.json
          behavior: update

  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: bridgecrewio/checkov-action@v12
        with:
          directory: .
          output_format: cli

Frequently asked questions

Related articles

• Terraform Diagram Generator — Visualize HCL Architecture Instantly
• Visualize Checkov Security Findings on Your Architecture Diagram
• Visualize Infracost Estimates on Your Architecture Diagram