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.

Add ciimports.py — CI pipelines (GitHub Actions / GitLab CI) as diagrams (#87)

Agents365.ai5828cb510b62
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0f406b4..88cbf61 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,20 @@ All notable changes to **drawio-skill** are documented here. The format is based
on [Keep a Changelog](https://keepachangelog.com/), and the project follows
semantic-ish versioning (the `version:` field in `skills/drawio-skill/SKILL.md`).
+## [1.32.0] — 2026-07-14
+### Added
+- **`scripts/ciimports.py`** — CI pipelines as diagrams. Reads GitHub Actions
+ workflows (`.github/workflows/*.yml`, or a repo root) and/or `.gitlab-ci.yml`
+ (auto-detected) and emits an autolayout graph: job nodes labeled with runner,
+ `matrix ×N` size, and reusable-workflow targets (purple); `needs:` dependency
+ edges; an `on:` trigger node per workflow feeding the root jobs; containers per
+ workflow (GitHub) or per stage (GitLab, including the implicit previous-stage
+ DAG for jobs without `needs`). Feeds `autolayout.py` like every other importer.
+ Requires PyYAML. Extractors: 12 → 13; scripts: 30 → 31.
+- Routing entries in SKILL.md step 3 + resources table, toolbox quick-guide/§3
+ rows, README/README_CN examples + extractor row, a cross-reference in
+ `docs/CI.md`/`CI_CN.md`, and 2 regression tests (81 total).
+
## [1.31.0] — 2026-07-13
### Added
- **`scripts/relabel.py`** — language variants / bulk text swaps of an existing
diff --git a/README.md b/README.md
index b01efe2..b8363ee 100644
--- a/README.md
+++ b/README.md
@@ -166,6 +166,7 @@ kubectl get all,ing,cm,secret,pvc -o json | python3 scripts/k8simports.py - -o g
# Data & interactions
python3 scripts/sqlerd.py schema.sql -o graph.json # SQL DDL → ER diagram
+python3 scripts/ciimports.py . -o graph.json # GitHub Actions + GitLab CI -> pipeline DAG
python3 scripts/openapiimports.py openapi.yaml -o graph.json # OpenAPI/Swagger → API diagram (by method)
python3 scripts/seqlayout.py seq.json -o sequence.drawio # sequence diagram, direct to .drawio
python3 scripts/c4.py c4.json -o c4.drawio # C4 model, multi-page + drill-down
@@ -207,7 +208,7 @@ python3 scripts/autolayout.py graph.json -o diagram.drawio
| Piece | What it does |
|---|---|
-| **12 extractors** | import graphs for **Python · JS/TS · Go · Rust**, **Python class inheritance**, **Terraform / Kubernetes / docker-compose** resource graphs (official cloud icons), **SQL DDL → ERD**, **OpenAPI / Swagger → API diagram** (operations coloured by HTTP method + schemas), and **live** infra from `terraform show -json` / `docker inspect` / `kubectl get -o json` (draw what's actually deployed) |
+| **13 extractors** | import graphs for **Python · JS/TS · Go · Rust**, **Python class inheritance**, **Terraform / Kubernetes / docker-compose** resource graphs (official cloud icons), **SQL DDL → ERD**, **OpenAPI / Swagger → API diagram** (operations coloured by HTTP method + schemas), **CI pipelines → DAG** (GitHub Actions `needs:` graphs + GitLab stages, with triggers, matrix sizes, reusable-workflow calls), and **live** infra from `terraform show -json` / `docker inspect` / `kubectl get -o json` (draw what's actually deployed) |
| **Diagram diff** | `drawiodiff.py` compares two `.drawio` (or two live snapshots) into one colour-coded graph — added=green, removed=red, changed=orange — so you can see architecture / infra **drift** at a glance |
| **Language variants** | `relabel.py` swaps every label via a JSON map with layout/styles/ids untouched — `--extract` dumps all labels, translate the values, `--map` applies them. One diagram → EN + CN twins for bilingual docs |
| **Re-theme** | `restyle.py` applies a style preset (built-in `dark`/`corporate`/… or your own) to an *existing* `.drawio` — palette remapped by hue so same-colored nodes stay grouped; layout and edge routing untouched |
diff --git a/README_CN.md b/README_CN.md
index 92159bd..2f2640f 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -164,6 +164,7 @@ kubectl get all,ing,cm,secret,pvc -o json | python3 scripts/k8simports.py - -o g
# 数据与交互
python3 scripts/sqlerd.py schema.sql -o graph.json # SQL DDL → ER 图
+python3 scripts/ciimports.py . -o graph.json # GitHub Actions + GitLab CI -> 流水线 DAG
python3 scripts/openapiimports.py openapi.yaml -o graph.json # OpenAPI/Swagger → API 图(按方法着色)
python3 scripts/seqlayout.py seq.json -o sequence.drawio # 时序图,直接生成 .drawio
python3 scripts/c4.py c4.json -o c4.drawio # C4 模型,多页 + 下钻
@@ -205,7 +206,7 @@ python3 scripts/autolayout.py graph.json -o diagram.drawio
| 组件 | 作用 |
|---|---|
-| **12 个提取器** | **Python · JS/TS · Go · Rust** 的导入关系图、**Python 类继承**、**Terraform / Kubernetes / docker-compose** 资源图(自动配官方云图标)、**SQL DDL → ER 图**、**OpenAPI / Swagger → API 图**(按 HTTP 方法着色的接口 + schema),以及从 `terraform show -json` / `docker inspect` / `kubectl get -o json` 提取的**实时**基础设施(画出真正已部署的样子) |
+| **13 个提取器** | **Python · JS/TS · Go · Rust** 的导入关系图、**Python 类继承**、**Terraform / Kubernetes / docker-compose** 资源图(自动配官方云图标)、**SQL DDL → ER 图**、**OpenAPI / Swagger → API 图**(按 HTTP 方法着色的接口 + schema),**CI 流水线 → DAG**(GitHub Actions `needs:` 依赖图 + GitLab 阶段,含触发器、matrix 规模、可复用工作流调用)、以及从 `terraform show -json` / `docker inspect` / `kubectl get -o json` 提取的**实时**基础设施(画出真正已部署的样子) |
| **图对比 (diff)** | `drawiodiff.py` 把两张 `.drawio`(或两个实时快照)对比成一张彩色图 —— 新增=绿、删除=红、变更=橙 —— 一眼看出架构 / 基础设施**漂移** |
| **语言变体** | `relabel.py` 按 JSON 映射批量换标签,布局/样式/id 全不动 —— `--extract` 导出全部标签,翻译值后 `--map` 应用。一张图 → 中英双胞胎,双语文档必备 |
| **换主题** | `restyle.py` 给**已有** `.drawio` 应用风格预设(内置 `dark`/`corporate`/… 或自定义)—— 按色相重映射调色板,同色节点保持同组;布局与连线路由不动 |
diff --git a/docs/CI.md b/docs/CI.md
index da91097..1920428 100644
--- a/docs/CI.md
+++ b/docs/CI.md
@@ -10,6 +10,8 @@ source (.tf / manifests / schema.sql / seq.json / graph.json)
→ 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.
## Option A — draw.io desktop + xvfb (GitHub Actions)
diff --git a/docs/CI_CN.md b/docs/CI_CN.md
index aae256b..c926443 100644
--- a/docs/CI_CN.md
+++ b/docs/CI_CN.md
@@ -10,6 +10,8 @@
→ autolayout.py → validate.py --strict(门禁)→ drawio -x(渲染)→ 产物
```
+彩蛋:流水线本身也能入图 —— `ciimports.py <仓库根目录>` 把 `.github/workflows/*.yml` + `.gitlab-ci.yml` 转成 jobs/`needs:` 依赖 DAG(含触发器、matrix 规模、可复用工作流调用),走同一条 autolayout → validate → 渲染流程。
+
Importer 的节点 id 是稳定的(模块路径、`type.name`、`kind/name`),代码或基础设施变更后重新生成的 `.drawio` diff 可读、可 review。
## 方案 A —— draw.io 桌面版 + xvfb(GitHub Actions)
diff --git a/skills/drawio-skill/SKILL.md b/skills/drawio-skill/SKILL.md
index 241af03..0bf5783 100644
--- a/skills/drawio-skill/SKILL.md
+++ b/skills/drawio-skill/SKILL.md
@@ -1,6 +1,6 @@
---
name: drawio-skill
-version: 1.31.0
+version: 1.32.0
description: Use when the user requests diagrams, flowcharts, architecture diagrams, ER diagrams, UML / sequence / class diagrams, SysML / MBSE diagrams (block definition, internal block, requirement, parametric), BPMN business process diagrams, swimlane / cross-functional flowcharts, network topology, cloud architecture from Terraform or Kubernetes manifests, ML/DL model figures (Transformer/CNN/LSTM), mind maps, or any visualization. Also use proactively when explaining systems with 3+ components, complex data flows, or relationships that benefit from visual representation. Best suited when the diagram needs custom styling, rich shape vocabulary, swimlanes, or exportable images (PNG/SVG/PDF/JPG). Generates .drawio XML and exports locally via the native draw.io desktop CLI.
license: MIT
homepage: https://github.com/Agents365-ai/drawio-skill
@@ -34,7 +34,7 @@ When the workflow references one of these, read it on demand — none of them ne
| File | Read it when |
|---|---|
-| `references/toolbox.md` | You're **not sure which bundled script fits** a request, or want to chain several — a map of all 30 scripts grouped by use-case (author / import code / import IaC / import API spec / live infra / compare / annotate / reverse-export / utilities) with an "I have X, I want Y → use Z" guide |
+| `references/toolbox.md` | You're **not sure which bundled script fits** a request, or want to chain several — a map of all 31 scripts grouped by use-case (author / import code / import IaC / import API spec / live infra / compare / annotate / reverse-export / utilities) with an "I have X, I want Y → use Z" guide |
| `references/xml-authoring.md` | You're about to **hand-write `.drawio` XML** (workflow step 3) — file skeleton, shape/edge cells, containers, connection distribution, palette, spacing/grid rules. Not needed when a bundled generator writes the XML |
| `references/mermaid-authoring.md` | The diagram is a **standard type with no custom styling/icon needs** (flowchart, state, gantt, mindmap, timeline, journey, pie, …) and the CLI is **≥ v30** — author it as Mermaid text and let the CLI convert to native `.drawio` (structure only, layout free). Also documents the CLI's ELK `--layout` pass for XML |
| `references/diagram-types.md` | The user names a specific diagram type (ERD, UML class, sequence, C4, architecture, ML/DL, flowchart, SysML, BPMN, network topology, swimlane) |
@@ -58,6 +58,7 @@ When the workflow references one of these, read it on demand — none of them ne
| `scripts/svgflow.py` | The user wants an **animated / "flowing" diagram** (data-flow, moving edges) — `svgflow.py diagram.drawio -o flow.svg` exports to SVG and makes every edge a marching-ants animation (dashes travel along the arrows). Self-contained looping `.svg` that renders on GitHub / any browser; `--speed` / `--dash` / `--reverse` |
| `scripts/drawio2mermaid.py` | The user wants to **convert a `.drawio` into Mermaid text** (diagrams-as-code for a Markdown file that GitHub renders) — `drawio2mermaid.py diagram.drawio` emits a `flowchart` (containers → `subgraph`s, edge labels kept, cylinder/rhombus shapes mapped); `--fenced` wraps in ```mermaid, multi-page → one graph per page. Structural only (styling/icons don't survive) |
| `scripts/sqlerd.py` | The user wants an **ER diagram from SQL DDL** — parses `CREATE TABLE` statements into per-table nodes (columns with PK/FK markers) and crow's-foot FK edges for autolayout |
+| `scripts/ciimports.py` | The user wants a **CI pipeline diagram** (GitHub Actions workflows or GitLab CI) — `ciimports.py <repo-root>` reads `.github/workflows/*.yml` + `.gitlab-ci.yml` and emits jobs (runner, matrix size, reusable-workflow calls), `needs:` dependency edges, per-workflow trigger nodes, and stage/workflow containers for autolayout. Needs PyYAML |
| `scripts/openapiimports.py` | The user wants an **API diagram from an OpenAPI / Swagger spec** — `openapiimports.py spec.yaml` maps each operation to a node **coloured by HTTP method** (GET blue, POST green, PUT/PATCH orange, DELETE red) plus one node per component schema, with edges from operations to the schemas they use and between nested schemas. `--group` boxes by tag, `--no-schemas` shows just the endpoint surface; feeds autolayout |
| `scripts/heatmap.py` | The user wants to **colour an existing `.drawio` by data** (a cost / latency / traffic / error-rate heat map) — `heatmap.py diagram.drawio -m metrics.csv` matches each metric (CSV `key,value` or JSON `{key:value}`) to a node by id or label and recolours it along a gradient (`--palette heat\|cool\|warm`, `--reverse`), optionally scaling node size (`--size`) and adding a legend. Post-processes any diagram; export as usual |
| `scripts/seqlayout.py` | The user wants a **sequence diagram** — describe participants + messages as JSON and the script computes all lifeline/activation/arrow geometry deterministically (no hand-placed coordinates, no Graphviz needed) |
@@ -114,7 +115,7 @@ When a preset loads successfully, mention it in the first line of the reply: *"U
1. **Check deps** — **resolve which name the binary has on this system** and use that name verbatim in every subsequent command in this workflow. Try in order: (a) `drawio --version` (the canonical name for Homebrew cask, jgraph `.deb`/`.rpm`, Arch AUR), (b) `draw.io --version` (older builds, some custom symlinks, some distro packages), (c) macOS `.app` direct: `/Applications/draw.io.app/Contents/MacOS/draw.io --version`, (d) Windows: `"C:\Program Files\draw.io\draw.io.exe" --version`. The first one that prints a version is your binary; remember the exact path/name and substitute it for `drawio` in every export command below. **Do not copy the example commands verbatim if your binary is named differently** — the examples use `drawio` only because it's the most common. On macOS-Homebrew, `drawio` is just a thin wrapper script that execs `/Applications/draw.io.app/Contents/MacOS/draw.io` — they run the same engine, so candidate (c) is only needed when the `drawio` wrapper is absent (e.g. the app was installed by drag-and-drop without the cask). **Also note the major version** the command printed: **≥ 30** unlocks Mermaid→`.drawio` conversion and the ELK `--layout` pass (see `references/mermaid-authoring.md`); on **≤ 29** both are unavailable — `.mmd` input fails and `--layout` corrupts argument parsing — so never emit those flags there.
2. **Plan** — identify shapes, relationships, layout (LR or TB), group by tier/layer
-3. **Generate** — produce the `.drawio` file, choosing the authoring mode: **(a) Mermaid → CLI convert** when the diagram is a standard type with no custom styling/icon needs **and** the CLI is ≥ v30 — write a `.mmd` and run `drawio -x -f xml -o <name>.drawio <name>.mmd`, see `references/mermaid-authoring.md` (structure only; layout comes free; never `--layout` afterwards). **(b) Hand-written XML** for custom styling, vendor icons, swimlanes, precise geometry — **read `references/xml-authoring.md` first** (skeleton, cell forms, palette, spacing rules). **(c) A bundled generator** for the data-driven cases below. **For large or layout-heavy diagrams (dependency/call graphs, code structure, >~15 nodes), don't hand-place** — describe the graph as JSON and run `python3 <this-skill-dir>/scripts/autolayout.py graph.json -o <name>.drawio` to compute node positions + orthogonal edge routing via Graphviz (see `references/autolayout.md`; add `--tune` to auto-pick the more readable direction). For a **Python / JS-TS / Go / Rust project**, the matching importer (`scripts/pyimports.py`, `jsimports.py`, `goimports.py`, or `rustimports.py`) extracts the import graph (transitive-reduced; add `--group` to box modules by sub-package, nested for deep trees) ready for autolayout; for a **Python class hierarchy**, `scripts/pyclasses.py` extracts classes + inheritance instead; for **Terraform / Kubernetes / docker-compose** (`scripts/tfimports.py`, `k8simports.py`, `composeimports.py`), the importer extracts the resource/service reference graph — tf/k8s nodes resolve to their official cloud icons automatically; to draw **what is actually running** rather than the declared config, pipe `terraform show -json` into `scripts/tfstate.py` or `docker inspect $(docker ps -q)` into `scripts/dockerimports.py` (`k8simports.py` already accepts live `kubectl get ... -o json`) — see `references/live-infra.md`; for an **ER diagram from SQL DDL**, `scripts/sqlerd.py` parses `CREATE TABLE` into table nodes + crow's-foot FK edges; for an **API diagram from an OpenAPI / Swagger spec**, `scripts/openapiimports.py` maps operations (coloured by HTTP method) + component schemas into a graph for autolayout. To turn any generated `.drawio` into a **metric heat map** — recolour nodes by a CSV/JSON of cost/latency/traffic/errors — run `python3 <this-skill-dir>/scripts/heatmap.py <name>.drawio -m metrics.csv` (matches on cell id or label; `--palette`, `--size`, legend). For a **sequence diagram**, skip autolayout entirely — describe participants + messages as JSON and run `python3 <this-skill-dir>/scripts/seqlayout.py seq.json -o <name>.drawio` (deterministic lifeline/activation/arrow geometry; see the script docstring for the JSON schema). For a **C4 model**, `python3 <this-skill-dir>/scripts/c4.py c4.json -o <name>.drawio` emits the full multi-page Context→Container→Component set with drill-down links (schema in the script docstring). For complex architecture diagrams with many visible edge labels, give labels `labelBackgroundColor=#ffffff;fontSize=11` and use edge geometry `x`/`y` offsets plus `<mxPoint as="offset" />` to move long labels into nearby whitespace instead of relying on draw.io's default midpoint placement. After generating any `.drawio`, run `python3 <this-skill-dir>/scripts/validate.py <name>.drawio` for a fast structural lint (dangling edges, dup ids, overlaps) before exporting. Default output dir is the user's working dir; if the user specified an output path or directory (e.g. `./artifacts/`, `docs/images/`), use that instead — `mkdir -p` the target dir first. Apply the same dir choice to PNG/SVG/PDF exports in steps 4 and 7.
+3. **Generate** — produce the `.drawio` file, choosing the authoring mode: **(a) Mermaid → CLI convert** when the diagram is a standard type with no custom styling/icon needs **and** the CLI is ≥ v30 — write a `.mmd` and run `drawio -x -f xml -o <name>.drawio <name>.mmd`, see `references/mermaid-authoring.md` (structure only; layout comes free; never `--layout` afterwards). **(b) Hand-written XML** for custom styling, vendor icons, swimlanes, precise geometry — **read `references/xml-authoring.md` first** (skeleton, cell forms, palette, spacing rules). **(c) A bundled generator** for the data-driven cases below. **For large or layout-heavy diagrams (dependency/call graphs, code structure, >~15 nodes), don't hand-place** — describe the graph as JSON and run `python3 <this-skill-dir>/scripts/autolayout.py graph.json -o <name>.drawio` to compute node positions + orthogonal edge routing via Graphviz (see `references/autolayout.md`; add `--tune` to auto-pick the more readable direction). For a **Python / JS-TS / Go / Rust project**, the matching importer (`scripts/pyimports.py`, `jsimports.py`, `goimports.py`, or `rustimports.py`) extracts the import graph (transitive-reduced; add `--group` to box modules by sub-package, nested for deep trees) ready for autolayout; for a **Python class hierarchy**, `scripts/pyclasses.py` extracts classes + inheritance instead; for **Terraform / Kubernetes / docker-compose** (`scripts/tfimports.py`, `k8simports.py`, `composeimports.py`), the importer extracts the resource/service reference graph — tf/k8s nodes resolve to their official cloud icons automatically; to draw **what is actually running** rather than the declared config, pipe `terraform show -json` into `scripts/tfstate.py` or `docker inspect $(docker ps -q)` into `scripts/dockerimports.py` (`k8simports.py` already accepts live `kubectl get ... -o json`) — see `references/live-infra.md`; for an **ER diagram from SQL DDL**, `scripts/sqlerd.py` parses `CREATE TABLE` into table nodes + crow's-foot FK edges; for an **API diagram from an OpenAPI / Swagger spec**, `scripts/openapiimports.py` maps operations (coloured by HTTP method) + component schemas into a graph for autolayout; for a **CI pipeline diagram** (GitHub Actions / GitLab CI), `scripts/ciimports.py` extracts jobs, `needs:` edges, triggers, and stage/workflow containers. To turn any generated `.drawio` into a **metric heat map** — recolour nodes by a CSV/JSON of cost/latency/traffic/errors — run `python3 <this-skill-dir>/scripts/heatmap.py <name>.drawio -m metrics.csv` (matches on cell id or label; `--palette`, `--size`, legend). For a **sequence diagram**, skip autolayout entirely — describe participants + messages as JSON and run `python3 <this-skill-dir>/scripts/seqlayout.py seq.json -o <name>.drawio` (deterministic lifeline/activation/arrow geometry; see the script docstring for the JSON schema). For a **C4 model**, `python3 <this-skill-dir>/scripts/c4.py c4.json -o <name>.drawio` emits the full multi-page Context→Container→Component set with drill-down links (schema in the script docstring). For complex architecture diagrams with many visible edge labels, give labels `labelBackgroundColor=#ffffff;fontSize=11` and use edge geometry `x`/`y` offsets plus `<mxPoint as="offset" />` to move long labels into nearby whitespace instead of relying on draw.io's default midpoint placement. After generating any `.drawio`, run `python3 <this-skill-dir>/scripts/validate.py <name>.drawio` for a fast structural lint (dangling edges, dup ids, overlaps) before exporting. Default output dir is the user's working dir; if the user specified an output path or directory (e.g. `./artifacts/`, `docs/images/`), use that instead — `mkdir -p` the target dir first. Apply the same dir choice to PNG/SVG/PDF exports in steps 4 and 7.
4. **Export draft** — run CLI to produce a preview PNG. **Do NOT pass `-e`** at this step — the embedded `zTXt mxGraphModel` chunk it adds causes vision APIs (Claude included) to return 400 "Could not process image" in step 5. **Cap the preview width with `--width 2000` (not `-s 2`)** — Claude's vision API rejects images larger than 2576×2576px with "Unable to resize image — dimensions exceed the 2576x2576px limit", and `-s 2` on a medium-or-larger diagram easily overshoots that ceiling. Save the clean preview as `<name>.png` (single extension). Embedding and full-resolution scale are for the final export only (step 7).
5. **Self-check** — use the agent's built-in vision capability to read the exported PNG, catch obvious issues, auto-fix before showing user (requires a vision-enabled model such as Claude Sonnet/Opus). If reading the PNG returns a 400 / "Could not process image" error, you almost certainly exported with `-e` by mistake — re-export without `-e` and retry once. If it still fails, skip self-check and continue to step 6.
6. **Review loop** — show image to user, collect feedback, apply targeted XML edits, re-export, repeat until approved
diff --git a/skills/drawio-skill/references/toolbox.md b/skills/drawio-skill/references/toolbox.md
index 47bf3fe..832fdc2 100644
--- a/skills/drawio-skill/references/toolbox.md
+++ b/skills/drawio-skill/references/toolbox.md
@@ -1,6 +1,6 @@
# Toolbox — every bundled script, by use-case
-A map of the 30 bundled scripts grouped by what you're trying to do. The
+A map of the 31 bundled scripts grouped by what you're trying to do. The
per-task routing table in `SKILL.md` says *when* to reach for each; this says
*how they fit together*. Read it when you're not sure which script a request
maps to, or you want to chain several.
@@ -24,6 +24,7 @@ exports it:
| a running cluster/stack/cloud | what's **actually deployed** | `tfstate` · `dockerimports` · `k8simports -` |
| a SQL schema | an ER diagram | `sqlerd` |
| an OpenAPI / Swagger spec | an API diagram (by method) | `openapiimports` |
+| CI workflows (GH Actions / GitLab) | the pipeline as a DAG | `ciimports` |
| a diagram + a metrics file | it coloured by the data | `heatmap` |
| a sequence of interactions | a UML sequence diagram | `seqlayout` |
| a system at 3 zoom levels | a C4 model with drill-down | `c4` |
@@ -58,6 +59,7 @@ All emit graph JSON → `autolayout.py`.
- **`k8simports.py`** — K8s manifests → objects as official kind icons (edges: Ingress→Service→workload→ConfigMap/Secret/PVC).
- **`composeimports.py`** — docker-compose → service boxes + volume cylinders.
- **`sqlerd.py`** — SQL DDL (`CREATE TABLE`) → ERD with crow's-foot FK edges.
+- **`ciimports.py`** — GitHub Actions (`.github/workflows/*.yml`) and/or `.gitlab-ci.yml` -> pipeline DAG: job nodes (runner, `matrix xN`, reusable-workflow calls in purple), `needs:` edges, an `on:` trigger node per workflow, jobs boxed per workflow / per GitLab stage.
- **`openapiimports.py`** — OpenAPI 3 / Swagger 2 spec → API diagram: one node per operation (coloured by HTTP method) + one per component schema, with edges to the schemas each operation uses and between nested schemas. `--group` by tag.
## 4. Live infrastructure → diagram (actually running)
diff --git a/skills/drawio-skill/scripts/ciimports.py b/skills/drawio-skill/scripts/ciimports.py
new file mode 100644
index 0000000..1c865ac
--- /dev/null
+++ b/skills/drawio-skill/scripts/ciimports.py
@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""Extract a CI pipeline (GitHub Actions / GitLab CI) as autolayout graph JSON.
+
+GitHub Actions: every job becomes a node (label: name, runner, matrix size,
+reusable-workflow target), `needs:` become edges, and each workflow gets a
+trigger node (its `on:` events) feeding the jobs that have no `needs`. Given a
+repo root, all of `.github/workflows/*.yml|yaml` are read and each workflow is
+boxed in its own container.
+
+GitLab CI (`.gitlab-ci.yml`, auto-detected): jobs become nodes grouped by
+stage; edges come from `needs:`, and jobs without `needs` inherit the stage
+DAG (every job of the previous stage), matching GitLab's execution order.
+
+ python3 ciimports.py . # repo root -> all workflows
+ python3 ciimports.py .github/workflows/ci.yml -o graph.json
+ python3 autolayout.py graph.json -o pipeline.drawio
+
+Requires PyYAML (pip install pyyaml).
+
+Usage: python3 ciimports.py <repo-root | workflow.yml ...> [-o graph.json]
+ [--direction TB|LR]
+"""
+import argparse
+import json
+import os
+import sys
+
+JOB_STYLE = "rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;"
+REUSE_STYLE = "rounded=1;whiteSpace=wrap;html=1;fillColor=#e1d5e7;strokeColor=#9673a6;"
+TRIGGER_STYLE = "ellipse;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;"
+
+GITLAB_RESERVED = {"stages", "variables", "workflow", "default", "include", "image",
+ "services", "before_script", "after_script", "cache", "pages"}
+
+
+def find_workflows(path):
+ """Workflow files for a path: file(s) as-is, a repo root via .github/workflows."""
+ if os.path.isfile(path):
+ return [path]
+ wfdir = os.path.join(path, ".github", "workflows")
+ files = sorted(os.path.join(wfdir, f) for f in os.listdir(wfdir)
+ if f.endswith((".yml", ".yaml"))) if os.path.isdir(wfdir) else []
+ gitlab = os.path.join(path, ".gitlab-ci.yml")
+ if os.path.isfile(gitlab):
+ files.append(gitlab)
+ if not files:
+ sys.exit(f"error: no workflow files under {path}")
+ return files
+
+
+def matrix_size(strategy):
+ n = 1
+ matrix = (strategy or {}).get("matrix") or {}
+ if not isinstance(matrix, dict):
+ return 0 # dynamic (fromJSON) — unknown
+ for key, vals in matrix.items():
+ if key not in ("include", "exclude") and isinstance(vals, list):
+ n *= len(vals)
+ n += len(matrix.get("include") or []) - len(matrix.get("exclude") or [])
+ return max(n, 1)
+
+
+def parse_actions(spec, wf_id, wf_name, group):
+ """One GitHub Actions workflow -> (nodes, edges)."""
+ nodes, edges = [], []
+ # YAML 1.1 quirk: bare `on:` parses as boolean True
+ on = spec.get("on", spec.get(True, {}))
+ events = sorted(on) if isinstance(on, dict) else \
+ ([on] if isinstance(on, str) else sorted(on or []))
+ trig_id = f"{wf_id}//trigger"
+ nodes.append({"id": trig_id, "label": "on: " + (", ".join(events) or "?"),
+ "style": TRIGGER_STYLE, "width": 160, "height": 50, "group": group})
+ jobs = spec.get("jobs") or {}
+ for jid, job in jobs.items():
+ job = job or {}
+ lines = [job.get("name") or jid]
+ if job.get("uses"):
+ lines.append("uses: " + os.path.basename(str(job["uses"])))
+ style = REUSE_STYLE
+ else:
+ style = JOB_STYLE
+ runner = job.get("runs-on")
+ if runner:
+ lines.append(str(runner if isinstance(runner, str) else ", ".join(runner)))
+ n = matrix_size(job.get("strategy"))
+ if n > 1:
+ lines.append(f"matrix ×{n}")
+ elif n == 0:
+ lines.append("matrix (dynamic)")
+ nodes.append({"id": f"{wf_id}//{jid}", "label": "\n".join(lines),
+ "style": style, "width": 180, "height": 60, "group": group})
+ needs = job.get("needs") or []
+ needs = [needs] if isinstance(needs, str) else needs
+ for dep in needs:
+ if dep in jobs:
+ edges.append({"source": f"{wf_id}//{dep}", "target": f"{wf_id}//{jid}"})
+ if not needs:
+ edges.append({"source": trig_id, "target": f"{wf_id}//{jid}"})
+ return nodes, edges
+
+
+def parse_gitlab(spec, wf_id, group_prefix):
+ """A .gitlab-ci.yml -> (nodes, edges); jobs grouped by stage."""
+ stages = spec.get("stages") or ["build", "test", "deploy"]
+ jobs = {k: v for k, v in spec.items()
+ if isinstance(v, dict) and k not in GITLAB_RESERVED and not k.startswith(".")
+ and ("script" in v or "trigger" in v or "extends" in v or "stage" in v)}
+ nodes, edges = [], []
+ by_stage = {}
+ for jid, job in jobs.items():
+ stage = job.get("stage") or "test"
+ by_stage.setdefault(stage, []).append(jid)
+ nodes.append({"id": f"{wf_id}//{jid}", "label": jid, "style": JOB_STYLE,
+ "width": 160, "height": 50,
+ "group": f"{group_prefix}{stage}"})
+ order = [s for s in stages if s in by_stage]
+ for jid, job in jobs.items():
+ needs = [(n.get("job") if isinstance(n, dict) else n) for n in job.get("needs") or []]
+ needs = [n for n in needs if n in jobs]
+ if needs:
+ edges.extend({"source": f"{wf_id}//{n}", "target": f"{wf_id}//{jid}"} for n in needs)
+ else: # stage DAG: all jobs of the previous stage
+ stage = job.get("stage") or "test"
+ i = order.index(stage) if stage in order else 0
+ if i > 0:
+ edges.extend({"source": f"{wf_id}//{p}", "target": f"{wf_id}//{jid}"}
+ for p in by_stage[order[i - 1]])
+ return nodes, edges
+
+
+def main():
+ ap = argparse.ArgumentParser(description="CI pipeline -> autolayout graph JSON.")
+ ap.add_argument("paths", nargs="+",
+ help="repo root, or workflow file(s) (.github/workflows/*.yml, .gitlab-ci.yml)")
+ ap.add_argument("-o", "--output", help="output JSON path (default: stdout)")
+ ap.add_argument("--direction", default="LR", choices=["TB", "LR"])
+ args = ap.parse_args()
+
+ try:
+ import yaml
+ except ImportError:
+ sys.exit("error: PyYAML is required (pip install pyyaml)")
+
+ files = [f for p in args.paths for f in find_workflows(p)]
+ nodes, edges = [], []
+ for path in files:
+ with open(path, encoding="utf-8") as f:
+ try:
+ spec = yaml.safe_load(f) or {}
+ except yaml.YAMLError as e:
+ sys.stderr.write(f"warning: skipping {path}: {e}\n")
+ continue
+ wf_id = os.path.splitext(os.path.basename(path))[0]
+ if os.path.basename(path) == ".gitlab-ci.yml" or (
+ "jobs" not in spec and "stages" in spec):
+ n, e = parse_gitlab(spec, wf_id, "stage: " if len(files) == 1
+ else f"{wf_id} / stage: ")
+ elif spec.get("jobs"):
+ wf_name = spec.get("name") or wf_id
+ group = wf_name if len(files) > 1 else None
+ n, e = parse_actions(spec, wf_id, wf_name, group)
+ else:
+ sys.stderr.write(f"warning: {path} has no jobs — skipped\n")
+ continue
+ nodes.extend(n)
+ edges.extend(e)
+ if not nodes:
+ sys.exit("error: no CI jobs found")
+
+ graph = {"direction": args.direction, "nodes": nodes, "edges": edges}
+ text = json.dumps(graph, indent=2)
+ if args.output:
+ with open(args.output, "w", encoding="utf-8") as f:
+ f.write(text)
+ sys.stderr.write(f"wrote {args.output}\n")
+ else:
+ sys.stdout.write(text)
+ sys.stderr.write(f"{len(nodes)} nodes, {len(edges)} edges from {len(files)} file(s)\n")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tests/test_scripts.py b/tests/test_scripts.py
index 790fe9d..5c951d9 100644
--- a/tests/test_scripts.py
+++ b/tests/test_scripts.py
@@ -1249,5 +1249,63 @@ class TestRestyle(unittest.TestCase):
self.assertIn("dark", r.stderr + r.stdout)
+class TestCiImports(unittest.TestCase):
+ @staticmethod
+ def _write(path, text):
+ os.makedirs(os.path.dirname(path), exist_ok=True)
+ with open(path, "w", encoding="utf-8") as f:
+ f.write(text)
+
+ def _need_yaml(self):
+ try:
+ import yaml # noqa: F401
+ except ImportError:
+ self.skipTest("PyYAML not installed")
+
+ ACTIONS = (
+ "name: CI\n"
+ "on: [push]\n"
+ "jobs:\n"
+ " lint:\n runs-on: ubuntu-latest\n steps: [{run: make lint}]\n"
+ " test:\n runs-on: ubuntu-latest\n"
+ " strategy:\n matrix:\n py: ['3.10', '3.11']\n"
+ " steps: [{run: pytest}]\n"
+ " deploy:\n needs: [lint, test]\n"
+ " uses: org/shared/.github/workflows/deploy.yml@main\n")
+
+ GITLAB = (
+ "stages: [build, test]\n"
+ "compile:\n stage: build\n script: [make]\n"
+ "unit:\n stage: test\n script: [make test]\n")
+
+ def test_actions_workflow(self):
+ self._need_yaml()
+ with tempfile.TemporaryDirectory() as d:
+ self._write(os.path.join(d, ".github", "workflows", "ci.yml"), self.ACTIONS)
+ graph = json.loads(run("ciimports.py", d).stdout)
+ by_id = {n["id"]: n for n in graph["nodes"]}
+ self.assertIn("ci//trigger", by_id)
+ self.assertEqual(by_id["ci//trigger"]["label"], "on: push")
+ self.assertIn("matrix \u00d72", by_id["ci//test"]["label"])
+ self.assertIn("uses: deploy.yml@main", by_id["ci//deploy"]["label"])
+ edges = {(e["source"], e["target"]) for e in graph["edges"]}
+ self.assertIn(("ci//trigger", "ci//lint"), edges) # no needs -> trigger
+ self.assertIn(("ci//lint", "ci//deploy"), edges)
+ self.assertIn(("ci//test", "ci//deploy"), edges)
+ self.assertNotIn(("ci//trigger", "ci//deploy"), edges) # has needs
+
+ def test_gitlab_stage_dag(self):
+ self._need_yaml()
+ with tempfile.TemporaryDirectory() as d:
+ p = os.path.join(d, ".gitlab-ci.yml")
+ self._write(p, self.GITLAB)
+ graph = json.loads(run("ciimports.py", p).stdout)
+ by_id = {n["id"]: n for n in graph["nodes"]}
+ self.assertEqual(by_id[".gitlab-ci//unit"]["group"], "stage: test")
+ edges = {(e["source"], e["target"]) for e in graph["edges"]}
+ # no needs -> previous stage DAG
+ self.assertEqual(edges, {(".gitlab-ci//compile", ".gitlab-ci//unit")})
+
+
if __name__ == "__main__":
unittest.main()