Recommended setups

Complete, copy-and-paste settings files for a small repository, a monorepo, an open-source project and an organisation with a shared preset, with why each part is there.

Starting from an empty file is hard when you do not yet know which of smartcloud’s sixteen features you want. This page gives you four complete settings files for common situations. Pick the one closest to yours, copy it into .github/smartcloud.yml, change the names, and delete what you do not need.

Each file has been checked with smartcloud validate, so it works as written. After each one, a table explains why every section is there, and what it does when a run starts.

Your situation	Start from	Token it needs
One small repository, one or two people	A single small repository	The workflow token
Several apps and packages in one repository	A monorepo	The workflow token
A public project that takes pull requests from anyone	An open-source project	A GitHub App for settings; the workflow token for the rest
Many repositories in one organisation	An organisation with a shared preset	A GitHub App

Every setup assumes the workflow from Getting started. Want to understand each section before copying? Build your settings file adds them one at a time.

Whichever you pick, add the schema line at the top (every example has it). Your editor then completes keys and underlines mistakes as you change the file.

A single small repository

Good for: a personal project, a small library, an internal tool. One or two people merge everything, and you want tidy labels, readable history and no pile of forgotten issues, without anyone being blocked.

.github/smartcloud.yml

# yaml-language-server: $schema=https://raw.githubusercontent.com/Resnovas/smartcloud/main/schema/smartcloud.schema.json
version: 2

# Who runs the project, and which bots to trust.
roles:
  maintainers: [octocat]
  trustedBots: ['dependabot[bot]']

# The labels the repository should have.
labels:
  bug:
    name: bug
    color: 'D73A4A'
    description: Something is not working
  feature:
    name: enhancement
    color: 'A2EEEF'
    description: New feature or request
  docs:
    name: documentation
    color: '0075CA'
    description: Improvements or additions to documentation
  dependencies:
    name: dependencies
    color: '0366D6'
    description: Updates a dependency
  stale:
    name: stale
    color: 'CFD3D7'
    description: No activity for a while

# Label pull requests by what they change.
labelling:
  docs:
    label: docs
    on: [pullRequest]
    when:
      condition:
        - type: filesMatch
          condition: 'docs/**'
  dependencies:
    label: dependencies
    on: [pullRequest]
    when:
      condition:
        - type: lockfileChanged
          condition: true
  fix:
    label: bug
    on: [pullRequest]
    when:
      condition:
        - type: titleMatches
          condition: '^fix(\(.+\))?!?: '

# Size: XS to Size: XL on every pull request.
sizeLabels: {}

# Pull request titles are Conventional Commits.
conventions:
  rules:
    title:
      on: [pullRequest]
      preset: conventionalCommits

# One check, smartcloud, that waits for every other check.
required: {}

# Quiet issues get a nudge, then close.
stale:
  on: [issue]
  staleAfterDays: 60
  staleLabel: stale
  staleComment: This issue has had no activity for 60 days. Comment to keep it open.
  abandonedAfterDays: 14
  close: true
  exempt:
    labels: [pinned, security]

# Old conversations lock so nobody revives them by accident.
lock:
  afterDays: 30
  reason: resolved
  comment: This has been closed for 30 days, so it is now locked. Open a new issue for anything new.

# /label, /assign, /rebase and the rest, in comments.
commands: {}

Section	Why it is there	What happens when it runs
roles	Names you as the maintainer, so the few checks that care go easier on your own pull requests. Dependabot is trusted.	Nothing on its own; other features read it.
labels	One place to define the labels, so every clone of the repository has the same ones with the same colours.	On a push to main and daily, missing labels are created and changed ones corrected.
labelling	Labels that apply themselves: documentation for docs changes, dependencies when a lockfile changes, bug for fix:.	On every pull request event, labels are added while their rule passes and removed when it stops passing.
sizeLabels	A Size: XS to Size: XL label tells you at a glance how long a review will take.	Every pull request carries one size label, updated as it grows.
conventions	Conventional titles make a readable history and let release tools work out the next version.	A title like Update readme fails smartcloud / conventions with an example of a good one.
required	One smartcloud check to require in branch protection, however many CI jobs you add later.	On pull requests, the smartcloud job waits for every other check and passes only if they all do.
stale	Issues nobody touches for two months get a nudge, then close, so the list stays meaningful. pinned and security stay.	Daily: quiet issues get the stale label and a comment, and close 14 days later unless someone replies.
lock	Stops people commenting on long-closed issues instead of opening new ones.	Daily: items closed for 30 days are locked with a short explanation.
commands	/label, /assign, /rebase and friends in comments, handy from a phone.	On a comment, smartcloud reacts, runs the command if the person’s role allows it, and replies.

