Skip to content

Commit c1a329d

Browse files
mchwangclaude
andcommitted
Count neutral and skipped required checks as passing, and read a check's latest run
GitHub counts a required check run that completed NEUTRAL or SKIPPED as passing; the inspection read both as failure, which now ends a merge job blocked. When a check has several runs with one name (a re-run), the first listed won, so an older failure could outrank a newer pending or passing run. The run that started last now counts (a run not started yet counts as the latest; on a tie, the one that passes least). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent d2de1b3 commit c1a329d

3 files changed

Lines changed: 87 additions & 15 deletions

File tree

‎docs/implementation/merge-handoff.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ Without a runner, **Merge PR** works as before.
3535
| Wait for checks | The job inspects the pull request (fresh) at once, then again after 10 s, with the wait doubling up to 60 s. | every required check succeeds, or the required set was read and is empty, and nothing else blocks | a required check fails, or 30 minutes pass (job: `blocked`, if the preparation still applies: the block re-checks readiness in its transaction, and a review edit or other task change meanwhile ends the job `failed` instead); the pull request moved, another blocker appears, or GitHub or the local review cannot be read (job: `failed`; one failed read fails closed rather than retrying; each inspection also loads the review, which awaits a history worker since #170, within the same 30-minute limit) |
3636
| Merge | The job calls the guarded merge with the current review token. Its inspections rerun the already-fixed check. | GitHub merged or queued the head, as the job's own merge attempt records it (job: `merged` or `queued`; `submitted` when GitHub accepted the merge but saving its outcome failed, so the attempt is still submitting and reconciles from GitHub) | GitHub refused (job: `blocked`; `failed` when GitHub refused because the head changed, which needs a fresh review, or when the review, snapshot or plan revision changed while GitHub was asked: the block is for the review the merge attempt was admitted for), validation refused (job: `failed`), or the outcome is unknown (job: `submitted`; the merge attempt reconciles as before) |
3737

38-
While waiting, an unknown mergeability (GitHub is still computing it) and a pending or missing required check keep the job waiting. No inspection starts after the 30 minutes, and one still running when they end is stopped, so only checks seen passing within the limit count. The guarded merge that follows inspects again and may ask GitHub to merge shortly after the limit; it refuses anything no longer clear. Unreadable branch rules never pass. Another blocker outranks a failing check: checks that fail on a head a collaborator pushed say nothing about this review, so the job ends `failed` and the task's status is unchanged.
38+
A required check run passes when it completed with success, neutral or skipped, as GitHub counts required checks; a commit status passes only with success. When a check has several runs or statuses with its name (a re-run), the one that started last counts, and a run not yet started counts as the latest. While waiting, an unknown mergeability (GitHub is still computing it) and a pending or missing required check keep the job waiting. No inspection starts after the 30 minutes, and one still running when they end is stopped, so only checks seen passing within the limit count. The guarded merge that follows inspects again and may ask GitHub to merge shortly after the limit; it refuses anything no longer clear. Unreadable branch rules never pass. Another blocker outranks a failing check: checks that fail on a head a collaborator pushed say nothing about this review, so the job ends `failed` and the task's status is unchanged.
3939

4040
## Outcomes
4141

‎github/merge.ts‎

Lines changed: 34 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,33 @@ function timestamp(value: unknown, label: string): string {
150150
}
151151

152152
/** GitHub CLI adapter. All arguments are literal argv; no shell is involved. */
153+
/**
154+
* The state GitHub gives one observed required check. A check run that completed SUCCESS, NEUTRAL or SKIPPED passes, as
155+
* GitHub treats those conclusions for required checks; a commit status passes only with SUCCESS.
156+
*/
157+
function observedCheckState(check: Record<string, unknown>): 'success' | 'pending' | 'failure' {
158+
if (typeof check.name === 'string') {
159+
const status = String(check.status ?? '').toUpperCase();
160+
const conclusion = String(check.conclusion ?? '').toUpperCase();
161+
if (['QUEUED','IN_PROGRESS','WAITING','PENDING','REQUESTED'].includes(status)) return 'pending';
162+
if (status === 'COMPLETED') return ['SUCCESS','NEUTRAL','SKIPPED'].includes(conclusion) ? 'success' : 'failure';
163+
return 'failure';
164+
}
165+
const status = String(check.state ?? '').toUpperCase();
166+
return status === 'SUCCESS' ? 'success' : ['PENDING','EXPECTED'].includes(status) ? 'pending' : 'failure';
167+
}
168+
/**
169+
* When an observed check run or status started, to pick the latest of several with one name. gh reports a run that has
170+
* not started yet with no time or the zero time (year 1); such a run was queued after every started one, so it counts
171+
* as the latest.
172+
*/
173+
function observedCheckStart(check: Record<string, unknown>): number {
174+
const at = typeof check.startedAt === 'string' ? Date.parse(check.startedAt) : NaN;
175+
return Number.isFinite(at) && new Date(at).getUTCFullYear() > 1 ? at : Number.POSITIVE_INFINITY;
176+
}
177+
/** Among runs with the same start, the one that passes least counts, so a tie never reads as passing. */
178+
const checkStateRank = { failure: 0, pending: 1, success: 2 } as const;
179+
153180
export class GhMergeGateway implements MergeGateway, MergeQueueGateway {
154181
readonly config: GhMergeConfig;
155182
readonly run: RunGh;
@@ -366,24 +393,17 @@ export class GhMergeGateway implements MergeGateway, MergeQueueGateway {
366393
}
367394
}
368395
const requiredChecks = [...requirements.values()].map(required => {
369-
const match = observed.find(check => {
396+
const matches = observed.filter(check => {
370397
const context = typeof check.name === 'string' ? check.name : check.context;
371398
const app = check.app && typeof check.app === 'object' ? (check.app as { databaseId?: unknown }).databaseId : null;
372399
return context === required.context && (required.appId === null || app === required.appId);
373400
});
374-
if (!match) return { ...required, state: 'missing' as const };
375-
let state: RequiredCheck['state'];
376-
if (typeof match.name === 'string') {
377-
const status = String(match.status ?? '').toUpperCase();
378-
const conclusion = String(match.conclusion ?? '').toUpperCase();
379-
if (['QUEUED','IN_PROGRESS','WAITING','PENDING','REQUESTED'].includes(status)) state = 'pending';
380-
else if (status === 'COMPLETED') state = conclusion === 'SUCCESS' ? 'success' : 'failure';
381-
else state = 'failure';
382-
} else {
383-
const status = String(match.state ?? '').toUpperCase();
384-
state = status === 'SUCCESS' ? 'success' : ['PENDING','EXPECTED'].includes(status) ? 'pending' : 'failure';
385-
}
386-
return { ...required, state };
401+
if (!matches.length) return { ...required, state: 'missing' as const };
402+
// A re-run adds a newer run (or status) with the same name; GitHub counts the latest one, so an older failure
403+
// does not outrank a newer pending or passing run.
404+
const latest = matches.map(check => ({ state: observedCheckState(check), at: observedCheckStart(check) }))
405+
.reduce((best, next) => next.at > best.at || (next.at === best.at && checkStateRank[next.state] < checkStateRank[best.state]) ? next : best);
406+
return { ...required, state: latest.state };
387407
});
388408
return { rulesKnown, atomicBaseGuard, mergeQueue, requiredChecks };
389409
}

‎test/merge.test.ts‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -940,6 +940,58 @@ it('parses required checks from both rule sources and pins the gh merge head', a
940940
expect(pullReads).toBe(2);
941941
});
942942

943+
/** Inspects a pull request whose one required check, `test` from any app, has these observed runs and statuses. */
944+
async function requiredTestState(statusCheckRollup: unknown[]) {
945+
const run = async (args: readonly string[]) => {
946+
const joined = args.join(' ');
947+
if (joined.startsWith('pr view 7')) return JSON.stringify({ number: 7, isDraft: false, baseRefName: 'main', baseRefOid: sha('a'), headRefName: 'feature', headRefOid: sha('b'), state: 'OPEN', mergeable: 'MERGEABLE', statusCheckRollup });
948+
if (joined.includes('/rules/branches/')) return JSON.stringify([[{ type: 'required_status_checks', parameters: { strict_required_status_checks_policy: false, required_status_checks: [{ context: 'test', integration_id: null }] } }]]);
949+
if (/branches\/main$/.test(joined)) return JSON.stringify({ protected: false });
950+
if (joined.endsWith('/protection')) throw new Error('gh: Branch not protected (HTTP 404)');
951+
{ const fixed = alreadyFixedReads(args); if (fixed !== null) return fixed; }
952+
throw new Error(`Unexpected gh call: ${joined}`);
953+
};
954+
const state = await new GhMergeGateway({ repository: 'owner/repo', pullRequest: 7, issue: 21 }, run).inspect();
955+
expect(state.rulesKnown).toBe(true);
956+
return state.requiredChecks.map(check => check.state);
957+
}
958+
959+
it.each([
960+
['SUCCESS', 'success'], ['NEUTRAL', 'success'], ['SKIPPED', 'success'],
961+
['FAILURE', 'failure'], ['CANCELLED', 'failure'], ['TIMED_OUT', 'failure'], ['ACTION_REQUIRED', 'failure'], ['STARTUP_FAILURE', 'failure'], ['STALE', 'failure'],
962+
] as const)('reads a required check run that completed %s as %s, as GitHub does for required checks', async (conclusion, expected) => {
963+
expect(await requiredTestState([{ name: 'test', status: 'COMPLETED', conclusion, startedAt: '2026-10-11T00:00:00Z' }])).toEqual([expected]);
964+
});
965+
966+
it.each([
967+
['a newer pending re-run over an older failure', [
968+
{ name: 'test', status: 'COMPLETED', conclusion: 'FAILURE', startedAt: '2026-10-11T00:00:00Z', completedAt: '2026-10-11T00:01:00Z' },
969+
{ name: 'test', status: 'IN_PROGRESS', conclusion: '', startedAt: '2026-10-11T00:05:00Z', completedAt: '0001-01-01T00:00:00Z' },
970+
], 'pending'],
971+
['a newer passing re-run over an older failure', [
972+
{ name: 'test', status: 'COMPLETED', conclusion: 'FAILURE', startedAt: '2026-10-11T00:00:00Z' },
973+
{ name: 'test', status: 'COMPLETED', conclusion: 'SUCCESS', startedAt: '2026-10-11T00:05:00Z' },
974+
], 'success'],
975+
['a newer failure over an older pass, listed first', [
976+
{ name: 'test', status: 'COMPLETED', conclusion: 'FAILURE', startedAt: '2026-10-11T00:05:00Z' },
977+
{ name: 'test', status: 'COMPLETED', conclusion: 'SUCCESS', startedAt: '2026-10-11T00:00:00Z' },
978+
], 'failure'],
979+
['a queued re-run that has not started (zero time) over an older failure', [
980+
{ name: 'test', status: 'COMPLETED', conclusion: 'FAILURE', startedAt: '2026-10-11T00:00:00Z' },
981+
{ name: 'test', status: 'QUEUED', conclusion: '', startedAt: '0001-01-01T00:00:00Z' },
982+
], 'pending'],
983+
['the run that passes least when two started at once', [
984+
{ name: 'test', status: 'COMPLETED', conclusion: 'SUCCESS', startedAt: '2026-10-11T00:00:00Z' },
985+
{ name: 'test', status: 'COMPLETED', conclusion: 'FAILURE', startedAt: '2026-10-11T00:00:00Z' },
986+
], 'failure'],
987+
['a newer commit status over an older failed one', [
988+
{ context: 'test', state: 'FAILURE', startedAt: '2026-10-11T00:00:00Z' },
989+
{ context: 'test', state: 'SUCCESS', startedAt: '2026-10-11T00:05:00Z' },
990+
], 'success'],
991+
] as const)('counts the latest observation of a required check: %s', async (_case, rollup, expected) => {
992+
expect(await requiredTestState([...rollup])).toEqual([expected]);
993+
});
994+
943995
it('rejects an unsupported runtime merge method', () => {
944996
expect(() => new GhMergeGateway({ repository: 'owner/repo', pullRequest: 7, issue: 21, method: 'typo' as 'merge' })).toThrow(/merge method/i);
945997
});

0 commit comments

Comments
 (0)