Required

One aggregate check that passes only when every other check on a pull request has passed.

A ruleset requires status checks by name, so every new workflow job means editing the ruleset, and a renamed job silently stops being required. The required feature replaces that list with one check: the job running smartcloud waits for every other check on the pull request’s head commit, and passes only when they all have. The ruleset then requires that job’s check alone.

It is enabled by a required section, and runs on pull request events in a job that passes its own check run id:

required:
  ignore: ['^codecov/', '/preview/i']
  timeout: 60

jobs:
  smartcloud:
    name: smartcloud
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      checks: write
      issues: write
      statuses: read
    steps:
      - uses: resnovas/smartcloud@v2
        with:
          checkRunId: ${{ job.check_run_id }}

Then require the smartcloud check in the ruleset; with the settings feature, requiredChecks: [smartcloud]. List your main CI check under expect too, so a deleted or renamed CI job cannot let the aggregate pass with nothing to wait for. Until every repository does, keep that CI check required in the ruleset beside smartcloud, because a restricted run (a fork or Dependabot pull request) skips the private house preset and with it required.

Key	Default	Meaning
ignore	none	Checks that do not count, as patterns matched against each check run’s name or status’s context.
expect	none	Checks that must appear and pass, as patterns, such as ^check$. One that has not appeared by the timeout fails the aggregate.
timeout	60	Minutes to wait for the other checks, from 1 to 360. Checks still running then fail the aggregate.

What counts

Every check on the head commit counts: the latest check run of each app and name, from GitHub Actions or any app, and the latest commit status of each context. A ruleset picks a required check the same way. A re-run, or a workflow started again by an edit or a review, leaves the older runs of its checks on the commit, often cancelled; only the latest run of each check counts, so an older cancelled or failed run never fails the aggregate. Two jobs with the same name published by the same app are one check, as they are to a ruleset, so give jobs in different workflows different names.

Three kinds are left out:

• every run of the job running smartcloud (until its own run shows up in the list, the feature concludes nothing and looks again): its own, found by checkRunId, and any other run with the same app and name, such as one a review started while this one waits;
• smartcloud’s own smartcloud / <feature> check runs, because their findings already decide the job’s own result. smartcloud marks every check run it creates with the external_id smartcloud, and only runs with that mark from an app smartcloud runs as (the job’s app, or the GitHub App its token acts as) are left out. A check run of the same name from another app or workflow, unmarked or marked otherwise, counts;
• anything an ignore pattern matches.

A check run that concludes success, neutral or skipped passes, as it does for a ruleset. Any other conclusion (failure, cancelled, timed out, action required, stale) fails, as does a status of failure or error.

How it waits

The feature looks at the checks every 15 seconds.

• As soon as one check fails, the aggregate fails, with one error per failed check linking to it.
• When nothing is pending, it looks once more, so a workflow queued a moment after the rest is not missed. Two looks in a row with the same checks, all passed, pass the aggregate with a notice.
• An expect pattern no check matches yet keeps it waiting; one still missing after timeout minutes fails it (required.missing).
• Checks still pending after timeout minutes fail it, one error each.
• If GitHub never lists the job’s own run before the timeout, it fails (required.unconfirmed) rather than pass unconfirmed.

Every other feature runs alongside, so labels and review requests are not delayed; the report comment and the per-feature check runs are published once the wait ends. Re-run the smartcloud job after re-running a failed check.

Without checkRunId the job would wait for itself. In the action, a configured required section without it is an error (required.check-run-missing), so a workflow that was not updated cannot pass the aggregate unchecked; in CLI dry runs the feature is skipped. Runs of the same aggregate job never wait for each other, but use one aggregate job per commit: two differently named jobs that each wait for every other check wait for each other until they time out. Give the workflow a concurrency group per pull request and event with cancel-in-progress, so a newer run replaces an older one on the same event instead of waiting beside it.

Tokens

The checks are read with the workflow’s own token (the workflowToken input, which defaults to it), not GITHUB_TOKEN: that can be a personal access token or an app token without checks and statuses read, while the job’s checks and statuses permissions give the workflow token both. On a pull request from a fork, the workflow token is read-only, which is enough.

Rolling it out

The feature does nothing until the workflow passes checkRunId, so the order is:

1. Release a smartcloud version with the feature, and use it in the workflow.
2. Add the required section to the config, or to a preset the config extends. Until the next step it is skipped, and the smartcloud check reports the other features as before.
3. Pass checkRunId and grant statuses: read in the workflow. From here the smartcloud check waits for every other check.
4. Only then make the ruleset require the smartcloud check alone. Dropping the other required checks before step 3 would leave pull requests gated by nothing but smartcloud’s own findings.