Migrating from v1

v2 replaces v1’s runners and per-context JSON with one flat YAML file where each feature has its own section. smartcloud migrate converts a v1 config for you, and warns about every v1 key it does not carry over.

Convert the config

smartcloud migrate .github/config.json --out .github/smartcloud.yml

See CLI for how to run the command. Read every warning it prints.

Review the result

Rule keys are generated from v1’s contexts and positions, such as pr.xs or shared.0. Rename them if you like: keys only need to be unique. Then add the v2 features v1 did not have, such as commits or reviews gate.

Validate

smartcloud validate

Switch the workflow

Point the workflow at resnovas/smartcloud@v2, as in the quick start, and delete .github/config.json.

Until you switch, v2 still reads a v1 config: a file without version: 2 is migrated on the fly on every run, with the same warnings. Converting once keeps the warnings out of your runs and lets you use v2’s own sections.

What maps where

v1	v2
`labels` (a list or a map)	`labels`, keyed by the v1 key, or for a list by the label’s name in lower case with other characters replaced by `-`.
`runners[].<context>.labels`	`labelling`, one rule per label keyed `<context>.<label>`.
`runners[].<context>.enforceConventions`	`conventions.rules`, keyed `<context>.<position>`. The named conventions `semanticTitle`, `gitmojis` and `semanticEmoji` become a `preset`; condition lists become `when`. `failedComment` becomes `message`, and `contexts` is kept.
`enforceConventions.commentHeader`, `commentFooter`	`conventions.comment.header`, `footer`.
`runners[].<context>.stale`	`stale`. `stale.days` becomes `staleAfterDays` (default 60), `abandoned.days` becomes `abandonedAfterDays`, and the comments and labels carry over.
`runners[].<context>.automaticApprove`	`reviews.automaticApprove`, keyed `<context>.<position>`.
`runners[].<context>.requestApprovals`	`reviews.requestApprovals`, keyed `<context>.<name>`.
The `skipDelete` action input	`labelSync.prune`. v2 never deletes labels unless `prune` is `true`.
The `fillEmpty` action input	`extends`. Shared settings now come from presets; the input is ignored with a warning.
The `config: .github/config.json` input	Nothing. v2 finds `.github/config.json` on its own and migrates it on the fly, with a warning for each dropped key, until you commit `.github/smartcloud.yml`.

v1’s contexts become the on of each rule: pr rules get on: [pullRequest], issue rules get on: [issue], and sharedConfig and schedule rules apply to both. In keys, sharedConfig is written shared. With more than one runner, keys are prefixed r0., r1. and so on so none collide. v1 conditions carry over unchanged: v2 keeps the same field names, pattern forms and $not shapes. See Conditions.

What is dropped

v1 key	Why
`versioning`, `prereleaseName`, `manageRelease`	Versioning and releases belong to release-please, as the v1 README advised.
`duplicateHotfix`, `createMilestone`, `assignMilestone`, `createBranch`, `openBranch`	v1 never implemented them.
`assignProject`, the `project` context, `onColumn`, `moveToColumn`	They used classic Projects, which GitHub has retired.
`syncRemote`	It used classic Projects or was never implemented.
`root`	v1 never read it.
`branch`	v2 runs on the event it receives.
`retryLimit`	v2 retries GitHub API calls itself.
`$schema`	v2 uses its own schema.

Any other key is reported as unknown and ignored. v2 has a single stale section, so a second stale in another context is dropped with a warning.

Check your stale labels

stale.staleLabel and stale.abandonedLabel are label names as GitHub shows them, not keys of labels. If your v1 config gave the stale label a different display name, for example a stale entry named Status - Stale, set staleLabel to that name.

Example: labels only

The Eventiva config defines labels and nothing else. Two of its ten labels:

.github/config.json

{
  "labels": [
    {
      "name": "type:core",
      "color": "0E8A16",
      "description": "Core module - can be depended on by any other module"
    },
    {
      "name": "layer:backend",
      "color": "5319E7",
      "description": "Backend layer - can depend on backend and shared layers"
    }
  ]
}

smartcloud migrate output for those two, with no warnings:

.github/smartcloud.yml

# yaml-language-server: $schema=https://raw.githubusercontent.com/Resnovas/smartcloud/main/schema/smartcloud.schema.json
version: 2
labels:
  type:core:
    name: type:core
    color: 0E8A16
    description: Core module - can be depended on by any other module
  layer:backend:
    name: layer:backend
    color: "5319E7"
    description: Backend layer - can depend on backend and shared layers

