Set up the GitHub Action

Post an interactive architecture diagram on every pull request, generated from your AWS CDK, Terraform or Pulumi build output — without giving ArcSync access to your source code.

VanLandinghamLabs/arcsync-action@v3Stable · MITNode 24 runtime

How it works

The action is a thin uploader. Your workflow synthesizes the infrastructure first, and the action collects the build output and uploads it to the ArcSync API, which parses it server-side and returns a Mermaid diagram plus a link to the interactive canvas on arcsync.dev. On pull-request runs it then posts the diagram as a PR comment.

Your stack	Build step	What `path` points at
AWS CDK	`cdk synth`	the `cdk.out` directory (every `*.template.json` in it)
Terraform	`terraform show -json tfplan > plan.json`	that single plan file
Pulumi	`pulumi preview --save-plan=plan.json`	that single plan file

For AWS CDK and Pulumi this is also the cheaper path: those are the two engines ArcSync otherwise synthesizes on its own servers, metered against your monthly server-synth quota. Running the action builds them in your CI instead, which does not consume that quota.

CloudFormation templates, Azure ARM templates and Serverless Framework projects are parsed statically and have no CI build output to send, so the action does not upload them — point ArcSync at the repository directly instead.

ArcSync never sees your source code

The action never clones your repository and uploads only the synthesized infrastructure description. If GITHUB_TOKEN is available it also reads basic repository metadata (name, description) to label the diagram — a best-effort lookup that is skipped silently when the token is absent.

Create credentials

Most repositories need no credential at all

Install the ArcSync GitHub App and the workflow authenticates with its own OIDC token — nothing to copy, store, or rotate. The steps below are for repositories where an App install is not possible, and for CI that is not GitHub Actions.

Sign in at arcsync.dev and open Settings → GitHub Action credentials.
Enter a label (your repo name works well) and click Create credential.
Copy the Client ID and Client Secret, then add them to your repository under Settings → Secrets and variables → Actions as ARCSYNC_CLIENT_ID and ARCSYNC_CLIENT_SECRET.

The secret is shown once

Store the client secret in your repository secrets immediately — it cannot be retrieved later. If you lose it, revoke the credential in Settings and create a new one.

Setting this up with a coding agent? Copy a prompt that points it at the agent-readable version of this page. It carries the gh secret set instruction and never the secret value — a prompt is logged, sent to a model provider, and sometimes written to disk.

Set up the ArcSync GitHub Action in this repository.

First read https://arcsync.dev/docs/github-action.md — it has the required
`permissions:` block and the correct `path` value for each IaC type.
Getting the permissions wrong has consequences that cannot be undone later.

Create a credential at arcsync.dev → Settings → GitHub Action credentials.

For the secret: run `gh secret set ARCSYNC_CLIENT_SECRET` and ask me to
paste the value interactively. Do not write it to a file, echo it, or
include it in a commit.

Then add the workflow and open a pull request.

Add the workflow

A complete workflow for an AWS CDK project. The two non-obvious lines:id-token: write is required — it lets the action prove which repository the upload came from, so nobody else can write to your diagram by naming your repo URL. Without it the action stops before uploading. pull-requests: write lets the action post the diagram comment; the action's github-token input defaults to the workflow's own token, so nothing else needs wiring for the comment.

name: Architecture diagram

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read
  id-token: write       # binds the upload to this repository
  pull-requests: write  # required for the PR comment

jobs:
  diagram:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npm ci
      - run: npx cdk synth
      - uses: VanLandinghamLabs/arcsync-action@v3
        with:
          path: cdk.out
          api-client-id: ${{ secrets.ARCSYNC_CLIENT_ID }}
          api-client-secret: ${{ secrets.ARCSYNC_CLIENT_SECRET }}

Open a pull request that touches your infrastructure and the diagram comment appears on the PR within the run. Subsequent pushes update the same comment instead of stacking new ones.

Terraform projects

For Terraform, point path at a terraform show -json file instead of a directory:

- run: |
    terraform init
    terraform plan -out=tfplan
    terraform show -json tfplan > plan.json
- uses: VanLandinghamLabs/arcsync-action@v3
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  with:
    path: plan.json
    api-client-id: ${{ secrets.ARCSYNC_CLIENT_ID }}
    api-client-secret: ${{ secrets.ARCSYNC_CLIENT_SECRET }}

