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.
View on GitHub Marketplace Free, no secrets needed. Works with Terraform, Bicep, Pulumi, Kubernetes, CloudFormation, CDK, and Docker Compose. Install the Action →
What the action does
When a contributor opens or updates a pull request, the action:
- Reads the list of changed files from the GitHub API
- Filters for IaC files —
.tf,.bicep,terragrunt.hcl, Kubernetes YAML, CloudFormation templates, Pulumi TypeScript/Python, and Docker Compose files - Reads each file's content and auto-detects its format
- Encodes the content into a shareable infrasketch.cloud URL
- Posts a PR comment with a table of diagram links — one per IaC file
- 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 }}
Note: permissions: pull-requests: write must be set on the job, not just the workflow. The github-token input defaults to the automatic token — you don't need to create any secrets.
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/*.ymlfiles containingapiVersion:andkind: -
CloudFormation — YAML/JSON containing
AWSTemplateFormatVersion -
CDK — synthesized CloudFormation JSON with
Resourceskey -
Pulumi —
__main__.pyorindex.tswith@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'
Large files: Files over 200 KB are detected but skipped — a warning appears in the PR comment. For large Terraform projects, use plan JSON (terraform show -json) pasted directly into infrasketch.cloud for the most accurate diagram.
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
Does the action need AWS, Azure, or GCP credentials?
No. InfraSketch does static analysis of your HCL/YAML source code — it never calls cloud APIs. Only GITHUB_TOKEN is needed, and that's provided automatically by GitHub Actions.
Does my code get sent to InfraSketch servers?
No. The action encodes your file content as a base64 URL hash. The diagram link opens infrasketch.cloud — a static website that decodes the hash in the browser and renders the diagram client-side. No content ever reaches InfraSketch servers.
The comment isn't appearing — what's wrong?
Check that permissions: pull-requests: write is set on the job block, not just the workflow. Also verify the paths filter matches your changed files — if no matching files changed, the action exits silently.
Can I use it with GitHub Enterprise?
Yes. The action uses the standard GitHub API via GITHUB_TOKEN — the same mechanism works on GitHub Enterprise Server 3.x+. No additional configuration needed.
Will it work with private repositories?
Yes. The GitHub Action runs within your repository's GitHub Actions context. The generated diagram links encode content in the URL hash — they open InfraSketch in the browser locally. Private repo code is never transmitted anywhere.
Install the InfraSketch GitHub Action Free, no secrets, works in 2 minutes. Supports Terraform, Bicep, Pulumi, Kubernetes, CloudFormation, CDK, Terragrunt, and Docker Compose. View on GitHub Marketplace →
Top comments (0)