CI and Pages automation
GitHub Actions provides the repository's automated quality and publishing loop. Pull requests and pushes to main run the check suite, while pushes to main can also publish the static diagram gallery and update plugin version metadata. This page complements Diagram quality assurance and Diagram verification suite.
Workflow map
The workflows separate review checks from main-branch publishing and post-merge maintenance. A pull request enters CI only; a push to main can enter all three paths.
flowchart LR
PR[Pull request to main] --> CI[CI checks]
Push[Push to main] --> CI
Push --> Pages[Build gallery artifact]
Pages --> Deploy[Deploy GitHub Pages]
Push --> Bump[Prepare and publish version update]
Bump --> Main[Updated main]
Main --> CI
Main --> Pages
Repository validation
The CI workflow is the repository's review gate. It checks package metadata and maintainer policy, validates package rules, verifies Python compatibility, and runs source, rendered-output, documentation, accessibility, geometry, import, motion, and chart-data checks. It also checks generated assets, screenshots, thumbnails, standalone SVG exports, packaged self-checks, architecture-delta records, axonometric plan examples, and visual tone claims. The package gate also validates the Claude marketplace package and protects the rule that pull requests do not change manifest versions. The checks run on pull requests and on pushes to main, so the branch remains checked after automation creates a new commit.
CI uses separate package and compatibility checks plus a platform and Python-version matrix for the broad validation job. The matrix covers Linux, Windows, and macOS with Python 3.11 and 3.12, while the compatibility check covers Python 3.9. The rendered-layout check runs on one Linux Python 3.12 leg because its headless Chromium pixel result is the single calibrated visual reference; the other matrix legs still run the source checks. Validation steps report their outcomes even when an earlier check fails, which gives maintainers one summary of the run instead of stopping at the first error. The workflow also compares generated icon assets with their checked-in form and records each verification gate in the run summary. The standalone SVG export check protects the contract that exported files retain their needed styles and do not collide in their definition IDs. Arc diagrams also have dedicated span-geometry and checker gates. See the diagram verification suite for the checks themselves.
References: .github/…/ci.yml• L3-14 .github/…/ci.yml• L16-78 .github/…/ci.yml• L79-102 .github/…/ci.yml• L103-570 .github/…/ci.yml• L572-625 .github/…/ci.yml• L626-738
Gallery publication
The Pages workflow publishes the gallery as a static artifact. On a push to main, or after a manual dispatch, it packages skills/diagram-design/assets and sends that artifact to the GitHub Pages deployment environment. There is no separate site build in this workflow; the gallery's HTML assets are the hosted output.
Only one Pages deployment runs at a time. A new run waits for an active deployment instead of cancelling it, which avoids replacing a deployment while it is in progress. Pull requests do not publish the hosted gallery because this workflow has no pull-request trigger.
References: .github/…/pages.yml• L1-16 .github/…/pages.yml• L17-46 README.md• L105-107
Post-merge version maintenance
The Auto Version Bump workflow keeps the four plugin manifests and the shared skill metadata aligned after changes reach main. It examines the merged commits since the last manifest bump, uses release labels to choose the strongest required bump, and prepares a tightly limited update. A second job rechecks the branch before it publishes the change, so a newer push does not receive a stale version update.
The preparation job runs with read-only access and passes a short-lived patch artifact to the publishing job. The publishing job checks the artifact's paths and exact version changes again before it commits. The protected token is introduced only for the final push. Concurrent main-branch updates are serialized; if main advances during preparation or publication, the current run does not push and a newer queued run recomputes the update. Pull requests must not change plugin versions because the CI package gate enforces this boundary. Details belong in Plugin release automation.
References: .github/…/auto-bump.yml• L1-21 .github/…/auto-bump.yml• L23-35 .github/…/auto-bump.yml• L50-145 .github/…/auto-bump.yml• L147-219 .github/…/auto-bump.yml• L220-321 .github/…/auto-bump.yml• L323-368 .github/…/ci.yml• L43-78
Review previews
Visual changes use rendered evidence as part of review. The pull request template asks contributors to attach a preview for each changed diagram variant, and it requires light, dark, and full-editorial previews when a new diagram type is added. The assigned workflows publish the main gallery but do not generate pull-request screenshot attachments.
The committed preview collection now includes light, dark, and full-editorial arc-diagram images for reviewers. These files support side-by-side review before the live Pages gallery provides the browsable artifact after a main-branch push. The example collection and its variant rules are described in Diagram example gallery.
References: .github/PULL_REQUEST_TEMPLATE.md• L5-19 .github/PULL_REQUEST_TEMPLATE.md• L33-39 docs/…/arc-diagram-light.png docs/…/arc-diagram-dark.png docs/…/arc-diagram-full.png README.md• L105-107
Change checklist
When these files or sections are changed, remember to consider these:
- When a CI gate is added, removed, or renamed, update the CI summary and the contributor-facing validation list so the reported result still maps to a real check.
- When a new diagram verifier or contract gate is added, keep its source check and its CI summary row aligned so failures remain visible in the run summary.
- When the standalone SVG export contract changes, keep its export validation and the matching CI summary gate aligned.
- When the gallery entry point or asset directory changes, update the Pages artifact path and the links that users use to open the hosted or local gallery.
- When a visual example or canonical screenshot changes, keep the gallery registration, screenshot digest data, and freshness gate aligned.
- When version ownership changes, keep the PR no-bump rule, release-label policy, manifest allowlist, and post-merge publish path consistent.
- When Pages permissions, its environment, or its concurrency policy changes, recheck who can publish and whether deployments can overlap.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A pull request edits one of the plugin manifest versions | The package gate rejects the pull request before merge | Leave version changes to Auto Version Bump on main and use release labels for a larger bump |
| A visual change makes the rendered result spill, collapse, or overflow | The Linux Chromium render gate fails even when source checks pass | Keep the pinned Playwright and Chromium pair and inspect the rendered output rather than relying on source geometry |
| A standalone SVG export loses its styles or conflicts in its definition IDs | The standalone export gate fails even when the source diagram checks pass | Keep the export contract and its dedicated validation aligned with the SVG output |
| Architecture-delta snapshots or ledger data fall out of sync | The architecture-delta gate rejects the change even when other diagram checks pass | Update the checked snapshot and ledger inputs with the related architecture change |
| A tone claim no longer matches the polarity of its ramp | The skin-polarity gate rejects the affected diagram set | Keep the claim text and the referenced ramp semantics aligned |
| A shipped example is not reachable from the gallery or a support link points to a missing file | The documentation and routing gate fails | Register the example and update its routing and reference links in the same change |
| The Pages artifact path no longer contains the gallery entry point | The deployment has no valid hosted gallery output | Treat skills/diagram-design/assets and its entry point as the Pages publish contract |
main advances between version preparation and the final push | The current bump is skipped, leaving the newer queued run to recalculate it | Do not bypass the source and freshness checks or push the prepared patch manually |
| The prepared version artifact contains an unexpected path or a broader file change | The publishing job refuses to commit the bump | Keep the release allowlist and exact semantic validation aligned with the files that own the version |
AUTO_BUMP_TOKEN is missing or cannot update protected main | The validated version update is not published | Keep the secret configured and limit its use to the final publish step |
Key files
| File | Why to read it |
|---|---|
| .github/…/ci.yml | Defines the pull-request and main-branch quality gate, its package and compatibility checks, its platform matrix, its rendered-output oracle, its diagram contract gates, and its run summary. |
| .github/…/pages.yml | Defines how the static gallery becomes a GitHub Pages artifact and how deployments are serialized. |
| .github/…/auto-bump.yml | Defines the protected post-merge version-maintenance path, its restricted patch artifact, and its stale-branch protections. |
| .github/PULL_REQUEST_TEMPLATE.md | Defines the visual preview evidence expected from diagram changes. |
| docs/…/arc-diagram-light.png, docs/…/arc-diagram-dark.png, docs/…/arc-diagram-full.png | Provide the committed light, dark, and full-editorial arc-diagram review evidence. |
| CONTRIBUTING.md | Maps the workflow gates to contributor actions and explains the no-version-bump rule. |
| README.md | Shows the public gallery link and the local gallery entry point that Pages publishes. |