Left out on purpose: commits, disclosure and reviews.gate would only slow a one-person project down, and settings needs a GitHub App. Add settings later if you want the repository’s merge buttons and branch rules kept as code; see Settings.

A monorepo

Good for: one repository holding several apps and shared packages, with different people owning different parts. The problem to solve is routing: every pull request should say which parts it touches and reach the people who own them.

.github/smartcloud.yml

# yaml-language-server: $schema=https://raw.githubusercontent.com/Resnovas/smartcloud/main/schema/smartcloud.schema.json
version: 2

roles:
  maintainers: [octocat, hubot]
  trustedBots: ['dependabot[bot]', 'renovate[bot]']

# One label per package, so a reviewer sees at a glance what a pull request touches.
labels:
  web:
    name: 'pkg: web'
    color: '1D76DB'
  api:
    name: 'pkg: api'
    color: '5319E7'
  shared:
    name: 'pkg: shared'
    color: 'FBCA04'
  ci:
    name: ci
    color: 'EDEDED'
    description: Changes the build or CI
  stale:
    name: stale
    color: 'CFD3D7'

labelling:
  web:
    label: web
    on: [pullRequest]
    when:
      condition:
        - type: filesMatch
          condition: 'apps/web/**'
  api:
    label: api
    on: [pullRequest]
    when:
      condition:
        - type: filesMatch
          condition: 'apps/api/**'
  shared:
    label: shared
    on: [pullRequest]
    when:
      condition:
        - type: filesMatch
          condition: 'packages/**'
  ci:
    label: ci
    on: [pullRequest]
    when:
      condition:
        - type: filesMatch
          condition: '.github/workflows/**'

sizeLabels: {}

# The scope in "feat(web): ..." must name a package, so the changelog groups by package.
conventions:
  rules:
    title:
      on: [pullRequest]
      preset: conventionalCommits
      contexts: [web, api, shared, ci, deps, release]

# Branch names carry the author and the issue, such as ann/app-142-login-form.
branches:
  names:
    tracked:
      preset: prefixed
      pattern: '/[a-z]+-\d+/i'
  exempt:
    branches: ['^dependabot/', '^renovate/', '^smartcloud/']

# Owners per package, written into CODEOWNERS for you.
codeowners:
  rules:
    everything:
      paths: ['*']
      owners: ['@my-org/maintainers']
    web:
      comment: The web app
      paths: [/apps/web/]
      owners: ['@my-org/frontend']
    api:
      comment: The API
      paths: [/apps/api/]
      owners: ['@my-org/backend']

# Ask one owner of the changed package for a review, in turn.
reviews:
  requestApprovals:
    owners:
      reviewers: []
      strategy: codeowners
      count: 1
      when:
        condition:
          - type: isDraft
            condition: false

# The aggregate waits for the CI job and gives a long test suite time.
required:
  expect: ['^ci$']
  timeout: 90

stale:
  on: [pullRequest]
  staleAfterDays: 21
  staleLabel: stale
  staleComment: No activity for three weeks. Push, comment or /stale-snooze to keep this open.
  abandonedAfterDays: 14
  close: true

commands: {}

Section	Why it is there	What happens when it runs
labels and labelling	One pkg: label per app or package, applied by the paths a pull request changes, so the list of pull requests can be filtered by package.	A pull request that changes apps/web/ and packages/ gets pkg: web and pkg: shared.
conventions contexts	The scope in feat(web): ... must name a real package, so release notes and changelogs group changes correctly.	feat(frontend): ... fails, because frontend is not in contexts; feat(web): ... passes.
branches	Branch names carry the author and an issue key (ann/app-142-login-form), so every branch leads back to its issue.	A branch called patch-1 fails smartcloud / branches. Dependabot, Renovate and smartcloud’s own branches are exempt.
codeowners	The owners of each package are written into CODEOWNERS from the config, and CODEOWNERS is checked for lines GitHub would silently ignore.	On a push, if CODEOWNERS is out of date, a pull request from smartcloud/codeowners updates its marked block.
reviews.requestApprovals	One owner of the changed package is asked to review, rather than every owner of every package.	When a pull request is ready for review, one owner from CODEOWNERS is requested; drafts wait.
required	Monorepo CI often runs many jobs; the ruleset requires smartcloud alone, and expect makes sure the ci job ran at all.	The smartcloud check waits up to 90 minutes for every other check, and fails if ci never appeared.
stale	Pull requests that stall block others in a busy repository; three weeks is a nudge, five a close.	Daily: quiet pull requests get stale, then close two weeks later unless someone pushes or comments /stale-snooze.

