Set up the GitHub Action

Post an interactive architecture diagram on every pull request, generated from your cdk synth or terraform plan output — without giving ArcSync access to your source code.

VanLandinghamLabs/arcsync-action@v2Stable · MITNode 24 runtime

How it works

The action is a thin uploader. Your workflow synthesizes the infrastructure first —cdk synth or terraform plan — and the action collects the build output: every *.template.json in a cdk.out directory, or a single terraform show -json file. It uploads that 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.

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

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.

Add the workflow

A complete workflow for an AWS CDK project. The two non-obvious lines:pull-requests: write lets the action post the diagram comment, and GITHUB_TOKEN is passed as an environment variable — the action reads it from the environment, not from an input.

name: Architecture diagram

on:
  pull_request:

permissions:
  contents: read
  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@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        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@v2
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  with:
    path: plan.json
    api-client-id: ${{ secrets.ARCSYNC_CLIENT_ID }}
    api-client-secret: ${{ secrets.ARCSYNC_CLIENT_SECRET }}

Inputs

Input	Description
api-client-idREQ string	ArcSync client ID, created at arcsync.dev → Settings → GitHub Action credentials.
api-client-secretREQ 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 `terraform show -json` file.
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@v2
  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.

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 `cdk synth` (or `terraform show -json`) 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.
GITHUB_TOKEN not available — skipping PR comment	Pass the token to the step:`env: 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`.