> ## Documentation Index
> Fetch the complete documentation index at: https://smartcloud.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```yaml theme={null}
required:
  ignore: ['^codecov/', '/preview/i']
  timeout: 60
```

```yaml theme={null}
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](/features/settings#ruleset) 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](/conditions) 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.