Change the package names, the team names (@my-org/frontend) and the ^ci$ pattern to your CI job’s name. strategy: codeowners needs a CODEOWNERS file on the base branch, which the codeowners section writes for you.

An open-source project

Good for: a public project where anyone can open a pull request. You want a clear, fair bar for contributions (sign-off, disclosure of AI help, maintainer review), a welcoming first experience, and settings nobody can quietly change.

.github/smartcloud.yml

# yaml-language-server: $schema=https://raw.githubusercontent.com/Resnovas/smartcloud/main/schema/smartcloud.schema.json
version: 2

# Two or more maintainers turn the review gate and ruleset approvals on.
roles:
  maintainers: [octocat, hubot]
  trustedBots: ['dependabot[bot]', 'renovate[bot]', 'github-actions[bot]']

# Findings link to your own CONTRIBUTING.md, GOVERNANCE.md and AI_POLICY.md.
links:
  policyBase: https://github.com/my-org/my-project/blob/main

labels:
  bug:
    name: bug
    color: 'D73A4A'
  feature:
    name: enhancement
    color: 'A2EEEF'
  good-first-issue:
    name: good first issue
    color: '7057FF'
    description: A small, well-described task for a newcomer
  first-contribution:
    name: first contribution
    color: 'C2E0C6'
    description: The author's first pull request here; be welcoming
  needs-triage:
    name: needs triage
    color: 'FBCA04'
    description: A maintainer has not looked at this yet
  stale:
    name: stale
    color: 'CFD3D7'
  pinned:
    name: pinned
    color: '0E8A16'
    description: Never marked stale

labelling:
  first-contribution:
    label: first-contribution
    on: [pullRequest]
    when:
      condition:
        - type: authorAssociation
          condition: [firstTimeContributor, firstTimer]
  needs-triage:
    label: needs-triage
    on: [issue]
    when:
      condition:
        - type: hasAssignee
          condition: false
        - type: hasMilestone
          condition: false

sizeLabels: {}

conventions:
  rules:
    title:
      on: [pullRequest]
      preset: conventionalCommits
    linked-issue:
      on: [pullRequest]
      level: warning
      message: Link the issue this pull request fixes, for example "Fixes #123".
      when:
        condition:
          - type: linksIssue
            condition: true

# Every commit is signed off (DCO), and AI help is credited.
commits:
  dco: true
  aiAttribution: true

# The pull request template asks how AI was used; this checks the answer.
disclosure:
  requireDraft: true

# Two maintainer approvals for an outside pull request, one for a maintainer's own.
reviews:
  gate:
    outside: 2
    maintainer: 1
  # Ask one maintainer, in turn, to review each pull request once it is ready.
  requestApprovals:
    triage:
      reviewers: [octocat, hubot]
      strategy: round-robin
      when:
        condition:
          - type: isDraft
            condition: false

required:
  expect: ['^test$']

stale:
  staleAfterDays: 60
  staleLabel: stale
  staleComment: This has had no activity for 60 days. Comment, or ask a maintainer to add "pinned", to keep it open.
  abandonedAfterDays: 30
  close: true
  exempt:
    labels: [pinned, good first issue, security]

lock:
  afterDays: 60
  reason: resolved
  comment: Closed for 60 days, so this conversation is now locked. Please open a new issue and link this one.

commands:
  overrides:
    merge: { enabled: false }

# Needs a GitHub App token: see the note below this example.
settings:
  merging:
    mergeCommit: false
    squash: true
    rebase: false
    autoMerge: true
    deleteBranchOnMerge: true
    squashTitle: PR_TITLE
    squashMessage: COMMIT_MESSAGES
  features:
    wiki: false
    discussions: true
  security:
    privateVulnerabilityReporting: true
    dependabotAlerts: true
    dependabotSecurityUpdates: true
    secretScanning: true
  ruleset:
    blockDeletion: true
    blockForcePush: true
    pullRequest:
      requiredApprovals: 1
      dismissStaleReviews: true
      conversationResolution: true
      mergeMethods: [squash]
    statusChecks:
      checks:
        smartcloud: true
        test: true
  actions:
    workflowPermissions: read

