polymech/zeroclaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
541c357002
zeroclaw/docs/ci-map.md
jordanthejet 541c357002 docs: rewrite CI docs for simplified 4-workflow system 
Remove all references to deleted workflows (ci-run.yml, CI Required Gate,
sec-audit, pub-docker-img, pub-release, pub-homebrew-core, pr-intake-checks,
pr-labeler, pr-auto-response, pr-check-stale, pr-check-status, pr-label-policy,
workflow-sanity, main-promotion-gate, sec-codeql, sec-vorpal, etc.).

Rewrite docs to match the current 4 workflows:
- ci.yml (PR checks: test + build)
- release.yml (automatic beta release on push to master)
- ci-full.yml (manual full cross-platform build matrix)
- promote-release.yml (manual stable release)

Files rewritten:
- docs/ci-map.md — complete rewrite for current workflows
- docs/release-process.md — new two-tier release model (beta/stable)
- .github/workflows/main-branch-flow.md — simplified delivery flows
- .github/workflows/README.md — removed deleted helper scripts

Files updated (stale CI references removed):
- docs/pr-workflow.md
- docs/reviewer-playbook.md
- CONTRIBUTING.md
- Vietnamese locale sync: docs/vi/ and docs/i18n/vi/ (ci-map, pr-workflow,
  release-process, reviewer-playbook)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 17:35:04 -05:00

3.3 KiB
Raw Blame History

CI Workflow Map

This document explains what each GitHub workflow does, when it runs, and whether it should block merges.

For event-by-event delivery behavior across PR, merge, push, and release, see .github/workflows/master-branch-flow.md.

Workflows

CI (.github/workflows/ci.yml)

  • Trigger: pull requests to master
  • Purpose: run tests and build release binaries on Linux and macOS
  • Jobs:
    • test — cargo nextest run --locked with mold linker
    • build — release build matrix (x86_64-unknown-linux-gnu, aarch64-apple-darwin)
  • Merge gate: both test and build must pass before merge

Beta Release (.github/workflows/release.yml)

  • Trigger: push to master (every merged PR)
  • Purpose: build, package, and publish a beta pre-release with Docker image
  • Jobs:
    • version — compute vX.Y.Z-beta.<run_number> from Cargo.toml
    • build — 5-target release matrix (linux x86_64/aarch64, macOS x86_64/aarch64, Windows x86_64)
    • publish — create GitHub pre-release with archives + SHA256SUMS
    • docker — build and push multi-platform Docker image to GHCR (beta + version tag)

CI Full Matrix (.github/workflows/ci-full.yml)

  • Trigger: manual workflow_dispatch only
  • Purpose: build release binaries on additional targets not covered by the PR CI
  • Jobs:
    • build — 3-target matrix (aarch64-unknown-linux-gnu, x86_64-apple-darwin, x86_64-pc-windows-msvc)
  • Note: useful for verifying cross-compilation before a stable release

Promote Release (.github/workflows/promote-release.yml)

  • Trigger: manual workflow_dispatch with version input (e.g. 0.2.0)
  • Purpose: build, package, and publish a stable (non-pre-release) GitHub release with Docker image
  • Jobs:
    • validate — confirm input version matches Cargo.toml, confirm tag does not already exist
    • build — same 5-target matrix as Beta Release
    • publish — create GitHub stable release with archives + SHA256SUMS
    • docker — build and push multi-platform Docker image to GHCR (latest + version tag)

Trigger Map

Workflow Trigger
CI Pull requests to master
Beta Release Push to master
CI Full Matrix Manual dispatch only
Promote Release Manual dispatch only

Fast Triage Guide

  1. CI failing on PR: inspect .github/workflows/ci.yml — check test and build job logs.
  2. Beta release failing after merge: inspect .github/workflows/release.yml — check version, build, publish, and docker job logs.
  3. Promote release failing: inspect .github/workflows/promote-release.yml — check validate job (version/tag mismatch) and build/publish/docker jobs.
  4. Cross-platform build issues: run CI Full Matrix manually via .github/workflows/ci-full.yml to test additional targets.

Maintenance Rules

  • Keep merge-blocking checks deterministic and reproducible (--locked where applicable).
  • Follow docs/release-process.md for release cadence and version discipline.
  • Prefer explicit workflow permissions (least privilege).
  • Keep Actions source policy restricted to approved allowlist patterns (see docs/actions-source-policy.md).