# Deploy pipeline flowchart from a GitHub Actions workflow
> A flowchart of how a push reaches production, drawn from the repository's GitHub Actions workflow: jobs as steps, checks as decisions with yes and no exits, and the outcomes. When the workflow changes, the agent records the change as a revision with a structural diff.
## Metadata
- **Diagram family**: `flowchart`
- **Source**: GitHub Actions workflow (YAML)
- **Workflow types**: scan, generate, update, validate, render, diff
- **Audience**: developer, platform
- **MCP tools**: `diagram_create`, `diagram_get`, `diagram_edit`, `diagram_render`, `diagram_history`
- **HTTP endpoints**:
  - `POST /v1/diagrams`
  - `GET /v1/diagrams/{id}`
  - `POST /v1/diagrams/{id}/revisions`
  - `GET /v1/diagrams/{id}/render`
  - `GET /v1/diagrams/{id}/compare`
---
---

## What this example shows

The deploy pipeline of a service called orders-api, drawn by an agent as a flowchart from the repository's GitHub Actions workflow: a push to main is built and tested, deployed to staging and smoke-tested there, then rolled out to production. Each check is a decision with its `yes` and `no` exits labeled, and every failure ends in a rollback or a fix pull request. The agent wrote no coordinates. Revision 2 records pull request 218, which replaces the straight deploy to production with a canary: the workflow shifts 10% more traffic to the new release, checks the error rate, and repeats until the release carries all of it. Scroll to the **Revision diff** panel below to see both revisions, before and after, with the compare response from `diagram_history`. It lists the canary's step, its two checks and their four edges as added; as changed, the two edges that now lead into and out of the canary and the steps the engine moved to make room for it; and the old production deploy as removed.

## When to use it

When a team's release process lives in a CI workflow and people keep asking what happens after they merge: which checks gate production, what a failed smoke test does, who gets paged. The YAML lists jobs and conditions; the flowchart shows the paths through them. Each pull request that changes the workflow becomes a revision, so reviewers see the new path before it runs for the first time.

## What the agent does

On the first run the agent reads the workflow, makes a process for each job or step a reader needs to see and a decision for each check that chooses what runs next, joins them in the order the jobs `need` each other, labels every exit with its answer, and saves the diagram with `diagram_create`.

For each pull request that changes the workflow, the agent turns the change into typed operations and saves them with `diagram_edit` as a revision whose message names the pull request. For pull request 218 that is one edit: `createNode` for the canary's step and its two checks, `createEdge` for their edges and the loop back, `updateEdge` to move the smoke tests' `yes` exit onto the canary and to start the edge into "Deployed" at the last check, and `deleteElement` for the production deploy it replaces. The edges keep their IDs, so the compare names them as changed rather than as one removed and one added. `diagram_history` with `compare` lists what changed, and `diagram_render` draws the new revision for the pull request.

## What the output includes

- One `diagramFamily: "flowchart"` diagram per workflow, that every later run edits rather than redraws.
- Decisions with labeled `yes` and `no` exits, a loop drawn back to the step it repeats, and pills for the trigger and the two outcomes.
- A revision for each pull request that changes the workflow, its message starting with the pull request's number.
- A compare JSON listing the steps, checks and edges each pull request adds, changes and removes.

## What this example does not aim to do

It draws the workflow as written, not its runs. A run's timings, retries and the job that failed belong in the CI system's own run view. It also leaves out the scripts the workflow calls: a step that runs `deploy.sh` is drawn as the step, not as what the script does inside.
## Agent workflow
Draw a team's deploy pipeline as a flowchart from its GitHub Actions workflow, then record each pull request that changes the workflow as a revision named for it, so reviewers see the new path to production before it first runs.
**Inputs**

- The workflow file on the default branch (.github/workflows/deploy.yml)
- The pull request's change to that file
- The diagram's Zindex key, orders-api-deploy, or its ID from .zindex.json (the diagram is created on the first run)
- A Zindex API key, or an MCP client signed in to Zindex
**Outputs**

- Revision 1: the pipeline drawn from the workflow, laid out by the engine
- One revision per pull request that changes the workflow, its message starting with the pull request's number
- A compare listing the steps, checks and edges the pull request adds, changes and removes
- Rendered SVG and PNG of the new revision, posted on the pull request
**Steps**

1. **Create or read the diagram** - On the first run, draw the workflow and save it with `diagram_create`: `diagramFamily: "flowchart"`, a `key` such as `orders-api-deploy`, and a `brief` whose first line says what the diagram shows. Zindex mints the ID; the key is how later runs find the diagram, and the brief's first line is what a search shows. On later runs, read it with `diagram_get` instead.
   _MCP: `diagram_create` · HTTP: `POST /v1/diagrams`_

