IF Commons GitHub

workflows/model

The typed model of a GitHub Actions workflow (commons 0030-generated-workflows FR-002, FR-005): the triggers, the jobs, the steps, the strategy, the permissions and the concurrency of a workflow as values the compiler checks, so that a step that is neither uses nor run, a job with no step, a permission that is neither read nor write or an expression written as a plain string is a type error, and a mistake the types cannot say (an action with no version, a job that needs a job that is not there) is a finding of validateWorkflow. The files GitHub reads are made from these values by render.ts; nothing here reads or writes a file.

An expression is made with expr("matrix.os"), which gives ${{ matrix.os }} and a type of its own, so that a string that is meant to be read by the runner is told from one that is not. A step is a uses step or a run step (use(...) and run(...)), a job has its steps as a non-empty tuple, and a workflow has its jobs by id, in the order they are written. The condition of a job or a step (if) is the text of an expression without its ${{ }}, as GitHub reads it.

import { expr, job, run, use, validateWorkflow } from "./model.ts";
const w = { file: "x", name: "x", on: { push: {} }, jobs: { test: job({ runsOn: "ubuntu-latest", timeoutMinutes: 5, steps: [use("actions/checkout@v4"), run("bun test")] }) } };
validateWorkflow(w); // []
expr("matrix.os"); // "${{ matrix.os }}"

Spec: 0001-libraries FR-004

Source: commons/libraries/src/workflows/model.ts

7 of 20 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

CompositeActiontypeno test imports it
type CompositeAction = {
  /** The folder of the action under `.github/actions/`. */
  readonly folder: string;
  readonly name: string;
  readonly description: string;
  readonly inputs: Readonly<Record<string, { readonly description: string; readonly default?: string }>>;
  readonly steps: readonly [Step, ...Step[]];
};

A composite action, the file action.yml of a folder under .github/actions/ (its name is fixed by GitHub, so it cannot carry .auto.).

exprconst
const expr: (e: string) => Expr

The expression with the text e (expr("matrix.os") is ${{ matrix.os }}).

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

Exprtypeno test imports it
type Expr = string & { readonly [expression]: true };

A string the runner reads as an expression: ${{ ... }}.

Filtertypeno test imports it
type Filter = { readonly branches?: readonly string[]; readonly paths?: readonly string[]; readonly tags?: readonly string[] };

The branches, paths and tags a push or a pull request is run for; none is every one.

jobconst
const job: (j: Job) => Job

A job, written as a function so that its steps are read as a non-empty tuple.

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

