Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

fix(ci): say why the run-ci label can't start PR CI (#9955)

teobfe7a3c7cf50
diff --git a/.agents/skills/run-ci/SKILL.md b/.agents/skills/run-ci/SKILL.md
index 560b919277..1d2f56f7d5 100644
--- a/.agents/skills/run-ci/SKILL.md
+++ b/.agents/skills/run-ci/SKILL.md
@@ -62,7 +62,13 @@ To read the state once, look at the `CI gate` row of `gh pr checks <pr>`:
| pass, `Passed on <sha>` | Every check passed or was path-skipped | Done |
| fail, `Failed: <jobs>` | Those called workflows failed | Open the linked run, fix, push, run again |
| fail, `The PR moved on ...` or `The merge commit did not include ...` | Labelled too soon after a push | Add the label again |
-| missing | A fork PR, before its first run | A maintainer adds the label |
+| fail, `PR CI can't start: ...` | The PR conflicts with `main`, or was last pushed before `PR CI` existed | Merge `main` in, push, add the label again |
+| missing | A fork PR before its first run, or a PR that conflicts with `main` | A maintainer adds the label; or merge `main` in and push |
+
+GitHub takes `PR CI` from the PR's merge commit with `main`, which it rebuilds
+on a push but not when `main` moves, and runs nothing on a conflicting PR. So on
+such a PR the label alone starts nothing; `CI Gate Label Check` then removes it
+and says why in `CI gate`.
## Fix a failure
diff --git a/.github/workflows/ci-gate-fork.yml b/.github/workflows/ci-gate-fork.yml
index 3c142a75a5..3d77768e42 100644
--- a/.github/workflows/ci-gate-fork.yml
+++ b/.github/workflows/ci-gate-fork.yml
@@ -35,6 +35,8 @@ jobs:
// start a requested run begins: remove the label, check the merge commit
// holds the PR head, set pending
// finish the run ends: success when every job passed or was path-skipped
+ // label the label goes on a PR: fail when it can't start PR CI, because the
+ // PR conflicts with main or its merge commit predates PR CI
// fork-request the label goes on a fork PR: what start does with a write
// token, from a trusted run of `main`'s workflow
// fork after a fork PR's run, whose read-only token could not set the status
@@ -58,6 +60,10 @@ jobs:
// the generated workflows and the Rust that generates them.
export const PR_CI_PATH = '.github/workflows/pr-ci.yml';
export const CI_SOURCES = ['.github', 'tooling/xtask/crates/xtask_workflows'] as const;
+ export const STALE_MERGE =
+ "PR CI can't start: this PR's merge commit predates PR CI. Merge main in, push, and add the run-ci label again.";
+ export const CONFLICTS =
+ "PR CI can't start: this PR conflicts with main. Merge main in, push, and add the run-ci label again.";
export const FORK_CHANGES_CI =
'fork changes CI workflows: a maintainer must review and run CI from a branch';
@@ -76,6 +82,25 @@ jobs:
return value;
}
+ /// Whether a path exists at a ref.
+ async function exists(path: string, ref: string): Promise<boolean> {
+ const response = await fetch(`${API}/repos/${repo()}/contents/${path}?ref=${ref}`, {
+ method: 'HEAD',
+ headers: {
+ accept: 'application/vnd.github+json',
+ authorization: `Bearer ${env('GH_TOKEN')}`,
+ 'x-github-api-version': '2022-11-28',
+ },
+ });
+ if (response.status === 404) {
+ return false;
+ }
+ if (!response.ok) {
+ throw new Error(`HEAD contents/${path}?ref=${ref}: HTTP ${response.status}`);
+ }
+ return true;
+ }
+
async function github(method: string, path: string, body?: unknown): Promise<any> {
const response = await fetch(`${API}${path}`, {
method,
@@ -171,6 +196,19 @@ jobs:
return null;
}
+ /// Why the label can't start PR CI, or null. GitHub runs no `pull_request`
+ /// workflow on a conflicting PR, and takes the workflow files from the PR's
+ /// merge commit, which it refreshes on a push but not when main moves on.
+ export function labelBlocker(mergeable: boolean | null, mergeHasPrCi: boolean): string | null {
+ if (mergeable === false) {
+ return CONFLICTS;
+ }
+ if (!mergeHasPrCi) {
+ return STALE_MERGE;
+ }
+ return null;
+ }
+
async function setStatus(sha: string, state: State, description: string, targetUrl: string) {
await github('POST', `/repos/${repo()}/statuses/${sha}`, {
state,
@@ -236,6 +274,32 @@ jobs:
await github('DELETE', `/repos/${repo()}/issues/${pr}/labels/${encodeURIComponent(label())}`);
}
+ /// Why a label on the PR can't start PR CI, from GitHub's view of it now.
+ /// GitHub computes mergeability in the background, so wait briefly for it.
+ async function labelProblem(pr: string): Promise<string | null> {
+ let pull = await github('GET', `/repos/${repo()}/pulls/${pr}`);
+ for (let attempt = 0; pull.mergeable === null && attempt < 6; attempt++) {
+ await new Promise((resolve) => setTimeout(resolve, 5_000));
+ pull = await github('GET', `/repos/${repo()}/pulls/${pr}`);
+ }
+ const merge: string | null = pull.merge_commit_sha;
+ const hasPrCi = merge !== null && (await exists(PR_CI_PATH, merge));
+ return labelBlocker(pull.mergeable, hasPrCi);
+ }
+
+ async function labelCheck() {
+ const head = env('HEAD_SHA');
+ const pr = env('PR_NUMBER');
+ const problem = await labelProblem(pr);
+ if (!problem) {
+ console.log(`#${pr}'s merge commit holds ${PR_CI_PATH}; PR CI takes it from here.`);
+ return;
+ }
+ // The label stays otherwise, and adding it again must fire a new event.
+ await removeLabel(pr);
+ await setStatus(head, 'failure', problem, env('CI_GATE_DOCS_URL'));
+ }
+
async function remind() {
const head = env('HEAD_SHA');
const pr = env('PR_NUMBER');
@@ -318,6 +382,12 @@ jobs:
await removeLabel(pr);
+ const problem = await labelProblem(pr);
+ if (problem) {
+ await setStatus(head, 'failure', problem, env('CI_GATE_DOCS_URL'));
+ return;
+ }
+
// The run the label starts would use the fork's own workflow files.
if ((await forkCiChanges(env('BASE_REF'), head)).length > 0) {
await setStatus(head, 'failure', FORK_CHANGES_CI, env('PR_CHECKS_URL'));
@@ -369,6 +439,7 @@ jobs:
export async function main() {
const modes: Record<string, () => Promise<void>> = {
remind,
+ label: labelCheck,
start,
finish,
'fork-request': forkRequest,
@@ -392,6 +463,7 @@ jobs:
PR_NUMBER: ${{ github.event.pull_request.number }}
HEAD_SHA: ${{ github.event.pull_request.head.sha }}
BASE_REF: ${{ github.event.pull_request.base.ref }}
+ CI_GATE_DOCS_URL: https://github.com/macro-inc/macro/blob/main/.agents/skills/run-ci/SKILL.md
PR_CHECKS_URL: ${{ github.event.pull_request.html_url }}/checks
report:
if: github.event_name == 'workflow_run' && github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.head_repository.full_name != github.repository
@@ -414,6 +486,8 @@ jobs:
// start a requested run begins: remove the label, check the merge commit
// holds the PR head, set pending
// finish the run ends: success when every job passed or was path-skipped
+ // label the label goes on a PR: fail when it can't start PR CI, because the
+ // PR conflicts with main or its merge commit predates PR CI
// fork-request the label goes on a fork PR: what start does with a write
// token, from a trusted run of `main`'s workflow
// fork after a fork PR's run, whose read-only token could not set the status
@@ -437,6 +511,10 @@ jobs:
// the generated workflows and the Rust that generates them.
export const PR_CI_PATH = '.github/workflows/pr-ci.yml';
export const CI_SOURCES = ['.github', 'tooling/xtask/crates/xtask_workflows'] as const;
+ export const STALE_MERGE =
+ "PR CI can't start: this PR's merge commit predates PR CI. Merge main in, push, and add the run-ci label again.";
+ export const CONFLICTS =
+ "PR CI can't start: this PR conflicts with main. Merge main in, push, and add the run-ci label again.";
export const FORK_CHANGES_CI =
'fork changes CI workflows: a maintainer must review and run CI from a branch';
@@ -455,6 +533,25 @@ jobs:
return value;
}
+ /// Whether a path exists at a ref.
+ async function exists(path: string, ref: string): Promise<boolean> {
+ const response = await fetch(`${API}/repos/${repo()}/contents/${path}?ref=${ref}`, {
+ method: 'HEAD',
+ headers: {
+ accept: 'application/vnd.github+json',
+ authorization: `Bearer ${env('GH_TOKEN')}`,
+ 'x-github-api-version': '2022-11-28',
+ },
+ });
+ if (response.status === 404) {
+ return false;
+ }
+ if (!response.ok) {
+ throw new Error(`HEAD contents/${path}?ref=${ref}: HTTP ${response.status}`);
+ }
+ return true;
+ }
+
async function github(method: string, path: string, body?: unknown): Promise<any> {
const response = await fetch(`${API}${path}`, {
method,
@@ -550,6 +647,19 @@ jobs:
return null;
}
+ /// Why the label can't start PR CI, or null. GitHub runs no `pull_request`
+ /// workflow on a conflicting PR, and takes the workflow files from the PR's
+ /// merge commit, which it refreshes on a push but not when main moves on.
+ export function labelBlocker(mergeable: boolean | null, mergeHasPrCi: boolean): string | null {
+ if (mergeable === false) {
+ return CONFLICTS;
+ }
+ if (!mergeHasPrCi) {
+ return STALE_MERGE;
+ }
+ return null;
+ }
+
async function setStatus(sha: string, state: State, description: string, targetUrl: string) {
await github('POST', `/repos/${repo()}/statuses/${sha}`, {
state,
@@ -615,6 +725,32 @@ jobs:
await github('DELETE', `/repos/${repo()}/issues/${pr}/labels/${encodeURIComponent(label())}`);
}
+ /// Why a label on the PR can't start PR CI, from GitHub's view of it now.
+ /// GitHub computes mergeability in the background, so wait briefly for it.
+ async function labelProblem(pr: string): Promise<string | null> {
+ let pull = await github('GET', `/repos/${repo()}/pulls/${pr}`);
+ for (let attempt = 0; pull.mergeable === null && attempt < 6; attempt++) {
+ await new Promise((resolve) => setTimeout(resolve, 5_000));
+ pull = await github('GET', `/repos/${repo()}/pulls/${pr}`);
+ }
+ const merge: string | null = pull.merge_commit_sha;
+ const hasPrCi = merge !== null && (await exists(PR_CI_PATH, merge));
+ return labelBlocker(pull.mergeable, hasPrCi);
+ }
+
+ async function labelCheck() {
+ const head = env('HEAD_SHA');
+ const pr = env('PR_NUMBER');
+ const problem = await labelProblem(pr);
+ if (!problem) {
+ console.log(`#${pr}'s merge commit holds ${PR_CI_PATH}; PR CI takes it from here.`);
+ return;
+ }
+ // The label stays otherwise, and adding it again must fire a new event.
+ await removeLabel(pr);
+ await setStatus(head, 'failure', problem, env('CI_GATE_DOCS_URL'));
+ }
+
async function remind() {
const head = env('HEAD_SHA');
const pr = env('PR_NUMBER');
@@ -697,6 +833,12 @@ jobs:
await removeLabel(pr);
+ const problem = await labelProblem(pr);
+ if (problem) {
+ await setStatus(head, 'failure', problem, env('CI_GATE_DOCS_URL'));
+ return;
+ }
+
// The run the label starts would use the fork's own workflow files.
if ((await forkCiChanges(env('BASE_REF'), head)).length > 0) {
await setStatus(head, 'failure', FORK_CHANGES_CI, env('PR_CHECKS_URL'));
@@ -748,6 +890,7 @@ jobs:
export async function main() {
const modes: Record<string, () => Promise<void>> = {
remind,
+ label: labelCheck,
start,
finish,
'fork-request': forkRequest,
diff --git a/.github/workflows/ci-gate-label.yml b/.github/workflows/ci-gate-label.yml
new file mode 100644
index 0000000000..36d351beb7
--- /dev/null
+++ b/.github/workflows/ci-gate-label.yml
@@ -0,0 +1,460 @@
+# DO NOT EDIT — regenerate with `cargo x workflows` (from the repository root).
+# Source: tooling/xtask/crates/xtask_workflows/src/workflows/ci_gate_label.rs
+name: CI Gate Label Check
+'on':
+ pull_request_target:
+ types:
+ - labeled
+ branches:
+ - main
+jobs:
+ check:
+ if: github.event.label.name == 'run-ci' && github.event.pull_request.head.repo.full_name == github.repository
+ name: Check the label can start PR CI
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ issues: write
+ pull-requests: write
+ statuses: write
+ timeout-minutes: 5
+ steps:
+ - name: Check the merge commit holds PR CI
+ run: |
+ node --disable-warning=ExperimentalWarning --input-type=module-typescript <<'NODE_SCRIPT'
+ // Sets the commit status `main` requires before a merge: it is green only on a
+ // commit that a requested `PR CI` run passed. `CI_GATE_MODE` picks the step:
+ //
+ // remind a new commit: pending "not run" with the command to run it, unless
+ // the commit already has a gate status
+ // start a requested run begins: remove the label, check the merge commit
+ // holds the PR head, set pending
+ // finish the run ends: success when every job passed or was path-skipped
+ // label the label goes on a PR: fail when it can't start PR CI, because the
+ // PR conflicts with main or its merge commit predates PR CI
+ // fork-request the label goes on a fork PR: what start does with a write
+ // token, from a trusted run of `main`'s workflow
+ // fork after a fork PR's run, whose read-only token could not set the status
+ //
+ // Statuses go on the PR head commit, so a later push starts without one.
+ //
+ // A fork PR's run uses the workflow files of its merge commit, so a fork that
+ // edits them decides its own verdict. Both fork steps fail closed instead: the
+ // fork's CI sources must be the trees it branched from (`ciSourceChanges`).
+
+ import { readFileSync } from 'node:fs';
+
+ const API = 'https://api.github.com';
+ const DESCRIPTION_LIMIT = 140;
+ // An open request. Only trusted runs set statuses: a fork's token can't.
+ const RUNNING = 'Running on';
+ // Job names in `PR CI`; the fork step reads them back from the finished run.
+ export const START_JOB = 'Start';
+ export const GATE_JOB = 'CI gate';
+ // The workflow whose jobs the fork step trusts, and the trees that define it:
+ // the generated workflows and the Rust that generates them.
+ export const PR_CI_PATH = '.github/workflows/pr-ci.yml';
+ export const CI_SOURCES = ['.github', 'tooling/xtask/crates/xtask_workflows'] as const;
+ export const STALE_MERGE =
+ "PR CI can't start: this PR's merge commit predates PR CI. Merge main in, push, and add the run-ci label again.";
+ export const CONFLICTS =
+ "PR CI can't start: this PR conflicts with main. Merge main in, push, and add the run-ci label again.";
+ export const FORK_CHANGES_CI =
+ 'fork changes CI workflows: a maintainer must review and run CI from a branch';
+
+ type State = 'pending' | 'success' | 'failure' | 'error';
+ export type Needs = Record<string, { result: string }>;
+ export type RunJob = { name: string; conclusion: string | null };
+ type Outcome = { state: State; description: string } | null;
+ /// Git tree SHA of each CI source at a commit; null where the path is missing.
+ export type CiTrees = Record<string, string | null>;
+
+ function env(name: string): string {
+ const value = process.env[name];
+ if (!value) {
+ throw new Error(`${name} is not set`);
+ }
+ return value;
+ }
+
+ /// Whether a path exists at a ref.
+ async function exists(path: string, ref: string): Promise<boolean> {
+ const response = await fetch(`${API}/repos/${repo()}/contents/${path}?ref=${ref}`, {
+ method: 'HEAD',
+ headers: {
+ accept: 'application/vnd.github+json',
+ authorization: `Bearer ${env('GH_TOKEN')}`,
+ 'x-github-api-version': '2022-11-28',
+ },
+ });
+ if (response.status === 404) {
+ return false;
+ }
+ if (!response.ok) {
+ throw new Error(`HEAD contents/${path}?ref=${ref}: HTTP ${response.status}`);
+ }
+ return true;
+ }
+
+ async function github(method: string, path: string, body?: unknown): Promise<any> {
+ const response = await fetch(`${API}${path}`, {
+ method,
+ headers: {
+ accept: 'application/vnd.github+json',
+ authorization: `Bearer ${env('GH_TOKEN')}`,
+ 'x-github-api-version': '2022-11-28',
+ },
+ body: body === undefined ? undefined : JSON.stringify(body),
+ });
+ // Removing a label that is already gone is the outcome we wanted.
+ if (method === 'DELETE' && response.status === 404) {
+ return null;
+ }
+ if (!response.ok) {
+ throw new Error(`${method} ${path}: HTTP ${response.status} ${await response.text()}`);
+ }
+ return response.status === 204 ? null : response.json();
+ }
+
+ const repo = () => env('GITHUB_REPOSITORY');
+ const context = () => env('CI_GATE_CONTEXT');
+ const label = () => env('CI_GATE_LABEL');
+
+ /// REST, because `gh pr edit` fails on older gh releases.
+ export function runCommand(repository: string, pr: string, labelName: string): string {
+ return `gh api repos/${repository}/issues/${pr}/labels -f "labels[]=${labelName}"`;
+ }
+
+ /// The finished run's verdict from `toJSON(needs)`. Start must have succeeded;
+ /// a called workflow may be skipped, because its path filter did not match.
+ /// Null when start failed: it already set a status that says why.
+ export function gateOutcome(needs: Needs, head: string): Outcome {
+ if (needs.start?.result !== 'success') {
+ return null;
+ }
+
+ const failed = Object.entries(needs)
+ .filter(([, need]) => need.result !== 'success' && need.result !== 'skipped')
+ .map(([job]) => job);
+
+ if (failed.length > 0) {
+ return { state: 'failure', description: `Failed: ${failed.join(', ')}` };
+ }
+
+ return { state: 'success', description: `Passed on ${head.slice(0, 7)}` };
+ }
+
+ /// A fork run's verdict from its jobs. Null when the run was not a request
+ /// (unrelated label) or did not finish (cancelled).
+ export function forkOutcome(jobs: RunJob[], head: string, labelName: string): Outcome {
+ const start = jobs.find((job) => job.name === START_JOB);
+ const gate = jobs.find((job) => job.name === GATE_JOB);
+
+ if (!start || start.conclusion === 'skipped' || start.conclusion === 'cancelled') {
+ return null;
+ }
+
+ if (start.conclusion !== 'success') {
+ return {
+ state: 'failure',
+ description: `Could not start on ${head.slice(0, 7)}. Add the ${labelName} label again.`,
+ };
+ }
+
+ if (gate?.conclusion === 'success') {
+ return { state: 'success', description: `Passed on ${head.slice(0, 7)}` };
+ }
+
+ if (gate?.conclusion === 'failure') {
+ return { state: 'failure', description: 'Failed: see the PR CI run' };
+ }
+
+ return null;
+ }
+
+ /// The CI sources whose tree differs between a fork head and the commit it
+ /// branched from. A source missing from either side counts as changed.
+ export function ciSourceChanges(head: CiTrees, base: CiTrees): string[] {
+ return CI_SOURCES.filter((path) => !head[path] || !base[path] || head[path] !== base[path]);
+ }
+
+ /// Why a finished fork run can't be trusted, or null. The workflow is matched
+ /// by name, so a fork can add another file named `PR CI`; and even `pr-ci.yml`
+ /// is the fork's copy unless the CI sources are unchanged.
+ export function forkRunDistrust(runPath: string, changes: string[]): string | null {
+ if (changes.length > 0) {
+ return FORK_CHANGES_CI;
+ }
+ if (runPath !== PR_CI_PATH) {
+ return `The run came from ${runPath}, not ${PR_CI_PATH}`;
+ }
+ return null;
+ }
+
+ /// Why the label can't start PR CI, or null. GitHub runs no `pull_request`
+ /// workflow on a conflicting PR, and takes the workflow files from the PR's
+ /// merge commit, which it refreshes on a push but not when main moves on.
+ export function labelBlocker(mergeable: boolean | null, mergeHasPrCi: boolean): string | null {
+ if (mergeable === false) {
+ return CONFLICTS;
+ }
+ if (!mergeHasPrCi) {
+ return STALE_MERGE;
+ }
+ return null;
+ }
+
+ async function setStatus(sha: string, state: State, description: string, targetUrl: string) {
+ await github('POST', `/repos/${repo()}/statuses/${sha}`, {
+ state,
+ context: context(),
+ description: description.slice(0, DESCRIPTION_LIMIT),
+ target_url: targetUrl,
+ });
+ console.log(`${context()} on ${sha.slice(0, 10)}: ${state}: ${description}`);
+ }
+
+ /// The newest gate status on a commit (GitHub lists statuses newest first).
+ async function gateStatus(sha: string): Promise<{ state: string; description: string } | undefined> {
+ const statuses: { context: string; state: string; description: string | null }[] = await github(
+ 'GET',
+ `/repos/${repo()}/commits/${sha}/statuses?per_page=100`,
+ );
+ const status = statuses.find((each) => each.context === context());
+ return status && { state: status.state, description: status.description ?? '' };
+ }
+
+ /// Whether a trusted step opened a request on this commit that no result has
+ /// closed yet.
+ export function isOpenRequest(status: { state: string; description: string } | undefined): boolean {
+ return status?.state === 'pending' && status.description.startsWith(RUNNING);
+ }
+
+ /// The tree SHA at `path` in a commit, walking one directory at a time.
+ async function treeAt(commit: string, path: string): Promise<string | null> {
+ let tree: string = (await github('GET', `/repos/${repo()}/git/commits/${commit}`)).tree.sha;
+ for (const part of path.split('/')) {
+ const { tree: entries }: { tree: { path: string; type: string; sha: string }[] } = await github(
+ 'GET',
+ `/repos/${repo()}/git/trees/${tree}`,
+ );
+ const entry = entries.find((each) => each.path === part && each.type === 'tree');
+ if (!entry) {
+ return null;
+ }
+ tree = entry.sha;
+ }
+ return tree;
+ }
+
+ async function ciTrees(commit: string): Promise<CiTrees> {
+ const trees: CiTrees = {};
+ for (const path of CI_SOURCES) {
+ trees[path] = await treeAt(commit, path);
+ }
+ return trees;
+ }
+
+ /// The CI sources a fork head changed since it branched from `base`.
+ async function forkCiChanges(base: string, head: string): Promise<string[]> {
+ const compare = await github('GET', `/repos/${repo()}/compare/${base}...${head}`);
+ const changes = ciSourceChanges(await ciTrees(head), await ciTrees(compare.merge_base_commit.sha));
+ if (changes.length > 0) {
+ console.log(`${head.slice(0, 10)} changes ${changes.join(', ')}`);
+ }
+ return changes;
+ }
+
+ async function removeLabel(pr: string) {
+ await github('DELETE', `/repos/${repo()}/issues/${pr}/labels/${encodeURIComponent(label())}`);
+ }
+
+ /// Why a label on the PR can't start PR CI, from GitHub's view of it now.
+ /// GitHub computes mergeability in the background, so wait briefly for it.
+ async function labelProblem(pr: string): Promise<string | null> {
+ let pull = await github('GET', `/repos/${repo()}/pulls/${pr}`);
+ for (let attempt = 0; pull.mergeable === null && attempt < 6; attempt++) {
+ await new Promise((resolve) => setTimeout(resolve, 5_000));
+ pull = await github('GET', `/repos/${repo()}/pulls/${pr}`);
+ }
+ const merge: string | null = pull.merge_commit_sha;
+ const hasPrCi = merge !== null && (await exists(PR_CI_PATH, merge));
+ return labelBlocker(pull.mergeable, hasPrCi);
+ }
+
+ async function labelCheck() {
+ const head = env('HEAD_SHA');
+ const pr = env('PR_NUMBER');
+ const problem = await labelProblem(pr);
+ if (!problem) {
+ console.log(`#${pr}'s merge commit holds ${PR_CI_PATH}; PR CI takes it from here.`);
+ return;
+ }
+ // The label stays otherwise, and adding it again must fire a new event.
+ await removeLabel(pr);
+ await setStatus(head, 'failure', problem, env('CI_GATE_DOCS_URL'));
+ }
+
+ async function remind() {
+ const head = env('HEAD_SHA');
+ const pr = env('PR_NUMBER');
+
+ // A re-open or leaving draft keeps the head, so it may have a result already.
+ if (await gateStatus(head)) {
+ console.log(`${head.slice(0, 10)} already has a ${context()} status`);
+ return;
+ }
+
+ await setStatus(
+ head,
+ 'pending',
+ `Not run on this commit. Run: ${runCommand(repo(), pr, label())}`,
+ env('CI_GATE_DOCS_URL'),
+ );
+ }
+
+ async function start() {
+ const head = env('HEAD_SHA');
+ const pr = env('PR_NUMBER');
+ const runUrl = env('RUN_URL');
+ const sameRepo = env('SAME_REPO') === 'true';
+
+ // Fork tokens are read-only; the fork request step did both already.
+ if (sameRepo) {
+ await removeLabel(pr);
+ }
+
+ // A label added right after a push can carry the previous head, or a merge
+ // commit GitHub has not rebuilt yet. Either would test an old commit.
+ const pull = await github('GET', `/repos/${repo()}/pulls/${pr}`);
+ if (pull.head.sha !== head) {
+ const description = `The PR moved on from ${head.slice(0, 7)} to ${pull.head.sha.slice(0, 7)}. Run again: ${runCommand(repo(), pr, label())}`;
+ if (sameRepo) {
+ await setStatus(head, 'failure', description, runUrl);
+ }
+ throw new Error(description);
+ }
+
+ const merge = await github('GET', `/repos/${repo()}/commits/${env('MERGE_SHA')}`);
+ const parents: string[] = merge.parents.map((parent: { sha: string }) => parent.sha);
+
+ if (!parents.includes(head)) {
+ const description = `The merge commit did not include ${head.slice(0, 7)} yet. Run again: ${runCommand(repo(), pr, label())}`;
+ if (sameRepo) {
+ await setStatus(head, 'failure', description, runUrl);
+ }
+ throw new Error(description);
+ }
+
+ if (sameRepo) {
+ await setStatus(head, 'pending', `${RUNNING} ${head.slice(0, 7)}`, runUrl);
+ }
+ }
+
+ async function finish() {
+ const head = env('HEAD_SHA');
+ const outcome = gateOutcome(JSON.parse(env('NEEDS')), head);
+
+ if (!outcome) {
+ console.log('Start did not succeed; its status stands.');
+ process.exitCode = 1;
+ return;
+ }
+
+ if (env('SAME_REPO') === 'true') {
+ await setStatus(head, outcome.state, outcome.description, env('RUN_URL'));
+ }
+
+ if (outcome.state !== 'success') {
+ console.log(outcome.description);
+ process.exitCode = 1;
+ }
+ }
+
+ async function forkRequest() {
+ const head = env('HEAD_SHA');
+ const pr = env('PR_NUMBER');
+
+ await removeLabel(pr);
+
+ const problem = await labelProblem(pr);
+ if (problem) {
+ await setStatus(head, 'failure', problem, env('CI_GATE_DOCS_URL'));
+ return;
+ }
+
+ // The run the label starts would use the fork's own workflow files.
+ if ((await forkCiChanges(env('BASE_REF'), head)).length > 0) {
+ await setStatus(head, 'failure', FORK_CHANGES_CI, env('PR_CHECKS_URL'));
+ return;
+ }
+
+ await setStatus(head, 'pending', `${RUNNING} ${head.slice(0, 7)}`, env('PR_CHECKS_URL'));
+ }
+
+ async function fork() {
+ const event = JSON.parse(readFileSync(env('GITHUB_EVENT_PATH'), 'utf8'));
+ const run = event.workflow_run;
+ const head: string = run.head_sha;
+
+ // The request step opened this on the head the label was added at. A run on
+ // any other commit, such as one the fork pushed with a rewritten workflow,
+ // or a run after the result is in, finds no open request.
+ if (!isOpenRequest(await gateStatus(head))) {
+ console.log(`${head.slice(0, 10)} has no open ${context()} request; nothing to report.`);
+ return;
+ }
+
+ // Checked again here, from the run itself: the request step's view could be
+ // stale, and the run's path is only known now.
+ const distrust = forkRunDistrust(run.path, await forkCiChanges(env('BASE_REF'), head));
+ if (distrust) {
+ await setStatus(head, 'failure', distrust, run.html_url);
+ return;
+ }
+
+ const jobs: RunJob[] = [];
+ for (let page = 1; ; page++) {
+ const { jobs: batch } = await github(
+ 'GET',
+ `/repos/${repo()}/actions/runs/${run.id}/attempts/${run.run_attempt}/jobs?per_page=100&page=${page}`,
+ );
+ jobs.push(...batch);
+ if (batch.length < 100) {
+ break;
+ }
+ }
+
+ const outcome = forkOutcome(jobs, head, label());
+ if (outcome) {
+ await setStatus(head, outcome.state, outcome.description, run.html_url);
+ }
+ }
+
+ export async function main() {
+ const modes: Record<string, () => Promise<void>> = {
+ remind,
+ label: labelCheck,
+ start,
+ finish,
+ 'fork-request': forkRequest,
+ fork,
+ };
+ const mode = modes[env('CI_GATE_MODE')];
+ if (!mode) {
+ throw new Error(`unknown CI_GATE_MODE ${process.env.CI_GATE_MODE}`);
+ }
+ await mode();
+ }
+
+ await main();
+ NODE_SCRIPT
+ shell: bash
+ env:
+ CI_GATE_MODE: label
+ CI_GATE_CONTEXT: CI gate
+ CI_GATE_LABEL: run-ci
+ GH_TOKEN: ${{ github.token }}
+ PR_NUMBER: ${{ github.event.pull_request.number }}
+ HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+ CI_GATE_DOCS_URL: https://github.com/macro-inc/macro/blob/main/.agents/skills/run-ci/SKILL.md
diff --git a/.github/workflows/ci-gate-reminder.yml b/.github/workflows/ci-gate-reminder.yml
index 26877a0493..b5e6bcdfb5 100644
--- a/.github/workflows/ci-gate-reminder.yml
+++ b/.github/workflows/ci-gate-reminder.yml
@@ -29,6 +29,8 @@ jobs:
// start a requested run begins: remove the label, check the merge commit
// holds the PR head, set pending
// finish the run ends: success when every job passed or was path-skipped
+ // label the label goes on a PR: fail when it can't start PR CI, because the
+ // PR conflicts with main or its merge commit predates PR CI
// fork-request the label goes on a fork PR: what start does with a write
// token, from a trusted run of `main`'s workflow
// fork after a fork PR's run, whose read-only token could not set the status
@@ -52,6 +54,10 @@ jobs:
// the generated workflows and the Rust that generates them.
export const PR_CI_PATH = '.github/workflows/pr-ci.yml';
export const CI_SOURCES = ['.github', 'tooling/xtask/crates/xtask_workflows'] as const;
+ export const STALE_MERGE =
+ "PR CI can't start: this PR's merge commit predates PR CI. Merge main in, push, and add the run-ci label again.";
+ export const CONFLICTS =
+ "PR CI can't start: this PR conflicts with main. Merge main in, push, and add the run-ci label again.";
export const FORK_CHANGES_CI =
'fork changes CI workflows: a maintainer must review and run CI from a branch';
@@ -70,6 +76,25 @@ jobs:
return value;
}
+ /// Whether a path exists at a ref.
+ async function exists(path: string, ref: string): Promise<boolean> {
+ const response = await fetch(`${API}/repos/${repo()}/contents/${path}?ref=${ref}`, {
+ method: 'HEAD',
+ headers: {
+ accept: 'application/vnd.github+json',
+ authorization: `Bearer ${env('GH_TOKEN')}`,
+ 'x-github-api-version': '2022-11-28',
+ },
+ });
+ if (response.status === 404) {
+ return false;
+ }
+ if (!response.ok) {
+ throw new Error(`HEAD contents/${path}?ref=${ref}: HTTP ${response.status}`);
+ }
+ return true;
+ }
+
async function github(method: string, path: string, body?: unknown): Promise<any> {
const response = await fetch(`${API}${path}`, {
method,
@@ -165,6 +190,19 @@ jobs:
return null;
}
+ /// Why the label can't start PR CI, or null. GitHub runs no `pull_request`
+ /// workflow on a conflicting PR, and takes the workflow files from the PR's
+ /// merge commit, which it refreshes on a push but not when main moves on.
+ export function labelBlocker(mergeable: boolean | null, mergeHasPrCi: boolean): string | null {
+ if (mergeable === false) {
+ return CONFLICTS;
+ }
+ if (!mergeHasPrCi) {
+ return STALE_MERGE;
+ }
+ return null;
+ }
+
async function setStatus(sha: string, state: State, description: string, targetUrl: string) {
await github('POST', `/repos/${repo()}/statuses/${sha}`, {
state,
@@ -230,6 +268,32 @@ jobs:
await github('DELETE', `/repos/${repo()}/issues/${pr}/labels/${encodeURIComponent(label())}`);
}
+ /// Why a label on the PR can't start PR CI, from GitHub's view of it now.
+ /// GitHub computes mergeability in the background, so wait briefly for it.
+ async function labelProblem(pr: string): Promise<string | null> {
+ let pull = await github('GET', `/repos/${repo()}/pulls/${pr}`);
+ for (let attempt = 0; pull.mergeable === null && attempt < 6; attempt++) {
+ await new Promise((resolve) => setTimeout(resolve, 5_000));
+ pull = await github('GET', `/repos/${repo()}/pulls/${pr}`);
+ }
+ const merge: string | null = pull.merge_commit_sha;
+ const hasPrCi = merge !== null && (await exists(PR_CI_PATH, merge));
+ return labelBlocker(pull.mergeable, hasPrCi);
+ }
+
+ async function labelCheck() {
+ const head = env('HEAD_SHA');
+ const pr = env('PR_NUMBER');
+ const problem = await labelProblem(pr);
+ if (!problem) {
+ console.log(`#${pr}'s merge commit holds ${PR_CI_PATH}; PR CI takes it from here.`);
+ return;
+ }
+ // The label stays otherwise, and adding it again must fire a new event.
+ await removeLabel(pr);
+ await setStatus(head, 'failure', problem, env('CI_GATE_DOCS_URL'));
+ }
+
async function remind() {
const head = env('HEAD_SHA');
const pr = env('PR_NUMBER');
@@ -312,6 +376,12 @@ jobs:
await removeLabel(pr);
+ const problem = await labelProblem(pr);
+ if (problem) {
+ await setStatus(head, 'failure', problem, env('CI_GATE_DOCS_URL'));
+ return;
+ }
+
// The run the label starts would use the fork's own workflow files.
if ((await forkCiChanges(env('BASE_REF'), head)).length > 0) {
await setStatus(head, 'failure', FORK_CHANGES_CI, env('PR_CHECKS_URL'));
@@ -363,6 +433,7 @@ jobs:
export async function main() {
const modes: Record<string, () => Promise<void>> = {
remind,
+ label: labelCheck,
start,
finish,
'fork-request': forkRequest,
diff --git a/.github/workflows/export-ci-telemetry.yml b/.github/workflows/export-ci-telemetry.yml
index 7de9291028..deb83c59c8 100644
--- a/.github/workflows/export-ci-telemetry.yml
+++ b/.github/workflows/export-ci-telemetry.yml
@@ -18,6 +18,7 @@ name: Export CI telemetry
- Build macOS DMG
- CI Gate Reminder
- CI Gate for Forks
+ - CI Gate Label Check
- CLA
- Cancel Stuck Cloud Storage Deploys
- Cleanup Preview
diff --git a/.github/workflows/pr-ci.yml b/.github/workflows/pr-ci.yml
index de19166951..240054fe71 100644
--- a/.github/workflows/pr-ci.yml
+++ b/.github/workflows/pr-ci.yml
@@ -38,6 +38,8 @@ jobs:
// start a requested run begins: remove the label, check the merge commit
// holds the PR head, set pending
// finish the run ends: success when every job passed or was path-skipped
+ // label the label goes on a PR: fail when it can't start PR CI, because the
+ // PR conflicts with main or its merge commit predates PR CI
// fork-request the label goes on a fork PR: what start does with a write
// token, from a trusted run of `main`'s workflow
// fork after a fork PR's run, whose read-only token could not set the status
@@ -61,6 +63,10 @@ jobs:
// the generated workflows and the Rust that generates them.
export const PR_CI_PATH = '.github/workflows/pr-ci.yml';
export const CI_SOURCES = ['.github', 'tooling/xtask/crates/xtask_workflows'] as const;
+ export const STALE_MERGE =
+ "PR CI can't start: this PR's merge commit predates PR CI. Merge main in, push, and add the run-ci label again.";
+ export const CONFLICTS =
+ "PR CI can't start: this PR conflicts with main. Merge main in, push, and add the run-ci label again.";
export const FORK_CHANGES_CI =
'fork changes CI workflows: a maintainer must review and run CI from a branch';
@@ -79,6 +85,25 @@ jobs:
return value;
}
+ /// Whether a path exists at a ref.
+ async function exists(path: string, ref: string): Promise<boolean> {
+ const response = await fetch(`${API}/repos/${repo()}/contents/${path}?ref=${ref}`, {
+ method: 'HEAD',
+ headers: {
+ accept: 'application/vnd.github+json',
+ authorization: `Bearer ${env('GH_TOKEN')}`,
+ 'x-github-api-version': '2022-11-28',
+ },
+ });
+ if (response.status === 404) {
+ return false;
+ }
+ if (!response.ok) {
+ throw new Error(`HEAD contents/${path}?ref=${ref}: HTTP ${response.status}`);
+ }
+ return true;
+ }
+
async function github(method: string, path: string, body?: unknown): Promise<any> {
const response = await fetch(`${API}${path}`, {
method,
@@ -174,6 +199,19 @@ jobs:
return null;
}
+ /// Why the label can't start PR CI, or null. GitHub runs no `pull_request`
+ /// workflow on a conflicting PR, and takes the workflow files from the PR's
+ /// merge commit, which it refreshes on a push but not when main moves on.
+ export function labelBlocker(mergeable: boolean | null, mergeHasPrCi: boolean): string | null {
+ if (mergeable === false) {
+ return CONFLICTS;
+ }
+ if (!mergeHasPrCi) {
+ return STALE_MERGE;
+ }
+ return null;
+ }
+
async function setStatus(sha: string, state: State, description: string, targetUrl: string) {
await github('POST', `/repos/${repo()}/statuses/${sha}`, {
state,
@@ -239,6 +277,32 @@ jobs:
await github('DELETE', `/repos/${repo()}/issues/${pr}/labels/${encodeURIComponent(label())}`);
}
+ /// Why a label on the PR can't start PR CI, from GitHub's view of it now.
+ /// GitHub computes mergeability in the background, so wait briefly for it.
+ async function labelProblem(pr: string): Promise<string | null> {
+ let pull = await github('GET', `/repos/${repo()}/pulls/${pr}`);
+ for (let attempt = 0; pull.mergeable === null && attempt < 6; attempt++) {
+ await new Promise((resolve) => setTimeout(resolve, 5_000));
+ pull = await github('GET', `/repos/${repo()}/pulls/${pr}`);
+ }
+ const merge: string | null = pull.merge_commit_sha;
+ const hasPrCi = merge !== null && (await exists(PR_CI_PATH, merge));
+ return labelBlocker(pull.mergeable, hasPrCi);
+ }
+
+ async function labelCheck() {
+ const head = env('HEAD_SHA');
+ const pr = env('PR_NUMBER');
+ const problem = await labelProblem(pr);
+ if (!problem) {
+ console.log(`#${pr}'s merge commit holds ${PR_CI_PATH}; PR CI takes it from here.`);
+ return;
+ }
+ // The label stays otherwise, and adding it again must fire a new event.
+ await removeLabel(pr);
+ await setStatus(head, 'failure', problem, env('CI_GATE_DOCS_URL'));
+ }
+
async function remind() {
const head = env('HEAD_SHA');
const pr = env('PR_NUMBER');
@@ -321,6 +385,12 @@ jobs:
await removeLabel(pr);
+ const problem = await labelProblem(pr);
+ if (problem) {
+ await setStatus(head, 'failure', problem, env('CI_GATE_DOCS_URL'));
+ return;
+ }
+
// The run the label starts would use the fork's own workflow files.
if ((await forkCiChanges(env('BASE_REF'), head)).length > 0) {
await setStatus(head, 'failure', FORK_CHANGES_CI, env('PR_CHECKS_URL'));
@@ -372,6 +442,7 @@ jobs:
export async function main() {
const modes: Record<string, () => Promise<void>> = {
remind,
+ label: labelCheck,
start,
finish,
'fork-request': forkRequest,
@@ -561,6 +632,8 @@ jobs:
// start a requested run begins: remove the label, check the merge commit
// holds the PR head, set pending
// finish the run ends: success when every job passed or was path-skipped
+ // label the label goes on a PR: fail when it can't start PR CI, because the
+ // PR conflicts with main or its merge commit predates PR CI
// fork-request the label goes on a fork PR: what start does with a write
// token, from a trusted run of `main`'s workflow
// fork after a fork PR's run, whose read-only token could not set the status
@@ -584,6 +657,10 @@ jobs:
// the generated workflows and the Rust that generates them.
export const PR_CI_PATH = '.github/workflows/pr-ci.yml';
export const CI_SOURCES = ['.github', 'tooling/xtask/crates/xtask_workflows'] as const;
+ export const STALE_MERGE =
+ "PR CI can't start: this PR's merge commit predates PR CI. Merge main in, push, and add the run-ci label again.";
+ export const CONFLICTS =
+ "PR CI can't start: this PR conflicts with main. Merge main in, push, and add the run-ci label again.";
export const FORK_CHANGES_CI =
'fork changes CI workflows: a maintainer must review and run CI from a branch';
@@ -602,6 +679,25 @@ jobs:
return value;
}
+ /// Whether a path exists at a ref.
+ async function exists(path: string, ref: string): Promise<boolean> {
+ const response = await fetch(`${API}/repos/${repo()}/contents/${path}?ref=${ref}`, {
+ method: 'HEAD',
+ headers: {
+ accept: 'application/vnd.github+json',
+ authorization: `Bearer ${env('GH_TOKEN')}`,
+ 'x-github-api-version': '2022-11-28',
+ },
+ });
+ if (response.status === 404) {
+ return false;
+ }
+ if (!response.ok) {
+ throw new Error(`HEAD contents/${path}?ref=${ref}: HTTP ${response.status}`);
+ }
+ return true;
+ }
+
async function github(method: string, path: string, body?: unknown): Promise<any> {
const response = await fetch(`${API}${path}`, {
method,
@@ -697,6 +793,19 @@ jobs:
return null;
}
+ /// Why the label can't start PR CI, or null. GitHub runs no `pull_request`
+ /// workflow on a conflicting PR, and takes the workflow files from the PR's
+ /// merge commit, which it refreshes on a push but not when main moves on.
+ export function labelBlocker(mergeable: boolean | null, mergeHasPrCi: boolean): string | null {
+ if (mergeable === false) {
+ return CONFLICTS;
+ }
+ if (!mergeHasPrCi) {
+ return STALE_MERGE;
+ }
+ return null;
+ }
+
async function setStatus(sha: string, state: State, description: string, targetUrl: string) {
await github('POST', `/repos/${repo()}/statuses/${sha}`, {
state,
@@ -762,6 +871,32 @@ jobs:
await github('DELETE', `/repos/${repo()}/issues/${pr}/labels/${encodeURIComponent(label())}`);
}
+ /// Why a label on the PR can't start PR CI, from GitHub's view of it now.
+ /// GitHub computes mergeability in the background, so wait briefly for it.
+ async function labelProblem(pr: string): Promise<string | null> {
+ let pull = await github('GET', `/repos/${repo()}/pulls/${pr}`);
+ for (let attempt = 0; pull.mergeable === null && attempt < 6; attempt++) {
+ await new Promise((resolve) => setTimeout(resolve, 5_000));
+ pull = await github('GET', `/repos/${repo()}/pulls/${pr}`);
+ }
+ const merge: string | null = pull.merge_commit_sha;
+ const hasPrCi = merge !== null && (await exists(PR_CI_PATH, merge));
+ return labelBlocker(pull.mergeable, hasPrCi);
+ }
+
+ async function labelCheck() {
+ const head = env('HEAD_SHA');
+ const pr = env('PR_NUMBER');
+ const problem = await labelProblem(pr);
+ if (!problem) {
+ console.log(`#${pr}'s merge commit holds ${PR_CI_PATH}; PR CI takes it from here.`);
+ return;
+ }
+ // The label stays otherwise, and adding it again must fire a new event.
+ await removeLabel(pr);
+ await setStatus(head, 'failure', problem, env('CI_GATE_DOCS_URL'));
+ }
+
async function remind() {
const head = env('HEAD_SHA');
const pr = env('PR_NUMBER');
@@ -844,6 +979,12 @@ jobs:
await removeLabel(pr);
+ const problem = await labelProblem(pr);
+ if (problem) {
+ await setStatus(head, 'failure', problem, env('CI_GATE_DOCS_URL'));
+ return;
+ }
+
// The run the label starts would use the fork's own workflow files.
if ((await forkCiChanges(env('BASE_REF'), head)).length > 0) {
await setStatus(head, 'failure', FORK_CHANGES_CI, env('PR_CHECKS_URL'));
@@ -895,6 +1036,7 @@ jobs:
export async function main() {
const modes: Record<string, () => Promise<void>> = {
remind,
+ label: labelCheck,
start,
finish,
'fork-request': forkRequest,
diff --git a/docs/development/ci.md b/docs/development/ci.md
index 46d61cc78f..d0d39e56b2 100644
--- a/docs/development/ci.md
+++ b/docs/development/ci.md
@@ -10,6 +10,10 @@ Run CI deliberately: at a checkpoint, a coherent locally tested chunk you want
real CI on before building further, or when you think the PR is done. Never
after every push, and never instead of local checks.
+If the label starts nothing and `CI gate` says `PR CI can't start`, the PR
+conflicts with `main` or was last pushed before `PR CI` existed: merge `main`
+in, push, and add the label again.
+
The [`run-ci` skill](../../.agents/skills/run-ci/SKILL.md) has the commands,
what each `CI gate` state means, re-runs, and fork PRs. The workflows are
generated from Rust; see the
diff --git a/tooling/xtask/crates/xtask_workflows/src/workflows.rs b/tooling/xtask/crates/xtask_workflows/src/workflows.rs
index 89e31b8f5e..671cac4eac 100644
--- a/tooling/xtask/crates/xtask_workflows/src/workflows.rs
+++ b/tooling/xtask/crates/xtask_workflows/src/workflows.rs
@@ -28,6 +28,7 @@ mod check_generated;
mod check_node_modules_nix;
mod check_tauri_lockfiles;
mod ci_gate_fork;
+mod ci_gate_label;
mod ci_gate_reminder;
mod cla;
mod cleanup_preview;
@@ -308,6 +309,11 @@ const WORKFLOWS: &[WorkflowFile] = &[
file_name: "ci-gate-reminder.yml",
render_yaml: || render_gh_workflow(ci_gate_reminder::ci_gate_reminder)(),
},
+ WorkflowFile {
+ slug: "ci_gate_label",
+ file_name: "ci-gate-label.yml",
+ render_yaml: || render_gh_workflow(ci_gate_label::ci_gate_label)(),
+ },
WorkflowFile {
slug: "ci_gate_fork",
file_name: "ci-gate-fork.yml",
diff --git a/tooling/xtask/crates/xtask_workflows/src/workflows/ci_gate_fork.rs b/tooling/xtask/crates/xtask_workflows/src/workflows/ci_gate_fork.rs
index f0491f683f..97b0cc376a 100644
--- a/tooling/xtask/crates/xtask_workflows/src/workflows/ci_gate_fork.rs
+++ b/tooling/xtask/crates/xtask_workflows/src/workflows/ci_gate_fork.rs
@@ -61,6 +61,7 @@ fn request() -> Job {
.add_env(("PR_NUMBER", "${{ github.event.pull_request.number }}"))
.add_env(("HEAD_SHA", "${{ github.event.pull_request.head.sha }}"))
.add_env(("BASE_REF", "${{ github.event.pull_request.base.ref }}"))
+ .add_env(("CI_GATE_DOCS_URL", pr_ci::GATE_DOCS_URL))
.add_env((
"PR_CHECKS_URL",
"${{ github.event.pull_request.html_url }}/checks",
diff --git a/tooling/xtask/crates/xtask_workflows/src/workflows/ci_gate_label.rs b/tooling/xtask/crates/xtask_workflows/src/workflows/ci_gate_label.rs
new file mode 100644
index 0000000000..642477153e
--- /dev/null
+++ b/tooling/xtask/crates/xtask_workflows/src/workflows/ci_gate_label.rs
@@ -0,0 +1,53 @@
+//! `CI Gate Label Check` — when the `run-ci` label goes on a PR, checks that it
+//! can start [`pr_ci`](crate::workflows::pr_ci), and says why not in `CI gate`.
+//! Generated into `ci-gate-label.yml`.
+//!
+//! `pull_request` runs take their workflow files from the PR's merge commit with
+//! `main`. GitHub refreshes that commit on a push, not when `main` moves, and
+//! makes none while the PR conflicts. So the label on a PR last pushed before
+//! `PR CI` existed, or on a conflicting one, starts nothing. This workflow uses
+//! `pull_request_target`, which runs `main`'s copy whatever the merge commit
+//! holds, and checks out nothing.
+
+use gh_workflow::{
+ Event, Expression, Job, Level, Permissions, PullRequestTarget, PullRequestType, Workflow,
+};
+
+use crate::workflows::pr_ci;
+
+/// Build the workflow.
+pub fn ci_gate_label() -> Workflow {
+ Workflow::new("CI Gate Label Check")
+ .on(Event::default().pull_request_target(
+ PullRequestTarget::default()
+ .add_branch("main")
+ .add_type(PullRequestType::Labeled),
+ ))
+ .add_job("check", check())
+}
+
+/// Fork PRs get the same check in `CI Gate for Forks`, before it opens their
+/// request.
+fn check() -> Job {
+ Job::default()
+ .name("Check the label can start PR CI")
+ .cond(Expression::new(format!(
+ "github.event.label.name == '{}' && github.event.pull_request.head.repo.full_name == github.repository",
+ pr_ci::RUN_LABEL
+ )))
+ .runs_on("ubuntu-latest")
+ .timeout_minutes(5u32)
+ .permissions(Permissions {
+ contents: Some(Level::Read),
+ issues: Some(Level::Write),
+ pull_requests: Some(Level::Write),
+ statuses: Some(Level::Write),
+ ..Default::default()
+ })
+ .add_step(
+ pr_ci::gate_step("Check the merge commit holds PR CI", "label")
+ .add_env(("PR_NUMBER", "${{ github.event.pull_request.number }}"))
+ .add_env(("HEAD_SHA", "${{ github.event.pull_request.head.sha }}"))
+ .add_env(("CI_GATE_DOCS_URL", pr_ci::GATE_DOCS_URL)),
+ )
+}
diff --git a/tooling/xtask/crates/xtask_workflows/src/workflows/export_ci_telemetry.rs b/tooling/xtask/crates/xtask_workflows/src/workflows/export_ci_telemetry.rs
index 3184a6c8d3..8eb97514df 100644
--- a/tooling/xtask/crates/xtask_workflows/src/workflows/export_ci_telemetry.rs
+++ b/tooling/xtask/crates/xtask_workflows/src/workflows/export_ci_telemetry.rs
@@ -25,6 +25,7 @@ const OBSERVED_WORKFLOWS: &[&str] = &[
"Build macOS DMG",
"CI Gate Reminder",
"CI Gate for Forks",
+ "CI Gate Label Check",
"CLA",
"Cancel Stuck Cloud Storage Deploys",
"Cleanup Preview",
diff --git a/tooling/xtask/crates/xtask_workflows/src/workflows/scripts/ci_gate.test.ts b/tooling/xtask/crates/xtask_workflows/src/workflows/scripts/ci_gate.test.ts
index b55e816782..caedcdd224 100644
--- a/tooling/xtask/crates/xtask_workflows/src/workflows/scripts/ci_gate.test.ts
+++ b/tooling/xtask/crates/xtask_workflows/src/workflows/scripts/ci_gate.test.ts
@@ -4,6 +4,9 @@ import assert from 'node:assert/strict';
import { describe, test } from 'node:test';
import {
ciSourceChanges,
+ CONFLICTS,
+ labelBlocker,
+ STALE_MERGE,
FORK_CHANGES_CI,
forkOutcome,
forkRunDistrust,
@@ -183,3 +186,24 @@ describe('forkRunDistrust', () => {
);
});
});
+
+describe('labelBlocker', () => {
+ test('a mergeable PR whose merge commit holds PR CI can start it', () => {
+ assert.equal(labelBlocker(true, true), null);
+ assert.equal(labelBlocker(null, true), null);
+ });
+
+ test('a conflicting PR runs no pull_request workflow', () => {
+ assert.equal(labelBlocker(false, false), CONFLICTS);
+ });
+
+ test('a merge commit from before PR CI, or none, starts nothing', () => {
+ assert.equal(labelBlocker(true, false), STALE_MERGE);
+ assert.equal(labelBlocker(null, false), STALE_MERGE);
+ });
+
+ test('both explanations fit a commit status', () => {
+ assert.ok(STALE_MERGE.length <= 140);
+ assert.ok(CONFLICTS.length <= 140);
+ });
+});
diff --git a/tooling/xtask/crates/xtask_workflows/src/workflows/scripts/ci_gate.ts b/tooling/xtask/crates/xtask_workflows/src/workflows/scripts/ci_gate.ts
index 8ffddb7488..9e6672ea74 100644
--- a/tooling/xtask/crates/xtask_workflows/src/workflows/scripts/ci_gate.ts
+++ b/tooling/xtask/crates/xtask_workflows/src/workflows/scripts/ci_gate.ts
@@ -6,6 +6,8 @@
// start a requested run begins: remove the label, check the merge commit
// holds the PR head, set pending
// finish the run ends: success when every job passed or was path-skipped
+// label the label goes on a PR: fail when it can't start PR CI, because the
+// PR conflicts with main or its merge commit predates PR CI
// fork-request the label goes on a fork PR: what start does with a write
// token, from a trusted run of `main`'s workflow
// fork after a fork PR's run, whose read-only token could not set the status
@@ -29,6 +31,10 @@ export const GATE_JOB = 'CI gate';
// the generated workflows and the Rust that generates them.
export const PR_CI_PATH = '.github/workflows/pr-ci.yml';
export const CI_SOURCES = ['.github', 'tooling/xtask/crates/xtask_workflows'] as const;
+export const STALE_MERGE =
+ "PR CI can't start: this PR's merge commit predates PR CI. Merge main in, push, and add the run-ci label again.";
+export const CONFLICTS =
+ "PR CI can't start: this PR conflicts with main. Merge main in, push, and add the run-ci label again.";
export const FORK_CHANGES_CI =
'fork changes CI workflows: a maintainer must review and run CI from a branch';
@@ -47,6 +53,25 @@ function env(name: string): string {
return value;
}
+/// Whether a path exists at a ref.
+async function exists(path: string, ref: string): Promise<boolean> {
+ const response = await fetch(`${API}/repos/${repo()}/contents/${path}?ref=${ref}`, {
+ method: 'HEAD',
+ headers: {
+ accept: 'application/vnd.github+json',
+ authorization: `Bearer ${env('GH_TOKEN')}`,
+ 'x-github-api-version': '2022-11-28',
+ },
+ });
+ if (response.status === 404) {
+ return false;
+ }
+ if (!response.ok) {
+ throw new Error(`HEAD contents/${path}?ref=${ref}: HTTP ${response.status}`);
+ }
+ return true;
+}
+
async function github(method: string, path: string, body?: unknown): Promise<any> {
const response = await fetch(`${API}${path}`, {
method,
@@ -142,6 +167,19 @@ export function forkRunDistrust(runPath: string, changes: string[]): string | nu
return null;
}
+/// Why the label can't start PR CI, or null. GitHub runs no `pull_request`
+/// workflow on a conflicting PR, and takes the workflow files from the PR's
+/// merge commit, which it refreshes on a push but not when main moves on.
+export function labelBlocker(mergeable: boolean | null, mergeHasPrCi: boolean): string | null {
+ if (mergeable === false) {
+ return CONFLICTS;
+ }
+ if (!mergeHasPrCi) {
+ return STALE_MERGE;
+ }
+ return null;
+}
+
async function setStatus(sha: string, state: State, description: string, targetUrl: string) {
await github('POST', `/repos/${repo()}/statuses/${sha}`, {
state,
@@ -207,6 +245,32 @@ async function removeLabel(pr: string) {
await github('DELETE', `/repos/${repo()}/issues/${pr}/labels/${encodeURIComponent(label())}`);
}
+/// Why a label on the PR can't start PR CI, from GitHub's view of it now.
+/// GitHub computes mergeability in the background, so wait briefly for it.
+async function labelProblem(pr: string): Promise<string | null> {
+ let pull = await github('GET', `/repos/${repo()}/pulls/${pr}`);
+ for (let attempt = 0; pull.mergeable === null && attempt < 6; attempt++) {
+ await new Promise((resolve) => setTimeout(resolve, 5_000));
+ pull = await github('GET', `/repos/${repo()}/pulls/${pr}`);
+ }
+ const merge: string | null = pull.merge_commit_sha;
+ const hasPrCi = merge !== null && (await exists(PR_CI_PATH, merge));
+ return labelBlocker(pull.mergeable, hasPrCi);
+}
+
+async function labelCheck() {
+ const head = env('HEAD_SHA');
+ const pr = env('PR_NUMBER');
+ const problem = await labelProblem(pr);
+ if (!problem) {
+ console.log(`#${pr}'s merge commit holds ${PR_CI_PATH}; PR CI takes it from here.`);
+ return;
+ }
+ // The label stays otherwise, and adding it again must fire a new event.
+ await removeLabel(pr);
+ await setStatus(head, 'failure', problem, env('CI_GATE_DOCS_URL'));
+}
+
async function remind() {
const head = env('HEAD_SHA');
const pr = env('PR_NUMBER');
@@ -289,6 +353,12 @@ async function forkRequest() {
await removeLabel(pr);
+ const problem = await labelProblem(pr);
+ if (problem) {
+ await setStatus(head, 'failure', problem, env('CI_GATE_DOCS_URL'));
+ return;
+ }
+
// The run the label starts would use the fork's own workflow files.
if ((await forkCiChanges(env('BASE_REF'), head)).length > 0) {
await setStatus(head, 'failure', FORK_CHANGES_CI, env('PR_CHECKS_URL'));
@@ -340,6 +410,7 @@ async function fork() {
export async function main() {
const modes: Record<string, () => Promise<void>> = {
remind,
+ label: labelCheck,
start,
finish,
'fork-request': forkRequest,