src/github/dispatch.ts

Functions

Imports

It imports src/env.ts, src/github/client.ts. Imported by src/github.ts.

Source

1import type { RepoEnv as Env } from "../env";
2import { assertRepoArg, resolveRepo, getDefaultBranch, ghFetch } from "./client";
3
4// ci_dispatch (src/github/actions.ts reads CI): fire a workflow or rerun failed jobs,
5// then poll for the run it started.
6
7// Fire a workflow_dispatch. workflow_dispatch runs the workflow file as it exists at
8// `ref`, so a caller that passes no override dispatches against the default branch.
9//
10// `refOverride` exists for ci_dispatch, where a human asking for a branch means that
11// branch.
12async function dispatchWorkflow(
13  env: Env,
14  namespace: string,
15  workflowFile: string,
16  inputs: Record<string, string>,
17  repoSelector?: string,
18  refOverride?: string
19): Promise<{ repo: string; workflow: string; ref: string; inputs: Record<string, string> }> {
20  assertRepoArg("workflow", workflowFile);
21  if (refOverride) assertRepoArg("ref", refOverride);
22  const { owner, repo, full } = await resolveRepo(env, namespace, repoSelector);
23  const ref = refOverride ?? (await getDefaultBranch(env, owner, repo));
24  const resp = await ghFetch(
25    env,
26    owner,
27    repo,
28    `/repos/${owner}/${repo}/actions/workflows/${encodeURIComponent(workflowFile)}/dispatches`,
29    {
30      method: "POST",
31      headers: { "Content-Type": "application/json" },
32      body: JSON.stringify({ ref, inputs }),
33    }
34  );
35  // 204 is the success code here, and there is no body to read on either path.
36  if (!resp.ok) {
37    throw new Error(
38      `workflow dispatch failed for ${full} ${workflowFile} (${resp.status}): ${(await resp.text()).slice(0, 300) || "no response body"}`
39    );
40  }
41  return { repo: full, workflow: workflowFile, ref, inputs };
42}
43
44// What CI is doing on one branch. Read by the tick so a timeout can name WHICH
45// failure it was: the workflow never started, it is still running, or it finished
46// and the report never arrived. Those three have different fixes.
47//
48// `id` and `head_sha` are for ci_dispatch: workflow_dispatch replies 204 with no
49// body, so naming the run it started means looking for one that did not exist before.
50async function workflowRunsForBranch(
51  env: Env,
52  namespace: string,
53  branch: string,
54  repoSelector?: string
55): Promise<
56  Array<{
57    id: number;
58    head_sha: string;
59    name: string;
60    status: string;
61    conclusion: string | null;
62    created_at: string;
63    updated_at: string;
64    url: string;
65  }>
66> {
67  const { owner, repo } = await resolveRepo(env, namespace, repoSelector);
68  const resp = await ghFetch(
69    env,
70    owner,
71    repo,
72    `/repos/${owner}/${repo}/actions/runs?branch=${encodeURIComponent(branch)}&per_page=5`
73  );
74  if (!resp.ok) throw new Error(`workflow run lookup failed (${resp.status}): ${(await resp.text()).slice(0, 200)}`);
75  const data = (await resp.json()) as {
76    workflow_runs: Array<{
77      id: number;
78      head_sha: string;
79      name: string;
80      status: string;
81      conclusion: string | null;
82      created_at: string;
83      updated_at: string;
84      html_url: string;
85    }>;
86  };
87  return data.workflow_runs.map((r) => ({
88    id: r.id,
89    head_sha: r.head_sha,
90    name: r.name,
91    status: r.status,
92    conclusion: r.conclusion,
93    created_at: r.created_at,
94    updated_at: r.updated_at,
95    url: r.html_url,
96  }));
97}
98
99export const CI_DISPATCH_POLL_MS = 30_000;
100export const CI_DISPATCH_POLL_INTERVAL_MS = 3_000;
101
102// A workflow is a YAML file in .github/workflows. GitHub's dispatch endpoint also
103// accepts a numeric id or a full path; this tool takes the file name only.
104function refuseUnnamedWorkflow(workflow: string): void {
105  const basename = workflow.split("/").pop() ?? "";
106  if (!/^[A-Za-z0-9._-]+\.ya?ml$/.test(basename)) {
107    throw new Error(`ci_dispatch refuses: '${workflow}' is not a workflow file name. Pass the file name (for example ci.yml).`);
108  }
109}
110
111async function rerunFailedJobs(env: Env, target: { owner: string; repo: string; full: string }, runId: number) {
112  const { owner, repo, full } = target;
113  const resp = await ghFetch(env, owner, repo, `/repos/${owner}/${repo}/actions/runs/${runId}/rerun-failed-jobs`, {
114    method: "POST",
115  });
116  if (!resp.ok) {
117    throw new Error(
118      `ci_dispatch rerun failed for run ${runId} (${resp.status}): ${(await resp.text()).slice(0, 300) || "no response body"}`
119    );
120  }
121  return { repo: full, mode: "rerun" as const, run_id: runId, rerun_requested: true };
122}
123
124// Dispatches the workflow on ref and polls until a new run for that ref appears or
125// the timeout passes.
126async function dispatchAndPoll(
127  env: Env,
128  namespace: string,
129  full: string,
130  args: { workflow: string; ref: string; inputs?: Record<string, string> },
131  repoSelector: string | undefined,
132  timing: { timeoutMs: number; intervalMs: number }
133) {
134  const { timeoutMs, intervalMs } = timing;
135  // The runs that already exist for this ref, so the new one can be told apart. The
136  // dispatch endpoint answers 204 with no body and names nothing it started.
137  const before = new Set((await workflowRunsForBranch(env, namespace, args.ref, repoSelector)).map((r) => r.id));
138
139  try {
140    await dispatchWorkflow(env, namespace, args.workflow, args.inputs ?? {}, repoSelector, args.ref);
141  } catch (err) {
142    const message = err instanceof Error ? err.message : String(err);
143    // GitHub answers 422 naming workflow_dispatch when the workflow file has no such
144    // trigger. Saying so beats an opaque 422 the caller has to read the YAML for.
145    if (/workflow_dispatch/i.test(message)) {
146      throw new Error(
147        `ci_dispatch refuses: ${args.workflow} has no workflow_dispatch trigger on ${full}, so it cannot be started by hand. Add "on: workflow_dispatch:" to that workflow, or trigger it the way it is configured. GitHub said: ${message.slice(0, 200)}`
148      );
149    }
150    throw err;
151  }
152
153  // POLL, because 204 means accepted, not started. A caller with no run id has
154  // nothing to watch, which is what this tool returns one for.
155  const deadline = Date.now() + timeoutMs;
156  let appeared: Awaited<ReturnType<typeof workflowRunsForBranch>>[number] | undefined;
157  let polls = 0;
158  while (Date.now() < deadline) {
159    await new Promise((resolve) => setTimeout(resolve, intervalMs));
160    polls += 1;
161    appeared = (await workflowRunsForBranch(env, namespace, args.ref, repoSelector)).find((r) => !before.has(r.id));
162    if (appeared) break;
163  }
164
165  if (!appeared) {
166    return {
167      repo: full,
168      mode: "dispatch" as const,
169      workflow: args.workflow,
170      ref: args.ref,
171      dispatched: true,
172      run_id: null,
173      polls,
174      note: `dispatch was accepted, but no new run appeared for ${args.ref} within ${timeoutMs / 1000}s. It may still start; check capsid_inspect_repo action ci with this ref. A dispatch that is accepted and never runs usually means the workflow's own conditions excluded it.`,
175    };
176  }
177  return {
178    repo: full,
179    mode: "dispatch" as const,
180    workflow: args.workflow,
181    ref: args.ref,
182    dispatched: true,
183    run_id: appeared.id,
184    status: appeared.status,
185    url: appeared.url,
186    polls,
187  };
188}
189
190/** Trigger a workflow_dispatch, or rerun a run's failed jobs. dispatchWorkflow is
191 *  the only dispatch path. */
192export async function ciDispatch(
193  env: Env,
194  namespace: string,
195  args: { workflow?: string; ref?: string; run_id?: number; inputs?: Record<string, string> },
196  repoSelector?: string,
197  // Injectable for tests only; the tool never passes it, so production uses the
198  // constants above. Without it the timeout case costs 30 seconds in the suite.
199  poll: { timeoutMs?: number; intervalMs?: number } = {}
200) {
201  const timeoutMs = poll.timeoutMs ?? CI_DISPATCH_POLL_MS;
202  const intervalMs = poll.intervalMs ?? CI_DISPATCH_POLL_INTERVAL_MS;
203  if (args.workflow !== undefined) refuseUnnamedWorkflow(args.workflow);
204  const target = await resolveRepo(env, namespace, repoSelector);
205
206  if (args.run_id) {
207    if (args.workflow) throw new Error("ci_dispatch: pass workflow and ref to start a run, or run_id to rerun one, not both");
208    return rerunFailedJobs(env, target, args.run_id);
209  }
210
211  if (!args.workflow || !args.ref) throw new Error("ci_dispatch: workflow and ref are both required to start a run");
212  return dispatchAndPoll(
213    env,
214    namespace,
215    target.full,
216    { workflow: args.workflow, ref: args.ref, inputs: args.inputs },
217    repoSelector,
218    { timeoutMs, intervalMs }
219  );
220}