Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 13 additions & 4 deletions .github/scripts/native-queue-policy.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -29,12 +29,19 @@ class PendingEvidence extends Error {}
// A provider's inability to evaluate is not a negative sign-off verdict. It
// still blocks admission, and is deliberately not PendingEvidence: polling or
// retrying the admission job cannot repair the external provider.
const DCO_ENUMERATION_SUMMARY_PREFIX =
'The DCO check could not be evaluated because the complete pull request commit list could not be retrieved.';
const DCO_ENUMERATION_SUMMARY_FALLBACK =
'That fallback did not complete, so the DCO verdict is unknown.';
const DCO_PROVIDER_UNAVAILABLE_TEXT = 'DCO provider unavailable';
const DCO_PROVIDER_RUNBOOK = 'src/docs/operator-reference/dco-provider-unavailable.md';

class ProviderUnavailable extends Error {
constructor(run, head) {
super(`DCO provider unavailable on ${head}: verdict UNKNOWN (App ${DCO_APP_ID}, ` +
super(`${DCO_PROVIDER_UNAVAILABLE_TEXT} on ${head}: verdict UNKNOWN (App ${DCO_APP_ID}, ` +
`check run ${run.id}, conclusion ${run.conclusion}). Admission remains blocked. ` +
'An operator must investigate the DCO provider enumeration path; see ' +
'docs/operations/dco-provider-unavailable.md. No PR source change is requested.');
`${DCO_PROVIDER_RUNBOOK}. No PR source change is requested.`);
}
}

Expand All @@ -43,8 +50,8 @@ function dcoEnumerationUnavailable(run) {
// Call only after validating provider, head and completed status.
return run.name === 'DCO' && run.conclusion === 'failure' &&
typeof run.output?.summary === 'string' &&
run.output.summary.startsWith('The DCO check could not be evaluated because the complete pull request commit list could not be retrieved.') &&
run.output.summary.includes('That fallback did not complete, so the DCO verdict is unknown.');
run.output.summary.startsWith(DCO_ENUMERATION_SUMMARY_PREFIX) &&
run.output.summary.includes(DCO_ENUMERATION_SUMMARY_FALLBACK);
}

function membersForGroup(entries, group) {
Expand Down Expand Up @@ -265,4 +272,6 @@ module.exports = {
PendingEvidence, membersForGroup, assertEligible, evidenceForHead, closedNoop, evaluate,
isTransientAPIError,
ProviderUnavailable,
DCO_ENUMERATION_SUMMARY_PREFIX, DCO_ENUMERATION_SUMMARY_FALLBACK,
DCO_PROVIDER_UNAVAILABLE_TEXT, DCO_PROVIDER_RUNBOOK,
};
10 changes: 8 additions & 2 deletions .github/scripts/native-queue-policy.test.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,17 @@ const {
PendingEvidence, membersForGroup, assertEligible, evidenceForHead, closedNoop, evaluate,
isTransientAPIError,
ProviderUnavailable,
DCO_ENUMERATION_SUMMARY_PREFIX,
DCO_ENUMERATION_SUMMARY_FALLBACK,
DCO_PROVIDER_UNAVAILABLE_TEXT,
DCO_PROVIDER_RUNBOOK,
} = require('./native-queue-policy.cjs');

const sha = n => n.toString(16).padStart(40, '0');
// App 1861 check run 125732155592 on #16378, head 1989d20aa8d0d92cce761786ac05825aef1d9d3a.
const unavailableSummary = 'The DCO check could not be evaluated because the complete pull request commit list could not be retrieved.\n\n' +
const unavailableSummary = DCO_ENUMERATION_SUMMARY_PREFIX + '\n\n' +
'GitHub returned 250 commits from the REST API, so the app attempted to retrieve the full list through GraphQL before evaluating the pull request. ' +
'That fallback did not complete, so the DCO verdict is unknown.\n\nHTTP status: unknown\nGitHub request ID: unavailable';
DCO_ENUMERATION_SUMMARY_FALLBACK + '\n\nHTTP status: unknown\nGitHub request ID: unavailable';
const group = {
base_sha: sha(1), head_sha: sha(4), base_ref: 'refs/heads/v5',
head_ref: 'refs/heads/gh-readonly-queue/v5/pr-2-example',
Expand Down Expand Up @@ -176,6 +180,8 @@ test('provider enumeration UNKNOWN blocks both admission paths without retry or
assert.ok(error instanceof ProviderUnavailable);
assert.ok(!(error instanceof PendingEvidence));
assert.match(error.message, /verdict UNKNOWN.*App 1861/);
assert.ok(error.message.startsWith(DCO_PROVIDER_UNAVAILABLE_TEXT));
assert.ok(error.message.includes(DCO_PROVIDER_RUNBOOK));
assert.match(error.message, /Admission remains blocked/);
assert.match(error.message, /No PR source change is requested/);
return true;
Expand Down
1 change: 1 addition & 0 deletions changelog.d/changed-dco-provider-runbook-location.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Moved the DCO provider-unavailable runbook to `src/docs/operator-reference/` and named its policy-message literals; admission behavior is unchanged ([#16404](https://github.com/hivecommons/hive/issues/16404)).
5 changes: 5 additions & 0 deletions src/docs/native-merge-queue.md
Original file line number Diff line number Diff line change
Expand Up @@ -371,6 +371,11 @@ handles rejected/broken heads; there is no second fixer or merge engine.

## Diagnostics and rollback

- If the authoritative DCO App cannot enumerate a large PR's complete commit
history, admission reports **DCO provider unavailable / verdict UNKNOWN**
and remains blocked. Follow the [provider diagnosis and recovery runbook](operator-reference/dco-provider-unavailable.md);
a provider enumeration failure does not request a PR source change or permit
substitution of the lowercase prow `dco` status.
- Inspect the PR's exact-head checks and the **group SHA** checks separately.
A green member head does not establish green integration evidence.
`native-queue-policy` logs the failing provider, provenance, membership,
Expand Down
2 changes: 2 additions & 0 deletions src/docs/operator-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -135,3 +135,5 @@ The reference is organized into the sections below. Existing links to this page
- [Red-main circuit breaker](operator-reference/v6-controls.md#red-main-circuit-breaker-red_main_threshold)
<a id="open-held-pr-cap-max_open_held_prs"></a>
- [Open held PR cap](operator-reference/v6-controls.md#open-held-pr-cap-max_open_held_prs)
<a id="dco-provider-unavailable-on-large-forward-merges"></a>
- [DCO provider unavailable on large forward merges](operator-reference/dco-provider-unavailable.md)
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# DCO provider unavailable on large forward merges

[Contents](../operator-reference.md)

`native-queue-policy` requires the latest completed **DCO** check from App
**1861** to succeed on the exact current PR head. When that provider reports
that it could not retrieve the complete PR commit list, admission is blocked
Expand Down
Loading