Skip to content

Commit f64d17c

Browse files
roomoteedelauna
authored andcommitted
ci: add conservative change-based validation with a reliable required gate (#2291)
1 parent 5a7f3f8 commit f64d17c

13 files changed

Lines changed: 2173 additions & 5 deletions
Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
name: "Classify changed files"
2+
3+
description: "Classifies a pull request change range as documentation-only or full validation. The classification fails safe: every uncertain input selects full validation."
4+
5+
inputs:
6+
event-name:
7+
description: "GitHub event name that drives skip eligibility"
8+
required: true
9+
head-sha:
10+
description: "Head commit SHA of the classification range"
11+
required: true
12+
force-full-label:
13+
description: "When true, force full validation because the ci:full-validation label is present"
14+
required: false
15+
default: "false"
16+
force-full-variable:
17+
description: "When true, force full validation because the ZOO_CODE_REQUIRE_FULL_VALIDATION repository variable is true"
18+
required: false
19+
default: "false"
20+
21+
outputs:
22+
category:
23+
description: "docs-only or full"
24+
value: ${{ steps.classify.outputs.category }}
25+
reason:
26+
description: "Human-readable classification reason"
27+
value: ${{ steps.classify.outputs.reason }}
28+
reason-code:
29+
description: "Stable classification reason code"
30+
value: ${{ steps.classify.outputs.reason-code }}
31+
changed-files:
32+
description: "Number of changed files in the classification range"
33+
value: ${{ steps.classify.outputs.changed-files }}
34+
allowlist-fingerprint:
35+
description: "Fingerprint of the active documentation-only allowlist"
36+
value: ${{ steps.classify.outputs.allowlist-fingerprint }}
37+
38+
runs:
39+
using: "composite"
40+
steps:
41+
- id: classify
42+
shell: bash
43+
run: |
44+
HEAD_SHA="${{ inputs.head-sha }}"
45+
FLAGS=()
46+
if [[ "${{ inputs.force-full-label }}" == "true" ]]; then
47+
FLAGS+=("--force-full-label")
48+
fi
49+
if [[ "${{ inputs.force-full-variable }}" == "true" ]]; then
50+
FLAGS+=("--force-full-variable")
51+
fi
52+
# The pull_request checkout is the synthetic merge commit, so its
53+
# first parent is the base branch tip that was actually merged
54+
# into. A failed resolution fails the step and fails safe.
55+
BASE_SHA="$(git rev-parse "${HEAD_SHA}^1")"
56+
node scripts/change-classification.mjs ci --event "${{ inputs.event-name }}" --head "$HEAD_SHA" --base "$BASE_SHA" "${FLAGS[@]}"

‎.github/workflows/code-qa.yml‎

Lines changed: 110 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,36 @@ permissions:
2020
contents: read
2121

2222
jobs:
23+
classify:
24+
# Classifies the pull request change range before any validation
25+
# runs. Only an explicit documentation-only allowlist match can
26+
# skip expensive jobs, and only for pull_request events; a failed
27+
# or missing classification fails safe to full validation. The
28+
# validation-gate job below audits this decision on every run.
29+
runs-on: ubuntu-latest
30+
outputs:
31+
category: ${{ steps.classify.outputs.category }}
32+
reason: ${{ steps.classify.outputs.reason }}
33+
reason-code: ${{ steps.classify.outputs.reason-code }}
34+
changed-files: ${{ steps.classify.outputs.changed-files }}
35+
allowlist-fingerprint: ${{ steps.classify.outputs.allowlist-fingerprint }}
36+
steps:
37+
- name: Checkout code
38+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
39+
with:
40+
# Classification resolves the merge base from history.
41+
fetch-depth: 0
42+
# This job never pushes — don't persist the GITHUB_TOKEN.
43+
persist-credentials: false
44+
- name: Classify changed files
45+
id: classify
46+
uses: ./.github/actions/classify-changes
47+
with:
48+
event-name: ${{ github.event_name }}
49+
head-sha: ${{ github.sha }}
50+
force-full-label: ${{ github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:full-validation') }}
51+
force-full-variable: ${{ vars.ZOO_CODE_REQUIRE_FULL_VALIDATION == 'true' }}
52+
2353
dependency-review:
2454
runs-on: ubuntu-latest
2555
# Only meaningful for PRs — validates the dependency diff of the pull
@@ -65,7 +95,29 @@ jobs:
6595
exit 1
6696
fi
6797
98+
format-check:
99+
# Always runs, including documentation-only pull requests: Prettier
100+
# checks every Markdown file, so formatting validation must never be
101+
# reduced by classification. This job also validates the classifier
102+
# and gate logic on every run.
103+
runs-on: ubuntu-latest
104+
steps:
105+
- name: Checkout code
106+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
107+
- name: Setup Node.js and pnpm
108+
uses: ./.github/actions/setup-node-pnpm
109+
with:
110+
install-args: "--frozen-lockfile"
111+
- name: Check formatting
112+
run: pnpm format:check
113+
- name: Test change classification and validation gate
114+
run: pnpm test:change-gate
115+
68116
check-translations:
117+
needs: classify
118+
# Fail-safe: only a successful documentation-only classification on
119+
# a pull request skips this job. Everything else runs unchanged.
120+
if: ${{ !cancelled() && (needs.classify.result != 'success' || github.event_name != 'pull_request' || needs.classify.outputs.category != 'docs-only') }}
69121
runs-on: ubuntu-latest
70122
steps:
71123
- name: Checkout code
@@ -80,6 +132,8 @@ jobs:
80132
run: node scripts/check-i18n-interpolation.js
81133

82134
knip:
135+
# Intentionally ungated: the repository invariant test requires the
136+
# knip job to run without conditions or allowed failure.
83137
runs-on: ubuntu-latest
84138
steps:
85139
- name: Checkout code
@@ -96,6 +150,10 @@ jobs:
96150
run: pnpm knip:production
97151

98152
compile:
153+
needs: classify
154+
# Fail-safe: only a successful documentation-only classification on
155+
# a pull request skips this job. Everything else runs unchanged.
156+
if: ${{ !cancelled() && (needs.classify.result != 'success' || github.event_name != 'pull_request' || needs.classify.outputs.category != 'docs-only') }}
99157
runs-on: ubuntu-latest
100158
steps:
101159
- name: Checkout code
@@ -104,8 +162,6 @@ jobs:
104162
uses: ./.github/actions/setup-node-pnpm
105163
with:
106164
install-args: "--frozen-lockfile"
107-
- name: Check formatting
108-
run: pnpm format:check
109165
- name: Lint
110166
run: pnpm lint
111167
- name: Check types
@@ -131,7 +187,8 @@ jobs:
131187

132188
build-vsix:
133189
name: Build test VSIX
134-
if: github.event_name == 'pull_request'
190+
needs: classify
191+
if: ${{ !cancelled() && github.event_name == 'pull_request' && (needs.classify.result != 'success' || needs.classify.outputs.category != 'docs-only') }}
135192
runs-on: ubuntu-latest
136193
steps:
137194
- name: Checkout code
@@ -158,6 +215,10 @@ jobs:
158215

159216
unit-test:
160217
name: platform-unit-test (${{ matrix.name }})
218+
needs: classify
219+
# Fail-safe: only a successful documentation-only classification on
220+
# a pull request skips this job. Everything else runs unchanged.
221+
if: ${{ !cancelled() && (needs.classify.result != 'success' || github.event_name != 'pull_request' || needs.classify.outputs.category != 'docs-only') }}
161222
runs-on: ${{ matrix.os }}
162223
concurrency:
163224
# Duplicate runs for one commit must not race the OS-specific Turbo cache save.
@@ -317,3 +378,49 @@ jobs:
317378
packages/core/coverage/unit/lcov.info
318379
packages/core/coverage/integration/lcov.info
319380
retention-days: 7
381+
382+
validation-gate:
383+
# Always-running required gate for change-based validation. It
384+
# rejects a missing or failed classification, validation jobs that
385+
# did not run when full validation was required, jobs that ran when
386+
# a documentation-only skip was expected, and a classifier replay
387+
# that disagrees with the recorded classification. It also records
388+
# the classification, the skipped work, runner minutes, and the
389+
# required-check completion time in the job summary.
390+
if: always()
391+
needs:
392+
- classify
393+
- dependency-review
394+
- invisible-chars
395+
- format-check
396+
- check-translations
397+
- knip
398+
- compile
399+
- build-vsix
400+
- unit-test
401+
runs-on: ubuntu-latest
402+
permissions:
403+
contents: read
404+
actions: read
405+
steps:
406+
- name: Checkout code
407+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
408+
with:
409+
# The gate replays the classifier against the same range.
410+
fetch-depth: 0
411+
# This job never pushes — don't persist the GITHUB_TOKEN.
412+
persist-credentials: false
413+
- name: Run validation gate
414+
env:
415+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
416+
NEEDS_JSON: ${{ toJSON(needs) }}
417+
EVENT_NAME: ${{ github.event_name }}
418+
PR_DRAFT: ${{ github.event.pull_request.draft }}
419+
RUN_ID: ${{ github.run_id }}
420+
HEAD_SHA: ${{ github.sha }}
421+
FORCE_FULL_LABEL: ${{ github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:full-validation') }}
422+
FORCE_FULL_VARIABLE: ${{ vars.ZOO_CODE_REQUIRE_FULL_VALIDATION == 'true' }}
423+
WATCHED_JOBS: dependency-review:pr-only:ungated,invisible-chars:always:ungated,format-check:always:ungated,check-translations:always:gated,knip:always:ungated,compile:always:gated,build-vsix:pr-only:gated,unit-test:always:gated
424+
run: |
425+
BASE_SHA="$(git rev-parse "${HEAD_SHA}^1")"
426+
node scripts/change-gate.mjs ci --base "$BASE_SHA" --head "$HEAD_SHA"

‎.github/workflows/codeql.yml‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,43 @@ permissions:
1919
contents: read
2020

2121
jobs:
22+
classify:
23+
# Classifies the pull request change range before any validation
24+
# runs. Only an explicit documentation-only allowlist match can
25+
# skip expensive jobs, and only for pull_request events; a failed
26+
# or missing classification fails safe to full validation. The
27+
# validation-gate job below audits this decision on every run.
28+
runs-on: ubuntu-latest
29+
outputs:
30+
category: ${{ steps.classify.outputs.category }}
31+
reason: ${{ steps.classify.outputs.reason }}
32+
reason-code: ${{ steps.classify.outputs.reason-code }}
33+
changed-files: ${{ steps.classify.outputs.changed-files }}
34+
allowlist-fingerprint: ${{ steps.classify.outputs.allowlist-fingerprint }}
35+
steps:
36+
- name: Checkout code
37+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
38+
with:
39+
# Classification resolves the merge base from history.
40+
fetch-depth: 0
41+
# This job never pushes — don't persist the GITHUB_TOKEN.
42+
persist-credentials: false
43+
- name: Classify changed files
44+
id: classify
45+
uses: ./.github/actions/classify-changes
46+
with:
47+
event-name: ${{ github.event_name }}
48+
head-sha: ${{ github.sha }}
49+
force-full-label: ${{ github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:full-validation') }}
50+
force-full-variable: ${{ vars.ZOO_CODE_REQUIRE_FULL_VALIDATION == 'true' }}
51+
2252
analyze:
2353
name: Analyze (${{ matrix.language }})
54+
needs: classify
55+
# Fail-safe: only a successful documentation-only classification on
56+
# a pull request skips this job. Merge-queue, push, and scheduled
57+
# analysis always runs.
58+
if: ${{ !cancelled() && (needs.classify.result != 'success' || github.event_name != 'pull_request' || needs.classify.outputs.category != 'docs-only') }}
2459
# Runner size impacts CodeQL analysis time. To learn more, please see:
2560
# - https://gh.io/recommended-hardware-resources-for-running-codeql
2661
# - https://gh.io/supported-runners-and-hardware-resources
@@ -89,3 +124,42 @@ jobs:
89124
uses: github/codeql-action/analyze@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
90125
with:
91126
category: "/language:${{matrix.language}}"
127+
128+
validation-gate:
129+
# Always-running required gate for change-based validation. It
130+
# rejects a missing or failed classification, validation jobs that
131+
# did not run when full validation was required, jobs that ran when
132+
# a documentation-only skip was expected, and a classifier replay
133+
# that disagrees with the recorded classification. It also records
134+
# the classification, the skipped work, runner minutes, and the
135+
# required-check completion time in the job summary.
136+
if: always()
137+
needs:
138+
- classify
139+
- analyze
140+
runs-on: ubuntu-latest
141+
permissions:
142+
contents: read
143+
actions: read
144+
steps:
145+
- name: Checkout code
146+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
147+
with:
148+
# The gate replays the classifier against the same range.
149+
fetch-depth: 0
150+
# This job never pushes — don't persist the GITHUB_TOKEN.
151+
persist-credentials: false
152+
- name: Run validation gate
153+
env:
154+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
155+
NEEDS_JSON: ${{ toJSON(needs) }}
156+
EVENT_NAME: ${{ github.event_name }}
157+
PR_DRAFT: ${{ github.event.pull_request.draft }}
158+
RUN_ID: ${{ github.run_id }}
159+
HEAD_SHA: ${{ github.sha }}
160+
FORCE_FULL_LABEL: ${{ github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:full-validation') }}
161+
FORCE_FULL_VARIABLE: ${{ vars.ZOO_CODE_REQUIRE_FULL_VALIDATION == 'true' }}
162+
WATCHED_JOBS: analyze:always:gated
163+
run: |
164+
BASE_SHA="$(git rev-parse "${HEAD_SHA}^1")"
165+
node scripts/change-gate.mjs ci --base "$BASE_SHA" --head "$HEAD_SHA"

‎.github/workflows/e2e.yml‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,41 @@ permissions:
1717
contents: read
1818

1919
jobs:
20+
classify:
21+
# Classifies the pull request change range before any validation
22+
# runs. Only an explicit documentation-only allowlist match can
23+
# skip expensive jobs, and only for pull_request events; a failed
24+
# or missing classification fails safe to full validation. The
25+
# validation-gate job below audits this decision on every run.
26+
runs-on: ubuntu-latest
27+
outputs:
28+
category: ${{ steps.classify.outputs.category }}
29+
reason: ${{ steps.classify.outputs.reason }}
30+
reason-code: ${{ steps.classify.outputs.reason-code }}
31+
changed-files: ${{ steps.classify.outputs.changed-files }}
32+
allowlist-fingerprint: ${{ steps.classify.outputs.allowlist-fingerprint }}
33+
steps:
34+
- name: Checkout code
35+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
36+
with:
37+
# Classification resolves the merge base from history.
38+
fetch-depth: 0
39+
# This job never pushes — don't persist the GITHUB_TOKEN.
40+
persist-credentials: false
41+
- name: Classify changed files
42+
id: classify
43+
uses: ./.github/actions/classify-changes
44+
with:
45+
event-name: ${{ github.event_name }}
46+
head-sha: ${{ github.sha }}
47+
force-full-label: ${{ github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:full-validation') }}
48+
force-full-variable: ${{ vars.ZOO_CODE_REQUIRE_FULL_VALIDATION == 'true' }}
49+
2050
e2e-mock:
51+
needs: classify
52+
# Fail-safe: only a successful documentation-only classification on
53+
# a pull request skips this job. Merge-queue validation always runs.
54+
if: ${{ !cancelled() && (needs.classify.result != 'success' || github.event_name != 'pull_request' || needs.classify.outputs.category != 'docs-only') }}
2155
runs-on: ubuntu-latest
2256
timeout-minutes: 30
2357
steps:
@@ -191,3 +225,42 @@ jobs:
191225
with:
192226
path: .cache/e2e-pass
193227
key: ${{ steps.e2e-marker.outputs.cache-primary-key }}
228+
229+
validation-gate:
230+
# Always-running required gate for change-based validation. It
231+
# rejects a missing or failed classification, validation jobs that
232+
# did not run when full validation was required, jobs that ran when
233+
# a documentation-only skip was expected, and a classifier replay
234+
# that disagrees with the recorded classification. It also records
235+
# the classification, the skipped work, runner minutes, and the
236+
# required-check completion time in the job summary.
237+
if: always()
238+
needs:
239+
- classify
240+
- e2e-mock
241+
runs-on: ubuntu-latest
242+
permissions:
243+
contents: read
244+
actions: read
245+
steps:
246+
- name: Checkout code
247+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
248+
with:
249+
# The gate replays the classifier against the same range.
250+
fetch-depth: 0
251+
# This job never pushes — don't persist the GITHUB_TOKEN.
252+
persist-credentials: false
253+
- name: Run validation gate
254+
env:
255+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
256+
NEEDS_JSON: ${{ toJSON(needs) }}
257+
EVENT_NAME: ${{ github.event_name }}
258+
PR_DRAFT: ${{ github.event.pull_request.draft }}
259+
RUN_ID: ${{ github.run_id }}
260+
HEAD_SHA: ${{ github.sha }}
261+
FORCE_FULL_LABEL: ${{ github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:full-validation') }}
262+
FORCE_FULL_VARIABLE: ${{ vars.ZOO_CODE_REQUIRE_FULL_VALIDATION == 'true' }}
263+
WATCHED_JOBS: e2e-mock:always:gated
264+
run: |
265+
BASE_SHA="$(git rev-parse "${HEAD_SHA}^1")"
266+
node scripts/change-gate.mjs ci --base "$BASE_SHA" --head "$HEAD_SHA"

0 commit comments

Comments
 (0)