2. **Read the workflow** - Read `.github/workflows/deploy.yml`. The trigger (`on: push` to `main`) and the outcomes, deployed and release failed, become pills. Each job, or each step inside a job that a reader needs to see, becomes a `process`. Each check whose result chooses what runs next becomes a `decision` labeled with a question: a job's success when another job runs `if: failure()`, and a test inside a step's loop, such as the canary's error rate. Edges follow `needs`, and each exit of a decision is labeled `yes` or `no`. A loop is an edge back to the step it repeats.

3. **Read the diagram's current revision** - For each pull request that changes `.github/workflows/`, call `diagram_get`. The outline's first line gives the current revision number (MAIN_REVISION), the 'before' state for the compare, and its lines give each node with its type and label and each edge with its ends and label, so you can see which IDs already exist.
   _MCP: `diagram_get` · HTTP: `GET /v1/diagrams/${SCENE_ID}`_

4. **Compute the operation batch** - New jobs and steps become `createNode`, new checks a `decision`, new paths `createEdge`, removed jobs `deleteElement`, renamed ones `updateNode`. A path that now leads somewhere else keeps its edge: move it with `updateEdge` and a new `from` or `to`. Deleting a node deletes the edges at it, so move the edges you keep before the delete. A change to no job, condition or order (a runner image, a cache key, a timeout) isn't a change to the pipeline.

5. **Save the pull request as a revision** - Call `diagram_edit` with the ops, `baseRevision` = MAIN_REVISION and a message that starts with the pull request's number: `PR 218: roll out to production as a canary`. This creates PR_REVISION. The edit is all or nothing: if an operation has errors, it returns `VALIDATION_FAILED` and saves nothing. The response's `changed` names the canary's new elements, the two edges moved onto it, the production deploy it replaced, and the saved nodes the engine moved to make room for it.
   _MCP: `diagram_edit` · HTTP: `POST /v1/diagrams/${SCENE_ID}/revisions`_

6. **Fix what the warnings report** - The edit's `warnings` list the flowchart rules the new revision breaks and what drawing it noticed, each with a `code`, the `element` when there is one, and a one-line `fix`. The edit above returns none: each of its decisions has a `yes` and a `no` exit. `FAMILY_FLOWCHART_DECISION_FEW_EXITS` names a decision with fewer than two exits, and `FAMILY_FLOWCHART_EXIT_UNLABELED` an exit without its answer. Fix them with a follow-up edit.

7. **Compare the default branch's revision with the pull request's** - Call `diagram_history` with `compare: { from: MAIN_REVISION, to: PR_REVISION }`. It lists the element IDs the pull request adds, changes and removes, and the scene-level fields that changed, so the agent doesn't have to work out the change again.
   _MCP: `diagram_history` · HTTP: `GET /v1/diagrams/${SCENE_ID}/compare?from=${MAIN_REVISION}&to=${PR_REVISION}`_

8. **Render the new revision** - Get SVG and PNG links to the new revision; they work without a key for 7 days. The image is drawn once and kept, and it prints its address, `zindex.ai/d/<id>@<revision>`, and date, so it is traceable to its revision.
   _MCP: `diagram_render` · HTTP: `GET /v1/diagrams/${SCENE_ID}/render`_

9. **Post the change on the pull request** - Post one comment on the pull request: a one-line summary (`+1 step, +2 checks, a loop`), the image and the compare. When the pull request changes, record the difference as another revision with the same number and update that comment rather than adding another.
## Agent prompt

Drop this into a system prompt for an MCP-connected agent.

