Introduction

smartcloud is a GitHub Action that automates repository housekeeping and enforces contribution policy from one declarative file, .github/smartcloud.yml. It labels pull requests and issues, checks titles and commits, gates reviews, marks inactive work stale, keeps repository settings in line, and syncs shared files from a template repository. Each capability is a feature with its own section in the config. A feature whose section is absent does not run, so you opt in to exactly what you need.

Configuration

The config file, shared presets and the “add, never change” rule.

Conditions

The condition language that labelling, conventions and reviews use.

Reporting

Check runs, the single comment and the job summary.

Migrating from v1

Convert .github/config.json with smartcloud migrate.

Quick start

Write a config

Create .github/smartcloud.yml. This one keeps two labels in sync, labels documentation changes, and asks for conventional commit titles:

.github/smartcloud.yml

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

labels:
  docs:
    name: documentation
    color: 0075CA
    description: Improvements or additions to documentation
  bug:
    name: bug
    color: D73A4A

labelling:
  docs:
    label: docs
    on: [pullRequest]
    when:
      condition:
        - type: filesMatch
          condition: "docs/**"

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

The first line points editors at the JSON Schema, so they complete and check keys as you type.

Check it locally

smartcloud validate

Validation reads every preset the config extends and reports anything the schema rejects. See CLI for how to run it.

Add the workflow

Add a workflow that runs smartcloud on the events its features act on:

.github/workflows/smartcloud.yml

name: smartcloud

on:
  pull_request:
    types: [opened, edited, synchronize, reopened, ready_for_review, converted_to_draft]
  pull_request_review:
    types: [submitted, dismissed]
  issues:
    types: [opened, edited, reopened, labeled, unlabeled]
  push:
    branches: [main]
  schedule:
    - cron: "0 6 * * *"
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write
  checks: write
  issues: write

jobs:
  smartcloud:
    runs-on: ubuntu-latest
    steps:
      - uses: resnovas/smartcloud@v2

Permissions

Permission	Why smartcloud needs it
`contents: write`	The sync feature pushes a branch with synced files. Reading presets and templates needs at least `read`.
`pull-requests: write`	Labels, review requests, automatic approvals and the report comment on pull requests.
`checks: write`	One check run per feature on the commit.
`issues: write`	Labels, stale comments and the report comment on issues. Repository labels are managed through this permission too.

The settings feature changes repository administration settings, and the sync feature reads its source from another repository and may push workflow files, which the workflow token cannot do. Pass a stronger token as GITHUB_TOKEN, with the workflow token as the fallback. A GitHub App token is best: GitHub signs the commits smartcloud makes with it, it can create check runs, and its rate limit is the app’s own. Mint it with actions/create-github-app-token, and skip that step where the key is missing, as on forks and Dependabot runs:

steps:
  - id: app
    if: >-
      (!github.event.pull_request || github.event.pull_request.head.repo.full_name == github.repository)
      && github.actor != 'dependabot[bot]' && github.event.pull_request.user.login != 'dependabot[bot]'
    continue-on-error: true
    uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
    with:
      # GitHub accepts the App ID wherever the client ID is asked for.
      client-id: ${{ vars.APP_ID }}
      private-key: ${{ secrets.APP_PRIVATE_KEY }}
      # The token covers only the repositories named here: add the ones your
      # presets and sync sources live in.
      owner: ${{ github.repository_owner }}
      repositories: ${{ github.event.repository.name }},.github
  - uses: resnovas/smartcloud@v2
    with:
      GITHUB_TOKEN: ${{ steps.app.outputs.token || github.token }}

Never mint the token in a job that runs pull request code; smartcloud’s own job runs a release, not the pull request.

A run with only the workflow token is restricted rather than failed: smartcloud skips settings, sync, private presets in other repositories and every write GitHub refuses, and lists them in the job summary. Pull requests from forks, and Dependabot’s runs and pull requests (even when a person reviews them), are always restricted, whatever token the workflow passes; see Restricted runs.

Action inputs

Every input is optional.

Input	Default	What it does
`GITHUB_TOKEN`	`${{ github.token }}`	The token smartcloud acts with. Settings, sync and private presets in other repositories need a stronger token than the workflow token.
`workflowToken`	`${{ github.token }}`	The workflow’s own token. Leave it at its default: smartcloud compares `GITHUB_TOKEN` with it to tell a restricted run, and acts with it on forks and Dependabot runs.
`config`	the first of `.github/smartcloud.yml`, `.github/smartcloud.yaml`, `.github/config.json`	The config file’s path in the repository.
`configJson`	none	The config given inline, as YAML or JSON. Wins over the file.
`configRef`	the default branch	The branch, tag or commit to read the config from.
`dryRun`	`false`	Record every write in the job summary instead of making it.
`features`	every configured feature	A comma-separated list of the features to run, for example `labels,stale`.

The config is read through the GitHub API, so the workflow needs no checkout step. It comes from the default branch unless configRef says otherwise, so a pull request cannot loosen the rules it is checked against. The run fails when any finding is an error or a feature fails to run. Any other failure, such as a missing config, is one error annotation, never a stack trace. The v1 inputs fillEmpty and skipDelete are still accepted and ignored with a warning. See Migrating from v1.

Which events run which features

Event	Features
`pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment`	conventions, commits, disclosure, reviews, labels (labelling rules), sync (the edit check)
`issues`, `issue_comment` on an issue	conventions, labels (labelling rules)
`push`	labels (label sync), settings, sync
`schedule`, `workflow_dispatch`	labels (label sync), stale, settings, sync
`repository_dispatch`, `merge_group`	labels (label sync)

Any other event is a clean no-op that records a notice. A comment on a pull request carries no pull request data, so smartcloud acts on the pull request events instead.

Getting started

Features

Running smartcloud

Maintaining smartcloud

Configuration

Conditions

Reporting

Migrating from v1

Quick start

Permissions

Action inputs

Which events run which features

Configuration

Conditions

Reporting

Migrating from v1

​Quick start

​Permissions

​Action inputs

​Which events run which features

Quick start

Permissions

Action inputs

Which events run which features