Skip to content

Commit 731b50a

Browse files
Jimbo4350Jimbo4350
committed
Track haddock dead-link CI failures in a rolling issue
When the haddock-links check fails on master, open (or comment on) a single tracking issue identified by the marker label 'haddock-ci-failure', @-mentioning the breaker — sourced from the master commit's associated PR via listPullRequestsAssociatedWithCommit, which handles squash merges. The issue body documents the fix recipe (add the package's doc base URL to IOG_DOC_BASES, or add the package to KNOWN_UNDOCUMENTED). Each failure appends a comment with the run URL so the audit trail of consecutive breakages is visible in one place. Add an id to the haddock-links step so the new tag-breaker step can gate on its specific outcome (failure() && steps.<id>.outcome == 'failure'), avoiding spurious issue creation on unrelated failures (cabal build, nix shell, network glitch in haddock-project, etc.).
1 parent 2f86a4a commit 731b50a

1 file changed

Lines changed: 156 additions & 0 deletions

File tree

‎.github/workflows/github-page.yml‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ jobs:
4040
cabal haddock-project --output=./website --internal --foreign-libraries
4141
4242
- name: Fix cross-package Haddock links
43+
id: fix-haddock-links
4344
run: |
4445
./scripts/fix-haddock-links.sh ./website
4546
@@ -69,3 +70,158 @@ jobs:
6970
publish_dir: website
7071
cname: cardano-api.cardano.intersectmbo.org
7172
force_orphan: true
73+
74+
# ──────────────────────────────────────────────────────────────────
75+
# Tracking-issue logic for post-merge dead-link failures.
76+
#
77+
# Why: when fix-haddock-links.sh exits 1 on master (because some
78+
# newly-introduced CHaP package has no entry in IOG_DOC_BASES /
79+
# KNOWN_UNDOCUMENTED), the Deploy step further down skips and the
80+
# docs site stays at its last good revision. Without this step, the
81+
# only signal that something is broken is a red Actions run that
82+
# nobody is necessarily watching. This step opens a GitHub issue
83+
# tagging whoever introduced the breakage, so it lands on someone's
84+
# board instead of going unnoticed.
85+
#
86+
# Behaviour summary: one rolling issue per outage period. First
87+
# failure opens a new issue. Subsequent failures (while the issue
88+
# is still open) append a comment instead of opening a duplicate.
89+
# Once a maintainer fixes the root cause and closes the issue, the
90+
# next failure opens a fresh one.
91+
#
92+
# The fire conditions on the `if:` line below — all three required:
93+
# - failure() → the job overall is failing
94+
# - steps.fix-haddock-links.outcome → specifically the haddock-links
95+
# == 'failure' step failed (not e.g. cabal,
96+
# nix-shell, or the typedoc build)
97+
# - github.ref == 'refs/heads/master' → only on master pushes; not
98+
# on workflow_dispatch from
99+
# feature branches
100+
- name: Open / update dead-link tracking issue
101+
if: failure() && steps.fix-haddock-links.outcome == 'failure' && github.ref == 'refs/heads/master'
102+
uses: actions/github-script@v7
103+
with:
104+
script: |
105+
// Marker label used to identify the rolling tracking issue.
106+
// Looking up issues by label is more robust than by title (a
107+
// title match would break the moment someone edits the title).
108+
const labelName = 'haddock-ci-failure';
109+
const titleText = 'Haddock dead-link CI failures on master';
110+
111+
// ─── 1. Ensure the marker label exists ──────────────────────
112+
// First time this step ever fires, the label doesn't exist
113+
// yet and createLabel returns 201. Every subsequent run, the
114+
// API returns 422 ("name has already been taken") which we
115+
// swallow so the step continues. Any other error (403 = no
116+
// permission, 5xx = GitHub outage, etc.) re-throws and fails
117+
// the step, leaving a stack trace for debugging.
118+
try {
119+
await github.rest.issues.createLabel({
120+
owner: context.repo.owner,
121+
repo: context.repo.repo,
122+
name: labelName,
123+
color: 'd93f0b',
124+
description: 'Post-merge haddock-links CI failures (rolling tracking issue)',
125+
});
126+
} catch (e) {
127+
if (e.status !== 422) throw e;
128+
}
129+
130+
// ─── 2. Identify the breaker ────────────────────────────────
131+
// We want to @-mention the *PR opener* (the author who wrote
132+
// the change), not the merger (who clicked the merge button)
133+
// or the committer (whose name might be set to a bot identity).
134+
// listPullRequestsAssociatedWithCommit takes the new master
135+
// HEAD's SHA and returns the PR(s) that produced it. Works for
136+
// merge-commit, rebase, and squash-merge styles — GitHub
137+
// records the commit→PR association regardless. We read
138+
// pr.user.login from the result to get the PR opener.
139+
//
140+
// Fallback: in the unlikely case a master commit has no
141+
// associated PR (direct push by a maintainer), use
142+
// context.actor — the user who triggered the workflow run.
143+
const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
144+
owner: context.repo.owner,
145+
repo: context.repo.repo,
146+
commit_sha: context.sha,
147+
});
148+
const pr = prs[0];
149+
const author = pr ? pr.user.login : context.actor;
150+
const prRef = pr ? `#${pr.number}` : `commit ${context.sha.slice(0, 7)}`;
151+
const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
152+
153+
// Body fragment used both as the comment body (when an issue
154+
// already exists) and appended to the issue body (when we
155+
// create a new one). Same content, two contexts.
156+
const commentBody = [
157+
`### New failure`,
158+
``,
159+
`On master after ${prRef} (committed by @${author}).`,
160+
``,
161+
`**Run:** ${runUrl}`,
162+
``,
163+
`Open the run log and look for \`=== Actionable — fix these ===\` to see which package(s) the probe couldn't resolve.`,
164+
].join('\n');
165+
166+
// ─── 3. Look up the existing tracking issue ─────────────────
167+
// Filter by `state: open` so a closed (i.e. already-fixed)
168+
// tracking issue doesn't get reused — we want a fresh issue
169+
// for the next outage period, not to reopen a stale one.
170+
// per_page: 1 because we only need to know whether ANY exists.
171+
const { data: issues } = await github.rest.issues.listForRepo({
172+
owner: context.repo.owner,
173+
repo: context.repo.repo,
174+
state: 'open',
175+
labels: labelName,
176+
per_page: 1,
177+
});
178+
179+
// ─── 4. Branch on whether one was found ─────────────────────
180+
if (issues.length > 0) {
181+
// Existing open issue → comment on it; don't open a duplicate.
182+
// Also add the new breaker as an assignee (idempotent — if
183+
// they're already assigned the API silently no-ops).
184+
const existing = issues[0];
185+
await github.rest.issues.createComment({
186+
owner: context.repo.owner,
187+
repo: context.repo.repo,
188+
issue_number: existing.number,
189+
body: commentBody,
190+
});
191+
await github.rest.issues.addAssignees({
192+
owner: context.repo.owner,
193+
repo: context.repo.repo,
194+
issue_number: existing.number,
195+
assignees: [author],
196+
});
197+
console.log(`Appended to existing issue #${existing.number}: ${existing.html_url}`);
198+
} else {
199+
// No open issue → create one. The body documents the fix
200+
// recipe so the assignee doesn't need to find it elsewhere.
201+
const issueBody = [
202+
`Tracking issue for post-merge \`Update github pages\` workflow failures on the haddock-links check. The Deploy step skips on failure, so the published docs site stays at its last good revision until this issue is resolved.`,
203+
``,
204+
`## How to fix`,
205+
``,
206+
`For each package listed under \`=== Actionable — fix these ===\` in the failing run:`,
207+
``,
208+
`1. Check the package's source repo for a published Haddocks site (gh-pages, CloudFront, etc.).`,
209+
`2. If found: append the base URL to \`IOG_DOC_BASES\` in \`scripts/fix-haddock-links.sh\`.`,
210+
`3. If genuinely unpublished: add the package name to \`KNOWN_UNDOCUMENTED\`.`,
211+
``,
212+
`Then re-run the workflow from the Actions tab. Close this issue once the workflow goes green again.`,
213+
``,
214+
`---`,
215+
``,
216+
commentBody,
217+
].join('\n');
218+
const created = await github.rest.issues.create({
219+
owner: context.repo.owner,
220+
repo: context.repo.repo,
221+
title: titleText,
222+
body: issueBody,
223+
labels: [labelName],
224+
assignees: [author],
225+
});
226+
console.log(`Opened tracking issue #${created.data.number}: ${created.data.html_url}`);
227+
}

0 commit comments

Comments
 (0)