1717# under the License.
1818#
1919
20+ # Publishes the status of each open PR's fork build as a `Build` check on the PR.
21+ # Fork builds still run in contributors' forks on push (build_main.yml); this
22+ # workflow only reports their results. Running on a schedule avoids
23+ # `pull_request_target` and needs no maintainer approval for fork PRs.
24+ #
25+ # Each pass synchronizes existing `Build` checks with their fork runs. A missing
26+ # check is created as `queued`, pointing at the fork run for the PR head commit,
27+ # and synchronized on a later pass. If no fork run is found, an `action_required`
28+ # check with guidance is created instead. GitHub may delay or drop scheduled
29+ # runs, so neither the initial check nor result updates are immediate.
30+
2031name : Update build status workflow
2132
2233on :
@@ -63,11 +74,11 @@ jobs:
6374 return false;
6475 };
6576
66- // List all check-runs for a commit. per_page=100 (not the default 30) matches
67- // notify_test_workflow.yml: a SHA can accumulate more check-runs than one page
68- // (CI matrix, external checks, duplicate Build checks from reopened PRs), which
69- // could otherwise push the target Build check off the first page and leave the PR
70- // stuck in 'queued' forever .
77+ // List all check-runs for a commit. github.paginate follows every page, so the Build
78+ // check is found even when a SHA accumulates many check-runs (CI matrix, external
79+ // checks, duplicate Build checks from reopened PRs); missing it would leave the PR
80+ // stuck in 'queued' forever. per_page=100 (not the default 30) only reduces the
81+ // number of requests .
7182 const listCheckRuns = (ref) => github.paginate(
7283 'GET /repos/{owner}/{repo}/commits/{ref}/check-runs',
7384 {
96107 return params;
97108 };
98109
99- // A Build check this updater can actually sync: not action_required (notify writes
100- // that when it missed the fork run, and it carries no run params) and with output
110+ // A Build check this updater can actually sync: not action_required (written when
111+ // no fork run was found , and it carries no run params) and with output
101112 // text carrying the {owner, repo, run_id} needed to fetch the fork run. A Build check
102113 // with empty/malformed/fieldless output can never be synced, so it must not count as
103114 // present - otherwise it would suppress the backfill and leave the PR stuck with an
@@ -107,7 +118,7 @@ jobs:
107118 && parseRunParams(cr) != null;
108119
109120 // An action_required Build check: the contributor-facing "enable Actions / rebase"
110- // status notify writes when it found no fork run. It is not syncable, but it already
121+ // status written when no fork run was found . It is not syncable, but it already
111122 // carries the guidance the no-run backfill branch would create, so it is "useful".
112123 const isActionRequiredBuildCheck = (cr) =>
113124 cr.name == 'Build' && cr.conclusion == 'action_required';
@@ -151,22 +162,20 @@ jobs:
151162 continue
152163 }
153164
154- // Does this SHA already carry an action_required Build check? notify (or an
155- // earlier pass of this updater) writes one when no fork run was found. It is
165+ // Does this SHA already carry an action_required Build check? An earlier pass
166+ // of this updater writes one when no fork run was found. It is
156167 // not syncable, so it never suppresses the backfill below - which means a PR
157168 // that permanently lacks a fork run (Actions disabled, old master) would
158169 // otherwise re-poll on every 15-minute pass forever. When one is already
159170 // present, the backfill's re-poll is unnecessary (see below).
160171 const hasActionRequiredBuildCheck = checkRuns.some(isActionRequiredBuildCheck)
161172
162- // Track whether a syncable Build check exists (see isSyncableBuildCheck).
163- // notify_test_workflow.yml creates one per push; if that job never completed
164- // (e.g. cancelled while starved of an ASF runner) the check is missing and the
165- // backfill after this loop recreates it. Sync every match (no early break): a
166- // SHA can carry more than one Build check (reopened PRs, or a backfill that
167- // raced notify). Branch protection evaluates the newest check-run of a given
168- // name, so syncing only the first would leave a newer duplicate stuck in
169- // 'queued' and block the PR.
173+ // Track whether a syncable Build check exists (see isSyncableBuildCheck); if
174+ // not, the backfill after this loop creates one. Sync every match (no early
175+ // break): a SHA can carry more than one Build check (reopened PRs, or
176+ // overlapping updater runs). Branch protection evaluates the newest check-run
177+ // of a given name, so syncing only the first would leave a newer duplicate
178+ // stuck in 'queued' and block the PR.
170179 let syncableBuildCheck = false
171180 // Build checks whose referenced fork run is permanently gone (404). They parse
172181 // as syncable (their output still carries valid run params) but can never be
@@ -244,14 +253,13 @@ jobs:
244253 }
245254 }
246255
247- // No syncable Build check: notify_test_workflow.yml never created one, or only
248- // a stale action_required one exists. Recreate it here, mirroring notify. Skip
249- // if the head repo was deleted.
256+ // No syncable Build check: none was created yet, or only a stale action_required
257+ // one exists. Create it here. Skip if the head repo was deleted.
250258 if (!syncableBuildCheck && pr.head.repo) {
251259 const forkOwner = pr.head.repo.owner.login
252260 const forkRepo = pr.head.repo.name
253- // Look up the fork's build_main.yml runs for the PR branch, matching
254- // notify_test_workflow.yml. Filter by branch (head.ref), not just head_sha:
261+ // Look up the fork's build_main.yml runs for the PR branch.
262+ // Filter by branch (head.ref), not just head_sha:
255263 // build_main.yml skips fork pushes to master (the "Sync fork" case), so the
256264 // same SHA can carry a skipped/unrelated run on another branch, and a
257265 // head_sha-only lookup could attach the Build check to that run instead of
@@ -311,18 +319,15 @@ jobs:
311319 // An action_required Build check already exists and we still found no run:
312320 // the guidance check the no-run branch below would create is already present,
313321 // so there is nothing to backfill. Skip the recheck listing and the create
314- // outright. (This is only reachable via the single, sleepless lookup above,
315- // so there was no ~6s window for notify to have created a syncable check in
316- // the meantime; even if it had, skipping is safe - with no run there is
317- // nothing to promote to 'queued' this pass anyway.)
322+ // outright.
318323 if (hasActionRequiredBuildCheck && !matched_run) {
319324 console.log(' action_required Build check present; nothing to backfill')
320325 continue
321326 }
322327
323328 // Recheck for an existing Build check immediately before creating one. The
324- // poll above can span up to ~6 seconds, during which notify_test_workflow.yml
325- // may create the check; this recheck skips the backfill in that common case.
329+ // poll above can span up to ~6 seconds, during which an overlapping updater run
330+ // may create the check; this recheck skips the backfill in that case.
326331 // It narrows but cannot fully close the window (there is no atomic
327332 // create-if-absent, and the list endpoint is eventually consistent) - the
328333 // sync loop above stays tolerant of duplicates so any that slip through still
@@ -382,8 +387,8 @@ jobs:
382387 } else {
383388 // No run for this head commit after re-polling (empty result, permanent
384389 // lookup failure, or build_main.yml missing): Actions is disabled, the
385- // branch is on an old master, or the commit never triggered a run. Mirror
386- // notify's action_required check so the PR carries a required status
390+ // branch is on an old master, or the commit never triggered a run. Create
391+ // an action_required check so the PR carries a required status
387392 // telling the contributor how to fix it.
388393 console.log(' No forked run for head SHA; creating action_required check')
389394 await github.rest.checks.create({
0 commit comments