Zyeta Enterprise operations

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

ArtifactBuilt byConsumed by
archify.zip (the skill)scripts/build-zip.shSkills CLI, npx skills add, DSH, agents
GitHub Release + assetrelease.yml on v*The update notifier and manual downloads
docs/skill-updates/.../stable.jsonA follow-up commitThe notifier's version check
Static website (website/dist)website job, AstroGitHub Pages, Cloudflare Pages
SBOM + provenance attestationsecurity.yml, provenance.ymlAuditors, 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

JobScope gateBlocks mergeProves
scopealwaysindirectlyWhich coverage this change needs. Fails closed on an unclassifiable diff.
test (18) test (20) test (24)not docsyesThe public CLI contract on every supported Node runtime.
test (22) (canonical-test)not docsyesCanonical runtime: core contracts, affected suites, goldens when generated output moved.
full-regression (1|2)full onlyvia test (22)Complete regression, split in two shards; runs once for renderer, viewer, dependency and workflow changes.
browser-regression (1|2)browser gatevia webm-artifactReal Chrome: rendered output and interaction, not source assertions.
webm-decodewebm gatevia webm-artifactA motion export contains distinct decoded frames, not a static still.
webm-artifactalwaysyesAggregates the browser and WebM gates into one always-present check.
zip-freshnesspackage gateyesCommitted archify.zip is the byte-identical deterministic build.
published-update-manifestmanifest gateyesstable.json points at a real, published, byte-matching Release.
package smoke (ubuntu|macos|windows)package gateyesThe packaged skill installs and validates on three platforms.
Windows test portability (Node 22|24)windows gateyesPath, 8.3-name and delivery-lock behaviour under real Windows paths.
websitewebsite gateno (conditional)Astro typecheck, build, browser continuity, Cloudflare output contract.

Two design decisions are worth keeping in mind when you change a job name:

  1. Aggregator jobs exist so a required check is always present. webm-artifact is 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.
  2. 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

JobTriggerBlocks mergeProves
security / action pinsPR, push, weeklyyesEvery remote action is a 40-character commit SHA, and the repo's own pinning contract passes.
security / codeqlPR (same-repo), push, weeklyno — enforced by the code_scanning ruleset rule insteadStatic 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 reviewPRyesA new dependency with a known advisory or an incompatible licence never reaches main.
security / sbom (root|archify|website)PR, pushyesA CycloneDX SBOM exists for each package root; the shipped skill still declares zero runtime dependencies.
security / workflow lintPR, pushyesactionlint plus the repository's own workflow contracts (ci-scope, Cloudflare, compatibility).

Delivery

WorkflowTriggerGate
ci.yml → deploy-pagespush to main, all gates greenGitHub Pages, environment github-pages, obsolete-run rejection by comparing main HEAD.
ci.yml → deploy-cloudflarepush to main, vars.CLOUDFLARE_PAGES_PROJECT setCloudflare Pages, environment cloudflare-pages, production branch only.
release.ymlpush of a v* tagEnvironment production (platform reviewer), version/tag match, full suite, deterministic archive, annotated tag for stable.
provenance.ymlrelease publishedSHA-256 sums, build provenance attestation, SBOM asset. Never rebuilds.
preview.ymlPR touching website/**Non-production Cloudflare preview branch pr-<n>, same-repo PRs only.
governance.ymldaily, and on governance changesRead-only drift report against enterprise/governance/.
dsh.ymlPR/push touching the DSH integrationThe independently versioned plugin contract.
contributor-cards.ymlPR, and merged PR via pull_request_targetCard 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

EnvironmentUsed byProtectionHolds
productionrelease.yml release jobRequired reviewers (platform team), no self-review, tag policy v*Nothing — publication uses GITHUB_TOKEN
cloudflare-pagesci.yml deploy-cloudflareReviewer (platform), branch mainCLOUDFLARE_API_TOKEN
github-pagesci.yml deploy-pagesBranch main onlyNothing
previewpreview.ymlNone (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

Artifacts and retention

ArtifactProducerRetentionPurpose
website-dist, website-cloudflare-distwebsite job90 daysThe exact bytes Pages and Cloudflare deploy.
website-homepage-evidencewebsite job90 daysVisual evidence for a website review.
sbom-*security.yml90 daysPer-root CycloneDX documents.
governance-drift-reportgovernance.yml90 daysWhat drifted, and when it was last checked.
SHA256SUMS.txt, *.cdx.jsonprovenance.ymlRelease lifetimeVerifiable with the release.

What is deliberately absent