Skip to content

Agent skill that turns natural language, code, Terraform/K8s, SQL, OpenAPI, AsyncAPI, Protobuf and GraphQL sources into editable, tested draw.io architecture diagrams: incremental sync, multi-view projection, drift diff, CI architecture tests, whiteboard derasterize, interactive HTML/PPTX/Mermaid exports.

4.8 KB
Raw Blame

Rendering diagrams in CI

中文

Keep diagram sources in the repo (graph JSON from the importers, seq.json, c4.json, or hand-written .drawio) and let CI regenerate, lint, and export them — the diagram-as-code loop:

source (.tf / manifests / schema.sql / seq.json / graph.json)
   → extractor (tfimports / k8simports / sqlerd / seqlayout / …)
   → autolayout.py → validate.py --strict (gate) → drawio -x (render) → artifact

Bonus: the pipeline itself can be the diagram — ciimports.py <repo-root> turns .github/workflows/*.yml + .gitlab-ci.yml into a jobs/needs: DAG (triggers, matrix sizes, reusable-workflow calls) for the same autolayout → validate → render loop.

Importer node ids are stable (module paths, type.name, kind/name), so regenerated .drawio files produce reviewable diffs when the underlying code or infra changes.

For turnkey gates, this repo also ships composite GitHub Actions: a pure-Python architecture-rule gate (drawio-architecture-test) and a visual PR diagram diff (drawio-diff) — see ../skills/drawio-skill/references/ci-gate.md and ../skills/drawio-skill/references/pr-bot.md.

Option A — draw.io desktop + xvfb (GitHub Actions)

The desktop CLI works headless under xvfb. Complete workflow:

name: diagrams
on:
  push:
    paths: ["infra/**", "diagrams/**"]

jobs:
  render:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # The skill's scripts (importers, autolayout, validate)
      - run: git clone --depth 1 https://github.com/Agents365-ai/drawio-skill /tmp/drawio-skill
      - run: sudo apt-get update && sudo apt-get install -y graphviz xvfb

      # draw.io desktop (latest release .deb)
      - name: Install draw.io
        run: |
          URL=$(curl -s https://api.github.com/repos/jgraph/drawio-desktop/releases/latest \
                | grep -o 'https://[^"]*amd64[^"]*\.deb' | head -1)
          curl -sL "$URL" -o /tmp/drawio.deb
          sudo apt-get install -y /tmp/drawio.deb

      - name: Regenerate, lint, render
        run: |
          S=/tmp/drawio-skill/skills/drawio-skill/scripts
          python3 $S/tfimports.py infra -o /tmp/graph.json
          python3 $S/autolayout.py /tmp/graph.json -o diagrams/infra.drawio
          python3 $S/validate.py diagrams/infra.drawio --strict   # gate: fail on any warning
          export HOME=${HOME:-/tmp}
          xvfb-run -a --server-args="-screen 0 1280x1024x24" \
            drawio -x -f png -e -s 2 -o diagrams/infra.drawio.png \
            diagrams/infra.drawio --disable-gpu --no-sandbox
          python3 $S/repair_png.py diagrams/infra.drawio.png       # fix -e IEND truncation

      - uses: actions/upload-artifact@v4
        with: {name: diagrams, path: "diagrams/*.png"}

Notes (all from the skill's troubleshooting experience):

  • --no-sandbox must be the last argument — earlier positions make drawio treat it as the input file. Required when running as root (CI containers).
  • export HOME=/tmp if the runner has no home; add --disable-gpu on servers.
  • After any -e PNG export, run repair_png.py — the CLI truncates the IEND chunk (issue #8).
  • --page-index <n> (1-based) exports one page of a multi-page file (e.g. c4.py output).
  • If the .deb install fails on missing libs: sudo apt-get install -y libgtk-3-0 libnotify4 libnss3 libgbm1 libasound2t64.

Option B — Docker REST renderer (no desktop install)

tomkludy/drawio-renderer exposes headless export as a REST API — useful on runners where installing a .deb is not an option:

jobs:
  render:
    runs-on: ubuntu-latest
    services:
      drawio:
        image: tomkludy/drawio-renderer:latest
        ports: ["5000:5000"]
    steps:
      - uses: actions/checkout@v4
      - name: Render via REST
        run: |
          curl -s -X POST http://localhost:5000/convert \
            -H 'Content-Type: application/json' \
            -d "$(python3 -c 'import json,sys;print(json.dumps({
                  "source": open("diagrams/infra.drawio").read(),
                  "format": "png", "scale": 2}))')" \
            -o diagrams/infra.png

Validation (validate.py --strict) needs only Python — it runs the same way in both options.

Committing rendered images back

Prefer uploading artifacts or publishing to Pages over committing PNGs. If you do commit them (e.g. README images), guard against loops:

      - name: Commit refreshed diagrams
        run: |
          git config user.name github-actions
          git config user.email [email protected]
          git add diagrams/*.png
          git diff --cached --quiet || git commit -m "ci: refresh diagrams [skip ci]"
          git push