From 9672fe0679e4c2dd5714b75e92f1cc13487c9430 Mon Sep 17 00:00:00 2001 From: OB Date: Sat, 5 Sep 2026 18:40:50 +0200 Subject: [PATCH 1/2] fix(docs): share repository instructions --- AGENTS.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ CHANGELOG.md | 5 +++++ CLAUDE.md | 50 +------------------------------------------------- package.json | 2 +- 4 files changed, 56 insertions(+), 50 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..ee13f72 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,49 @@ +# coroboros/ci + +Reusable GitHub Actions workflows + composite actions for the Coroboros stack. + +## Commands + +- `actionlint -shellcheck=shellcheck` — workflows, `action.yml`, inline shell. +- `yamllint -c .yamllint .` — YAML lint. + +## Important files + +- `.github/workflows/javascript-npm-packages.yml` — bundled NPM pipeline (`preflight` / `security-gate` / `publish-package` / `security`). +- `.github/workflows/rust-packages.yml` — bundled Cargo pipeline (`preflight` matrix / `security-gate` / `verify-package` / `publish-package` / `security`) + opt-in cargo-dist binary layer (`dist-plan` / `dist-build` / `dist-host` / `dist-publish`, gated on `[package.metadata.dist]` or `[workspace.metadata.dist]`). +- `.github/workflows/security-gate.yml` — blocking gate `publish-package` `needs:`. `scan-supply-chain` (auto-routed: `Cargo.toml` → `security/rust/cargo-deny` advisories+bans+sources, else `security/osv-scanner`) + `scan-secrets` (gitleaks). A separate reusable workflow so the caller's `publish` can `needs:` the whole gate as one job, running each scan once. Imposed via the package workflows, importable standalone by a non-package repo. +- `.github/workflows/security.yml` — advisory layer, never blocks: `review-dependencies` (PR-only) + `check-licenses` (Rust, `security/rust/cargo-deny` `checks: licenses`). License/quality policy lives here, off the gate. +- `.github/workflows/{self-lint,self-test,self-security,self-release}.yml` — self-CI: lint, the security composites + `security-gate`/`security` workflows via local `./`, the `v0` rolling-tag move, and `self-test` smoke-testing every composite (plus `javascript/base`/`rust/base` on `test/fixtures/`) every PR. Workflow self-tests resolve their `@v0` composites against the released `v0`, so a brand-new composite is testable only once a release moves `v0` onto it. +- `.github/actions/{check-docs,javascript/base,rust/{base,native-deps,test-deps,install-dist,pin-version,harden-homebrew-formula},security/{gitleaks,osv-scanner,rust/cargo-deny},release/{verify-tag,generate-changelog,github-release,commit-artifacts}}/action.yml` — composites. +- `.github/dependabot.yml` — auto-PRs for pinned action SHAs. `renovate.json` + `.github/workflows/renovate.yml` — self-hosted Renovate (needs the `RENOVATE_TOKEN` PAT secret, scope `repo` + `workflow`) auto-bumps the version-pinned tooling; `.github/renovate/sync-tool-sha.sh` re-syncs each paired tarball SHA-256 in the same PR. +- `security/.gitleaks.toml` — canonical gitleaks ruleset. +- `security/deny.toml` — canonical cargo-deny ruleset, imposed via `--config` (consumer `deny.toml` ignored; `deny.exceptions.toml` rejected). An unfixable transitive advisory → PR a justified `ignore = ["RUSTSEC-…"]` (with `# why`) to this file, never a per-repo override. +- `README.md` — public documentation (single source for pipelines, composables, structure, flow, env, security, examples). + +## Rules + +- **Imposed, not proposed.** Zero `inputs:` / `secrets:` on reusable workflows unless variation is legitimate. +- **Pin third-party actions by commit SHA**, inline `# vX` comment. No `@main`, `@master`, `@vX`. +- **Pin tooling binaries by version.** SHA-256 verification on binary release tarballs. No `curl | bash`. +- **Composite refs**: `coroboros/ci/.github/actions/@v0` from reusable workflows and consumers. Exception — `self-security.yml` uses local `./.github/actions/security/` so a PR self-tests its own composites; a reusable workflow's `./` resolves to the caller's checkout, so `security.yml` must pin `@v0`. +- **`secrets:`** declares only what the job consumes. Never `secrets: inherit`. +- **`gitleaks` CLI direct**, not `gitleaks/gitleaks-action@v2` (paid org license). +- **House style**: + - Env values quoted: `KEY: "value"`. + - GH workflow log commands: `::error::`, `::warning::`, `::notice::`. No ANSI codes. + - Declare env keys only where consumed. + - Job ids: `verb-noun`, kebab-case (imperative verb + object), mirroring the GitLab CI pipelines — `verify-package`, `publish-package`, `generate-changelog`, `commit-artifacts`, `verify-tag`. Phase call-jobs that `uses:` another workflow may stay single-word (`preflight`, `security-gate`, `security`); the cargo-dist `dist-plan`/`dist-build`/`dist-host`/`dist-publish` jobs mirror its subcommands. Reusable-workflow job ids are consumer-visible — rename deliberately. +- **Action and workflow files = implementation only.** Rationale lives in `AGENTS.md` or `CHANGELOG.md`. + +## Adding a workflow or composite + +1. Update `README.md` (Pipelines / Composables table + Examples + Environment). +2. `actionlint -shellcheck=shellcheck` must exit 0. + +## Release flow + +- PR-only; no direct commits to `main`. +- In the PR (before merge): bump `package.json:version` + prepend `CHANGELOG.md` section (`## vX.Y.Z - DD/MM/YYYY`). +- Squash-merge. +- `git tag X.Y.Z && git push origin X.Y.Z` (no `v` prefix). `self-release.yml` then moves the rolling `v0` tag — no manual `git tag -f v0`. +- `gh release create X.Y.Z --title X.Y.Z --notes-file `. diff --git a/CHANGELOG.md b/CHANGELOG.md index 320eb7c..ace8f77 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # Changelog +## v0.2.11 - 05/09/2026 + +### Fixes +- Use `AGENTS.md` as the shared repository instruction source, imported by `CLAUDE.md`. + ## v0.2.10 - 08/07/2026 ### Fixes diff --git a/CLAUDE.md b/CLAUDE.md index 3ab9de1..43c994c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,49 +1 @@ -# coroboros/ci - -Reusable GitHub Actions workflows + composite actions for the Coroboros stack. - -## Commands - -- `actionlint -shellcheck=shellcheck` — workflows, `action.yml`, inline shell. -- `yamllint -c .yamllint .` — YAML lint. - -## Important files - -- `.github/workflows/javascript-npm-packages.yml` — bundled NPM pipeline (`preflight` / `security-gate` / `publish-package` / `security`). -- `.github/workflows/rust-packages.yml` — bundled Cargo pipeline (`preflight` matrix / `security-gate` / `verify-package` / `publish-package` / `security`) + opt-in cargo-dist binary layer (`dist-plan` / `dist-build` / `dist-host` / `dist-publish`, gated on `[package.metadata.dist]` or `[workspace.metadata.dist]`). -- `.github/workflows/security-gate.yml` — blocking gate `publish-package` `needs:`. `scan-supply-chain` (auto-routed: `Cargo.toml` → `security/rust/cargo-deny` advisories+bans+sources, else `security/osv-scanner`) + `scan-secrets` (gitleaks). A separate reusable workflow so the caller's `publish` can `needs:` the whole gate as one job, running each scan once. Imposed via the package workflows, importable standalone by a non-package repo. -- `.github/workflows/security.yml` — advisory layer, never blocks: `review-dependencies` (PR-only) + `check-licenses` (Rust, `security/rust/cargo-deny` `checks: licenses`). License/quality policy lives here, off the gate. -- `.github/workflows/{self-lint,self-test,self-security,self-release}.yml` — self-CI: lint, the security composites + `security-gate`/`security` workflows via local `./`, the `v0` rolling-tag move, and `self-test` smoke-testing every composite (plus `javascript/base`/`rust/base` on `test/fixtures/`) every PR. Workflow self-tests resolve their `@v0` composites against the released `v0`, so a brand-new composite is testable only once a release moves `v0` onto it. -- `.github/actions/{check-docs,javascript/base,rust/{base,native-deps,test-deps,install-dist,pin-version,harden-homebrew-formula},security/{gitleaks,osv-scanner,rust/cargo-deny},release/{verify-tag,generate-changelog,github-release,commit-artifacts}}/action.yml` — composites. -- `.github/dependabot.yml` — auto-PRs for pinned action SHAs. `renovate.json` + `.github/workflows/renovate.yml` — self-hosted Renovate (needs the `RENOVATE_TOKEN` PAT secret, scope `repo` + `workflow`) auto-bumps the version-pinned tooling; `.github/renovate/sync-tool-sha.sh` re-syncs each paired tarball SHA-256 in the same PR. -- `security/.gitleaks.toml` — canonical gitleaks ruleset. -- `security/deny.toml` — canonical cargo-deny ruleset, imposed via `--config` (consumer `deny.toml` ignored; `deny.exceptions.toml` rejected). An unfixable transitive advisory → PR a justified `ignore = ["RUSTSEC-…"]` (with `# why`) to this file, never a per-repo override. -- `README.md` — public documentation (single source for pipelines, composables, structure, flow, env, security, examples). - -## Rules - -- **Imposed, not proposed.** Zero `inputs:` / `secrets:` on reusable workflows unless variation is legitimate. -- **Pin third-party actions by commit SHA**, inline `# vX` comment. No `@main`, `@master`, `@vX`. -- **Pin tooling binaries by version.** SHA-256 verification on binary release tarballs. No `curl | bash`. -- **Composite refs**: `coroboros/ci/.github/actions/@v0` from reusable workflows and consumers. Exception — `self-security.yml` uses local `./.github/actions/security/` so a PR self-tests its own composites; a reusable workflow's `./` resolves to the caller's checkout, so `security.yml` must pin `@v0`. -- **`secrets:`** declares only what the job consumes. Never `secrets: inherit`. -- **`gitleaks` CLI direct**, not `gitleaks/gitleaks-action@v2` (paid org license). -- **House style**: - - Env values quoted: `KEY: "value"`. - - GH workflow log commands: `::error::`, `::warning::`, `::notice::`. No ANSI codes. - - Declare env keys only where consumed. - - Job ids: `verb-noun`, kebab-case (imperative verb + object), mirroring the GitLab CI pipelines — `verify-package`, `publish-package`, `generate-changelog`, `commit-artifacts`, `verify-tag`. Phase call-jobs that `uses:` another workflow may stay single-word (`preflight`, `security-gate`, `security`); the cargo-dist `dist-plan`/`dist-build`/`dist-host`/`dist-publish` jobs mirror its subcommands. Reusable-workflow job ids are consumer-visible — rename deliberately. -- **Action and workflow files = implementation only.** Rationale lives in `CLAUDE.md` or `CHANGELOG.md`. - -## Adding a workflow or composite - -1. Update `README.md` (Pipelines / Composables table + Examples + Environment). -2. `actionlint -shellcheck=shellcheck` must exit 0. - -## Release flow - -- PR-only; no direct commits to `main`. -- In the PR (before merge): bump `package.json:version` + prepend `CHANGELOG.md` section (`## vX.Y.Z - DD/MM/YYYY`). -- Squash-merge. -- `git tag X.Y.Z && git push origin X.Y.Z` (no `v` prefix). `self-release.yml` then moves the rolling `v0` tag — no manual `git tag -f v0`. -- `gh release create X.Y.Z --title X.Y.Z --notes-file `. +@AGENTS.md diff --git a/package.json b/package.json index c2243b2..40c467a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@coroboros/ci", - "version": "0.2.10", + "version": "0.2.11", "private": true, "description": "Reusable GitHub Actions CI for the Coroboros stack.", "license": "SEE LICENSE IN LICENSE.md", From 7ad3c8fd1a219a6c7f8bace6e59581bfadc7df94 Mon Sep 17 00:00:00 2001 From: OB Date: Sat, 5 Sep 2026 19:21:15 +0200 Subject: [PATCH 2/2] docs(instructions): correct workflow lint coverage --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index ee13f72..01cdc67 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ Reusable GitHub Actions workflows + composite actions for the Coroboros stack. ## Commands -- `actionlint -shellcheck=shellcheck` — workflows, `action.yml`, inline shell. +- `actionlint -shellcheck=shellcheck` — workflows and their inline shell. - `yamllint -c .yamllint .` — YAML lint. ## Important files