Pipeline architecture
How a change moves from a branch to a published release and a live website, which gate blocks it at each step, and what each gate is actually proving. The canonical rules for contributors live in CONTRIBUTING.md; this document is the operator's map.
Rendered version with diagrams: index.html. The diagram sources are in ../diagrams/ and are built by node enterprise/diagrams/build.mjs.
What the repository ships
| Artifact | Built by | Consumed by |
|---|---|---|
archify.zip (the skill) | scripts/build-zip.sh | Skills CLI, npx skills add, DSH, agents |
| GitHub Release + asset | release.yml on v* | The update notifier and manual downloads |
docs/skill-updates/.../stable.json | A follow-up commit | The notifier's version check |
Static website (website/dist) | website job, Astro | GitHub Pages, Cloudflare Pages |
| SBOM + provenance attestation | security.yml, provenance.yml | Auditors, gh attestation verify |
The skill has no runtime dependencies. That is a supply-chain property, not an accident, and security.yml fails if someone adds one.
The whole path
flowchart TB
subgraph authoring["Authoring"]
A[feature branch] -->|pull request| B[PR opened]
end
subgraph gates["Required gates on the PR"]
B --> C[scope classifier<br/>scripts/ci-scope.mjs]
C -->|docs| D[docs checks]
C -->|core| E[test 18/20/24 · test 22 · affected suites]
C -->|full| F[full regression shards · browser · webm · package · windows]
B --> G[security gates<br/>pins · codeql · dependency review · sbom · lint]
B --> H[website build + browser continuity]
end
subgraph merge["Merge control"]
D --> I{protect-main ruleset}
E --> I
F --> I
G --> I
H --> I
I -->|1 approval · CODEOWNERS · last-push approval<br/>required contexts green · no agent bypass| J[dev]
end
subgraph promote["Promotion"]
J -->|trial use on real diagram tasks| K[PR dev → main]
K --> L[main]
end
subgraph publish["Publication"]
L -->|tag v*| M[release.yml<br/>environment: production]
M -->|reviewer approves| N[GitHub Release + archify.zip]
N --> O[provenance.yml<br/>SHA256SUMS + attestation + SBOM]
L --> P[deploy-pages / deploy-cloudflare]
end
Job inventory
Everything below is real today. "Blocks merge" means the check is in the protect-main required set and a failure stops the pull request.
Verification — .github/workflows/ci.yml
| Job | Scope gate | Blocks merge | Proves |
|---|---|---|---|
scope | always | indirectly | Which coverage this change needs. Fails closed on an unclassifiable diff. |
test (18) test (20) test (24) | not docs | yes | The public CLI contract on every supported Node runtime. |
test (22) (canonical-test) | not docs | yes | Canonical runtime: core contracts, affected suites, goldens when generated output moved. |
full-regression (1|2) | full only | via test (22) | Complete regression, split in two shards; runs once for renderer, viewer, dependency and workflow changes. |
browser-regression (1|2) | browser gate | via webm-artifact | Real Chrome: rendered output and interaction, not source assertions. |
webm-decode | webm gate | via webm-artifact | A motion export contains distinct decoded frames, not a static still. |
webm-artifact | always | yes | Aggregates the browser and WebM gates into one always-present check. |
zip-freshness | package gate | yes | Committed archify.zip is the byte-identical deterministic build. |
published-update-manifest | manifest gate | yes | stable.json points at a real, published, byte-matching Release. |
package smoke (ubuntu|macos|windows) | package gate | yes | The packaged skill installs and validates on three platforms. |
Windows test portability (Node 22|24) | windows gate | yes | Path, 8.3-name and delivery-lock behaviour under real Windows paths. |
website | website gate | no (conditional) | Astro typecheck, build, browser continuity, Cloudflare output contract. |
Two design decisions are worth keeping in mind when you change a job name:
- Aggregator jobs exist so a required check is always present.
webm-artifactis required; the two jobs it aggregates are conditional. A required check that is skipped leaves a pull request permanently pending, so the aggregate always runs and fails when a dependency failed or was skipped unexpectedly. - The classifier is allowed to ask for more, never less. An empty diff, an unknown path or an unavailable comparison base all select full coverage. A failed classification cannot become a successful skip.
Security — .github/workflows/security.yml
| Job | Trigger | Blocks merge | Proves |
|---|---|---|---|
security / action pins | PR, push, weekly | yes | Every remote action is a 40-character commit SHA, and the repo's own pinning contract passes. |
security / codeql | PR (same-repo), push, weekly | no — enforced by the code_scanning ruleset rule instead | Static analysis with security-extended queries. Not required directly because fork PRs cannot upload results; the ruleset blocks a merge on a high-severity alert regardless of author. |
security / dependency review | PR | yes | A new dependency with a known advisory or an incompatible licence never reaches main. |
security / sbom (root|archify|website) | PR, push | yes | A CycloneDX SBOM exists for each package root; the shipped skill still declares zero runtime dependencies. |
security / workflow lint | PR, push | yes | actionlint plus the repository's own workflow contracts (ci-scope, Cloudflare, compatibility). |
Delivery
| Workflow | Trigger | Gate |
|---|---|---|
ci.yml → deploy-pages | push to main, all gates green | GitHub Pages, environment github-pages, obsolete-run rejection by comparing main HEAD. |
ci.yml → deploy-cloudflare | push to main, vars.CLOUDFLARE_PAGES_PROJECT set | Cloudflare Pages, environment cloudflare-pages, production branch only. |
release.yml | push of a v* tag | Environment production (platform reviewer), version/tag match, full suite, deterministic archive, annotated tag for stable. |
provenance.yml | release published | SHA-256 sums, build provenance attestation, SBOM asset. Never rebuilds. |
preview.yml | PR touching website/** | Non-production Cloudflare preview branch pr-<n>, same-repo PRs only. |
governance.yml | daily, and on governance changes | Read-only drift report against enterprise/governance/. |
dsh.yml | PR/push touching the DSH integration | The independently versioned plugin contract. |
contributor-cards.yml | PR, and merged PR via pull_request_target | Card rendering. The privileged run checks out the default branch only and never executes PR code. |
Promotion path
dev is the integration branch, main is stable. A change lands on dev, gets used on real diagram tasks, and is promoted to main in a separate pull request that records the tested revision and any unresolved issue. Passing CI is not trial-use acceptance; CONTRIBUTING.md owns that distinction and this pipeline does not try to encode it.
Publication is a tag on main, not a merge. That separation is why a rollback is cheap: the site can be reverted with a commit, a release can be superseded with a new tag, and neither requires unpicking a deploy pipeline.
Environment and secret placement
| Environment | Used by | Protection | Holds |
|---|---|---|---|
production | release.yml release job | Required reviewers (platform team), no self-review, tag policy v* | Nothing — publication uses GITHUB_TOKEN |
cloudflare-pages | ci.yml deploy-cloudflare | Reviewer (platform), branch main | CLOUDFLARE_API_TOKEN |
github-pages | ci.yml deploy-pages | Branch main only | Nothing |
preview | preview.yml | None (non-production) | CLOUDFLARE_API_TOKEN |
A pull request never sees a production secret: environment secrets are only released to a job that declares the environment, and no pull_request job here declares one. That is also why preview uses its own environment rather than borrowing the production one.
Token permissions
- Every workflow declares a top-level
permissions:block, defaulting tocontents: read. A job opts in to more (pages: write,security-events: write,contents: writefor a release) only where it needs it. - No workflow uses
permissions: write-all. persist-credentials: falseis set on checkouts that do not need to push.
Artifacts and retention
| Artifact | Producer | Retention | Purpose |
|---|---|---|---|
website-dist, website-cloudflare-dist | website job | 90 days | The exact bytes Pages and Cloudflare deploy. |
website-homepage-evidence | website job | 90 days | Visual evidence for a website review. |
sbom-* | security.yml | 90 days | Per-root CycloneDX documents. |
governance-drift-report | governance.yml | 90 days | What drifted, and when it was last checked. |
SHA256SUMS.txt, *.cdx.json | provenance.yml | Release lifetime | Verifiable with the release. |
What is deliberately absent
- No merge queue. The ruleset's
strict_required_status_checks_policyalready requires an up-to-date branch; a queue would add a second, weaker truth. - No self-hosted runners. Nothing here needs one, and a self-hosted runner on a public repository is a standing invitation.
- No auto-merge.
repository.jsondisables it, so no bot or agent can arm a merge and let it complete unattended. - No second release pipeline.
provenance.ymldescribes published bytes; it never builds or uploadsarchify.zip.CONTRIBUTING.mdis explicit that the existing release gates are reused rather than duplicated. - No deploy from a pull request. Previews publish to a preview branch; the production branch is only reachable from
mainafter every gate.