GitHub Actions Workflow Viewer

VMark renders GitHub Actions workflow YAML as an interactive directed-acyclic-graph (DAG) and lets you edit jobs, steps, and triggers through structured forms — without ever losing comments, anchors, or formatting in the underlying file.

The feature works in two surfaces:

1. Standalone .yml files under .github/workflows/ (or any file whose top-level shape matches a workflow): split view with the source on the left and the interactive canvas + forms editor on the right.
2. Markdown code fences: when a triple-backtick yaml or yml fenced block contains a recognizable workflow, VMark renders it as a Mermaid-style DAG inline, the same way mermaid blocks are rendered.

Standalone workflow files

Open any .github/workflows/*.yml file in VMark. The file opens in a split view — YAML source on the left, the workflow workbench on the right (the Source / Split / Preview toggle switches layouts). The workbench shows:

• The full workflow as an interactive React Flow canvas (jobs as nodes, needs: dependencies as edges).
• A structured editor panel below the canvas.
• Save / Discard controls in the editor header.

Click a job in the canvas to edit it. Click a step inside the job to edit that step.

While you edit the source, VMark keeps the two panes in sync: moving the cursor into a job's lines highlights its node on the canvas, $ expressions autocomplete against the parsed workflow's contexts, and Cmd-clicking a local uses: reference opens the target file.

Job editing

Editable fields:

Field	Patch kind
name	job.set
runs-on	job.set
if	job.set

Read-only summary: step count, needs:, and uses: (for reusable-workflow jobs).

Step editing

Editable fields:

Field	Patch kind
name	step.set
run (for run-steps)	step.set
working-directory	step.set
if	step.set
with: keys	with.set / with.remove

The with: block renders as add/edit/remove key/value rows. Renaming a key emits a with.remove for the old key followed by a with.set for the new one.

For uses: steps, the action reference itself is read-only — change it in source if you need a different action.

Triggers

The trigger summary (event, branches, tags, paths, cron, types) is read-only in this version. Editing dense trigger structure via single-line inputs is too lossy; edit triggers in source until a dedicated picker ships.

Saving edits

Edits queue up in an in-memory patch list as you change fields. The Save button shows the current count (e.g., 3 unsaved).

When you click Save, VMark:

1. Reads the current YAML from the editor.
2. Applies every queued patch to the YAML's CST (concrete syntax tree) — preserving comments, anchors, and existing formatting.
3. Writes the result back into the editor as if you had typed it.

The file becomes dirty in the normal sense; press Cmd+S to write to disk.

Preserving formatting

The default save path runs every patch through the yaml package's CST API — comments, anchor nodes, custom indentation, and existing flow-vs-block style choices are preserved.

Disable Preserve YAML formatting on save in Settings → Advanced if you prefer canonical reformatted output. The reformat path drops comments, so this is opt-in.

Code fences in markdown

Type a workflow into a YAML code fence:

```yaml
name: ci
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pnpm test
```text

VMark detects the workflow shape (top-level jobs: with runs-on per job) and renders the diagram inline. The diagram is read-only — edit the source to change the workflow.

Diagnostics

VMark surfaces parse + lint diagnostics next to the source:

Code prefix	Meaning
GHA-PARSE-*	Malformed YAML or missing required keys
GHA-JOB-*	Job-level issues (duplicate id, conflicting uses: + steps:)
GHA-NEEDS-*	Dependency issues (unknown ref, cycle)
GHA-STEP-*	Step-level issues
GHA-EXPR-*	Unknown context references
GHA-MATRIX-*	Matrix expansion issues
GHA-SEC-*	Security warnings (e.g., pull_request_target checkout patterns)
GHA-ACTIONLINT-*	Forwarded from actionlint if installed

Install actionlint for richer expression diagnostics. With Use actionlint when available on — in Settings → Advanced (Workflow files), on by default — VMark runs the binary from your login-shell PATH each time a workflow file's source changes and appends its findings to the workbench's Diagnostics banner, tagged GHA-ACTIONLINT-<rule>; the built-in checks above never wait for it. If the toggle is on but the binary is not installed, VMark tells you once per session and otherwise stays quiet; if the binary is present but fails to run, the failure is reported once with actionlint's own message. Turn the toggle off to skip actionlint entirely. The MCP workflow.validate operation runs the same check on demand.

Action metadata

For uses: steps that reference public GitHub Actions, VMark fetches each action's action.yml to populate input descriptions in the structured editor. Results are cached on disk for 24 hours. Workspace-local actions (./…) are read from disk, never the network.

To keep the workflow editor fully offline, turn off Fetch action metadata in Settings → Advanced (Workflow files) — with it off, no network requests are made and the with: form falls back to free-form key/value rows.

Exports

The workflow side panel includes three export options accessible from its header menu:

Format	Use for
Mermaid	Embedding in READMEs and other markdown docs. Lossy: omits run status, action icons, custom badges, and matrix expansion details.
SVG	Embedding in docs that need vector graphics. Uses foreignObject for HTML content.
PNG	Sharing in chat or anywhere SVG isn't supported. Renders at the canvas's current zoom.

What this is not

VMark does not execute GitHub Actions workflows. It is a viewer and editor — execution remains GitHub's job. The feature is purely for reading, reviewing, and authoring workflow YAML.