Visualize Pull Requests with Kanvas Snapshot

Kanvas Snapshot posts a picture of your infrastructure as a comment on each GitHub pull request. Reviewers see which components a Kubernetes manifest, Docker Compose file, or Helm chart defines, and how they connect, before they read the YAML. The comment updates on every push to the pull request.

The snapshot runs in a GitHub Actions workflow on GitHub-hosted runners. It never touches your cluster. For how a snapshot is built and what it can and cannot do, see Kanvas Snapshot.

You can set it up two ways. The Layer5 GitHub App path installs the workflow for you. The direct path has you add the action to a workflow you own. Both produce the same comment.

Before you start 🔗

• A Layer5 Cloud account.
• A repository on github.com that holds the infrastructure file. GitHub Enterprise Server, GitLab, and Bitbucket are not supported.
• Permission to install a GitHub App on the repository, and to add repository secrets and commit to the default branch.
• A plan that includes GitOps Snapshots. See availability by plan.

Set up with the Layer5 GitHub App 🔗

The Connect wizard for GitHub in Layer5 Cloud walks through seven stages. Running it again later updates the connection.

Cloud never writes the secret for you. Add MESHERY_TOKEN to each repository yourself, with that exact name, and confirm the checkbox in the wizard. The wizard generates a new token each time the secrets stage opens, and it cannot show an earlier one again. Generate tokens in Layer5 Cloud and revoke them there; see Tokens.

What the installed workflow does 🔗

The wizard commits .github/workflows/kanvas.yml to the default branch of each repository, with the commit message Install Kanvas workflow. If that file already exists, the wizard replaces it.

Two behaviors matter after install:

• The input type is always Kubernetes Manifest. If the file you chose is a Docker Compose file or a Helm chart, edit application_type in the committed workflow to Docker Compose or Helm Chart.
• The workflow is built from the latest template at install time. Installing the same repository twice on different days can produce a different workflow. Review the committed file before you rely on it.

Per-repository install results are:

If you uninstall the App 🔗

Cloud checks whether the App installation still exists. When GitHub reports that it does not, Cloud deletes the stale GitHub connection. Run the wizard again to reconnect.

Use the action in your own workflow 🔗

Skip the wizard when you want to choose the triggers, run snapshots from a workflow you already maintain, or authenticate with a personal access token instead of the App.

1. Generate a Layer5 Cloud API token and store it as a repository secret, for example MESHERY_TOKEN.
2. Add a workflow. The action needs its own repository checked out to a folder named action, and the same token permissions the installed workflow uses.

name: Kanvas Snapshot
on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  actions: read
  contents: write
  security-events: write
  statuses: write
  pull-requests: write
  id-token: write

jobs:
  snapshot:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/checkout@v4
        with:
          path: action
          repository: layer5labs/kanvas-snapshot
      - uses: layer5labs/[email protected]
        with:
          githubToken: ${{ secrets.GITHUB_TOKEN }}
          mesheryToken: ${{ secrets.MESHERY_TOKEN }}
          prNumber: ${{ github.event.pull_request.number }}
          application_type: "Kubernetes Manifest"
          filePath: manifests

To snapshot a file that is hosted at a public URL, such as a packaged Helm chart, replace filePath with application_url and set application_type to Helm Chart. Pin the action to the latest release tag; v0.2.44 is current at the time of writing.

Action inputs 🔗

When you give filePath a directory, the action merges the .yaml and .yml files directly inside it into one document. It does not read subfolders. Point it at the folder that holds the manifests, or at a single file.

The action outputs resource_url, the URL of the rendered image. When no image URL comes back, the action does not post a comment.

Choose other triggers 🔗

The comment needs a pull request number, so only pull request runs post one. Use any other workflow event, such as push, schedule, or workflow_dispatch, to render a snapshot without a comment and read resource_url in a later step. Leave prNumber at 0 or set skipComment to true for those runs.

What the pull request comment contains 🔗

The comment shows the rendered image, linked to itself, with links to the generated design in the catalog and to an editable copy in the Playground. The workflow keeps one comment per pull request and replaces its content on each run.

Alongside the comment, each run uploads debug logs, screenshots, and a video of the render as workflow artifacts, whether the run succeeds or fails. Open them from the workflow run when a snapshot looks wrong.

Change or remove snapshots 🔗

Troubleshooting 🔗

Known limitations 🔗

• Email delivery. The email input does not deliver mail today. The action sends its request in a shape the Layer5 Cloud endpoint rejects, and the workflow continues without a failure. Use the pull request comment or resource_url.
• No diffs. A snapshot shows the current file only. It does not compare against the base branch.
• Single design per repository in the wizard. To snapshot more than one file, add the action to a workflow of your own for each file.
• GitHub.com only. The App and the install flow work against github.com.

Related Reading

• Kanvas Snapshot
• Snapshot a Helm Chart