Section	Why it is there	What happens when it runs
roles	With two maintainers listed, the review gate and ruleset approvals switch on. Bots that open routine pull requests are trusted.	Nothing on its own; the gate and the ruleset read it.
links	Findings link to your contributing guide and policies rather than the default ones.	Every finding in the report comment links to a page under this URL, such as CONTRIBUTING.md#dco.
labelling	first contribution reminds reviewers to be welcoming; needs triage marks issues nobody has picked up.	A newcomer’s pull request is labelled on opening; a new issue with no assignee and no milestone gets needs triage.
conventions	Conventional titles, plus a gentle warning when a pull request does not link the issue it fixes.	A missing Fixes #123 shows as a warning, which does not block merging.
commits	The DCO sign-off records that each contributor may submit their change; AI attribution keeps AI help visible in history.	A commit without Signed-off-by: fails smartcloud / commits with the command to fix it.
disclosure	Reviewers know how a change was made before reading it, and AI-assisted pull requests start as drafts. Add the fields to your pull request template.	A pull request without the disclosure fields fails smartcloud / disclosure, listing what is missing.
reviews	Two maintainer approvals for an outside pull request, one for a maintainer’s own; each ready pull request goes to one maintainer in turn.	smartcloud / reviews fails until enough maintainers approve; a reviewer is requested when the pull request leaves draft.
required	The ruleset requires smartcloud and test, and smartcloud waits for everything else.	The smartcloud check passes only when every check, including test, has passed.
stale and lock	Keeps the issue list honest without closing things people care about: pinned and good first issue are exempt.	Daily sweeps, with a comment each time so nobody is surprised.
commands	Maintainers and triagers work from comments; /merge is off so everything goes through the review gate and the ruleset.	/merge replies that it is turned off; the other commands work for the right roles.
settings	Merge buttons, security features and the default branch ruleset are kept as code, so a changed setting is put back on the next run.	On a push to main and daily, smartcloud changes only what differs and lists each change in the job summary.

Things to know for an open-source project:

• Pull requests from forks run restricted. GitHub gives them a read-only token, so smartcloud cannot request reviewers or post some comments there. It records a warning instead of failing, and the checks still run. The review gate and required checks still protect the merge.
• settings needs a GitHub App. Until you add one, the section is skipped with a notice, and everything else works. Preview the changes with smartcloud plan settings.
• secretScanning and privateVulnerabilityReporting only apply to public repositories. On a private one smartcloud leaves them and records a notice.
• Write the pull request template first. disclosure expects the AI level:, AI tools:, Accountable human: and Human review: fields; see Disclosure.

An organisation with a shared preset

Good for: an organisation with many repositories that should all follow the same rules. The shared rules live once, in a preset in the organisation’s .github repository, and each repository’s own file holds only what makes it different.

The preset, in my-org/.github:

my-org/.github/smartcloud/base.yml

# yaml-language-server: $schema=https://raw.githubusercontent.com/Resnovas/smartcloud/main/schema/smartcloud.schema.json
# my-org/.github/smartcloud/base.yml: the rules every my-org repository shares.
version: 2

roles:
  maintainers: [octocat, hubot]
  trustedBots: ['dependabot[bot]', 'renovate[bot]', 'github-actions[bot]', 'my-org-bot[bot]']

links:
  policyBase: https://github.com/my-org/.github/blob/main

labels:
  bug:
    name: bug
    color: 'D73A4A'
    description: Something is not working
  feature:
    name: enhancement
    color: 'A2EEEF'
    description: New feature or request
  docs:
    name: documentation
    color: '0075CA'
  dependencies:
    name: dependencies
    color: '0366D6'
  org-sync:
    name: org-sync
    color: 'EDEDED'
    description: Automated update from my-org/.github

labelling:
  docs:
    label: docs
    on: [pullRequest]
    when:
      condition:
        - type: filesMatch
          condition: '**/*.md'
  dependencies:
    label: dependencies
    on: [pullRequest]
    when:
      condition:
        - type: lockfileChanged
          condition: true

  # smartcloud's sync pull requests come from the org/sync branch (sync.branch below).
  org-sync:
    label: org-sync
    on: [pullRequest]
    when:
      condition:
        - type: branchMatches
          condition: '^org/sync$'

