6d56a040ce
* docs: harden collaboration policy and review automation * ci(docs): remove unsupported lychee --exclude-mail flag * docs(governance): reduce automation side-effects and tighten risk controls * docs(governance): add backlog pruning and supersede protocol * docs(agents): codify engineering principles and risk-tier workflow * docs(readme): add centered star history section at bottom * docs(agents): enforce privacy-safe and neutral test wording * docs(governance): enforce privacy-safe and neutral collaboration checks * fix(ci): satisfy rustfmt and discord schema test fields * docs(governance): require ZeroClaw-native identity wording * docs(agents): add ZeroClaw identity-safe naming palette * docs(governance): codify code naming and architecture contracts * docs(contributing): add naming and architecture good/bad examples * docs(pr): reduce checkbox TODOs and shift to label-first metadata * docs(pr): remove duplicate collaboration track field * ci(labeler): auto-derive module labels and expand provider hints * ci(labeler): auto-apply trusted contributor on PRs and issues * fix(ci): apply rustfmt updates from latest main * ci(labels): flatten namespaces and add contributor tiers * chore: drop stale rustfmt-only drift * ci: scope Rust and docs checks by change set * ci: exclude non-markdown docs from docs-quality targets * ci: satisfy actionlint shellcheck output style * ci(labels): auto-correct manual contributor tier edits * ci(labeler): auto-correct risk label edits * ci(labeler): auto-correct size label edits --------- Co-authored-by: Chummy <183474434+chumyin@users.noreply.github.com>
85 lines
4.9 KiB
Markdown
85 lines
4.9 KiB
Markdown
# CI Workflow Map
|
|
|
|
This document explains what each GitHub workflow does, when it runs, and whether it should block merges.
|
|
|
|
## Merge-Blocking vs Optional
|
|
|
|
Merge-blocking checks should stay small and deterministic. Optional checks are useful for automation and maintenance, but should not block normal development.
|
|
|
|
### Merge-Blocking
|
|
|
|
- `.github/workflows/ci.yml` (`CI`)
|
|
- Purpose: Rust validation (`fmt`, `clippy`, `test`, release build smoke) + docs quality checks when docs change
|
|
- Merge gate: `CI Required Gate`
|
|
- `.github/workflows/workflow-sanity.yml` (`Workflow Sanity`)
|
|
- Purpose: lint GitHub workflow files (`actionlint`, tab checks)
|
|
- Recommended for workflow-changing PRs
|
|
|
|
### Non-Blocking but Important
|
|
|
|
- `.github/workflows/docker.yml` (`Docker`)
|
|
- Purpose: PR docker smoke check and publish images on `main`/tag pushes
|
|
- `.github/workflows/security.yml` (`Security Audit`)
|
|
- Purpose: dependency advisories (`cargo audit`) and policy/license checks (`cargo deny`)
|
|
- `.github/workflows/release.yml` (`Release`)
|
|
- Purpose: build tagged release artifacts and publish GitHub releases
|
|
|
|
### Optional Repository Automation
|
|
|
|
- `.github/workflows/labeler.yml` (`PR Labeler`)
|
|
- Purpose: scope/path labels + size/risk labels + fine-grained module labels (`<module>:<component>`)
|
|
- Additional behavior: provider-related keywords in provider/config/onboard/integration changes are promoted to `provider:*` labels (for example `provider:kimi`, `provider:deepseek`)
|
|
- Additional behavior: applies contributor tiers on PRs by merged PR count (`experienced` >=10, `principal` >=20, `distinguished` >=50)
|
|
- Additional behavior: risk + size labels are auto-corrected on manual PR label edits (`labeled`/`unlabeled` events); apply `risk: manual` when maintainers intentionally override automated risk selection
|
|
- High-risk heuristic paths: `src/security/**`, `src/runtime/**`, `src/gateway/**`, `src/tools/**`, `.github/workflows/**`
|
|
- Guardrail: maintainers can apply `risk: manual` to freeze automated risk recalculation
|
|
- `.github/workflows/auto-response.yml` (`Auto Response`)
|
|
- Purpose: first-time contributor onboarding + label-driven response routing (`r:support`, `r:needs-repro`, etc.)
|
|
- Additional behavior: applies contributor tiers on issues by merged PR count (`experienced` >=10, `principal` >=20, `distinguished` >=50)
|
|
- Additional behavior: contributor-tier labels are treated as automation-managed (manual add/remove on PR/issue is auto-corrected)
|
|
- Guardrail: label-based close routes are issue-only; PRs are never auto-closed by route labels
|
|
- `.github/workflows/stale.yml` (`Stale`)
|
|
- Purpose: stale issue/PR lifecycle automation
|
|
- `.github/dependabot.yml` (`Dependabot`)
|
|
- Purpose: grouped, rate-limited dependency update PRs (Cargo + GitHub Actions)
|
|
- `.github/workflows/pr-hygiene.yml` (`PR Hygiene`)
|
|
- Purpose: nudge stale-but-active PRs to rebase/re-run required checks before queue starvation
|
|
|
|
## Trigger Map
|
|
|
|
- `CI`: push to `main`, PRs to `main`
|
|
- `Docker`: push to `main`, tag push (`v*`), PRs touching docker/workflow files, manual dispatch
|
|
- `Release`: tag push (`v*`)
|
|
- `Security Audit`: push to `main`, PRs to `main`, weekly schedule
|
|
- `Workflow Sanity`: PR/push when `.github/workflows/**`, `.github/*.yml`, or `.github/*.yaml` change
|
|
- `PR Labeler`: `pull_request_target` lifecycle events
|
|
- `Auto Response`: issue opened/labeled, `pull_request_target` opened/labeled
|
|
- `Stale`: daily schedule, manual dispatch
|
|
- `Dependabot`: weekly dependency maintenance windows
|
|
- `PR Hygiene`: every 12 hours schedule, manual dispatch
|
|
|
|
## Fast Triage Guide
|
|
|
|
1. `CI Required Gate` failing: start with `.github/workflows/ci.yml`.
|
|
2. Docker failures on PRs: inspect `.github/workflows/docker.yml` `pr-smoke` job.
|
|
3. Release failures on tags: inspect `.github/workflows/release.yml`.
|
|
4. Security failures: inspect `.github/workflows/security.yml` and `deny.toml`.
|
|
5. Workflow syntax/lint failures: inspect `.github/workflows/workflow-sanity.yml`.
|
|
6. Docs failures in CI: inspect `docs-quality` job logs in `.github/workflows/ci.yml`.
|
|
|
|
## Maintenance Rules
|
|
|
|
- Keep merge-blocking checks deterministic and reproducible (`--locked` where applicable).
|
|
- Prefer explicit workflow permissions (least privilege).
|
|
- Use path filters for expensive workflows when practical.
|
|
- Keep docs quality checks low-noise (`markdownlint` + offline link checks).
|
|
- Keep dependency update volume controlled (grouping + PR limits).
|
|
- Avoid mixing onboarding/community automation with merge-gating logic.
|
|
|
|
## Automation Side-Effect Controls
|
|
|
|
- Prefer deterministic automation that can be manually overridden (`risk: manual`) when context is nuanced.
|
|
- Keep auto-response comments deduplicated to prevent triage noise.
|
|
- Keep auto-close behavior scoped to issues; maintainers own PR close/merge decisions.
|
|
- If automation is wrong, correct labels first, then continue review with explicit rationale.
|
|
- Use `superseded` / `stale-candidate` labels to prune duplicate or dormant PRs before deep review.
|