Required status check

Required status check

The rules module defines a required status check as a status check that a ruleset requires to pass before a change reaches a ref it targets, named by the context that a check run must report.¹ The schema models it as GhaRequiredStatusCheck, with check_context for that context. A ruleset names the checks it requires in requires_check, and emitted_by names the top-level workflow whose job reports a check.

How a check is named

The class’s comments state the rule:

• GitHub Actions reports each job as a check run named after the job: its name, or its id when it has none;
• a job of a called workflow is named after the calling job and the called job, joined by a slash with a space on each side, such as test / unit;
• a matrix job’s check name adds its matrix values in parentheses, such as docs (3.13).

The comment says that the otterdog documentation states the rule for a called job, and the README names otterdog among the schema’s influences for that rule.² job_path records the job ids from the top-level workflow’s job to the job that reports the check, with the calling job’s id first for a job of a called workflow.

scripts/derive.py applies the rule to a repository’s workflow files.³ Its docstring adds these details:

• a matrix job’s values are joined by a comma and a space;
• a name that reads the matrix context takes the values in its own place;
• the check names of a job that calls a workflow in another repository are reported as unresolved.

See Derive and check concepts from workflow files.

What else the class records

• integration_id names the GitHub App the check must come from; GitHub Actions is app 15368.
• strict_policy says whether a pull request must be tested against the latest code of the branch it targets.
• do_not_enforce_on_create says whether a branch may be created although the check would otherwise stop it.
• skip_conditions records what in the workflow can skip the job, as key paths such as on.pull_request.paths or jobs.test.if. A comment says that a job skipped by its own if, or because a job it needs failed or was skipped, reports success, so its required check passes without running. A path filter skips the whole run, and a calling job’s if or needs skips the call, which GitHub records under the caller’s name alone, so the check stays pending and blocks the merge.

The comments relate the class to two outside vocabularies. SLSA’s Source track lets an organization carry such a control into a Source Verification Summary Attestation as an ORG_SOURCE_ property, and slsa-framework’s source-tool emits one as GH_REQUIRED_CHECK_ followed by the check’s name. in-toto’s Test Result predicate is the shape of an attestation of what the check found.

In this repository

CONTRIBUTING.md asks maintainers to leave off any branch rule that requires status checks on main, because it would reject the release job’s own push to main.⁴

Footnotes

1. src/github_actions/schema/github_actions_rules.yaml, GhaRequiredStatusCheck ↩

2. README.md, the otterdog item of the Influences section ↩

3. scripts/derive.py, the docstring ↩

4. CONTRIBUTING.md, the last item of Releasing (maintainers) ↩