Skip to main content
smartcloud reads .github/smartcloud.yml (.github/smartcloud.yaml also works). The file is YAML; JSON is valid YAML, so a JSON file works too.
.github/smartcloud.yml
version: 2 is required. A file without it is treated as a v1 config and migrated on the fly, with a warning for everything the migration drops; see Migrating from v1. The configuration reference lists every key.

​
Unknown keys and invalid values

A run never fails because a key is unknown or a value is invalid, in your config or in any preset it extends. smartcloud drops it, warns, and runs with the rest, so a preset written for a newer smartcloud, such as one with a settings section this version does not know yet, keeps working with an older action. Each warning names the file and the key, for example:
What is dropped:
  • An unknown key, or a value of the wrong type or outside its allowed values, is dropped on its own; the rest of its section still applies.
  • A problem anywhere in a rule’s when drops the whole when, so a rule never runs with some of its conditions missing. A rule that cannot work without its when, such as a labelling rule or an automatic approval, is then dropped too; a convention that also names a preset keeps the preset. A problem inside any other list drops the whole list, never one item.
  • A section or rule still incomplete once every file is merged, such as sync without source, a label without color, or a convention with neither preset nor when, is dropped. A repository can still complete a rule its preset starts, or restate one to add a field, as Add, never change describes.
Dropping a setting that only tightens policy would loosen it. For example, a roles.maintainers list with one bad entry would leave fewer than two maintainers, and that opens the review gate. So an invalid value dropped from one of these settings is an error in the smartcloud / config check, not a warning. Every feature still runs, but the check fails and blocks merging until the config is fixed:
  • roles.maintainers
  • reviews.gate
  • commits
  • disclosure.requireDraft
  • settings.security
  • settings.ruleset
  • settings.actions
  • settings.collaborators
  • settings.teams
  • sync.check
This applies to an invalid value at, inside or around one of these, such as a whole sync section dropped for lacking its source. An unknown key there is still only a warning, because this version would not have applied it anyway. A value a preset sets that this version cannot read is dropped from the preset but stays locked: your config cannot set that key either, and a value it sets there is ignored with a warning. A preset that asks for a stricter setting than this version knows can never be turned into a weaker one. Some problems still fail the run, because they are not about one key: a file that is not YAML or JSON, is not a mapping, or has a malformed extends entry; a preset that cannot be read (outside a restricted run); presets that extend each other in a loop or more than five deep; and a config that changes a value its preset set, which Add, never change describes. The warnings appear in a smartcloud / config check run and the job summary; see Reporting. To catch mistakes before they reach a run, check the config with smartcloud validate or the MCP server’s validate_config, which are strict and report every unknown key and invalid value as an error, or let your editor check it against the JSON Schema named in the first line of the example above, which is strict too.

​
Sections

Every rule is a keyed map, never a list. Keys are how presets and repositories merge, and how an error names the rule it is about.

​
Roles

roles.maintainers and roles.trustedBots are lists of GitHub logins. Logins compare ignoring case, and a leading @ is optional.
  • Trusted bots skip the commits and disclosure checks and the review gate.
  • On a maintainer’s own pull request, the commits and disclosure features report errors at their maintainerLevel (warning by default). The repository owner counts as a maintainer for this.
  • The review gate and the ruleset’s required checks only apply once two or more maintainers are listed.
links.policyBase is the base URL of your governance documents. Findings link to pages under it, for example AI_POLICY.md#ai-02, CONTRIBUTING.md#dco and GOVERNANCE.md#review. The default is https://github.com/Resnovas/.github/blob/main.

​
Presets and extends

extends lists preset files to build on, each written as owner/repo/path@ref. The ref (a branch, tag or commit) is optional; without it the repository’s default branch is read.
A preset is an ordinary config file with version: 2, and may extend presets of its own. Presets are merged first, in the order listed, each preset’s own presets before it, and the repository’s config last. Presets extending each other in a loop are an error, as is nesting more than five deep.

​
Add, never change

Everything a preset sets is locked. A repository may add to what it inherits, but never change or remove it:
  • Adding is allowed. A new label, a new rule, or a new field on an inherited rule that the preset left unset.
  • Identical restatements are allowed. Repeating an inherited value exactly as it already is changes nothing, so a repository can keep a full copy of a rule without error.
  • Changing is an error. Any other value for something already set, whether a scalar, a list or a different shape, fails the whole run.
Lists are values, not collections to append to: if a preset sets roles.maintainers, a repository cannot add a name to it. Given this preset:
Resnovas/.github/smartcloud/house.yml
This repository config is valid: it restates bug identically, adds a description the preset left unset, and adds a new label.
.github/smartcloud.yml
Changing the colour instead fails with an error naming the path and the preset that set it:
The same rule applies between presets: a later preset cannot change what an earlier one set. version, extends and $schema describe a file rather than rules, so they are never merged.

​
Reading presets

The action reads presets through the GitHub API with its own token, so a preset in a private repository needs a token that can read that repository. A restricted run, such as a pull request from a fork, leaves out a preset from another repository that its token cannot read, and warns that the preset’s rules were not checked, rather than failing. The CLI resolves a token only when a config extends something; see CLI.
Last modified on September 27, 2026