sizeLabels: {}

conventions:
  rules:
    title:
      on: [pullRequest]
      preset: conventionalCommits

commits:
  dco: true

reviews:
  gate:
    outside: 2
    maintainer: 1

required: {}

settings:
  merging:
    mergeCommit: false
    squash: true
    rebase: true
    autoMerge: true
    deleteBranchOnMerge: true
    webCommitSignoff: true
  features:
    wiki: false
  security:
    dependabotAlerts: true
    dependabotSecurityUpdates: true
  ruleset:
    name: 'my-org: default branch'
    blockDeletion: true
    blockForcePush: true
    pullRequest:
      requiredApprovals: 1
      dismissStaleReviews: true
    statusChecks:
      checks:
        smartcloud: true
  actions:
    workflowPermissions: read

sync:
  source: my-org/.github/templates@main
  branch: org/sync
  check: true
  values:
    ORG_NAME: My Org
    COPYRIGHT_HOLDER: My Org Ltd
    SECURITY_EMAIL: [e-mail]

Each repository’s own file:

.github/smartcloud.yml

# yaml-language-server: $schema=https://raw.githubusercontent.com/Resnovas/smartcloud/main/schema/smartcloud.schema.json
version: 2

# Everything in the organisation's preset applies here, locked.
extends:
  - my-org/.github/smartcloud/base.yml@main

# The preset leaves these open: this repository deploys, and has its own CI job.
settings:
  environments:
    projectType: saas
  ruleset:
    requiredDeployments: [Staging]
    statusChecks:
      checks:
        ci: true

# The aggregate smartcloud check must see the ci job.
required:
  expect: ['^ci$']

# A label only this repository needs, next to the preset's.
labels:
  api:
    name: 'area: api'
    color: '5319E7'

labelling:
  api:
    label: api
    on: [pullRequest]
    when:
      condition:
        - type: filesMatch
          condition: 'src/api/**'

# Keep our own LICENSE, and fill in a value the templates ask each repository for.
sync:
  exclude:
    - LICENSE
  values:
    PROJECT_TYPE: saas

# The preset has no stale section, so this repository chooses its own.
stale:
  on: [pullRequest]
  staleAfterDays: 30
  staleLabel: stale

Where	Section	Why it is there
Preset	roles, links	The same maintainers, bots and policy documents everywhere. A repository cannot change them.
Preset	labels, labelling, sizeLabels	The same labels and automatic labelling in every repository, so organisation-wide searches such as label:bug work.
Preset	conventions, commits, reviews	The contribution bar, set once. Because presets are locked, no repository can quietly weaken it.
Preset	required, settings	Every repository gets the same merge buttons and default branch ruleset, requiring the smartcloud aggregate check.
Preset	sync	Shared files come from my-org/.github/templates; org-sync labels the sync pull requests. See Your organisation’s sync hub.
Repository	extends	Pulls in the preset. @main means a change to the preset reaches every repository on its next run.
Repository	settings.environments, settings.ruleset	What the preset leaves open on purpose: this repository deploys, so it has environments, and its ci job is required too.
Repository	required.expect	The aggregate check must see this repository’s own CI job.
Repository	labels, labelling	An extra label only this repository needs, next to the preset’s.
Repository	sync.exclude, sync.values	This repository keeps its own LICENSE, and fills in a value the templates ask for but the preset leaves to each repository.
Repository	stale	A section the preset does not set at all, so the repository chooses it freely.

How the two files combine, and what you may and may not do in the repository’s file:

• The preset is read first, then the repository’s file is laid on top (How files are merged).
• Adding is fine: a new label, a new rule, a key the preset left unset (such as settings.environments), a new entry in a map (such as settings.ruleset.statusChecks.checks.ci).
• Changing is not: giving labels.bug.color another value, or a different roles.maintainers list, fails the run with cannot change "...": it is set by .... Change the preset instead, and every repository follows.
• Leave keys unset in the preset on purpose when each repository must decide them, and say so in a comment at the top of the preset.

The preset needs a token that can read it. Make the .github repository public, or use a GitHub App installed on every repository; settings and sync need the app either way. Your organisation’s sync hub sets all of this up step by step.

Next steps

Build your settings file

Every section in the order to add it, and what each does when it runs.

Your organisation's sync hub

Make your own .github repository the source of presets and shared files.