Pulumi projects

For Pulumi, point path at a pulumi preview --save-plan file. The preview runs against a throwaway local stack, so it needs noPULUMI_ACCESS_TOKEN and never touches your deployed state — ArcSync only needs the resource graph the preview resolves.

- run: npm install --no-audit --no-fund # or your runtime's install step
- uses: pulumi/setup-pulumi@v2
- run: |
    pulumi login --local
    pulumi stack init arcsync-preview --non-interactive
    pulumi config set aws:skipCredentialsValidation true
    pulumi config set aws:skipMetadataApiCheck true
    pulumi config set aws:skipRequestingAccountId true
    pulumi preview --save-plan=plan.json --non-interactive
  env:
    PULUMI_CONFIG_PASSPHRASE: ''
    AWS_REGION: us-east-1
    AWS_ACCESS_KEY_ID: arcsync-stub
    AWS_SECRET_ACCESS_KEY: arcsync-stub
- uses: VanLandinghamLabs/arcsync-action@v3
  with:
    path: plan.json

Installing the ArcSync GitHub App writes this workflow for you, with the dependency-install step chosen from your project's runtime and a working-directory: added whenPulumi.yaml is not at the repository root.

Inputs

Input	Description
api-client-idOPT string	ArcSync client ID, created at arcsync.dev → Settings → GitHub Action credentials.
api-client-secretOPT string	ArcSync client secret — shown once when you create the credential.
pathOPT string · default: `cdk.out`	A `cdk synth` output directory (every `*.template.json` inside is uploaded), or a single plan file from `terraform show -json` or`pulumi preview --save-plan`.
commentOPT boolean · default: `true`	Post/update a PR comment with the diagram. Only applies to `pull_request` events.
outputOPT string	Local file path to write the returned Mermaid markdown, e.g. for committing to docs.
api-urlOPT string · default: `https://api.arcsync.dev`	ArcSync API endpoint. You only need this if ArcSync support tells you to change it.

Outputs

Output	Description
graph-url	URL of the interactive diagram on arcsync.dev.
graph-id	ArcSync graph ID, stable across re-runs on the same repo + branch.
mermaid	Mermaid markdown returned by the API — embeddable in READMEs and wikis.

Give the step an id to use the outputs in later steps:

- uses: VanLandinghamLabs/arcsync-action@v3
  id: arcsync
  with:
    api-client-id: ${{ secrets.ARCSYNC_CLIENT_ID }}
    api-client-secret: ${{ secrets.ARCSYNC_CLIENT_SECRET }}
- run: echo "Diagram: ${{ steps.arcsync.outputs.graph-url }}"

Pull-request comments

On pull_request events the action posts a single comment containing the Mermaid diagram and a link to the interactive canvas. The comment carries a hidden marker, so re-runs update the existing comment in place rather than adding a new one per push.

On pull_request runs the comment also includes an infra delta against the base branch. Free accounts see the resource count; Pro accounts see the per-resource table, with the changes highlighted in both the Mermaid diagram and the interactive canvas. The base branch needs its own run — the push trigger keeps main's diagram current so a pull request has something to diff against.

Set comment: "false" to skip commenting entirely.
If GITHUB_TOKEN is missing the action logs a warning and skips the comment — the run still succeeds and the outputs are still set.
On non-PR events (push, workflow_dispatch, schedules) no comment is attempted; use the graph-url output instead.

Troubleshooting

Symptom	Fix
No artifacts found at 'cdk.out'	Run the build step (`cdk synth`, `terraform show -json`, or`pulumi preview --save-plan`) before the action, and make sure`path` points at a directory containing `*.template.json` files or at the plan JSON file itself.
ArcSync token request failed (HTTP 4xx)	The client ID or secret is wrong or has been revoked. Recreate the credential at arcsync.dev → Settings → GitHub Action credentials and update both repository secrets.
No github-token input or GITHUB_TOKEN — skipping PR comment	The `github-token` input defaults to the workflow token, so this only appears when a workflow overrides it with an empty value. Remove the override, or pass the token explicitly:`with: github-token: ${{ secrets.GITHUB_TOKEN }}`.
Run succeeds but no comment appears	Comments are only posted on `pull_request` events, and the workflow needs `permissions: pull-requests: write`.