Skip to content
BranchesTags

Repository files navigation

ci-workflows

Reusable, configurable CI execution for the melodic-software org: composite actions that install and run each code-quality tool, plus the runner scripts they bundle.

Consumed by reference from a consumer job, never copied:

jobs:
  markdown:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@<sha>
      - uses: melodic-software/ci-workflows/.github/actions/markdown@<sha>

This repo is public, so its actions and reusable workflows are consumable by any repository — public or private, in or out of the org — with no access configuration and no PAT. The runner fetches the referenced action directly, and an action's bundled script is reached via $GITHUB_ACTION_PATH without any checkout of this repo. (Public is required because a public consumer such as melodic-software/claude-code-plugins can only uses: public repos.)

Contract

  • Configurable, not forkable. Each action exposes typed inputs with global-standard defaults. Consumers override repo-specific scope (globs, paths, tool versions, config location) through inputs — never by editing the action.
  • Pin by SHA. Reference every action at a full commit SHA; Dependabot (github-actions, weekly) opens bump PRs that are reviewed and merged manually. Dependabot updates only uses: SHAs — the tool versions pinned in each action's version:/analyzer-version: input default (and the checksum-verified install URLs) have no package manifest it can track, so the scheduled tool-version-drift-check workflow watches upstream releases and files an advisory issue when a default falls behind.
  • Each consumer aggregates locally. One action runs one tool inside a consumer job. The required-check contract is a single check named ci-status, produced by a thin gateway job the consumer keeps local so the required-check name stays un-nested. The gateway needs: the lane jobs and fails if any failed or was cancelled. Whether a skipped lane passes is the consumer's policy via the ci-status action's treat-skipped-as input — see that action below for when a skip must block rather than pass.

Versioning

Every tag is full SemVer (vX.Y.Z). A release is cut whenever main changes by something worth pinning to — release.yml's manual workflow_dispatch (patch/minor/major) makes each release a deliberate act, and cutting one after every meaningful change keeps main at the latest tag so Dependabot's github-actions group bumps consumers to a tagged SHA instead of tracking main HEAD by drift. There is no calendar cadence; GitHub's own guidance is silent on release frequency, and a tag-per-change policy is a closer fit for a repository whose only "release" event is "a consumer might need to pin to this." GitHub's reusable-workflow reference guidance treats a SHA, a release tag, and a branch as equally valid {ref} forms and states plainly that "Using the commit SHA is the safest option for stability and security" (Reuse workflows) — this repo's tag-per-change practice and every consumer's SHA pin both sit inside that guidance, not around it.