```
You look after the flowchart of the team's deploy pipeline, drawn from its GitHub Actions workflow, so anyone can see how a push reaches production and what happens when a check fails. You draw it once from the workflow, then record each pull request that changes the workflow as a revision named for it.

The diagram's Zindex ID is `${SCENE_ID}` and its key is `orders-api-deploy`. The workflow is `.github/workflows/deploy.yml`.

How to draw it:
- `diagramFamily: "flowchart"`, with no `layout` on any node: the engine places every node and routes every edge.
- The trigger and the outcomes are pills (`nodeType: "generic"`, `shape: "pill"`): "Push to main", "Deployed", "Release failed".
- Each job, or each step inside a job that a reader needs to see, is a `process` with a short verb phrase for a label. Each check whose result chooses what runs next (a job's success, an `if:` on another job's result, a test inside a loop) is a `decision` labeled with a question.
- Edges run in order, from each job to the jobs that `need` it. Label every exit of a decision with its answer, `yes` or `no`. A loop is an edge back to the step it repeats.

Steps:

1. If you don't have the diagram's ID yet, call `diagram_find({ query: "orders-api-deploy" })`, which returns it. If there is none, build the scene from the workflow on the default branch and call `diagram_create({ key: "orders-api-deploy", scene, message })` with a brief that states these conventions, and use the ID it returns.

2. For each pull request that changes `.github/workflows/`, call `diagram_get({ id: "${SCENE_ID}" })`. Read the current revision number from the outline's first line; call this `MAIN_REVISION`. The outline lists every node and edge with its ID and label.

3. Read the changed workflow. New jobs or steps become `createNode`, new checks a `decision`, new paths `createEdge`, removed jobs `deleteElement`, renamed ones `updateNode`. When a path now leads somewhere else, move its edge with `updateEdge` and a new `from` or `to` rather than deleting it. Deleting a node deletes the edges at it, so move the edges you keep before you delete the node. Reuse the diagram's IDs.

4. Call `diagram_edit({ id: "${SCENE_ID}", baseRevision: MAIN_REVISION, message, ops })` with a message that starts with the pull request's number, such as `PR 218: roll out to production as a canary`. Call the new revision `PR_REVISION`. If the call returns `REVISION_CONFLICT`, the diagram changed after you read it: the error lists what changed, so re-plan against the new revision.

5. The edit's `warnings` list what the new revision breaks, each with a `code`, the `element` and a one-line `fix`. `FAMILY_FLOWCHART_DECISION_FEW_EXITS` names a decision with fewer than two exits, and `FAMILY_FLOWCHART_EXIT_UNLABELED` an exit without its answer. Fix them with a follow-up edit.

6. Call `diagram_history({ id: "${SCENE_ID}", compare: { from: MAIN_REVISION, to: PR_REVISION } })` for the elements the pull request adds, changes and removes, then `diagram_render({ id: "${SCENE_ID}" })` for SVG and PNG links valid for 7 days.

7. Post one comment on the pull request: a one-line summary (`+1 step, +2 checks, a loop`), the image and the compare. When the pull request changes, record the difference as another revision with the same number and update that comment rather than adding another.

Hard rules: name the pull request in every revision message. Never redraw the diagram or recreate an element to change it; the IDs carry its history. Draw what the workflow runs, not what its comments say. If the pull request changes no job, condition or order (a runner image, a cache key, a timeout), post 'No changes to the pipeline' so reviewers know the check ran, and record nothing.
```
## Validation

Captured `POST /v1/diagrams/validate` response: **valid** (0 errors, 0 warnings)

_The scene validates with no errors or warnings._
## Resources
- **Canonical scene**: [/examples/deploy-pipeline-from-github-actions.scene.json](/examples/deploy-pipeline-from-github-actions.scene.json) (revision 2's scene, without the node positions Zindex saved with it)
- **Operations envelope**: [/examples/deploy-pipeline-from-github-actions.ops.json](/examples/deploy-pipeline-from-github-actions.ops.json)
- **Workflow recipe**: [/examples/deploy-pipeline-from-github-actions.workflow.json](/examples/deploy-pipeline-from-github-actions.workflow.json)
- **Revision diff**: [/examples/deploy-pipeline-from-github-actions.diff.json](/examples/deploy-pipeline-from-github-actions.diff.json)
- **Rendered SVG**: [/examples/deploy-pipeline-from-github-actions.svg](/examples/deploy-pipeline-from-github-actions.svg) (revision 2 as Zindex saved it: its edit moved no placed node `.diff.json` doesn't list; previewing `.scene.json` lays every node out from scratch, so nodes can land elsewhere)
- **Before SVG**: [/examples/deploy-pipeline-from-github-actions.before.svg](/examples/deploy-pipeline-from-github-actions.before.svg) (revision 1 as Zindex saved it, the revision diff's before picture)
- **Human page**: [/examples/deploy-pipeline-from-github-actions/](/examples/deploy-pipeline-from-github-actions/)
- **Manifest**: [/examples/index.json](/examples/index.json)
## Related examples

- [/examples/aws-architecture-from-terraform/](/examples/aws-architecture-from-terraform/)
- [/examples/request-flow-from-handler/](/examples/request-flow-from-handler/)
- [/examples/multi-agent-workflow/](/examples/multi-agent-workflow/)