diff --git a/.github/scripts/native-queue-policy.cjs b/.github/scripts/native-queue-policy.cjs index 51bcf634f5..1f4b7e82d2 100644 --- a/.github/scripts/native-queue-policy.cjs +++ b/.github/scripts/native-queue-policy.cjs @@ -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.`); } } @@ -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) { @@ -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, }; diff --git a/.github/scripts/native-queue-policy.test.cjs b/.github/scripts/native-queue-policy.test.cjs index 72a38e3e30..07e5eeb76e 100644 --- a/.github/scripts/native-queue-policy.test.cjs +++ b/.github/scripts/native-queue-policy.test.cjs @@ -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', @@ -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; diff --git a/changelog.d/changed-dco-provider-runbook-location.md b/changelog.d/changed-dco-provider-runbook-location.md new file mode 100644 index 0000000000..0b1e7a4b99 --- /dev/null +++ b/changelog.d/changed-dco-provider-runbook-location.md @@ -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)). diff --git a/src/docs/native-merge-queue.md b/src/docs/native-merge-queue.md index 42fa30eccc..17fda3c58f 100644 --- a/src/docs/native-merge-queue.md +++ b/src/docs/native-merge-queue.md @@ -373,7 +373,7 @@ handles rejected/broken heads; there is no second fixer or merge engine. - 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](../../docs/operations/dco-provider-unavailable.md); + 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. diff --git a/src/docs/operator-reference.md b/src/docs/operator-reference.md index 0e86b726d4..cca74fa301 100644 --- a/src/docs/operator-reference.md +++ b/src/docs/operator-reference.md @@ -123,3 +123,5 @@ The reference is organized into the sections below. Existing links to this page - [Knowledge: Context7 content caps](operator-reference/runtime-and-quota.md#knowledge-context7-content-caps) - [Inference endpoint fallbacks](operator-reference/runtime-and-quota.md#inference-endpoint-fallbacks) + +- [DCO provider unavailable on large forward merges](operator-reference/dco-provider-unavailable.md) diff --git a/docs/operations/dco-provider-unavailable.md b/src/docs/operator-reference/dco-provider-unavailable.md similarity index 99% rename from docs/operations/dco-provider-unavailable.md rename to src/docs/operator-reference/dco-provider-unavailable.md index 4e154835a2..7c4d51e086 100644 --- a/docs/operations/dco-provider-unavailable.md +++ b/src/docs/operator-reference/dco-provider-unavailable.md @@ -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