Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 23 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -417,12 +417,14 @@ CI results are read for the current head. The first required check to fail
prints `checks:failed` right away. `checks:passed` prints once nothing on the
head is still going (no pending check and no unfinished GitHub Actions run, which
may still create jobs), every check and workflow the base branch names is
present (except `quest land`'s, which no head carries), and every required
present (except `quest land`'s, which no head carries), each required check
from the app its requirement names, if any, and every required
check passed; it names the last required check that passed and is dated when
the head went idle. Each prints once per head, with the check's name
(spaces as `_`) in the actor field and its details URL. Results count as
`quest status` counts them, so neutral and skipped results pass and a rerun
supersedes an earlier run of the same check. Each job of a
`quest status` counts them, so neutral and skipped results pass, a rerun
supersedes an earlier run of the same check from the same workflow, and a cancelled check a newer run
of its workflow replaced is dropped. Each job of a
workflow a ruleset requires is required.
Requiredness comes from the base branch's protection and rulesets, readable
with read access. A failed optional check prints separately as `check:failed`,
Expand Down Expand Up @@ -501,8 +503,8 @@ comes last, and a missing value prints as `-`:
| `auto-merge` | Method, who enabled it, when, and the head it was enabled on. |
| `merge-queue` | Queue state, position, and when it was enqueued. |
| `landing-stopped` | The reason the latest merge-queue entry, auto-merge, or [`quest land`](#land-a-batch-with-quest-land) queue entry ended (such as `merge_conflict`, `failed_checks`, `manual`, `manually_disabled`, or `merged`), who ended it, and when; `-` once the PR has entered the merge queue or auto-merge again since. |
| `checks` | `failure` if any check fails, else `pending` if any is pending, else `success`, and `passed=`, `failing=`, `pending=` counts, all from each check's latest run; `-` when the head has no checks. |
| `check` | `failing` or `pending`, `required` or `optional`, the result, details URL, and name. |
| `checks` | `failure` if any check fails, else `pending` if any is pending or a requirement is unreported, else `success`, and `passed=`, `failing=`, `pending=` counts, all from the checks that count; `-` when the head has no checks and the base requires none. |
| `check` | `failing` or `pending`, `required` or `optional`, the result, details URL, and name. A required check or required workflow nothing reports yet prints as `pending required expected -` with its name, followed by `(from app <id>)` when the requirement names an app, or the workflow's repository and path, as `owner/name:path`. |
| `review` | `current` or `stale` against the head, state, reviewer, time, and URL of each reviewer's latest review. |
| `checkpoint` | Each bot reviewer that approves or requests changes, such as one whose approval the base requires, its round, and its review's URL, when that review is of the head and its latest verdict there, ignoring plain comments, is neither an approval nor a dismissal, at the end of its third, sixth, ... round: [`/quest-review`'s design checkpoint](#review-locally) for an online reviewer. A round is one commit it reviewed; a dismissed review counts as one that approves or requests changes. Only printed when due. |
| `reacted:<content>` | Actor, time, and the PR or review reacted to, as `quest wait` names reactions. |
Expand All @@ -514,9 +516,19 @@ The node ID is what GraphQL's `addPullRequestReviewThreadReply` and
`resolveReviewThread` take. Neutral and skipped checks pass. Only each check's
latest run counts, as for GitHub's mergeability: a rerun, or the same workflow
run again on the head, supersedes an earlier run of that name from the same
app, and a newer commit status supersedes an older one of its context. GitHub's
own rollup state counts the superseded runs too. A required check
is one branch protection or a ruleset requires for this PR. `--json` prints the
app and workflow file, and a newer commit status supersedes an older one of its context. A check
that reported `cancelled` also stops counting once a newer GitHub Actions run of
its workflow exists on the head, from any event, as when `cancel-in-progress`
cancels a run whose jobs, such as a matrix job under its unexpanded name, the
newer run never reports; a rerun counts as newer than every run that started
before it. Any other result keeps counting, as does a cancelled run nothing
replaced. Only then does it read the head's workflow runs, which needs Actions
read access. GitHub's own rollup state counts the superseded runs too. A required
check is one branch protection or a ruleset requires for this PR, or a job of a
workflow a ruleset requires. Like `quest wait`, it reads an open PR's
requirements from the base, matches a required check by name and, when the
requirement names one, its app, as GitHub and `quest land` do, and leaves out
`quest land`'s check, which no head carries. `--json` prints the
same facts as one object with the fields `url`, `state`, `draft`, `head`,
`mergeable`, `mergeState`, `reviewDecision`, `autoMerge`, `mergeQueue`,
`landingStopped`, `checks` (`state`, `passed`, `failing`, `pending`), `reviews`, `checkpoints` (`reviewer`, `round`, `url`), `reactions`,
Expand Down Expand Up @@ -561,8 +573,8 @@ are not told apart.
`quest merge` takes no label: the head-pinned auto-merge or merge-queue entry
it creates is the queue signal, so a queued PR shows no hold. It refuses while
any session holds the PR, so release your own hold first. `--land` needs the full 40-character
head SHA and refuses once the head moves, or while the latest run of any
check on it failed, required or not, naming each; pending checks do not block.
head SHA and refuses once the head moves, or while any check on it that
counts in `quest status` failed, required or not, naming each; pending checks do not block.
It also refuses a head that fails `quest check --no-stubs --base <base> --branch
<head branch>`, which it runs on git objects it fetches, so nothing from the
head runs, and ignores findings the base already has; run a `quest` the PR
Expand Down Expand Up @@ -758,8 +770,7 @@ down to one PR, and each batch that lands grows it back by one; the order and
size persist in the state directory. Conflicting
additions stay queued. A PR whose required checks are still running, or that
still needs an approving review the base requires, stays queued and sits out
batches until they pass and it is approved; only each check's latest run counts,
as in `quest status`. If it still waits two hours after
batches until they pass and it is approved; checks count as in `quest status`. If it still waits two hours after
its pick (twice the default `--timeout`), the daemon comments once on that pick,
naming what it waits for, since a check that never reports or an approval nobody
gives would hold it silently. The sandbox checks the tip once, without
Expand Down
11 changes: 11 additions & 0 deletions quest/m0/gate-required-workflows.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# [S] Gate counts required workflows

## Goal

The gate's check matching (`checks()` in `src/cli/land.ts`) counts the base's required workflows (ruleset `workflows` rules) the same way `quest status` and `quest wait` do, so the gate never lands a head whose required workflow never ran or has not passed.

## Plan

- Settled on [moq-dev/quest#674](https://github.com/moq-dev/quest/pull/674): keep this as its own quest in m0, since it is the same disagreement between readers that #674 fixes for status and wait.
- Reuse the shared `requiredOf` and `unreported` from `src/cli/status.ts`: a job in a required workflow counts as required, and a required workflow path nothing reports keeps the PR waiting rather than landing.
- Test the gate with a base whose ruleset requires a workflow that has not run on the head.
59 changes: 0 additions & 59 deletions quest/m0/superseded-runs.md

This file was deleted.

72 changes: 67 additions & 5 deletions src/cli/github.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
// The GitHub client shared by the commands that talk to GitHub, outside the repository-independent core.
import { execFileSync } from "node:child_process";
import { setTimeout as sleep } from "node:timers/promises";
import { cancelled, currentContexts, latestContexts, type RollupContext, type WorkflowRun } from "../github/checks";
import { git } from "./git";

const API = "https://api.github.com";
Expand Down Expand Up @@ -505,7 +506,7 @@ export interface RequiredCheck {
/** What a base branch requires, read from branch protection and rulesets. */
export interface Requirements {
checks: RequiredCheck[];
/** Workflow files that must pass as a whole, so each of their jobs is required. */
/** Workflow files that must pass as a whole, so each of their jobs is required, from {@link workflowKey}. */
workflows: string[];
/** Every rule the branch's active rulesets apply: `type`, `parameters`, and the ruleset's source. */
rules: ObjectValue[];
Expand All @@ -530,6 +531,32 @@ async function branchRules(github: GitHub, path: string): Promise<ObjectValue[]>
);
}

/**
* A workflow file as requirements name it: its repository's `owner/name` and its path, since a ruleset may
* require a workflow from another repository at the same path as a local one.
*/
export function workflowKey(repository: string, path: string): string {
return `${repository.toLowerCase()}:${path}`;
}

/** The workflow files `rules` require, each keyed by {@link workflowKey} from its rule's `repository_id`. */
async function requiredWorkflows(github: GitHub, rules: ObjectValue[]): Promise<string[]> {
const names = new Map<number, string>();
const keys: string[] = [];
for (const row of rules
.filter((rule) => rule.type === "workflows")
.flatMap((rule) => array(object(rule.parameters).workflows))) {
const id = Number(row.repository_id);
if (!names.has(id)) {
const response = await github.request(`/repositories/${id}`, { allow: [404] });
// A repository the token cannot see is still required; nothing on the head can match its name.
names.set(id, response.ok ? string(object(await response.json()).full_name) : `repository ${id}`);
}
keys.push(workflowKey(names.get(id)!, string(row.path)));
}
return [...new Set(keys)];
}

/** What `branch` of `repository` requires, read with read access from branch protection and rulesets. */
export async function requirements(github: GitHub, repository: Repository, branch: string): Promise<Requirements> {
const base = `/repos/${encodeURIComponent(repository.owner)}/${encodeURIComponent(repository.repo)}`;
Expand Down Expand Up @@ -560,16 +587,51 @@ export async function requirements(github: GitHub, repository: Repository, branc
(check, index) =>
checks.findIndex((other) => other.name === check.name && other.app === check.app) === index,
),
workflows: rules
.filter((rule) => rule.type === "workflows")
.flatMap((rule) => array(object(rule.parameters).workflows))
.map((row) => string(row.path)),
workflows: await requiredWorkflows(github, rules),
rules,
// Unknown counts as on, so a reader that needs the settings reads them rather than assume none.
classic: protection.enabled !== false,
};
}

/** Every GitHub Actions workflow run on `head`. Reading them needs Actions read access. */
export async function workflowRuns(github: GitHub, repository: Repository, head: string): Promise<WorkflowRun[]> {
const runs: WorkflowRun[] = [];
let path: string | undefined =
`/repos/${encodeURIComponent(repository.owner)}/${encodeURIComponent(repository.repo)}/actions/runs?head_sha=${head}&per_page=100`;
while (path) {
const response: Response = await github.request(path);
for (const row of array(object(await response.json()).workflow_runs))
runs.push({
...row,
id: Number(row.id),
workflow_id: Number(row.workflow_id),
check_suite_id: Number(row.check_suite_id),
// A run not yet started, such as one awaiting approval, has no start time, so its creation stands in.
run_started_at: string(row.run_started_at ?? row.created_at),
});
path = link(response, "next");
}
return runs;
}

/**
* Each check's latest report on `head` that still counts, as {@link currentContexts} judges it, and the
* head's workflow runs when they were read: only when a latest report is a cancelled check run, the only
* report they can drop.
*/
export async function currentChecks<T extends RollupContext>(
github: GitHub,
repository: Repository,
head: string,
contexts: T[],
): Promise<{ checks: T[]; runs?: WorkflowRun[] }> {
const latest = latestContexts(contexts);
if (!latest.some(cancelled)) return { checks: latest };
const runs = await workflowRuns(github, repository, head);
return { checks: currentContexts(contexts, runs), runs };
}

/**
* Whether a merged PR in `repository` had `commit` as its head or below it, as when `quest land` merged
* the base into the head before squashing; false for a commit GitHub does not have.
Expand Down
6 changes: 3 additions & 3 deletions src/cli/hold.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import { cleanAutoMergeRefusal, immediateMerge, queueHead } from "../github/merg
import { repositoryPath } from "./claims";
import {
array,
currentChecks,
GitHub,
type GitHubDependencies,
GitHubGraphQLError,
Expand All @@ -16,7 +17,6 @@ import {
requirements,
string,
} from "./github";
import { latestContexts } from "../github/checks";
import { ALLOWS, LAND_CHECK, METHOD_NAMES, contexts, enqueue } from "./land";
import { QUEUE_CHECK } from "./land-queue";
import type { LandingCheck } from "./landed";
Expand Down Expand Up @@ -345,12 +345,12 @@ export async function land(pr: PullRequest, request: LandRequest, deps: GitHubDe
}

/**
* Refuse a head on which any check's latest run failed, required or not, naming each: landing it
* Refuse a head on which any current check failed, required or not, naming each: landing it
* would spend a queue build on a known failure. Pending and absent checks do not block, nor does the
* own queue's informational check, which reports how a past pick ended rather than the head.
*/
async function passing(github: GitHub, pr: PullRequest, url: string, sha: string): Promise<void> {
const failing = latestContexts(await contexts(github, pr, sha))
const failing = (await currentChecks(github, pr, sha, await contexts(github, pr, sha))).checks
.filter((context) => context.name !== QUEUE_CHECK)
.map(classifyCheck)
.filter(({ outcome }) => outcome === "failing")
Expand Down
Loading
Loading