src/github/actions.ts

Functions

Imports

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

Source

1import type { RepoEnv as Env } from "../env";
2import { redact, redactText, type Redacted } from "../redact";
3import {
4  assertRepoArg,
5  cachedGet,
6  ghFetch,
7  resolveRepo,
8} from "./client";
9
10// Recent CI workflow runs for a namespace's repo, via the GitHub App. Read-only.
11// For the most recent failed run it also returns the failing jobs and steps and a
12// bounded log tail. Needs the App's Actions: Read permission; a 403 is surfaced as
13// a named error.
14//
15// The log tail is withheld from read-only keys. Run metadata (name, sha, conclusion)
16// is inert; a build log carries whatever the workflow echoed: resolved binding ids,
17// account ids, wrangler output, and any variable a step printed by accident. The runs
18// list stays open to read-only keys. Every log text returned, to anyone, is redacted
19// first (src/redact.ts). With run_id, jobs/job/step drill into any run the same way
20// (ciRunJobs below), behind the same log gate.
21
22// A ref matching this shape is filtered as a head sha, anything else as a branch.
23// GitHub has two query parameters for these and none that accepts either, so the
24// tool takes one `ref` and decides here.
25const SHA_SHAPE = /^[0-9a-f]{7,40}$/i;
26
27interface CiRunsOpts {
28  limit?: number;
29  logTail?: boolean;
30  ref?: string;
31  runId?: number;
32}
33interface CiDrillOpts extends CiRunsOpts {
34  jobs?: boolean;
35  job?: string;
36  step?: string;
37}
38type CiRunsResult = Awaited<ReturnType<typeof ciStatusFromRuns>>;
39type CiJobsResult = Awaited<ReturnType<typeof ciRunJobs>>;
40
41// Without the drill-in arguments the answer is always the run list, and the callers
42// that read `runs` (job-outcomes.ts, watcher.ts) keep that type. Only a call that
43// passes jobs, job or step can get the jobs view back.
44export async function ciStatus(env: Env, namespace: string, repoSelector?: string, opts?: CiRunsOpts): Promise<CiRunsResult>;
45export async function ciStatus(env: Env, namespace: string, repoSelector: string | undefined, opts: CiDrillOpts): Promise<CiRunsResult | CiJobsResult>;
46export async function ciStatus(
47  env: Env,
48  namespace: string,
49  repoSelector?: string,
50  opts: CiDrillOpts = {}
51) {
52  // The drill-in arguments narrow one run, so each needs the one above it. Refused
53  // before any GitHub call rather than ignored, so a caller never reads a run list
54  // believing it is the step it asked for.
55  if (opts.step !== undefined && opts.job === undefined) {
56    throw new Error("ci_status: step needs job, the job (name or id) the step ran in, and run_id");
57  }
58  if (opts.job !== undefined && opts.runId === undefined) {
59    throw new Error("ci_status: job needs run_id, the run the job belongs to. capsid_inspect_repo action ci without it lists runs and their ids");
60  }
61  if (opts.jobs === true && opts.runId === undefined) {
62    throw new Error("ci_status: jobs needs run_id, the run whose jobs to list. capsid_inspect_repo action ci without it lists runs and their ids");
63  }
64  if (opts.jobs === true && opts.job !== undefined) {
65    throw new Error("ci_status: pass jobs: true to list every job in the run, or job to read one, not both");
66  }
67  if (opts.ref) assertRepoArg("ref", opts.ref);
68  const { owner, repo, full } = await resolveRepo(env, namespace, repoSelector);
69  const limit = opts.limit && opts.limit > 0 ? Math.min(opts.limit, 20) : 10;
70  let query = `/repos/${owner}/${repo}/actions/runs?per_page=${limit}`;
71  if (opts.runId) {
72    // One run, by id. Wrapped back into the list's shape so the failed-run drill-in
73    // has one code path.
74    const one = await ghFetch(env, owner, repo, `/repos/${owner}/${repo}/actions/runs/${opts.runId}`);
75    if (one.status === 404) throw new Error(`ci_status: run ${opts.runId} does not exist on ${full}`);
76    if (!one.ok) throw new Error(`ci_status run lookup failed (${one.status}): ${await errorBody(one)}`);
77    const run = await one.json();
78    if (opts.jobs === true || opts.job !== undefined) {
79      return ciRunJobs(env, { owner, repo, full }, run as CiRun, { job: opts.job, step: opts.step, logTail: opts.logTail === true });
80    }
81    return ciStatusFromRuns(env, owner, repo, full, [run as CiRun], opts.logTail === true, { run_id: opts.runId });
82  }
83  if (opts.ref) {
84    if (SHA_SHAPE.test(opts.ref)) {
85      // An abbreviated sha is expanded first. GitHub matches head_sha exactly and
86      // documents nothing, so a short sha returns an empty run list rather than an
87      // error. One extra GET, only when the ref is short.
88      let full40 = opts.ref;
89      if (opts.ref.length < 40) {
90        const commit = await cachedGet(env, owner, repo, `/repos/${owner}/${repo}/commits/${encodeURIComponent(opts.ref)}`);
91        if (!commit.ok) {
92          throw new Error(
93            `ci_status: ${opts.ref} does not resolve to a commit on ${full} (${commit.status}), so runs cannot be filtered by it`
94          );
95        }
96        full40 = ((await commit.json()) as { sha: string }).sha;
97      }
98      query += `&head_sha=${encodeURIComponent(full40)}`;
99    } else {
100      query += `&branch=${encodeURIComponent(opts.ref)}`;
101    }
102  }
103  const resp = await ghFetch(env, owner, repo, query);
104  if (resp.status === 403) {
105    throw new Error(
106      "ci_status: the capsid-repo-access GitHub App lacks Actions: Read. Add that permission in the App settings and accept the installation prompt, then retry."
107    );
108  }
109  if (!resp.ok) throw new Error(`ci_status failed (${resp.status}): ${redactText(await resp.text())}`);
110  const data = (await resp.json()) as { workflow_runs: CiRun[] };
111  return ciStatusFromRuns(env, owner, repo, full, data.workflow_runs, opts.logTail === true, opts.ref ? { ref: opts.ref } : {});
112}
113
114interface CiRun {
115  id: number;
116  name: string;
117  head_sha: string;
118  status: string;
119  conclusion: string | null;
120  event: string;
121  created_at: string;
122  updated_at?: string;
123  html_url: string;
124}
125
126// The failing step's log, 64KB from its end, for write-grant keys. A job log ends
127// with post-run cleanup, so the last few thousand characters of a failed run are
128// `git config --unset-all` lines and the failure is far earlier. The region is found
129// by the failing step and then tailed. The read-only tier is unchanged.
130export const CI_LOG_BUDGET = 64 * 1024;
131
132// Actions labels groups by command, not step name, so a step's name appears nowhere
133// in its own log and a name search matches an incidental later occurrence. The
134// failing step is found by its started_at..completed_at window instead: every log
135// line carries an ISO timestamp.
136//
137// The jobs API truncates those to the second while log lines carry sub-second
138// stamps, so the upper bound is extended to the end of that second, or the last
139// second of output (where the error is) is dropped. Truncating down only widens the
140// lower bound, so `from` needs no adjustment.
141const STEP_STAMP_PRECISION_MS = 1000;
142
143// Every log text ci_status returns is redacted (src/redact.ts), and redacted BEFORE the
144// budget cut: a cut first could split a secret so its remaining half no longer matches
145// any pattern, or keep a private key's body without its BEGIN line.
146//
147// `label` is how the region is named: "failing step" for the failed-run drill-in, whose
148// wording callers already read, and "step" for a step the caller asked for by name.
149function stepLog(
150  log: string,
151  step: { name?: string; started_at?: string | null; completed_at?: string | null } | undefined,
152  label: "failing step" | "step" = "failing step"
153): { text: string; how: string; redactions: Redacted["redactions"] } {
154  const name = step?.name;
155  const from = step?.started_at ? Date.parse(step.started_at) : NaN;
156  const to = step?.completed_at ? Date.parse(step.completed_at) : NaN;
157
158  if (Number.isFinite(from) && Number.isFinite(to)) {
159    const windowed = log
160      .split("\n")
161      .filter((line) => {
162        const stamp = /^(\S+Z)/.exec(line);
163        if (!stamp) return false;
164        const at = Date.parse(stamp[1]);
165        return Number.isFinite(at) && at >= from && at < to + STEP_STAMP_PRECISION_MS;
166      })
167      .join("\n");
168    if (windowed.length > 0) {
169      const clean = redact(windowed);
170      return {
171        text: clean.text.length > CI_LOG_BUDGET ? clean.text.slice(-CI_LOG_BUDGET) : clean.text,
172        how:
173          clean.text.length > CI_LOG_BUDGET
174            ? `${label} "${name}" by timestamp window, last ${CI_LOG_BUDGET} bytes of it`
175            : `${label} "${name}" by timestamp window, whole (${clean.text.length} bytes)`,
176        redactions: clean.redactions,
177      };
178    }
179  }
180
181  // NAMED FALLBACK, not a silent one. "The end of the job log" and "the failing
182  // step" are different claims and the caller is told which one this is.
183  const clean = redact(log);
184  return {
185    text: clean.text.slice(-CI_LOG_BUDGET),
186    how: name
187      ? `step "${name}" had no usable timestamp window, so this is the last ${CI_LOG_BUDGET} bytes of the whole job, cleanup included`
188      : `no failing step was named, so this is the last ${CI_LOG_BUDGET} bytes of the whole job, cleanup included`,
189    redactions: clean.redactions,
190  };
191}
192
193// A GitHub error body is echoed into a result too, so it is redacted as well, before
194// its 200-character cut for the same reason as above.
195const errorBody = async (resp: Response): Promise<string> => redactText(await resp.text()).slice(0, 200) || "no response body";
196
197async function ciStatusFromRuns(
198  env: Env,
199  owner: string,
200  repo: string,
201  full: string,
202  workflowRuns: CiRun[],
203  logTail: boolean,
204  filter: { ref?: string; run_id?: number }
205) {
206  const runs = workflowRuns.map((r) => ({
207    name: r.name,
208    head_sha: r.head_sha?.slice(0, 7),
209    status: r.status,
210    conclusion: r.conclusion,
211    event: r.event,
212    created_at: r.created_at,
213    // When a completed run finished: the watcher's deploy-drift check waits a settle
214    // window after master's own CI run ends (src/watcher-detect.ts, deployVerdict).
215    updated_at: r.updated_at ?? null,
216    url: r.html_url,
217  }));
218
219  const result: {
220    repo: string;
221    filter?: { ref?: string; run_id?: number };
222    runs: typeof runs;
223    failed_run?: unknown;
224  } = { repo: full, runs };
225  if (filter.ref || filter.run_id) result.filter = filter;
226
227  // Drill into the most recent failed run so the caller sees why, not just that.
228  // Every degraded path is named: an errored jobs fetch or log fetch is reported
229  // rather than dropped, so a write-grant caller can tell "no log" from "the log was
230  // refused for you".
231  const failed = workflowRuns.find((r) => r.conclusion === "failure");
232  if (failed) {
233    const failedRun: Record<string, unknown> = {
234      name: failed.name,
235      head_sha: failed.head_sha?.slice(0, 7),
236      url: failed.html_url,
237    };
238    const jobsResp = await ghFetch(env, owner, repo, `/repos/${owner}/${repo}/actions/runs/${failed.id}/jobs`);
239    if (!jobsResp.ok) {
240      failedRun.jobs_unavailable = `${jobsResp.status}: ${await errorBody(jobsResp)}`;
241    } else {
242      const jobsData = (await jobsResp.json()) as {
243        jobs: Array<{
244          id: number;
245          name: string;
246          conclusion: string | null;
247          steps?: Array<{ name: string; conclusion: string | null; started_at?: string | null; completed_at?: string | null }>;
248        }>;
249      };
250      failedRun.jobs = jobsData.jobs
251        .filter((j) => j.conclusion === "failure")
252        .map((j) => ({
253          name: j.name,
254          failed_steps: (j.steps ?? []).filter((s) => s.conclusion === "failure").map((s) => s.name),
255        }));
256      const firstFailedJob = jobsData.jobs.find((j) => j.conclusion === "failure");
257      if (!logTail) {
258        // Unchanged: this is the read-only tier's boundary, not a degraded path.
259        failedRun.log_tail_withheld =
260          "read-only key: run metadata only. A write-grant key returns the failing step's log.";
261      } else if (!firstFailedJob) {
262        failedRun.log_tail_unavailable = "the run is marked failed but no job in it is, so there is no job log to read";
263      } else {
264        const logResp = await ghFetch(env, owner, repo, `/repos/${owner}/${repo}/actions/jobs/${firstFailedJob.id}/logs`);
265        if (logResp.ok) {
266          const failedStep = (firstFailedJob.steps ?? []).find((s) => s.conclusion === "failure");
267          const picked = stepLog(await logResp.text(), failedStep);
268          failedRun.failing_job = firstFailedJob.name;
269          failedRun.failing_step = failedStep?.name ?? null;
270          failedRun.log_region = picked.how;
271          failedRun.log = picked.text;
272          if (Object.keys(picked.redactions).length > 0) failedRun.log_redactions = picked.redactions;
273        } else {
274          failedRun.log_tail_unavailable = `${logResp.status}: ${await errorBody(logResp)}`;
275        }
276      }
277    }
278    result.failed_run = failedRun;
279  }
280  return result;
281}
282
283// One page of a run's jobs, the latest attempt only. GitHub's page limit, and the cap:
284// a run with more jobs than this says so rather than being paged through.
285export const CI_JOBS_MAX = 100;
286
287interface CiJob {
288  id: number;
289  name: string;
290  status: string;
291  conclusion: string | null;
292  started_at?: string | null;
293  completed_at?: string | null;
294  html_url?: string;
295  steps?: CiStep[];
296}
297
298interface CiStep {
299  number: number;
300  name: string;
301  status: string;
302  conclusion: string | null;
303  started_at?: string | null;
304  completed_at?: string | null;
305}
306
307const stepView = (s: CiStep) => ({
308  number: s.number,
309  name: s.name,
310  status: s.status,
311  conclusion: s.conclusion,
312  started_at: s.started_at ?? null,
313  completed_at: s.completed_at ?? null,
314});
315
316const jobView = (j: CiJob) => ({
317  id: j.id,
318  name: j.name,
319  status: j.status,
320  conclusion: j.conclusion,
321  started_at: j.started_at ?? null,
322  completed_at: j.completed_at ?? null,
323  url: j.html_url ?? null,
324  steps: (j.steps ?? []).map(stepView),
325});
326
327// A job or step named by the caller: a number is tried as the id (a job) or the number
328// (a step) first, then as a name. A name two entries share is refused with what tells
329// them apart, never resolved to the first.
330function pickOne<T extends { name: string }>(
331  items: T[],
332  wanted: string,
333  byNumber: (item: T) => number,
334  what: string,
335  where: string
336): T {
337  if (/^\d+$/.test(wanted)) {
338    const numbered = items.find((item) => byNumber(item) === Number(wanted));
339    if (numbered) return numbered;
340  }
341  const named = items.filter((item) => item.name === wanted);
342  if (named.length === 1) return named[0];
343  if (named.length > 1) {
344    throw new Error(
345      `ci_status: ${named.length} ${what}s in ${where} are named "${wanted}". Pass one by its ${what === "job" ? "id" : "number"}: ${named.map(byNumber).join(", ")}`
346    );
347  }
348  const known = items.slice(0, 30).map((item) => `"${item.name}" (${byNumber(item)})`);
349  throw new Error(`ci_status: no ${what} "${wanted}" in ${where}. It has: ${known.join(", ") || "none"}${items.length > 30 ? ", and more" : ""}`);
350}
351
352/** Every job of one run with its steps (jobs: true), or one job, or one step of it with
353 *  that step's log. For any run, not only a failed one. The log is withheld from a
354 *  read-only caller exactly as the failed-run tail is, and redacted for everyone else. */
355async function ciRunJobs(
356  env: Env,
357  target: { owner: string; repo: string; full: string },
358  run: CiRun,
359  opts: { job?: string; step?: string; logTail: boolean }
360) {
361  const { owner, repo, full } = target;
362  const resp = await ghFetch(
363    env,
364    owner,
365    repo,
366    `/repos/${owner}/${repo}/actions/runs/${run.id}/jobs?filter=latest&per_page=${CI_JOBS_MAX}`
367  );
368  if (resp.status === 403) {
369    throw new Error(
370      "ci_status: the capsid-repo-access GitHub App lacks Actions: Read. Add that permission in the App settings and accept the installation prompt, then retry."
371    );
372  }
373  if (!resp.ok) throw new Error(`ci_status jobs lookup for run ${run.id} failed (${resp.status}): ${await errorBody(resp)}`);
374  const data = (await resp.json()) as { total_count?: number; jobs: CiJob[] };
375  const jobs = data.jobs.slice(0, CI_JOBS_MAX);
376  const total = typeof data.total_count === "number" ? data.total_count : jobs.length;
377
378  const result: Record<string, unknown> = {
379    repo: full,
380    filter: {
381      run_id: run.id,
382      ...(opts.job === undefined ? { jobs: true } : { job: opts.job }),
383      ...(opts.step === undefined ? {} : { step: opts.step }),
384    },
385    run: {
386      name: run.name,
387      head_sha: run.head_sha?.slice(0, 7),
388      status: run.status,
389      conclusion: run.conclusion,
390      event: run.event,
391      created_at: run.created_at,
392      url: run.html_url,
393    },
394  };
395  const truncated =
396    total > jobs.length
397      ? `the run has ${total} jobs in its latest attempt and only the first ${jobs.length} were read (at most ${CI_JOBS_MAX})`
398      : null;
399
400  if (opts.job === undefined) {
401    result.jobs = jobs.map(jobView);
402    result.jobs_total = total;
403    if (truncated) result.jobs_truncated = truncated;
404    return result;
405  }
406
407  const where = `run ${run.id}${truncated ? ` (${truncated})` : ""}`;
408  const job = pickOne(jobs, opts.job, (j) => j.id, "job", where);
409  result.job = jobView(job);
410  if (opts.step === undefined) return result;
411
412  const step = pickOne(job.steps ?? [], opts.step, (s) => s.number, "step", `job "${job.name}"`);
413  result.step = stepView(step);
414  if (!opts.logTail) {
415    // The read-only tier's boundary, worded as the failed-run tail's is.
416    result.log_withheld = "read-only key: step metadata only. A write-grant key returns the step's log.";
417    return result;
418  }
419  const logResp = await ghFetch(env, owner, repo, `/repos/${owner}/${repo}/actions/jobs/${job.id}/logs`);
420  if (!logResp.ok) {
421    result.log_unavailable = `${logResp.status}: ${await errorBody(logResp)}`;
422    return result;
423  }
424  const picked = stepLog(await logResp.text(), step, "step");
425  result.log_region = picked.how;
426  result.log = picked.text;
427  if (Object.keys(picked.redactions).length > 0) result.log_redactions = picked.redactions;
428  return result;
429}
430