Jobtypeno test imports it
type Job = { readonly name?: string; readonly runsOn: Runner; readonly timeoutMinutes: number; readonly needs?: … (684 characters)
type Job = {
  readonly name?: string;
  readonly runsOn: Runner;
  readonly timeoutMinutes: number;
  readonly needs?: readonly string[];
  /** The text of the condition, without `${{ }}`. */
  readonly when?: string;
  readonly permissions?: Permissions;
  readonly environment?: { readonly name: string; readonly url?: string };
  readonly env?: Readonly<Record<string, Scalar>>;
  /** What the job gives the jobs that need it, by name: an expression of its steps' outputs. */
  readonly outputs?: Readonly<Record<string, Expr>>;
  readonly strategy?: Strategy;
  readonly steps: readonly [Step, ...Step[]];
  /** A comment written above the job. */
  readonly comment?: string;
};

A job of a generated workflow.

Permissionstype
type Permissions = Readonly<
  Partial<
    Record<
      "contents" | "pages" | "id-token" | "actions" | "packages" | "pull-requests" | "issues" | "checks" | "statuses",
      "read" | "write" | "none"
    >
  >
>;

The permissions of the token: each scope read or write.

Imported by 7 tests of the run (7 passed, 0 failed): the library's results

Runnertypeno test imports it
type Runner = "ubuntu-latest" | "ubuntu-24.04" | "macos-latest" | "windows-latest" | Expr;

The runners the workflows of this repository ask for, or an expression that gives one (expr("matrix.os")).

RunSteptypeno test imports it
type RunStep = StepCommon & {
  readonly kind: "run";
  readonly run: string;
  readonly shell?: "bash" | "pwsh" | "sh";
};

A step that runs a script.

Scalartypeno test imports it
type Scalar = string | number | boolean;

A value of a with or an env: a string, a number, a boolean or an expression.

Strategytypeno test imports it
type Strategy = {
  readonly failFast?: boolean;
  readonly matrix: Matrix;
};

The matrix strategy of a job of a generated workflow.

Triggerstypeno test imports it
type Triggers = { readonly push?: Filter; readonly pullRequest?: Filter; /** Run by hand from the Actions page, wi… (626 characters)
type Triggers = {
  readonly push?: Filter;
  readonly pullRequest?: Filter;
  /** Run by hand from the Actions page, with the inputs it asks for (true asks for none). */
  readonly workflowDispatch?: true | { readonly inputs: Readonly<Record<string, DispatchInput>> };
  /** Run on a schedule: each entry is a cron expression of five fields, in UTC. */
  readonly schedule?: readonly string[];
  /** Called by another workflow. */
  readonly workflowCall?: true;
  /** Run when other workflows of the repository have completed (on the default branch). */
  readonly workflowRun?: { readonly workflows: readonly string[] };
};

What starts a generated workflow: pushes, pull requests, dispatch and schedule.

useconst
const use: (uses: string, o?: Omit<UseStep, "kind" | "uses">) => UseStep

A step that uses an action.

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

UseSteptypeno test imports it
type UseStep = StepCommon & {
  readonly kind: "uses";
  readonly uses: string;
  readonly with?: Readonly<Record<string, Scalar>>;
};

A step that uses an action: owner/name@version, or ./path for one of this repository's.

validateActionfunction
function validateAction(a: CompositeAction): readonly string[]

What is wrong with a composite action, as validateWorkflow says of a workflow.

Imported by 7 tests of the run (7 passed, 0 failed): the library's results

validateWorkflowfunction
function validateWorkflow(w: Workflow): readonly string[]

What is wrong with a workflow, one sentence each: no trigger, a job that needs a job that is not there or itself, a step that is wrong, and a name that is not a file's.

Imported by 7 tests of the run (7 passed, 0 failed): the library's results

Workflowtype
type Workflow = { /** The file's name without its directory and extension: `data` is `.github/workflows/data.auto.yml`… (627 characters)
type Workflow = {
  /** The file's name without its directory and extension: `data` is `.github/workflows/data.auto.yml`. */
  readonly file: string;
  /** The workflow's name, which a check's name begins with. */
  readonly name: string;
  /** A comment written under the name. */
  readonly comment?: string;
  readonly on: Triggers;
  readonly permissions?: Permissions;
  readonly env?: Readonly<Record<string, Scalar>>;
  readonly concurrency?: { readonly group: string; readonly cancelInProgress: boolean | Expr };
  /** The jobs by id, in the order they are written. */
  readonly jobs: Readonly<Record<string, Job>>;
};

A generated workflow: its name, triggers, permissions and jobs.

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

DispatchInputtypeno test imports it
type DispatchInput = { readonly description: string; readonly type: "boolean"; readonly default: boolean };

A question a run by hand asks: a yes or no with its default.

Matrixtypeno test imports it
type Matrix = Readonly<Record<string, readonly (string | number)[]>> | Expr;

The cells of a matrix: the values of each axis, or an expression that gives the whole matrix (expr("fromJSON(needs.plan.outputs.linux)")), which a job reads from the output of another.

stepFindingsfunctionno test imports it
function stepFindings(s: Step, where: string): readonly string[]

What is wrong with a step, one sentence each: an action with no version, an empty script, a working directory on a step that uses an action.

Titles, headings, exports, tables, columns and requirements. Esc closes.