The list becomes a map keyed by each label’s name. A colour that YAML would read as a number, such as 5319E7, is quoted.

Example: a full v1 config

The v1 smartcloud config uses one runner with sharedConfig, pr, issue and schedule contexts, 94 labels, labelling rules, a convention, approvals and stale handling. The excerpts below are from the real smartcloud migrate output.

Labelling

"sharedConfig": {
  "labels": {
    "bug": {
      "requires": 1,
      "condition": [
        { "type": "titleMatches", "condition": "/^bug(\\(.*\\))?(!)?:/i" },
        { "type": "descriptionMatches", "condition": "/(created|new|opened|made)( an| a)? bug/i" }
      ]
    }
  }
},
"pr": {
  "labels": {
    "xs": { "requires": 1, "condition": [{ "type": "changesSize", "min": 0, "max": 10 }] }
  }
}

labelling:
  shared.bug:
    label: bug
    when:
      requires: 1
      condition:
        - type: titleMatches
          condition: /^bug(\(.*\))?(!)?:/i
        - type: descriptionMatches
          condition: /(created|new|opened|made)( an| a)? bug/i
  pr.xs:
    label: xs
    on:
      - pullRequest
    when:
      requires: 1
      condition:
        - type: changesSize
          min: 0
          max: 10

Conventions, approvals and stale

"sharedConfig": {
  "enforceConventions": {
    "condition": [{ "requires": 1, "condition": "semanticEmoji" }]
  },
  "stale": {
    "staleLabel": "stale",
    "stale": { "days": 60, "comment": "This has been automatically marked as stale by the bot." },
    "abandoned": { "days": 30, "label": "abandoned", "comment": "This has been automatically marked as abandoned by the bot." }
  }
},
"pr": {
  "automaticApprove": {
    "condition": [
      { "requires": 1, "condition": [{ "type": "creatorMatches", "condition": "/^dependabot/i" }] }
    ]
  },
  "requestApprovals": {
    "all": {
      "reviewers": ["tgtgamer"],
      "requires": 1,
      "condition": [
        { "type": "$not", "requires": 1, "condition": [{ "type": "creatorMatches", "condition": "/^dependabot/i" }] }
      ]
    }
  }
}

conventions:
  rules:
    shared.0:
      preset: semanticEmoji
reviews:
  requestApprovals:
    pr.all:
      reviewers:
        - tgtgamer
      when:
        requires: 1
        condition:
          - type: $not
            requires: 1
            condition:
              - type: creatorMatches
                condition: /^dependabot/i
  automaticApprove:
    pr.0:
      when:
        requires: 1
        condition:
          - type: creatorMatches
            condition: /^dependabot/i
stale:
  staleAfterDays: 60
  staleLabel: stale
  staleComment: This has been automatically marked as stale by the bot.
  abandonedAfterDays: 30
  abandonedLabel: abandoned
  abandonedComment: This has been automatically marked as abandoned by the bot.

Warnings

The run printed these warnings for the keys it did not carry over:

warning: .github/config.json: runners[0].$schema: dropped, v2 uses its own schema
warning: .github/config.json: runners[0].root: dropped, v1 never read it
warning: .github/config.json: runners[0].versioning: dropped, version bumping is release-please territory, as the v1 README advised
warning: .github/config.json: runners[0].prereleaseName: dropped, version bumping is release-please territory, as the v1 README advised
warning: .github/config.json: runners[0].pr.manageRelease: dropped, releases are release-please territory, as the v1 README advised
warning: .github/config.json: runners[0].pr.duplicateHotfix: dropped, v1 never implemented it
warning: .github/config.json: runners[0].pr.createMilestone: dropped, v1 never implemented it
warning: .github/config.json: runners[0].issue.createBranch: dropped, v1 never implemented it

In this config the stale label entry is named Status - Stale, while staleLabel is stale: see Check your stale labels.

Getting started

Features

Running smartcloud

Maintaining smartcloud

What maps where

What is dropped

Check your stale labels

Example: labels only

Example: a full v1 config

Labelling

Conventions, approvals and stale

Warnings

​What maps where

​What is dropped

​Check your stale labels

​Example: labels only

​Example: a full v1 config

​Labelling

​Conventions, approvals and stale

​Warnings

What maps where

What is dropped

Check your stale labels

Example: labels only

Example: a full v1 config

Labelling

Conventions, approvals and stale

Warnings