From 469837964f8c9791ec31ed9c4eb84e1743b9de9d Mon Sep 17 00:00:00 2001 From: Ronnie Pinnell Date: Fri, 6 Nov 2026 18:51:08 -0700 Subject: [PATCH] feat: runs-on input with vars.CI_RUNNER fallback on the reusable gates (BEN-17190) node-gates, python-gates and secret-scan take a runs-on string input (a label or a JSON array). Order: input, then vars.CI_RUNNER, then ubuntu-latest, so the default stays GitHub-hosted. README and AGENTS.md no longer say there is no runner-selection input. Co-Authored-By: Claude Sonnet 5.5 --- .github/workflows/node-gates.yml | 6 ++++- .github/workflows/python-gates.yml | 6 ++++- .github/workflows/secret-scan.yml | 7 +++++- AGENTS.md | 6 ++++- README.md | 37 ++++++++++++++++++++++++++---- tests/workflows.test.cjs | 10 ++++++++ 6 files changed, 63 insertions(+), 9 deletions(-) diff --git a/.github/workflows/node-gates.yml b/.github/workflows/node-gates.yml index 4d0a17b..335fc62 100644 --- a/.github/workflows/node-gates.yml +++ b/.github/workflows/node-gates.yml @@ -18,13 +18,17 @@ on: run-tests: type: boolean default: true + runs-on: + description: 'Runner label or JSON array of labels, for example ["self-hosted","linux-ci"]. Empty uses vars.CI_RUNNER, then ubuntu-latest.' + type: string + default: "" permissions: contents: read jobs: gates: - runs-on: ubuntu-latest + runs-on: ${{ fromJSON(startsWith(inputs['runs-on'] || vars.CI_RUNNER || 'ubuntu-latest', '[') && (inputs['runs-on'] || vars.CI_RUNNER || 'ubuntu-latest') || format('["{0}"]', inputs['runs-on'] || vars.CI_RUNNER || 'ubuntu-latest')) }} timeout-minutes: 15 defaults: run: diff --git a/.github/workflows/python-gates.yml b/.github/workflows/python-gates.yml index 86efc07..0c9d7ee 100644 --- a/.github/workflows/python-gates.yml +++ b/.github/workflows/python-gates.yml @@ -15,13 +15,17 @@ on: run-tests: type: boolean default: true + runs-on: + description: 'Runner label or JSON array of labels, for example ["self-hosted","linux-ci"]. Empty uses vars.CI_RUNNER, then ubuntu-latest.' + type: string + default: "" permissions: contents: read jobs: gates: - runs-on: ubuntu-latest + runs-on: ${{ fromJSON(startsWith(inputs['runs-on'] || vars.CI_RUNNER || 'ubuntu-latest', '[') && (inputs['runs-on'] || vars.CI_RUNNER || 'ubuntu-latest') || format('["{0}"]', inputs['runs-on'] || vars.CI_RUNNER || 'ubuntu-latest')) }} timeout-minutes: 15 defaults: run: diff --git a/.github/workflows/secret-scan.yml b/.github/workflows/secret-scan.yml index b7bda52..30dfbc1 100644 --- a/.github/workflows/secret-scan.yml +++ b/.github/workflows/secret-scan.yml @@ -1,11 +1,16 @@ name: secret-scan on: workflow_call: + inputs: + runs-on: + description: 'Runner label or JSON array of labels, for example ["self-hosted","linux-ci"]. Empty uses vars.CI_RUNNER, then ubuntu-latest.' + type: string + default: "" permissions: contents: read jobs: scan: - runs-on: ubuntu-latest + runs-on: ${{ fromJSON(startsWith(inputs['runs-on'] || vars.CI_RUNNER || 'ubuntu-latest', '[') && (inputs['runs-on'] || vars.CI_RUNNER || 'ubuntu-latest') || format('["{0}"]', inputs['runs-on'] || vars.CI_RUNNER || 'ubuntu-latest')) }} timeout-minutes: 10 steps: - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 diff --git a/AGENTS.md b/AGENTS.md index 14b7330..7c497a7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,5 +4,9 @@ Keep this package independent of private infrastructure and task trackers. Run the README verification commands for code changes. Preserve failure exit codes and explicit non-enforcement status for advisory checks. Changes to GitHub workflows require review and real hosted CI evidence before release. Never add -persistent self-hosted runners, secrets, or privileged PR execution here. Pin +secrets or privileged PR execution here, and do not make this library's own CI +depend on a persistent self-hosted runner. The reusable gates do take a `runs-on` +input, with a `vars.CI_RUNNER` fallback and `ubuntu-latest` as the default, so +callers (CEO decision, 2026-11-06, BEN-17190) choose their own runner; keep the +default hosted and keep the three workflows' expressions identical. Pin third-party Actions and document consumer-facing compatibility changes. diff --git a/README.md b/README.md index e06f186..6ef05bf 100644 --- a/README.md +++ b/README.md @@ -25,17 +25,43 @@ Reusable workflows: - `secret-scan.yml`: checksum-pinned Gitleaks CLI, full fetched history, redacted output. No organization license or caller secret needed. Failure blocks the job. + Input: `runs-on`. - `python-gates.yml`: install project dependencies, Ruff, pytest. Enabled tests fail when no tests are collected. Inputs: `python-version`, `working-directory`, - `run-lint`, `run-tests`. + `run-lint`, `run-tests`, `runs-on`. - `node-gates.yml`: npm ci, lint, typecheck, test. Missing enabled scripts fail. - Inputs: `node-version`, `working-directory`, `run-lint`, `run-typecheck`, `run-tests`. + Inputs: `node-version`, `working-directory`, `run-lint`, `run-typecheck`, `run-tests`, `runs-on`. -These initial workflows run on GitHub-hosted Ubuntu only. No runner-selection -input exists. Callers choose when workflows run; security scans should be invoked +## Runner selection + +Every reusable workflow takes a `runs-on` string input. The runner is chosen in +this order: + +1. The caller's `runs-on` input, a single label (`ubuntu-latest`) or a JSON array + of labels (`'["self-hosted","linux-ci"]'`). +2. The caller's repository or organization variable `CI_RUNNER`, in the same format. +3. `ubuntu-latest`. + +With no input and no `CI_RUNNER`, every workflow runs on GitHub-hosted Ubuntu, as +before. `CI_RUNNER` is read from the calling repository's variables, so set it +only where you mean every gate in that repository to move. Self-hosted use is +optional, and hosted runs remain the confirmation path. + +```yaml +jobs: + python: + uses: UpIceLabs/ci-workflows/.github/workflows/python-gates.yml@REVIEWED_COMMIT_SHA + with: + runs-on: '["self-hosted","linux-ci"]' +``` + +Callers choose when workflows run; security scans should be invoked on every PR without path filtering. Explicit `run-*` opt-outs are policy choices, not passing checks. Repository dependencies and package scripts are executed; run untrusted contributions only in disposable runners without privileged secrets. +This library does not provide or manage runners. A persistent self-hosted runner +that runs pull request code from forks or other untrusted sources is outside the +supported use; see the boundaries below. ## Reachability audit @@ -69,7 +95,8 @@ protect CI policy changes with review and required checks outside this audit. ## Maintenance and security boundaries - Keep permissions read-only; never use `pull_request_target` to execute PR code. -- Do not grant public projects access to persistent internal runner groups. +- Do not grant public projects access to persistent internal runner groups, and + do not point `runs-on` or `CI_RUNNER` at one for untrusted pull requests. - Pin third-party Actions by full commit and downloaded binaries by checksum. - Project dependency locking remains the consumer's responsibility. Python tool versions are pinned but their transitives are not hash-locked; this is not a diff --git a/tests/workflows.test.cjs b/tests/workflows.test.cjs index 2844a62..aa4c797 100644 --- a/tests/workflows.test.cjs +++ b/tests/workflows.test.cjs @@ -7,6 +7,7 @@ const {spawnSync} = require('node:child_process'); const yaml = require('../reachability/node_modules/js-yaml'); const root = path.resolve(__dirname, '..'); const read = file => yaml.load(fs.readFileSync(path.join(root, file), 'utf8')); +const reusable = ['node-gates.yml', 'python-gates.yml', 'secret-scan.yml']; test('public workflows use hosted runners, read-only permissions and pinned Actions', () => { for (const file of fs.readdirSync(path.join(root, '.github/workflows'))) { const workflow = read(`.github/workflows/${file}`); @@ -15,6 +16,11 @@ test('public workflows use hosted runners, read-only permissions and pinned Acti assert.deepEqual(workflow.permissions, {contents:'read'}); for (const job of Object.values(workflow.jobs)) { if (job.uses) assert.match(job.uses, /^\.\//); + else if (reusable.includes(file)) { + assert.match(job['runs-on'], /inputs\['runs-on'\] \|\| vars\.CI_RUNNER \|\| 'ubuntu-latest'/); + assert.equal(workflow.on.workflow_call.inputs['runs-on'].type, 'string'); + assert.equal(workflow.on.workflow_call.inputs['runs-on'].default, ''); + } else assert.equal(job['runs-on'], 'ubuntu-latest'); for (const step of job.steps || []) { if (step.uses && !step.uses.startsWith('./')) assert.match(step.uses, /@[a-f0-9]{40}$/); @@ -48,3 +54,7 @@ test('the library declares an unconditional secret scan route', () => { const manifest=JSON.parse(fs.readFileSync(path.join(root,'.github/ci-checks.json'),'utf8')); assert.equal(audit(root,manifest)[0].unconditional_pr,true); }); +test('all three reusable gates share one runs-on expression', () => { + const expressions = reusable.map(file => Object.values(read(`.github/workflows/${file}`).jobs)[0]['runs-on']); + assert.equal(new Set(expressions).size, 1); +});