No floating major tag (v1). GitHub's action-release guidance recommends "keeping major (v1) and minor (v1.1) tags current to the latest appropriate commit" so a consumer written as uses: owner/action@v1 keeps receiving non-breaking updates automatically (Releasing and maintaining actions). That guidance is scoped to actions consumed by a floating tag resolved at Actions runtime, and its own reusable-workflow reference page makes no equivalent recommendation. Neither the letter nor the premise of that guidance applies here: every consumer of this repository pins by 40-character commit SHA — the runner-policy allowlist requires it fleet-wide — so no consumer's workflow run ever resolves @v1, and a floating major tag would exist only as a label nothing at runtime reads. It would also actively conflict with the pin-comment convention consumers now follow (melodic-software/standards#248): that convention's primary form, # vX.Y.Z, asserts the comment names the release the pinned SHA corresponds to, a claim a moving tag cannot keep true once it moves. This is declined outright, not deferred by oversight; the trigger for revisiting it is this repository ever moving consumers onto tag-resolved-at-runtime references, which the current SHA-pin governance model gives no reason to expect.

v0.x carries no stability guarantee. Per SemVer's own terms, "Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable" (SemVer, item 4). This repository is v0.7.0 at the time of writing: a release may still ship a change a post-1.0 line would have to treat as its own minor/patch distinction. Committing to v1.0.0 — SemVer's "defines the public API" milestone (SemVer, item 5) — is a deliberate, separate decision this document defers rather than resolves; nothing here should be read as an implicit 1.0 commitment or a timeline toward one.

A caller's SHA pin does not cascade. Pinning this repository by SHA proves only that the one referenced file's bytes are fixed at that commit; GitHub resolves a reusable workflow's own nested calls to further reusable workflows or actions independently, at their own {ref} (Reusing workflow configurations). GitHub's docs do not call this out directly, but it follows structurally from that per-reference resolution model, and it is exactly the gap reported in a community discussion about a workflow whose nested composite actions kept tracking a branch after the caller pinned the calling workflow file to a commit. This repository closes that gap on its own side, not the consumer's: every external reference its own actions and workflows make — third-party actions such as astral-sh/setup-uv, anthropics/claude-code-action, and peter-evans/create-issue-from-file — is itself pinned to a full commit SHA with the same dual-form trailing comment consumers use (melodic-software/standards#248). A consumer's pin on this repository is only as trustworthy as this repository's own pins one level down, and this repository keeps that chain closed rather than asking every consumer to audit it.

Actions

  • .github/actions/markdown — markdownlint-cli2 over the repo's markdown.
  • .github/actions/shellcheck — ShellCheck over the repo's shell scripts (installs a pinned, checksum-verified binary). Its default discovery remains tracked *.sh/*.bash; extra-globs adds tracked extensionless inputs as newline-delimited Git pathspecs, with optional extra-exclude-codes scoped only to that extra lane so ordinary scripts keep the stricter result.
  • .github/actions/shfmt — shfmt formatting check over the repo's shell scripts, driven by the caller's .editorconfig (installs a pinned, checksum-verified binary).
  • .github/actions/powershell — PSScriptAnalyzer over the repo's PowerShell, via the bundled Invoke-Pssa.ps1. Each file is analyzed exactly once and any analyzer or rule error fails closed. PSUseCorrectCasing remains disabled while the upstream runspace-affinity defect is open; retrying a crashing rule is not a quality gate.
  • .github/actions/pulumi-deploy-guard — verifies the complete Pulumi personal OIDC allow-policy set against a versioned exact-claim contract, then exports stack state without plaintext secrets and classifies reviewed operational resource URNs as existing or first-apply. Both GitHub IaC repositories call this one implementation after OIDC authentication and before minting their broad GitHub governance token. Contract v2 uses GitHub immutable owner/repo IDs and rejects Pulumi's *, ?, and . pattern operators. Callers reserve its exact workflow name uniquely and require paired live positive/near-match negative token-exchange evidence before removing the legacy trust rules.
  • .github/actions/editorconfig — editorconfig-checker validation of tracked files against the repo's .editorconfig.
  • .github/actions/typos — typos spell-check over source against a caller-supplied config.
  • .github/actions/gitleaks — gitleaks secret scan over a directory or local Git history against a caller-supplied config. Git mode requires a valid, non-shallow local worktree or repository and explicitly scans commits reachable from HEAD and every locally present ref under refs/ (--all), including refs the remote advertised and the caller fetched into the checkout. Callers must use fetch-depth: 0 for advertised branch and tag history and fetch every other intended ref because hidden, unadvertised, or unfetched remote refs are absent locally and cannot be scanned. The action installs a pinned, checksum-verified binary, unconditionally redacts secret values, validates requested reports, and fails closed on missing, malformed, or operationally incomplete results.
  • .github/actions/actionlint — actionlint over the repo's GitHub Actions workflow files, with the canonical checksum-pinned ShellCheck release installed explicitly so embedded shell validation is identical on hosted and self-hosted workers.
  • .github/actions/lefthook-validate — installs a checksum-pinned Lefthook binary and runs its official validate command against the caller's fully loaded config. Native discovery is the default; config-file selects an explicit main config through Lefthook's documented LEFTHOOK_CONFIG override. extends fragments, remotes, and the matching local config are still loaded. The version and checksum inputs let a caller align the gate with an older consumer pin when necessary. This is a composed schema/load gate; Lefthook does not define it as a command or glob behavior test.
  • .github/actions/check-jsonschema — check-jsonschema validation of JSON/YAML against one schema per call (call once per schema group).
  • .github/actions/ci-status — aggregates a caller-built needs.*.result string into the single required gate check: success passes, anything else fails naming the offending result. treat-skipped-as is the caller's policy for skipped — pass (default) or fail for repos where a skipped lane means one that should have run did not, such as a runner selector falling back. An unrecognised policy value fails rather than defaulting. Empty input fails closed. GitHub offers no "all other jobs" selector, so the needs list and the matching results string stay caller-owned.
  • .github/actions/lychee-offline — lychee --offline link/anchor reference-integrity over the repo's docs (deterministic; no network).
  • .github/actions/reference-integrity — resolves file.md "Anchor" prose citations against each cited file's headings and bold lead-ins (dependency-free awk); pairs with lychee-offline, which covers link/fragment targets.
  • .github/actions/exec-bit — verifies every tracked shebang file carries git index mode 100755, so executable scripts keep their bit on checkout.
  • .github/actions/machine-specific-paths — rejects machine-specific absolute / user-home paths in tracked files (portable placeholders allowed).
  • .github/actions/comment-hygiene — scans comments for deferred-work markers (TODO/FIXME/HACK/XXX) and tracker references against its bundled organization policy, with an optional complete caller replacement.
  • .github/actions/eol-renormalize — detects index-level line-ending drift via git's clean filter, driven by the caller's .gitattributes (read-only).
  • .github/actions/ruff — Ruff lint + format-check over the repo's Python (via uvx; emits --output-format=github annotations).
  • .github/actions/pyright — Pyright strict, warnings-as-errors type-check over the repo's Python (via uvx).
  • .github/actions/biome — Biome lint + format-check over the repo's JS/TS (via npx; biome ci --error-on-warnings, emits --reporter=github annotations).
  • .github/actions/tsc — TypeScript tsc --noEmit type-check over the repo's TypeScript (via npx).
  • .github/actions/dotnet-build — builds .NET projects with Roslyn analyzers and code-style enforced as warnings-as-errors (the analysis owner: code-quality CAxxxx, code-style IDExxxx, nullable, and compiler warnings). Restores in NuGet locked mode by default: a committed packages.lock.json that drifted from the project dependencies fails with NU1004 instead of silently re-resolving (a no-op for repos without lock-file usage).
  • .github/actions/dotnet-format — verifies the C# formatting the build does not own: whitespace/layout via dotnet format whitespace --verify-no-changes, and using-directive organization via dotnet format style --diagnostics IDE0055 --verify-no-changes (the build-time analyzers own code-style and code-quality, so none of the three lanes double-report).

Each input's meaning and default is documented inline in the action's inputs: block.

Reusable workflows

Hosted workflow defaults use explicit GA operating-system generations (ubuntu-24.04 and windows-2025) instead of moving *-latest aliases. This keeps hosted/self-hosted parity reviews tied to a declared image contract while GitHub continues the normal weekly patching of each hosted image generation.

  • .github/workflows/pulumi-version-drift-check.yml — reusable-only maintenance job for GitHub IaC callers. It accepts only a hosted default-branch push, schedule, or manual dispatch, compares the exact .pulumi.version pin with Pulumi's current stable release, and maintains one marker-identified auditable incident across rename or manual closure without resetting its age. It never changes or auto-merges a pin, retires resolved incidents instead of reusing them, and hard-fails after 14 days of unresolved drift. Drift detection runs on actions/github-script rather than a gh/jq-driven shell script: this reusable runs on whatever runner the caller selects, and a self-hosted image is not guaranteed to ship those CLIs, so the implementation lives directly in the workflow on the action's bundled Node runtime instead of a generated, equality-tested copy of a repo-local .sh source. Per-caller concurrency serializes issue mutation.

  • .github/workflows/issue-triage-label.yml — applies a configured floor label (default priority: needs-triage) to an issue opened or reopened with no label matching a configured prefix (default priority:). Non-gating: never fails a PR or blocks a merge; it only guarantees new issues don't silently drop out of the triage queue for lack of a label. The guard is a label-set membership check (any label starting with label-prefix), not a title/body content match, so an explicit priority label at creation always wins. Fail-closed on a missing label: the raw add-labels endpoint auto-creates an unknown label name instead of failing, so this workflow first calls GET /repos/{owner}/{repo}/labels/{name} and hard-fails the job if that 404s, rather than ever letting a bare, undefined label get created. Label taxonomy stays github-iac-managed; this workflow only applies an existing label. Settled mechanism per claude-code-plugins#506's research-resolution comment. The caller owns the trigger and must include reopened alongside opened so an issue reopened after its tier was cleared re-acquires the floor:

    on:
  issues:
    types: [opened, reopened]
permissions: {}
jobs:
  issue-triage-label:
    permissions:
      issues: write
    uses: melodic-software/ci-workflows/.github/workflows/issue-triage-label.yml@<sha>

    Loop-safe by construction: adding a label emits issues.labeled, never opened/reopened, and GitHub does not start new workflow runs at all for GITHUB_TOKEN-authored events (except workflow_dispatch/ repository_dispatch), so this cannot re-trigger itself. Idempotent: a re-run is a no-op once the target label or any other tier-prefixed label is present. A human triager assigning a real tier after this workflow ran is expected to remove the floor label as part of that transition — this workflow only guarantees a floor and does not police tier assignment.

  • .github/workflows/standards-sync.yml — orchestrates exact-file distribution from the schema-v2 component manifest in melodic-software/standards. The standards checkout validates and materializes its own manifest; this workflow resolves one immutable standards SHA, then blocks every write lane until a separate metadata-only credential proves the expected App identity, active selected-repository installation metadata, and two consecutive exact views of the full unfiltered manifest's repository set. A caller's targets filter limits materialization only; it never weakens this installation-scope attestation. After that barrier, the workflow scopes a different GitHub App token to each target and opens a signed, human-reviewed PR enumerating every managed source-to-destination mapping. It never writes a downstream receipt and never copies components declared locally-owned; the owner-scoped attestation token is never passed to checkout or PR mutation. On PR creation only (never a later update, so a reviewer who deliberately disarmed a PR is not overridden), it also arms GitHub auto-merge (squash) via the same target-scoped token — unless the manifest opts that target out with automerge: false. A rejected arm attempt (for example an already-mergeable PR) is logged and does not fail the sync. See standards-sync-stuck-automerge-alert.yml for the companion watchdog over PRs that stay armed but blocked.

  • .github/workflows/standards-sync-stuck-automerge-alert.yml — scans the standards-sync target repositories, read from the standards manifest at run time (never hardcoded), for open PRs authored by the standards-sync App with auto-merge armed and GraphQL mergeStateStatus: BLOCKED for longer than threshold-hours (default 4). Consumed via uses: at job level from a scheduled caller that grants issues: write; the tracking issue lands in the caller's own repository (a marker-deduped rolling report, the same mechanism link-check.yml and queue-monitor-liveness.yml use), and the run fails when it finds any — a stuck armed PR is an actionable condition, not a flaky one, so this is intentionally not advisory.

  • .github/workflows/select-runner.yml — the single organization-approved hosted/self-hosted selector. With self-hosted-only, the selector itself queues on the always-on default melodic-ubuntu-24.04-x64 route so it never spends hosted minutes before returning the caller's admitted managed label — the default tier or the capped review tier — and never runs its own selection on the review tier's small capacity. The prefer-self-hosted and hosted-only selector paths run on the standard ubuntu-24.04 hosted runner (free on public repos, quota-covered on private) so their adaptive and explicit hosted semantics remain available. Every selector path has a two-minute timeout and returns one runs-on string. A downstream job has its own runner and timeout; the selector's platform limit does not carry into that job. prefer-self-hosted is deliberately fail-open to the configured hosted runner. It uses a read-only observer GitHub App and chooses local when a governed scale-set route has a managed-prefix runner that is online and not explicitly reported as non-ephemeral, regardless of busy state: liveness, not idleness. GitHub natively queues a job until a matching runner is available, failing it only after 24 hours queued, so a busy fleet absorbs bursts without spending hosted minutes; only a fully offline fleet falls back to the hosted route. Re-running failed jobs reuses the prior attempt's successful selector output; re-running all jobs makes a fresh liveness decision. Neither forces the hosted route. self-hosted-only instead returns the configured exact managed label without inventory or observer credentials, so a trusted private workload queues until governed capacity is available. The queue-only label must be one of the centrally allowlisted routes — the default melodic-ubuntu-24.04-x64 tier or the capped melodic-review-ubuntu-24.04-x64 review tier; adding another route requires a reviewed immutable selector revision. Invalid queue-only configuration and selector infrastructure faults fail the selector job instead of falling back to paid hosted execution. Public repositories and fork pull requests — on pull_request and pull_request_target alike — route hosted before the observer-token action can execute, following GitHub's self-hosted runner security guidance. Same-repository pull_request_target and merge_group runs are reviewed local event classes: pull_request_target executes only the trusted base-branch definition, and a merge group can be enqueued only by a write-access user after required checks pass, so metadata-only gates on those events reach governed capacity. Same-repository Dependabot runs route like any push: their lane code executes in ephemeral one-job workers, and the selector sources the observer key from the Dependabot secrets store on Dependabot events, so the org mirrors CI_RUNNER_OBSERVER_PRIVATE_KEY there. Call it exactly once per workflow and feed the single output to every lane's runs-on; per-lane selector fan-out only multiplies identical preflight jobs:

    jobs:
  select-runner:
    uses: melodic-software/ci-workflows/.github/workflows/select-runner.yml@<sha>
    with:
      policy: ${{ vars.CI_RUNNER_POLICY }}
      self-hosted-label: ${{ vars.CI_SELF_HOSTED_LABEL }}
      self-hosted-labels-json: ${{ vars.CI_SELF_HOSTED_LABELS_JSON }}
      hosted-runner: ${{ vars.CI_HOSTED_RUNNER }}
      scope: ${{ vars.CI_RUNNER_SCOPE }}
      managed-runner-prefix: ${{ vars.CI_MANAGED_RUNNER_PREFIX }}
      observer-client-id: ${{ vars.CI_RUNNER_OBSERVER_CLIENT_ID }}
    secrets:
      observer-private-key: ${{ secrets.CI_RUNNER_OBSERVER_PRIVATE_KEY }}

  test:
    needs: select-runner
    runs-on: ${{ needs.select-runner.outputs.runner }}
    steps:
      - run: ./test.sh

    Never use secrets: inherit; pass only the observer key. Stable output reasons are online, self-hosted-only, hosted-only, no-online-runner, missing-config, missing-secret, auth-error, api-timeout, api-error, invalid-response, and the strict infrastructure sentinel selector-error. The security eligibility guard also reports hosted-only. selector-conformance.yml runs the deterministic selector test suite and proves the public, hosted-only, and queue-only contracts without accessing local capacity. The tested CommonJS source is generated into the workflow, so the reusable-workflow SHA pins the implementation without a second checkout/ref. This matters because actions inside a called workflow otherwise run in the caller's repository context. A conformance check fails if the executable copy drifts.

    A required reusable gate that declares needs: select-runner must execute after selector failures and skips. GitHub otherwise skips the dependent job after a prerequisite failure, and a skipped required job reports success. It must also report on every outcome: the standards runner-policy validator requires selector-result reporters to declare exactly if: ${{ always() }} so every prerequisite outcome — including cancellation — still materializes the required check. GitHub generally recommends !cancelled() instead of always() for jobs that should stop with a cancelled workflow; this contract deliberately trades that for fail-closed reporting. The reusable gate uses its runner input for every prerequisite outcome, so the caller also owns the recovery route; the cost is bounded to one caller-selected reporter run on cancellation. Use the semantic-title gate's fail-closed prerequisite contract (this public-repository example intentionally falls back to hosted Ubuntu):

    pr-title:
  needs: select-runner
  if: ${{ always() }}
  permissions:
    pull-requests: read
  uses: melodic-software/ci-workflows/.github/workflows/semantic-pr.yml@<sha>
  with:
    runner: ${{ needs.select-runner.outputs.runner || 'ubuntu-24.04' }}
    prerequisite-result: ${{ needs.select-runner.result }}

    When the caller workflow is active, the reusable uses the caller's resolved runner value unchanged for success, failure, cancelled, skipped, and empty prerequisite results. Any result other than exact success then fails before title validation. An explicitly delivered cancelled result remains fail-closed because the result alone does not prove that a successor run will cover the same required check. If the caller workflow is cancelled manually or by concurrency.cancel-in-progress, the always() reporter still runs and reports for its own, now-superseded run; the superseding run reports its own result, and a stale failure left by a superseded run clears on re-run.

    The public fallback shown above and the reusable's omitted-input default both preserve ubuntu-24.04. A private self-hosted-only caller cannot reuse the public outputs.runner || 'label' form: on a strict-selector failure select-runner publishes the non-empty unroutable sentinel ci-runner-selection-failed, which a || fallback passes straight through instead of replacing. Gate the fallback on the selector result so the sentinel is ignored:

        runner: ${{ needs.select-runner.result == 'success' && needs.select-runner.outputs.runner || 'melodic-ubuntu-24.04-x64' }}

    The fallback label must itself be routable when selection fails; otherwise the required reporter job never starts and the non-success result cannot fail closed. Both success and reporting paths remain the existing single pr-title / pr-title job on the resolved runner; there is no routine aggregator or extra hosted job. GitHub documents that runs-on accepts an input-backed runner value.

    self-hosted-labels-json is an optional ordered JSON array of exact labels. When present it overrides self-hosted-label; malformed, empty, or duplicate candidate lists route hosted with invalid-response. Candidate priority is the array order, independent of runner API order. self-hosted-only requires exactly one centrally allowlisted candidate. Because GitHub documents runner labels as case-insensitive, candidate and inventory labels are compared through case-normalized keys, case-only duplicates are rejected, and the selector returns the configured spelling. V1's governed labels and name prefixes are conservative ASCII literals provisioned by IaC; this contract does not claim generic Unicode case-fold or collation safety. GitHub's generic default self-hosted labels (self-hosted, OS, and architecture labels), as well as a candidate equal to the hosted fallback, are rejected because returning either as runs-on could escape the managed fleet. Organization routing normally leaves it unset and uses one shared exact label. The personal phase provisions it as operational data so the documented live-proof fallback can switch from one shared label to two host-specific exact labels without a workflow or selector code change.

    GitHub's official runner-scale-set contract routes jobs by scale-set name. Its 2026-03-10 OpenAPI runner schema requires id, name, os, status, busy, and a labels array, but declares ephemeral optional. Live scale-set inventory can represent a JIT runner with an empty label array and omit ephemeral. When exactly one route is configured, the selector can unambiguously attribute such an empty-label runner inside the governed name prefix to that sole scale-set route. With an ordered multi-route list, an empty-label runner cannot be attributed safely and is ineligible; a candidate must be observed explicitly instead. A present non-boolean ephemeral value invalidates the complete inventory, and explicit false excludes and contaminates the inferred single-route namespace.

    When ephemeral is omitted, local selection relies on the governed trust assumption that the configured runner-name prefix and scale-set route are reserved for the ci-runner controller's one-job JIT workers. The REST response does not attest that ownership or lifecycle. The selector rejects visible namespace conflicts, but credentials and configuration must prevent another runner from satisfying the same prefix-and-route contract. Online state is still required in the returned inventory observation.

    V1 compute is Linux x64, but GitHub's official JIT-configuration response reports os: unknown, as can live JIT inventory. The selector therefore accepts case-insensitive linux or unknown only. unknown is not an OS attestation; it is accepted solely under the same governed prefix-and-route/JIT trust assumption. Any explicit bearer of a candidate route reporting another OS contaminates that route. Selected jobs separately assert the official runner context values runner.os == Linux and runner.arch == X64 before substantive work.

    Because downstream runs-on contains only the returned route, namespace integrity is checked across every explicit case-insensitive bearer returned by the paginated inventory—not only the online runner observed by the selector. A route is contaminated when an explicit bearer is outside the managed name prefix, reports ephemeral: false, or reports an OS outside the V1 Linux/JIT-unknown contract; that route is never returned. For one configured route, an empty-label managed runner is its unambiguous inferred bearer. For multiple configured routes, a conforming empty-label managed runner is ineligible because it cannot be attributed, while a nonconforming one contaminates every candidate because its hidden route could be any of them. An explicitly distinct clean lower-priority route remains eligible. Online counts include only eligible runners on clean routes. If every configured route is contaminated, selection fails hosted with invalid-response; omitted-field runners carrying unrelated explicit labels do not poison the managed namespace.

    Organization inventory is organization-wide. Selection therefore relies on IaC giving every same-label runner group identical selected-repository access for the migrated workflows. The selector cannot attest runner-group access parity: runner_group_id is optional in the inventory schema, and an observation without it does not prove which caller repositories can route to that runner.

    CI_HOSTED_RUNNER is operational configuration, but GitHub's runner-inventory API cannot prove that an arbitrary label belongs to hosted infrastructure. The selector therefore allowlists only the reviewed V1 value ubuntu-24.04 and canonicalizes every missing, malformed, unapproved, generic self-hosted, or configured local-candidate value back to it. Introducing another hosted label requires an explicit governance and conformance review.

    Inventory is an observation, not a reservation or snapshot. Pagination can race with registration and status changes between requests; stable total_count and unique runner IDs are fail-closed consistency checks, not snapshot isolation. Several simultaneous selectors can observe the same online runner and select local; GitHub queues that burst until capacity appears. Only when no matching runner is online do later selectors route hosted with no-online-runner. Validation, authentication, API, timeout, malformed-response, and github-script failures produce hosted outputs. A failure of the selector job or hosted runner before outputs exist cannot be converted by workflow expressions; dependent jobs remain blocked and must be rerun. This boundary is intentionally not described as atomic fallback.

  • .github/workflows/link-check.yml — online external-link checker, consumed via uses: at job level from a scheduled caller that grants issues: write. It is advisory: external link health is flaky, so it runs fail: false and maintains a rolling tracking issue rather than gating a build—opening or updating it on failure and, by default, closing it after the next clean run. Inputs (documented inline) let a caller shape the rolling issue — title, labels, native issue type, and the auto-close toggle — so a repo with an established issue scheme adopts the workflow without behavior change. (A whole scheduled job with issue maintenance is a reusable-workflow concern, not a composite action; the deterministic on-disk counterpart is the lychee-offline action above, which feeds ci-status.)

  • .github/workflows/zizmor.yml — GitHub Actions security/static-analysis lint with zizmor (dangerous triggers, excessive permissions, template injection). Advisory by default (fail-on-severity: never surfaces PR annotations without failing); consumed via uses: at job level. The workflow downloads the official x86_64 GNU/Linux archive for the reviewed v1.27.0 release, verifies its committed SHA-256 before extraction, and verifies the CLI-reported version before auditing. latest remains accepted for compatibility but resolves to that reviewed default rather than a mutable release. zizmor runs in its own native --format=github mode, emitting a GitHub annotation for every finding directly and gating on severity via zizmor's own graduated exit codes (informational/low/medium/high) — no SARIF intermediate, no hand-rolled parser. Callers opt into blocking by raising fail-on-severity to low, medium, or high; the legacy fail-on-findings boolean stays a back-compat alias for low. Installation, argument, and collection errors fail closed even in advisory mode. The verified binary runs from a fresh runner-temporary directory with a per-job cache and without Docker, a job/service container, or an installer-time privilege escalation. runner defaults to ubuntu-24.04 and can consume the approved selector output for eligible private, non-fork calls. SARIF upload to the Security tab remains a deferred opt-in. Inputs are documented inline.

  • .github/workflows/osv-scanner.yml — dependency vulnerability scan with Google's official native OSV-Scanner v2.4.0 Linux X64 binary. The exact binary, its provenance, and the SLSA verifier are checksum-pinned; the verifier then attests the expected Google source repository and exact release tag before the scanner runs. One native SARIF scan emits escaped GitHub annotations without retaining or uploading an artifact. Advisory for findings (fail-on-vuln off by default); supply-chain, scanner, and invalid-result errors always fail closed. V2.4.0 scans supported manifests and lockfiles; .NET .csproj/PackageReference and Central Package Management are enabled by default. A committed packages.lock.json remains the reproducibility contract enforced by dotnet-build's locked-mode restore, but is no longer the only .NET coverage path. An empty scan warns (advisory) or fails (blocking) unless the caller declares the repo genuinely dependency-less via allow-no-lockfiles: true. The caller must pass its approved selector output through runner; the native lane needs no Docker socket or privileged worker. Inputs are documented inline. See the official v2.4.0 release.

    “Enabled by default” is not treated as proof that every MSBuild layout is covered. Each consumer's verification run must show nonzero package discovery for its actual .csproj/Central Package Management layout; committed lockfiles and the empty-scan guard remain required until that proof passes. The scanner's documented exit contract is also enforced: only 0 (clean) and 1 (findings) can be completed scans, 128 follows the explicit no-packages policy, and every other code fails closed. Completed exit codes must agree with a regular, non-symlink SARIF file and its finding count. Workflow-command properties and messages are escaped before annotations are emitted.

    The reviewed pin is machine-readable in .github/osv-scanner-pin.json and the workflow verifies the downloaded asset's checksum, SLSA provenance, source, release tag, and reported version before scanning. The release download is accepted only when it matches the reviewed checksum. The daily tool-version-drift-check compares Google's latest stable release and the GitHub-reported asset digests, then refreshes the existing maintenance issue; it never rewrites or auto-merges the pin. Updating requires release review, official asset/provenance checksum verification, exact source and tag verification, and a verification run in a consuming repository. See the official installation and SLSA guidance. Native OSV requires a governed runner; the optional inputs on semantic-pr and native zizmor preserve compatibility.

  • .github/workflows/dependabot-lock-regen.yml — regenerates NuGet packages.lock.json on Dependabot PRs (dotnet restore --force-evaluate) and pushes the result back to the PR branch, covering the lock-file updates Dependabot's NuGet ecosystem misses. Self-guards to dependabot[bot] events on dependabot/nuget/ branches, so the caller is a thin unconditional pull_request job granting contents: write. Inputs, the optional PUSH_TOKEN Dependabot secret, and the default-token no-retrigger caveat are documented inline.

  • .github/workflows/pester.yml — runs a Pester suite on the fixed GitHub-hosted Windows 2025 runner with a pinned Pester install. A whole-job concern (its own runner OS + checkout), so a reusable workflow: the caller passes a run command and owns discovery/reporting/exit; this supplies the hosted runner, pinned Pester, and checkout. Inputs are documented inline.

  • .github/workflows/claude-review.yml — automated PR code review with anthropics/claude-code-action. Inputs (prompt, claude-args, track-progress, display-report, allowed-bots, exclude-comments-by-actor, skip-actors, timeout-minutes) have public-safe defaults documented inline. Consume it per the Claude lanes — shared consumption contract below.

  • .github/workflows/claude-security-review.yml — a dedicated LLM security-review pass with anthropics/claude-code-action, sibling of claude-review.yml with the same secrets interface and safe-handling model but a security-only prompt. It reviews the PR's changed files for the vulnerabilities static analysis misses — logic flaws, authorization gaps, injection surfaces, token/secret handling, dangerous workflow patterns (pull_request_target, script injection via the github context), permission-widening config changes, supply-chain pin loosening — and reports findings as a PR review with severity (CRITICAL/IMPORTANT/SUGGESTION) and a confidence axis, security only. The intended promotion path for the VERDICT is to flip to blocking on CRITICAL findings once the lane's precision is proven over a sustained window — an earned promotion (trust-before-scale). Always-report shape: a security pass on every PR is noise in a doc-heavy repo, so the lane scopes itself to security-sensitive surfaces — but the caller must NOT express that scope with a workflow-level on.pull_request.paths filter, because a path miss leaves a required check Pending forever and wedges every prose PR. Instead the caller triggers on all PR events and passes the paths input (security-sensitive surfaces in Actions paths: syntax: workflow files, permission/settings configs, hook and shell scripts, auth/token-touching code, network-call sites); the workflow's changes job evaluates it and a not-applicable PR yields a name-stable skipped security-review check. A consumer's ruleset may make that EXECUTION check required (check context <caller job> / security-review); the VERDICT stays advisory. Inputs (runner, paths, prompt, claude-args, skip-actors) have public-safe defaults documented inline. Consume it per the Claude lanes — shared consumption contract below, triggering on all PR events (no workflow-level paths:) and passing the paths input in the job:

    with:
  paths: |
    .github/workflows/**
    .github/actions/**
    **/*.sh
    **/*.ps1
    # plus the caller's own auth/token and network-call source paths

  • .github/workflows/claude-e2e-verify.yml — Claude-powered end-to-end verification of a PR with anthropics/claude-code-action. The caller passes a command that builds and serves its app plus the URL it listens on; the workflow provisions a pinned Playwright/Chromium toolchain, waits for the app to become healthy, then has the agent drive the running app through the caller's journeys and post its findings as a PR comment (the agent step runs continue-on-error). This workflow additionally owns the pinned browser toolchain. Inputs (runner, app-start-command, app-url, e2e-spec, claude-args, setup-command, timeout-minutes) are documented inline. Consume it per the Claude lanes — shared consumption contract below, with the caller additionally passing:

        with:
      app-start-command: npm ci && npm run build && npm run start
      app-url: http://localhost:3000

    This lane builds, serves, and browser-drives the PR head — it executes PR-authored code — so the fork-PR safety guarantee in the shared contract is what makes it safe: a fork gets no secrets and a read-only token, so that execution has nothing to exfiltrate. The Playwright CLI version is an in-workflow pin watched by tool-version-drift-check, not Dependabot. Promotion: flip to a selector-coupled required gate when the lane's findings prove precision over a sustained window — an earned promotion, mirroring the review lane's discipline.

  • .github/workflows/semantic-pr.yml — validates the PR title against the Conventional Commits spec (wraps the SHA-pinned amannn/action-semantic-pull-request). Gating: a non-conforming title fails the job. Because governed repos squash-merge with the squash title set to PR_TITLE, the PR title becomes the default-branch subject line, so this is the single lever that yields a Conventional-Commits history (no commit-msg hook needed). It is a standalone required check named pr-title, not a ci-status lane — title edits must not re-run the file-lint lanes; with the caller below the check a ruleset must require is pr-title / pr-title per the shared adoption contract. Inputs (runner, prerequisite-result, types, scopes, require-scope, subject-pattern, subject-pattern-error, validate-single-commit, ignore-labels) have spec-aligned defaults documented inline. Consume it from a thin caller that triggers on title-relevant events. prerequisite-result defaults to success for direct callers; selector-dependent required callers must use the fail-closed pattern above. edited is required so re-titling re-validates; the gate passes on merge_group since the title was validated at PR time. Adopt the canonical block below (not the in-repo .github/workflows/pr-title.yml, which intentionally still triggers on pull_request — see the note after the block):

    on:
  pull_request_target:
    types: [opened, edited, reopened, synchronize]
  merge_group:
permissions:
  pull-requests: read
concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true
jobs:
  pr-title:
    permissions:
      pull-requests: read
    uses: melodic-software/ci-workflows/.github/workflows/semantic-pr.yml@<sha>

    This check reads PR title metadata only — it checks out and runs no head code.

    This block is the canonical pattern to copy. The in-repo .github/workflows/pr-title.yml dogfood caller deliberately stays on pull_request for now: this repo is already gated on its own pr-title / pr-title check, so a PR that flips that caller to pull_request_target would have the required check run the base-branch (still-pull_request) definition and block the flip. The self-flip is therefore deferred; consumers should follow this documented block rather than copying the dogfood file.

  • .github/workflows/pr-issue-linkage.yml — validates the PR body carries a native closing keyword (Closes/Fixes/Resolves #N, including owner/repo#N, or the literal No linked issue when the PR closes nothing) and a non-empty ## Related section. Gating: a non-conforming body fails the job. HTML comments are stripped before either check, so an unedited PR template (whose instructional prose lives in comments) fails rather than passing vacuously. Generalizes melodic-software/provisioning's pr-body.yml into a shared reusable workflow — provisioning's own caller predates this workflow and is not required to switch. It is a standalone required check named pr-issue-linkage, not a ci-status lane — body edits must not re-run the file-lint lanes; with the caller below the check a ruleset must require is pr-issue-linkage / pr-issue-linkage per the shared adoption contract. Inputs (runner, prerequisite-result) match do-not-merge-gate.yml's shape. edited is required so a body edit re-validates; the gate passes on merge_group since the body was validated at PR time. Consume it from a thin caller that triggers on body-relevant events:

    on:
  pull_request_target:
    types: [opened, edited, reopened, synchronize]
  merge_group:
permissions: {}
concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true
jobs:
  pr-issue-linkage:
    permissions: {}
    uses: melodic-software/ci-workflows/.github/workflows/pr-issue-linkage.yml@<sha>

    This check reads PR body metadata only — it checks out and runs no head code.

    Optional input exempt-authors (comma-separated exact PR-author logins, default empty) skips body validation for the listed authors — matched by exact equality against github.event.pull_request.user.login, never a *[bot] pattern, so no unknown future bot is silently skipped on the gate. It is fail-closed: the empty default exempts no one, so bumping the pinned SHA changes nothing until a caller opts in. Use it for bots whose generated PR bodies cannot carry the closing-keyword + ## Related markers (dependabot/renovate); the caller passes exempt-authors: 'dependabot[bot]' alongside the uses: line.

  • .github/workflows/do-not-merge-gate.yml — fails the job while the calling PR carries a configured label (default do-not-merge). Gating: the label's presence fails the job; a caller that requires this check blocks the merge until the label is removed. It is a standalone required check named do-not-merge, not a ci-status lane; with the caller below the check a ruleset must require is do-not-merge / do-not-merge per the shared adoption contract. Inputs (runner, prerequisite-result, label) mirror semantic-pr's fail-closed pattern. Adopt the canonical block below:

    on:
  pull_request_target:
    types: [opened, reopened, synchronize, labeled, unlabeled]
  merge_group:
permissions:
  pull-requests: read
concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true
jobs:
  do-not-merge:
    permissions:
      pull-requests: read
    uses: melodic-software/ci-workflows/.github/workflows/do-not-merge-gate.yml@<sha>

    This check reads PR label metadata only — it checks out and runs no head code. labeled/unlabeled are required — without them, adding the label after the check already passed would not re-trigger it, and the merge would never actually be blocked. Even with them present, a same-repo automation that labels using the default GITHUB_TOKEN still does not re-trigger this gate — see the "Known limitation — GITHUB_TOKEN-authored label changes" note below. opened/reopened/synchronize cover the check reporting on every other PR lifecycle event a ruleset's required-status-check needs to see. Unlike the other two gates, this one re-evaluates the label on merge_group itself (looking up the PR named in the merge group's temporary ref and re-checking its current labels via the API): a label — unlike semantic-pr's title or pr-issue-linkage's body — can be added after the PR's own pull_request_target run last passed, e.g. while the PR already sits in the queue, so trusting that earlier result would let a labeled PR merge through.

    Known limitation — GITHUB_TOKEN-authored label changes. The labeled/unlabeled triggers above only re-evaluate the gate when GitHub actually starts a new workflow run for that event. GitHub does not start a run at all for labeled/unlabeled events produced by the default GITHUB_TOKEN — that is a platform-level recursive-run guard (triggering-a-workflow-from-a-workflow), not a gap in the trigger list above. So if a same-repo automation job (e.g. a labeling policy workflow) applies this gate's blocking label using the default GITHUB_TOKEN after the check already reported success on the PR's HEAD SHA, no run — live-refetch or otherwise — is ever triggered, and the earlier green check-run stays on that SHA until a genuinely new qualifying event occurs (e.g. synchronize from a subsequent push, or a non-default-token labeled/unlabeled event). No trigger-list change can close this; the gap is that GitHub never starts a run.

    Adoption requirement — label-setting automation must not use the default GITHUB_TOKEN. Any same-repo workflow that applies or removes this gate's blocking label must authenticate with a GitHub App installation token or a personal access token instead of ${{ secrets.GITHUB_TOKEN }} / ${{ github.token }}. Only a label change authored by a non-default token creates the labeled/unlabeled run that re-evaluates this gate; a default-token label change leaves an already-green check silently unenforced. Verify this for every same-repo labeling automation before requiring do-not-merge / do-not-merge on that repo.

    Known gap with batched merge queues: GitHub's merge queue batches multiple PRs into one merge group by default (max group size 5), and the batch's temporary ref/SHA is named for only the last PR in the batch (a [#1, #2] batch runs as pr-2). The reusable workflow's merge_group handling re-checks only that named PR's labels, so a PR that isn't last in its batch is not individually re-evaluated at merge-queue time. Closing this fully needs either a validated way to enumerate every PR in a batch from a merge_group run (no such API is documented; unverified), or setting merge queue maximum group size to 1 in the repo's ruleset (github-iac) so every merge group is single-PR. Until one of those lands, treat merge_group label coverage as best-effort, not exhaustive, on repos that allow batching.

    Adoption precondition — single-PR merge groups. This workflow does not itself detect or assert the queue's batch size; that only exists as the gap above. Coverage on merge_group runs is exhaustive only when a merge group contains exactly one PR. Before requiring do-not-merge / do-not-merge on a repo with a merge queue, confirm the queue actually produces single-PR groups — today that means the ruleset's merge-queue maximum group size is 1; a repo that instead relies on batch enumeration must first have that enumeration implemented and validated here, which does not exist yet. Making the check required on a queued repo without satisfying this precondition does not fail loudly: it keeps reporting green while under-enforcing on non-tip batch members. Re-verify this precondition whenever the repo's merge-queue configuration changes.

Claude lanes — shared consumption contract

claude-review.yml, claude-security-review.yml, and claude-e2e-verify.yml share one consumption shape. Each is advisory: it posts PR comments and never gates ci-status. (The advisory verdict is separate from execution evidence: claude-security-review.yml additionally takes a paths input and its name-stable security-review check may be made a required status check — see its entry above.) Each is a whole-job concern (job permissions: plus a secrets: interface), which is why each is a reusable workflow rather than a composite action — the caller owns the triggers and the permission grant, and the workflow owns the SHA-pinned anthropics/claude-code-action and the safe handling. Security rules live in CLAUDE.md.

on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
jobs:
  <lane>:
    permissions:
      contents: read
      pull-requests: write
      id-token: write
    uses: melodic-software/ci-workflows/.github/workflows/<lane>.yml@<sha>
    secrets:
      CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

The caller's job must grant those three permissions (a called workflow can only downgrade, not elevate) and the consumer repo must be in the CLAUDE_CODE_OAUTH_TOKEN org secret's selected scope. Pass that one named secret explicitly rather than secrets: inherit, which forwards every parent secret. Fork PRs receive no secrets by design and are not reviewed.

Standalone gate checks — shared adoption contract

semantic-pr.yml, pr-issue-linkage.yml, and do-not-merge-gate.yml are standalone required checks rather than ci-status lanes, and share one adoption shape. The emitted check context is <caller job> / <reusable job>, so a ruleset must require the doubled name (pr-title / pr-title, not bare pr-title) — and only after the caller is merged and emitting the check, or open PRs block on a check that never runs. Rulesets are governed via github-iac.

Each canonical caller triggers on pull_request_target, which runs the base-branch definition — a head-branch edit to the caller cannot bypass the gate. That is safe for all three because each reads PR metadata only and checks out no head code; the per-workflow entry above names which metadata. Under pull_request_target github.ref is the base branch, so the concurrency group keys on github.event.pull_request.number (falling back to github.ref for merge_group) — a github.ref key would collapse all PRs into one group and let one PR's run cancel another's required check.

merge_group is required on any repo with a merge queue: the queue gates on the check, and without the trigger that required check never reports and the queue deadlocks. It is inert where no queue exists.

Triage: fleet-wide single-workflow failure spikes

Before attributing a sudden, fleet-wide spike of failures in one reusable workflow to infrastructure flake, check that reusable's commit history and its job's runner routing (runs-on:, and whether it traces through select-runner.yml) first. A recent change that shells out to a CLI (gh, jq, …) combined with a routing change that moved callers onto a runner image without that CLI produces exactly this signature: many unrelated repos failing the same check at once, often with a low-level exit code rather than an application-level error.

Lesson from the 2026-07-18 do-not-merge spike (~191 failures across 6 repos, exit 127: gh: command not found): do-not-merge-gate.yml's label refetch ran gh api in a run: step on a runner the caller selects, and a routing shift landed it on a self-hosted image that does not ship the gh CLI. Fixed in #144 by porting to actions/github-script, which runs on the action's own bundled Node runtime and has no runner-image tooling dependency; the remaining gh-calling reusables were audited and ported the same way in #209. See REVIEW.md's "Always check" criterion for the standing rule this established.

Policy ownership and action inputs

Reusable rulesets are authored in melodic-software/standards. Consumers receive them through a tool-native package/reference or as managed files at the tool's normal root path. Config-driven actions default to those root paths and fail clearly when a required file is absent; an explicit input can select a repository-owned config where the tool supports customization.

Comment hygiene is the intentional CI-only exception: its default policy ships inside the action and is resolved through $GITHUB_ACTION_PATH, so consumers do not need another repository file. patterns-file accepts a complete replacement for repositories with a genuinely different policy. The small configs under fixtures/ exist only to exercise action contracts; they are not mirrors of the standards catalog.

About

SHA-pinned, configurable CI composite actions (one per code-quality tool) and reusable workflows; consumers aggregate them into a local ci-status gate.

Topics

cicode-qualitycomposite-actionsgithub-actionsreusable-workflowsself-hosted-runners

Resources

Readme

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages