|
| 1 | +// PR intake gate. The policy lives in CONTRIBUTING.md ("How pull requests get |
| 2 | +// in"); .github/workflows/require-linked-issue.yml wires this up to events. |
| 3 | +// |
| 4 | +// A pull request from someone without triage rights stays open only if its |
| 5 | +// description links (Fixes/Closes/Resolves #N) an open issue in this repo that |
| 6 | +// is either assigned to the PR author or labeled `help wanted`. Otherwise the |
| 7 | +// gate labels it `missing-issue-link`, leaves one comment, and closes it. It |
| 8 | +// re-evaluates — and reopens — the PR when the description is edited or the |
| 9 | +// author is assigned to the issue. A triage+ user reopening the PR, removing |
| 10 | +// the label, or adding `bypass-issue-check` overrides it, and the override |
| 11 | +// sticks. |
| 12 | +// |
| 13 | +// Everything that writes goes through mutate(); when the workflow passes |
| 14 | +// ENFORCE=false (its kill switch) the run only logs what it would have done. |
| 15 | +'use strict'; |
| 16 | + |
| 17 | +const LABEL = 'missing-issue-link'; // marks PRs the gate has closed |
| 18 | +const BYPASS_LABEL = 'bypass-issue-check'; // sticky maintainer override |
| 19 | +const OPEN_LABEL = 'help wanted'; // issue label that waives assignment |
| 20 | +const MARKER = '<!-- require-linked-issue -->'; |
| 21 | +const BOT_LOGIN = 'github-actions[bot]'; |
| 22 | +const MAX_ISSUES = 5; |
| 23 | + |
| 24 | +module.exports = async function run({ github, context, core }) { |
| 25 | + const { owner, repo } = context.repo; |
| 26 | + const enforce = process.env.ENFORCE === 'true'; |
| 27 | + const contributingUrl = `https://github.com/${owner}/${repo}/blob/main/CONTRIBUTING.md#how-pull-requests-get-in`; |
| 28 | + |
| 29 | + // ── Entry points ───────────────────────────────────────────────────────── |
| 30 | + |
| 31 | + if (context.eventName === 'issues') { |
| 32 | + // Someone was assigned an issue: re-evaluate their gate-closed PRs that |
| 33 | + // reference it (they may pass now). |
| 34 | + const issueNumber = context.payload.issue.number; |
| 35 | + const assignee = context.payload.assignee.login; |
| 36 | + const closed = await github.paginate(github.rest.issues.listForRepo, { |
| 37 | + owner, repo, state: 'closed', creator: assignee, labels: LABEL, per_page: 100, |
| 38 | + }); |
| 39 | + const prs = closed.filter((i) => i.pull_request && closingRefs(i.body).includes(issueNumber)); |
| 40 | + console.log(`#${issueNumber} assigned to ${assignee}: ${prs.length} gate-closed PR(s) reference it`); |
| 41 | + for (const pr of prs) await evaluate(pr.number, 'assigned', context.payload.sender?.login, issueNumber); |
| 42 | + return; |
| 43 | + } |
| 44 | + |
| 45 | + if (context.eventName === 'workflow_dispatch') { |
| 46 | + const n = parseInt(process.env.PR_NUMBER_INPUT, 10); |
| 47 | + if (!Number.isInteger(n) || n <= 0) throw new Error(`Bad pr_number input: ${process.env.PR_NUMBER_INPUT}`); |
| 48 | + await evaluate(n, 'dispatch', context.payload.sender?.login); |
| 49 | + return; |
| 50 | + } |
| 51 | + |
| 52 | + await evaluate(context.payload.pull_request.number, context.payload.action, context.payload.sender?.login); |
| 53 | + |
| 54 | + // ── The rules ──────────────────────────────────────────────────────────── |
| 55 | + |
| 56 | + async function evaluate(prNumber, action, sender, hintIssue = null) { |
| 57 | + // Always read the PR live; the event payload can be stale by the time a |
| 58 | + // queued run starts. |
| 59 | + const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber }); |
| 60 | + const labels = pr.labels.map((l) => l.name); |
| 61 | + // An `unlabeled` run only fires for LABEL (see the workflow `if:`), so the |
| 62 | + // event itself proves the label was there a moment ago. |
| 63 | + const gated = action === 'unlabeled' || labels.includes(LABEL); |
| 64 | + console.log(`PR #${prNumber} by ${pr.user.login} (${pr.state}${pr.draft ? ', draft' : ''}) — ${action} by ${sender ?? '-'}, enforce=${enforce}`); |
| 65 | + |
| 66 | + // 0. Scope: open PRs, plus closed PRs the gate closed itself. Merged PRs |
| 67 | + // and PRs someone closed for other reasons are left alone. |
| 68 | + if (pr.merged_at) return log('merged — nothing to do'); |
| 69 | + if (pr.state === 'closed' && !gated) return log('closed by someone else — not ours'); |
| 70 | + |
| 71 | + // 1. Exempt authors: bots, anyone with triage or better, and drafts (which |
| 72 | + // are checked again on ready_for_review). |
| 73 | + if (pr.user.type === 'Bot') return log('author is a bot — exempt'); |
| 74 | + if (await isTrusted(pr.user.login)) return pass('author has triage+ on this repo'); |
| 75 | + if (pr.draft) return log('draft — skipped until ready for review'); |
| 76 | + |
| 77 | + // 2. Overrides: a triage+ user reopening the PR or removing the label wants |
| 78 | + // it open. Anyone else doing so just triggers a re-check. |
| 79 | + if ((action === 'reopened' || action === 'unlabeled') && sender && (await isTrusted(sender))) { |
| 80 | + return pass(`${sender} ${action === 'reopened' ? 'reopened it' : 'removed the label'} — override`, { sticky: true }); |
| 81 | + } |
| 82 | + if (labels.includes(BYPASS_LABEL)) return pass(`carries ${BYPASS_LABEL}`); |
| 83 | + |
| 84 | + // 3. The rule: the description links an open issue in this repo that is |
| 85 | + // labeled `help wanted` or assigned to the author. Only the first few |
| 86 | + // references are fetched; a just-assigned issue is checked first. |
| 87 | + const author = pr.user.login.toLowerCase(); |
| 88 | + const refs = closingRefs(pr.body); |
| 89 | + if (hintIssue && refs.includes(hintIssue)) refs.unshift(...refs.splice(refs.indexOf(hintIssue), 1)); |
| 90 | + const linked = []; |
| 91 | + for (const num of refs.slice(0, MAX_ISSUES)) { |
| 92 | + const issue = await getIssue(num); |
| 93 | + if (!issue) continue; // missing, a PR, closed, or transferred away |
| 94 | + linked.push(num); |
| 95 | + if (issue.labels.some((l) => l.name.toLowerCase() === OPEN_LABEL)) return pass(`#${num} is labeled "${OPEN_LABEL}"`); |
| 96 | + if (issue.assignees.some((a) => a.login.toLowerCase() === author)) return pass(`author is assigned to #${num}`); |
| 97 | + } |
| 98 | + return fail(linked); |
| 99 | + |
| 100 | + // ── Outcomes ───────────────────────────────────────────────────────── |
| 101 | + |
| 102 | + async function pass(reason, { sticky = false } = {}) { |
| 103 | + console.log(`PASS: ${reason}`); |
| 104 | + if (sticky) await addLabel(prNumber, BYPASS_LABEL); |
| 105 | + if (pr.state === 'closed' && !(await reopen(pr, reason))) return; |
| 106 | + if (gated) { |
| 107 | + await removeLabel(prNumber, LABEL); |
| 108 | + await deleteGateComment(prNumber); |
| 109 | + } |
| 110 | + } |
| 111 | + |
| 112 | + async function fail(linkedIssues) { |
| 113 | + console.log(`FAIL: ${linkedIssues.length ? `not assigned to ${linkedIssues.map((n) => `#${n}`).join(', ')}` : 'no usable issue link'}`); |
| 114 | + await addLabel(prNumber, LABEL); |
| 115 | + await upsertGateComment(prNumber, closedComment(linkedIssues)); |
| 116 | + if (pr.state === 'open') { |
| 117 | + await mutate(`close PR #${prNumber}`, () => github.rest.pulls.update({ owner, repo, pull_number: prNumber, state: 'closed' })); |
| 118 | + } |
| 119 | + } |
| 120 | + |
| 121 | + function log(msg) { |
| 122 | + console.log(msg); |
| 123 | + } |
| 124 | + } |
| 125 | + |
| 126 | + // ── Comment text ───────────────────────────────────────────────────────── |
| 127 | + |
| 128 | + function closedComment(linkedIssues) { |
| 129 | + const issues = linkedIssues.map((n) => `#${n}`).join(', '); |
| 130 | + const why = linkedIssues.length |
| 131 | + ? `you aren't currently assigned to ${issues}` |
| 132 | + : "its description doesn't yet link an open issue in this repository (with `Fixes #123` or similar)"; |
| 133 | + const next = linkedIssues.length |
| 134 | + ? `If a maintainer would like this change as a PR from you, they'll assign you to ${issues} and this PR will reopen automatically — there's nothing more you need to do. (If you opened the issue, this PR already shows up on its timeline.)` |
| 135 | + : `If there isn't an issue for this yet, please [open one](https://github.com/${owner}/${repo}/issues/new/choose) — a clear description of the problem is genuinely the most useful thing for us. Then add \`Fixes #<number>\` to this PR's description. If a maintainer would like the change as a PR from you, they'll assign you to the issue and this PR will reopen automatically.`; |
| 136 | + return [ |
| 137 | + MARKER, |
| 138 | + `Thanks for the contribution. This repository only keeps pull requests open when they're linked to an issue that a maintainer has assigned to the author — [CONTRIBUTING.md](${contributingUrl}) explains why and how we work. This PR has been closed for now because ${why}.`, |
| 139 | + '', |
| 140 | + next, |
| 141 | + '', |
| 142 | + "There's no need to open a new PR — this one will be reopened. While it's closed, please push any updates as new commits rather than force-pushing, since GitHub can't reopen a PR whose branch has been rewritten.", |
| 143 | + '', |
| 144 | + `*Maintainers: reopening this PR, removing the \`${LABEL}\` label, or adding \`${BYPASS_LABEL}\` bypasses the check.*`, |
| 145 | + ].join('\n'); |
| 146 | + } |
| 147 | + |
| 148 | + function cannotReopenComment(pr, reason) { |
| 149 | + return [ |
| 150 | + MARKER, |
| 151 | + `This PR now passes the intake check (${reason}), but GitHub won't let it be reopened — usually because the branch was force-pushed or deleted while the PR was closed, or because another open PR uses the same branch.`, |
| 152 | + '', |
| 153 | + `If you have another open PR from this branch, please continue there. Otherwise, either push the branch back to \`${pr.head.sha.slice(0, 7)}\` and edit this PR's description to retry, or open a new PR with the same \`Fixes #<issue>\` line.`, |
| 154 | + ].join('\n'); |
| 155 | + } |
| 156 | + |
| 157 | + // ── Helpers ────────────────────────────────────────────────────────────── |
| 158 | + |
| 159 | + async function mutate(description, fn) { |
| 160 | + if (!enforce) { |
| 161 | + console.log(`[dry-run] would ${description}`); |
| 162 | + return undefined; |
| 163 | + } |
| 164 | + return fn(); |
| 165 | + } |
| 166 | + |
| 167 | + // Triage-or-better on this repo, from the permission endpoint's capability |
| 168 | + // flags (role names can be custom; author_association hides private org |
| 169 | + // members). Only a nonexistent user 404s; any other error must throw rather |
| 170 | + // than be read as "untrusted", or a maintainer's PR could be closed. |
| 171 | + async function isTrusted(username) { |
| 172 | + try { |
| 173 | + const { data } = await github.rest.repos.getCollaboratorPermissionLevel({ owner, repo, username }); |
| 174 | + const p = data.user?.permissions; |
| 175 | + if (!p) throw new Error(`permission response for ${username} has no capability flags`); |
| 176 | + const trusted = Boolean(p.triage || p.push || p.maintain || p.admin); |
| 177 | + console.log(` ${username}: ${trusted ? 'trusted' : 'not trusted'} (role ${data.role_name || '-'})`); |
| 178 | + return trusted; |
| 179 | + } catch (e) { |
| 180 | + if (e.status === 404) return false; |
| 181 | + throw new Error(`Permission check failed for ${username} (HTTP ${e.status ?? '?'}): ${e.message}`); |
| 182 | + } |
| 183 | + } |
| 184 | + |
| 185 | + // Issue numbers referenced with a closing keyword, in the forms GitHub itself |
| 186 | + // honors: `Fixes #1`, `closes owner/repo#1`, `Resolved https://github.com/owner/repo/issues/1`. |
| 187 | + function closingRefs(body) { |
| 188 | + const repoRef = `${owner}/${repo}`.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); |
| 189 | + const re = new RegExp( |
| 190 | + `\\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\\s*:?\\s*(?:${repoRef}#|#|https?://github\\.com/${repoRef}/issues/)(\\d+)`, |
| 191 | + 'gi', |
| 192 | + ); |
| 193 | + return [...new Set([...(body || '').matchAll(re)].map((m) => parseInt(m[1], 10)))]; |
| 194 | + } |
| 195 | + |
| 196 | + // The linked issue, or null if it doesn't exist, is actually a PR, isn't |
| 197 | + // open, or has been transferred to another repository. |
| 198 | + async function getIssue(num) { |
| 199 | + let issue; |
| 200 | + try { |
| 201 | + ({ data: issue } = await github.rest.issues.get({ owner, repo, issue_number: num })); |
| 202 | + } catch (e) { |
| 203 | + if (e.status === 404 || e.status === 410) return null; |
| 204 | + throw new Error(`Cannot fetch issue #${num} (HTTP ${e.status ?? '?'}): ${e.message}`); |
| 205 | + } |
| 206 | + if (issue.pull_request || issue.state !== 'open') return null; |
| 207 | + if (!issue.repository_url?.endsWith(`/${owner}/${repo}`)) return null; |
| 208 | + return issue; |
| 209 | + } |
| 210 | + |
| 211 | + // Reopen a gate-closed PR. GitHub refuses (422) if the branch was rewritten |
| 212 | + // or deleted while closed, or another open PR uses it. Explain that in the |
| 213 | + // comment and make sure the control label is (still) on, so the PR stays |
| 214 | + // gate-managed and a later edit or override retries the reopen. |
| 215 | + async function reopen(pr, reason) { |
| 216 | + try { |
| 217 | + await mutate(`reopen PR #${pr.number}`, () => github.rest.pulls.update({ owner, repo, pull_number: pr.number, state: 'open' })); |
| 218 | + return true; |
| 219 | + } catch (e) { |
| 220 | + if (e.status !== 422) throw e; |
| 221 | + core.warning(`GitHub refused to reopen PR #${pr.number}: ${e.message}`); |
| 222 | + await addLabel(pr.number, LABEL); |
| 223 | + await upsertGateComment(pr.number, cannotReopenComment(pr, reason)); |
| 224 | + return false; |
| 225 | + } |
| 226 | + } |
| 227 | + |
| 228 | + async function addLabel(prNumber, name) { |
| 229 | + await mutate(`add "${name}" to PR #${prNumber}`, async () => { |
| 230 | + await ensureLabelExists(name); |
| 231 | + await github.rest.issues.addLabels({ owner, repo, issue_number: prNumber, labels: [name] }); |
| 232 | + }); |
| 233 | + } |
| 234 | + |
| 235 | + async function removeLabel(prNumber, name) { |
| 236 | + await mutate(`remove "${name}" from PR #${prNumber}`, async () => { |
| 237 | + try { |
| 238 | + await github.rest.issues.removeLabel({ owner, repo, issue_number: prNumber, name }); |
| 239 | + } catch (e) { |
| 240 | + if (e.status !== 404) throw e; |
| 241 | + } |
| 242 | + }); |
| 243 | + } |
| 244 | + |
| 245 | + async function ensureLabelExists(name) { |
| 246 | + const meta = { |
| 247 | + [LABEL]: ['b76e79', 'Auto-closed: PR needs a linked issue assigned to its author (see CONTRIBUTING.md)'], |
| 248 | + [BYPASS_LABEL]: ['0e8a16', 'Maintainer override for the linked-issue intake gate'], |
| 249 | + }[name]; |
| 250 | + try { |
| 251 | + await github.rest.issues.getLabel({ owner, repo, name }); |
| 252 | + } catch (e) { |
| 253 | + if (e.status !== 404) throw e; |
| 254 | + try { |
| 255 | + await github.rest.issues.createLabel({ owner, repo, name, color: meta[0], description: meta[1] }); |
| 256 | + } catch (createErr) { |
| 257 | + if (createErr.status !== 422) throw createErr; // created concurrently |
| 258 | + } |
| 259 | + } |
| 260 | + } |
| 261 | + |
| 262 | + // The gate keeps at most one comment per PR: authored by the Actions bot and |
| 263 | + // carrying MARKER. It's created or updated on failure and deleted on pass. |
| 264 | + async function findGateComment(prNumber) { |
| 265 | + const comments = await github.paginate(github.rest.issues.listComments, { owner, repo, issue_number: prNumber, per_page: 100 }); |
| 266 | + return comments.find((c) => c.user?.login === BOT_LOGIN && c.body?.includes(MARKER)); |
| 267 | + } |
| 268 | + |
| 269 | + async function upsertGateComment(prNumber, body) { |
| 270 | + const existing = await findGateComment(prNumber); |
| 271 | + if (!existing) { |
| 272 | + await mutate(`comment on PR #${prNumber}`, () => github.rest.issues.createComment({ owner, repo, issue_number: prNumber, body })); |
| 273 | + } else if (existing.body !== body) { |
| 274 | + await mutate(`update the gate comment on PR #${prNumber}`, () => github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body })); |
| 275 | + } |
| 276 | + } |
| 277 | + |
| 278 | + async function deleteGateComment(prNumber) { |
| 279 | + const existing = await findGateComment(prNumber); |
| 280 | + if (!existing) return; |
| 281 | + await mutate(`delete the gate comment on PR #${prNumber}`, async () => { |
| 282 | + try { |
| 283 | + await github.rest.issues.deleteComment({ owner, repo, comment_id: existing.id }); |
| 284 | + } catch (e) { |
| 285 | + if (e.status !== 404) throw e; // already deleted by a concurrent run |
| 286 | + } |
| 287 | + }); |
| 288 | + } |
| 289 | +}; |
0 commit comments