Skip to main content
Every feature records two things while it runs:
  • Findings: a broken rule, a warning or a notice, each with a rule id, a message and, where there is one, a link to the policy it comes from.
  • Changes: what the feature did, such as a label added or a reviewer requested.
After the run, smartcloud publishes them in four places.

​
Check runs

Each feature that ran gets one completed check run on the commit, named smartcloud / <feature>, for example smartcloud / reviews. A feature that failed to run concludes as failure with the error as its summary, so a broken feature can never pass a required check. Findings with a file and line appear as annotations on the diff. Because each feature has its own check, you can make just the ones you enforce required in a ruleset. Findings that belong to no feature get a check of their own too: in a restricted run, smartcloud / access carries the restriction notice and a warning for each part of the config it left out (see Restricted runs).

​
One comment

On an issue or pull request, smartcloud keeps a single comment listing its errors and warnings in a table, and updates it in place on every run. Notices are left out of it. The comment is created only when there is something to act on. Once it exists, it is updated rather than repeated, including to say “All smartcloud checks pass.” when everything is fixed. A hidden <!-- smartcloud:report --> marker is how the next run finds it. Anyone can type that marker, so only a marker comment written by a bot account or by a login in roles.trustedBots is updated; smartcloud never edits anyone else’s comment and posts its own instead.

​
Job summary

The job summary shows the event, each feature’s result, the features that were skipped and why (not configured, or not handling that event), any failure in full, every finding including notices, and every change.

​
Annotations

Every finding is also printed as a workflow command, which Actions shows as an annotation on the run, and on the diff when the finding names a file.

​
Restricted runs

smartcloud runs with the lowest access that still works when it cannot, or should not, use a stronger token:
  • Pull requests from forks, and Dependabot’s runs and pull requests. smartcloud acts with the workflow token, whatever token the workflow passes as GITHUB_TOKEN, so code from outside the repository never runs alongside a stronger token. GitHub already gives such runs a read-only workflow token and no secrets.
  • The workflow token. When GITHUB_TOKEN is the workflow’s own token, for example because no app token was minted, the run is restricted too.
  • A rejected token. When GitHub refuses the token given as GITHUB_TOKEN, because it is invalid, expired or forbidden by an organisation policy, smartcloud warns, acts with the workflow token instead, and the run is restricted. An outage is not a rejection: it is reported as before.
A restricted run skips what its token cannot do, instead of failing:
  • A preset in extends from another repository that the token cannot read is left out, and so is a config section that fails only for keys the preset could have set, such as sync.source, or a convention rule that only tweaks a rule the preset defined. Each is a warning finding (access.config-skipped), because its rules were not checked in this run. A section with a mistake of its own still fails the run, as it would with the preset: a wrong value, or a missing key inside an entry the repository names, such as a label without a color. A missing preset in the repository itself still fails the run.
  • The settings and sync features are skipped, with the reason in the job summary.
  • A write GitHub refuses, such as a label, the report comment or a check run on a fork’s read-only token, is skipped and listed under Restricted access in the job summary.
When config was left out, the check runs show it. smartcloud cannot tell which rules an unreadable preset would have set, so it assumes any feature could be missing some: each feature’s check that would pass concludes as neutral instead, its title ends with “config left out”, and its summary lists what was left out. A failing check still fails. Neutral does not block a required check, so a pull request from a fork is not held up by config it cannot read, but the check no longer claims every rule passed. The run notes the restriction and its reason as a notice (access.restricted). The job summary and annotations are written by the job itself, so they always carry every finding. Publishing records a warning for any other reporting step it could not complete and carries on; reporting never fails the run.
Last modified on September 27, 2026