> ## 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.
# Introduction
> What smartcloud does, and how to run it in a repository.
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.
The config file, shared presets and the "add, never change" rule.
The condition language that labelling, conventions and reviews use.
Check runs, the single comment and the job summary.
Convert `.github/config.json` with `smartcloud migrate`.
## Quick start
Create `.github/smartcloud.yml`. This one keeps two labels in sync, labels documentation changes, and asks for conventional commit titles:
```yaml .github/smartcloud.yml theme={null}
# 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.
```sh theme={null}
smartcloud validate
```
Validation reads every preset the config extends and reports anything the schema rejects. See [CLI](/cli) for how to run it.
Add a workflow that runs smartcloud on the events its features act on:
```yaml .github/workflows/smartcloud.yml theme={null}
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. |
| `statuses: read` | Only for the [required](/features/required) feature, which reads the commit statuses as well as the check runs. |
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:
```yaml theme={null}
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](/reporting#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](/reporting#restricted-runs), acts with it on forks and Dependabot runs, and reads the pull request's checks with it for the required feature, since `GITHUB_TOKEN` can be a personal access token without checks and statuses read. |
| `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`. |
| `checkRunId` | none | The job's own check run, as `${{ job.check_run_id }}` gives it. The [required](/features/required) feature runs only when it is set, so it can wait for every other check and leave this job out. |
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](/migration).
## 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.