From 884a6273f772491ae5d62860557f8c69bfea6159 Mon Sep 17 00:00:00 2001 From: ciotlosm Date: Sat, 11 Jul 2026 15:36:24 +0300 Subject: [PATCH] feat(workflows): add pr-check shared wrapper Consumers currently call n3ary/actions/.github/workflows/pr-validation.yml directly from their local pr-check.yml. The call is identical across all 6 consumer repos (modulo enable-drift-check). Centralize that single line behind a new reusable workflow pr-check.yml so future changes to the shared contract land in one place. pr-check.yml is a thin wrapper that accepts the same inputs as pr-validation and forwards them. Internally it calls pr-validation via a relative path (./pr-validation.yml) so consumers always pick up the pr-validation version pinned by the same tag they pinned pr-check to. No hardcoded version drift between the two. Consumers should migrate from: uses: n3ary/actions/.github/workflows/pr-validation.yml@v22 to: uses: n3ary/actions/.github/workflows/pr-check.yml@v23 The job name changes from "shared" to "pr-check" so the branch- protection contexts become "pr-check:ascii-check" instead of "shared:ascii-check". Branch protection will need a one-time update per consumer. Refs: n3ary/standards#22 --- .github/workflows/pr-check.yml | 75 ++++++++++++++++++++++++++++++++++ README.md | 30 +++++++++----- 2 files changed, 95 insertions(+), 10 deletions(-) create mode 100644 .github/workflows/pr-check.yml diff --git a/.github/workflows/pr-check.yml b/.github/workflows/pr-check.yml new file mode 100644 index 0000000..b9f312b --- /dev/null +++ b/.github/workflows/pr-check.yml @@ -0,0 +1,75 @@ +name: PR Check (shared wrapper) + +# Reusable workflow. Consumers call this from their own +# `.github/workflows/pr-check.yml` instead of calling +# `pr-validation.yml` directly: +# +# jobs: +# pr-check: +# uses: n3ary/actions/.github/workflows/pr-check.yml@v23 +# with: +# enable-drift-check: 'true' # or false +# # repo-specific jobs +# +# Why this exists as a separate reusable (vs. calling pr-validation +# directly): +# - Single point of contact for the standard PR validation contract. +# If we add a new check, fix a default, or change how the shared +# workflow is called, consumers don't have to update their local +# file. +# - The naming pattern `[check] PR validation (on PR)` + the +# ascii + drift checks are the same for every n3ary repo. Keeping +# that in one place enforces consistency. +# +# Difference from `pr-validation.yml` (which this calls): none, today. +# `pr-validation.yml` is the actual implementation (ascii-check + +# drift-check jobs); this is the "call it with the standard inputs" +# wrapper. If we ever need a shared pre-step (e.g. checkout with +# fetch-depth: 0 for all consumers), it goes here, not in every +# consumer's local file. + +on: + workflow_call: + inputs: + enable-drift-check: + description: 'Run the drift-check job (vendored standards SHA).' + required: false + type: boolean + default: true + vendor-dir: + description: 'Path where vendored standards live. Used by drift-check.' + required: false + type: string + default: 'docs/standards' + standards-repo: + description: 'Owner/repo of the standards publisher.' + required: false + type: string + default: 'n3ary/standards' + standards-ref: + description: 'Ref of the standards repo.' + required: false + type: string + default: 'main' + base-ref: + description: 'Base ref to diff against. Falls back to PR base SHA.' + required: false + type: string + default: '' + +permissions: + contents: read + +jobs: + pr-validation: + # Use a relative path so consumers always get the pr-validation + # version pinned by the same tag they pinned pr-check to. If we + # hardcoded @v22 here, this wrapper would silently fall behind + # when pr-validation bumps to v23. + uses: ./pr-validation.yml + with: + enable-drift-check: ${{ inputs.enable-drift-check }} + vendor-dir: ${{ inputs.vendor-dir }} + standards-repo: ${{ inputs.standards-repo }} + standards-ref: ${{ inputs.standards-ref }} + base-ref: ${{ inputs.base-ref }} diff --git a/README.md b/README.md index 12fc58c..27ca686 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # n3ary/actions Composite GitHub Actions and reusable workflows for the [n3ary org](https://github.com/n3ary) (consumer + producers). -## Actions (composite) +## Reusable workflows | Action | Description | |---|---| @@ -13,7 +13,8 @@ Composite GitHub Actions and reusable workflows for the [n3ary org](https://gith | Workflow | Description | |---|---| | [check-standards-drift](.github/workflows/check-standards-drift.yml) | Fails the consuming PR if any vendored standard under `docs/standards/` is older than the current `n3ary/standards@main`. Replaces the per-consumer copy of `check-standards-drift.yml`. | -| [pr-validation](.github/workflows/pr-validation.yml) | Shared base PR-validation: `ascii-check` + optional `drift-check`. Call this instead of writing your own `pr-validation.yml`. | +| [pr-check](.github/workflows/pr-check.yml) | Standard "PR check" wrapper: the consumer-facing entry point. Calls `pr-validation` with the standard input contract. Consumers should use this, not `pr-validation` directly. | +| [pr-validation](.github/workflows/pr-validation.yml) | Shared base PR-validation: `ascii-check` + optional `drift-check`. Implementation behind `pr-check`. | ### `check-standards-drift` inputs @@ -38,7 +39,14 @@ jobs: uses: n3ary/actions/.github/workflows/check-standards-drift.yml@v1 ``` -### `pr-validation` inputs +### `pr-check` vs `pr-validation` + +- **`pr-check.yml`** is the consumer-facing entry point. It accepts the same inputs as `pr-validation` (`enable-drift-check`, `vendor-dir`, `standards-repo`, `standards-ref`, `base-ref`) and forwards them. Consumers should call this. +- **`pr-validation.yml`** is the actual implementation. It runs the `ascii-check` and `drift-check` jobs. Most consumers should never call this directly; only `pr-check` does. + +The split exists so a single change to the standard PR-check contract (e.g. adding a new shared step) lands in one place instead of in every consumer's local file. + +### `pr-check` inputs | Input | Required | Default | Description | | --- | --- | --- | --- | @@ -51,16 +59,18 @@ jobs: Example consumer workflow: ```yaml -# /.github/workflows/pr-validation.yml -name: PR Validation +# /.github/workflows/pr-check.yml +name: '[check] PR validation (on PR)' on: pull_request: branches: [main] permissions: contents: read jobs: - shared: - uses: n3ary/actions/.github/workflows/pr-validation.yml@v1 + pr-check: + uses: n3ary/actions/.github/workflows/pr-check.yml@v23 + with: + enable-drift-check: 'true' # or false if you don't vendor standards # repo-specific jobs (e.g. test matrix) validate: runs-on: ubuntu-latest @@ -69,9 +79,9 @@ jobs: - run: npm test ``` -Note: when called as `jobs.shared`, the called workflow's jobs -are prefixed with `shared:`. So the branch-protection context -names become `shared:ascii-check`, `shared:drift-check`. +Note: when called as `jobs.pr-check`, the called workflow's jobs +are prefixed with `pr-check:`. So the branch-protection context +names become `pr-check:ascii-check`, `pr-check:drift-check`. ## Consumers