From fd56d16e5b9b2a1343fdc8778610207c6d0776b7 Mon Sep 17 00:00:00 2001
From: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
Date: Tue, 3 Nov 2026 18:59:28 -0500
Subject: [PATCH] chore(ci): port DCO provider runbook relocation and policy
literals to v6
Ports the v5 change from #16468 so v6's native-queue-policy script exports
the same named DCO provider constants and links the relocated runbook.
Refs #16404
Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
---
.github/scripts/native-queue-policy.cjs | 17 +++++++++++++----
.github/scripts/native-queue-policy.test.cjs | 10 ++++++++--
.../changed-dco-provider-runbook-location.md | 1 +
src/docs/native-merge-queue.md | 5 +++++
src/docs/operator-reference.md | 2 ++
.../dco-provider-unavailable.md | 2 ++
6 files changed, 31 insertions(+), 6 deletions(-)
create mode 100644 changelog.d/changed-dco-provider-runbook-location.md
rename {docs/operations => src/docs/operator-reference}/dco-provider-unavailable.md (99%)
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 d6141bcf33..17fda3c58f 100644
--- a/src/docs/native-merge-queue.md
+++ b/src/docs/native-merge-queue.md
@@ -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,
diff --git a/src/docs/operator-reference.md b/src/docs/operator-reference.md
index b3f495dce4..0b41f91933 100644
--- a/src/docs/operator-reference.md
+++ b/src/docs/operator-reference.md
@@ -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)
- [Open held PR cap](operator-reference/v6-controls.md#open-held-pr-cap-max_open_held_prs)
+
+- [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