{
  "schemaVersion": "1.0",
  "id": "deploy-pipeline-from-github-actions",
  "title": "Deploy pipeline flowchart from a GitHub Actions workflow",
  "slug": "deploy-pipeline-from-github-actions",
  "diagramFamily": "flowchart",
  "goal": "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"
  ],
  "mcpTools": [
    "diagram_create",
    "diagram_get",
    "diagram_edit",
    "diagram_render",
    "diagram_history"
  ],
  "httpEndpoints": [
    "POST /v1/diagrams",
    "GET /v1/diagrams/{id}",
    "POST /v1/diagrams/{id}/revisions",
    "GET /v1/diagrams/{id}/render",
    "GET /v1/diagrams/{id}/compare"
  ],
  "steps": [
    {
      "id": "create_or_fetch_scene",
      "label": "Create or read the diagram",
      "description": "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": {
        "method": "POST",
        "path": "/v1/diagrams",
        "exampleRequest": "{\n  \"key\": \"orders-api-deploy\",\n  \"message\": \"Pipeline from .github/workflows/deploy.yml\",\n  \"scene\": {\n    \"schemaVersion\": \"0.1\",\n    \"diagramFamily\": \"flowchart\",\n    \"scene\": {\n      \"title\": \"orders-api deploy pipeline\",\n      \"brief\": \"How a push to main reaches production for orders-api, drawn from .github/workflows/deploy.yml.\"\n    },\n    \"elements\": [\n      \"...\"\n    ]\n  }\n}",
        "exampleResponse": "{\n  \"id\": \"dgm_oXSgS16StyHr\",\n  \"key\": \"orders-api-deploy\",\n  \"revision\": 1,\n  \"hash\": \"sha256:7585979f4749ea96bc9be944173d7cac389a8a39c81671e7204d513eb8a962e4\",\n  \"chain\": \"sha256:059e93fe243e0248c973cd27b7ff8cba9229cd05a57e79af9f16adcee6fa089a\",\n  \"warnings\": [],\n  \"created\": true\n}"
      }
    },
    {
      "id": "parse_workflow",
      "label": "Read the workflow",
      "description": "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.",
      "mcp": null,
      "http": null
    },
    {
      "id": "read_current",
      "label": "Read the diagram's current revision",
      "description": "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": {
        "method": "GET",
        "path": "/v1/diagrams/${SCENE_ID}",
        "exampleResponse": "{\n  \"id\": \"dgm_oXSgS16StyHr\",\n  \"revision\": 1,\n  \"text\": \"dgm_oXSgS16StyHr \\\"orders-api deploy pipeline\\\" r1 2026-11-06T15:50Z sha256:7585979f4749\\nkey: orders-api-deploy\\nbrief: How a push to main reaches production for orders-api, drawn from .github/workflows/deploy.yml.\\n  In run order, top to bottom: a process box for each job or step that does something, a decision for each check with labeled yes and no exits, pills for the trigger and the outcomes. Keep element IDs; change it with edits when the workflow changes, and name the pull request in the edit's message.\\nrecent: r1 curl/8.7.1 \\\"Pipeline from .github/workflows/deploy.yml\\\"\\noutline: 12 nodes, 12 edges\\n  push generic \\\"Push to main\\\"\\n  build process \\\"Build image\\\"\\n  test process \\\"Run tests\\\"\\n  testsOk decision \\\"Tests pass?\\\"\\n  staging process \\\"Deploy to staging\\\"\\n  smoke decision \\\"Smoke tests pass?\\\"\\n  prod process \\\"Deploy to production\\\"\\n  done generic \\\"Deployed\\\"\\n  rollback process \\\"Roll back\\\"\\n  notify process \\\"Notify on-call\\\"\\n  failed generic \\\"Release failed\\\"\\n  fix process \\\"Open fix PR\\\"\\n  e1: push -> build\\n  e2: build -> test\\n  e3: test -> testsOk\\n  e4: testsOk -> staging \\\"yes\\\"\\n  e5: testsOk -> fix \\\"no\\\"\\n  e6: staging -> smoke\\n  e7: smoke -> prod \\\"yes\\\"\\n  e8: smoke -> rollback \\\"no\\\"\\n  e12: prod -> done\\n  e14: rollback -> notify\\n  e15: notify -> failed\\n  e16: fix -> failed\"\n}"
      }
    },
    {
      "id": "compute_ops",
      "label": "Compute the operation batch",
      "description": "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.",
      "mcp": null,
      "http": null
    },
    {
      "id": "record_pr_revision",
      "label": "Save the pull request as a revision",
      "description": "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": {
        "method": "POST",
        "path": "/v1/diagrams/${SCENE_ID}/revisions",
        "exampleRequest": "{\n  \"baseRevision\": 1,\n  \"message\": \"PR 218: roll out to production as a canary\",\n  \"ops\": [\n    {\n      \"op\": \"createNode\",\n      \"id\": \"shift\",\n      \"nodeType\": \"process\",\n      \"label\": \"Shift 10% more traffic\"\n    },\n    {\n      \"op\": \"createNode\",\n      \"id\": \"errOk\",\n      \"nodeType\": \"decision\",\n      \"label\": \"Error rate OK?\"\n    },\n    {\n      \"op\": \"createNode\",\n      \"id\": \"full\",\n      \"nodeType\": \"decision\",\n      \"label\": \"At 100%?\"\n    },\n    {\n      \"op\": \"createEdge\",\n      \"id\": \"e9\",\n      \"from\": {\n        \"elementId\": \"shift\"\n      },\n      \"to\": {\n        \"elementId\": \"errOk\"\n      }\n    },\n    {\n      \"op\": \"createEdge\",\n      \"id\": \"e10\",\n      \"from\": {\n        \"elementId\": \"errOk\"\n      },\n      \"to\": {\n        \"elementId\": \"full\"\n      },\n      \"label\": \"yes\"\n    },\n    {\n      \"op\": \"createEdge\",\n      \"id\": \"e11\",\n      \"from\": {\n        \"elementId\": \"errOk\"\n      },\n      \"to\": {\n        \"elementId\": \"rollback\"\n      },\n      \"label\": \"no\"\n    },\n    {\n      \"op\": \"createEdge\",\n      \"id\": \"e13\",\n      \"from\": {\n        \"elementId\": \"full\"\n      },\n      \"to\": {\n        \"elementId\": \"shift\"\n      },\n      \"label\": \"no\"\n    },\n    {\n      \"op\": \"updateEdge\",\n      \"id\": \"e7\",\n      \"to\": {\n        \"elementId\": \"shift\"\n      }\n    },\n    {\n      \"op\": \"updateEdge\",\n      \"id\": \"e12\",\n      \"from\": {\n        \"elementId\": \"full\"\n      },\n      \"label\": \"yes\"\n    },\n    {\n      \"op\": \"deleteElement\",\n      \"id\": \"prod\"\n    }\n  ]\n}",
        "exampleResponse": "{\n  \"id\": \"dgm_oXSgS16StyHr\",\n  \"revision\": 2,\n  \"hash\": \"sha256:75383f9113843866179e9a86e8cd967d6d49eee4e51560ed9138be73179b46c3\",\n  \"chain\": \"sha256:4d2243b42fd9dea5e503d52e06d16e4ef4d6e57d9dfa773d05b4cbd4ddca67fd\",\n  \"warnings\": [],\n  \"changed\": {\n    \"added\": [\n      \"shift\",\n      \"errOk\",\n      \"full\",\n      \"e9\",\n      \"e10\",\n      \"e11\",\n      \"e13\"\n    ],\n    \"updated\": [\n      \"done\",\n      \"rollback\",\n      \"notify\",\n      \"failed\",\n      \"e7\",\n      \"e12\"\n    ],\n    \"removed\": [\n      \"prod\"\n    ]\n  }\n}"
      }
    },
    {
      "id": "check_warnings",
      "label": "Fix what the warnings report",
      "description": "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.",
      "mcp": null,
      "http": null
    },
    {
      "id": "compare_revisions",
      "label": "Compare the default branch's revision with the pull request's",
      "description": "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": {
        "method": "GET",
        "path": "/v1/diagrams/${SCENE_ID}/compare?from=${MAIN_REVISION}&to=${PR_REVISION}",
        "exampleResponse": "{\n  \"id\": \"dgm_oXSgS16StyHr\",\n  \"from\": 1,\n  \"to\": 2,\n  \"added\": [\n    \"shift\",\n    \"errOk\",\n    \"full\",\n    \"e9\",\n    \"e10\",\n    \"e11\",\n    \"e13\"\n  ],\n  \"changed\": [\n    \"done\",\n    \"rollback\",\n    \"notify\",\n    \"failed\",\n    \"e7\",\n    \"e12\"\n  ],\n  \"removed\": [\n    \"prod\"\n  ],\n  \"scene\": [],\n  \"authors\": [\n    {\n      \"by\": null,\n      \"client\": \"curl/8.7.1\"\n    }\n  ]\n}"
      }
    },
    {
      "id": "render",
      "label": "Render the new revision",
      "description": "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": {
        "method": "GET",
        "path": "/v1/diagrams/${SCENE_ID}/render",
        "exampleResponse": "{\n  \"id\": \"dgm_oXSgS16StyHr\",\n  \"title\": \"orders-api deploy pipeline\",\n  \"revision\": 2,\n  \"latest\": 2,\n  \"savedAt\": \"2026-11-06T15:50:25.964Z\",\n  \"hash\": \"sha256:75383f9113843866179e9a86e8cd967d6d49eee4e51560ed9138be73179b46c3\",\n  \"chain\": \"sha256:4d2243b42fd9dea5e503d52e06d16e4ef4d6e57d9dfa773d05b4cbd4ddca67fd\",\n  \"engine\": \"8.29.0+build.3500\",\n  \"svg\": \"https://api.zindex.ai/v1/images/dgm_oXSgS16StyHr@2.svg?e=1794585025&s=...\",\n  \"png\": \"https://api.zindex.ai/v1/images/dgm_oXSgS16StyHr@2.png?e=1794585025&s=...\",\n  \"expires\": \"2026-11-13T15:50:25.000Z\",\n  \"width\": 800,\n  \"height\": 1299\n}"
      }
    },
    {
      "id": "comment_on_pr",
      "label": "Post the change on the pull request",
      "description": "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.",
      "mcp": null,
      "http": null
    }
  ]
}