Configuration file

One YAML file describes every label you want and which repositories should have them. It is the source of truth: labelsync reconciles repositories towards it and never the other way round.

labelsync init writes a working example, and labelsync export <owner/repo> writes one from a repository that already has labels — which is where to start if any of your repositories do. How the loader implements all of this is in Architecture § Configuration.

Where the file is found

Without --config, the file is searched for in this order:

1. ./labels.yml or ./labels.yaml in the working directory
2. $XDG_CONFIG_HOME/labelsync/labels.yml (default ~/.config/labelsync/labels.yml)

Both spellings in one directory is an error rather than a coin flip — in either directory, even when the other one holds a perfectly good file. The ETag cache lives under $XDG_CACHE_HOME/labelsync (default ~/.cache/labelsync).

--config takes a file or a directory: --config ./ops searches ./ops for both spellings, the same way the working directory is searched.

A complete example

version: 1

# ── Which repositories ────────────────────────────────────────────────
groups:
  specs-all:
    org: specsnl
    exclude: ["*-archive", "sandbox-*"]
    skip_archived: true          # default: true
    skip_forks: true             # default: true
    visibility: all              # all | public | private   (default: all)

  laravel:
    repos:
      - specsnl/example-website
      - specsnl/example-platform

  personal:
    user: Ilyes512
    include: ["boilr-*", "docker-php-*"]

  everything:
    include_groups: [specs-all, personal]

# ── Groups for labels that name none of their own ─────────────────────
defaults:
  groups: [specs-all]

# ── Renames, applied first, preserving issue/PR associations ──────────
renames:
  - from: "bug"
    to: "type: bug"
  - from: "enhancement"
    to: "type: feature"

# ── The labels ────────────────────────────────────────────────────────
labels:
  - name: "type: bug"
    color: "d73a4a"
    description: "Something isn't working"

  - name: "type: feature"
    color: "0e8a16"
    description: "New functionality"

  - name: "priority: high"
    color: "b60205"

  - name: "laravel"
    color: "ff2d20"
    description: "Laravel-specific"
    groups: [laravel, personal]

Top-level keys

version has to be named rather than guessed: a file with no version is rejected, so a future schema change can be introduced without having to infer which one an existing file meant.

labels

Descriptions are authoritative, and that is the one thing to know before a first run. Omitting description does not mean “leave it alone”; it means “the description is empty”, and the next sync makes it so. Run export first and the descriptions you already have are in the file, so this never happens by accident.

Both length bounds are GitHub’s own and count characters, not bytes — a description of 100 emoji is exactly at the limit, the same as 100 letters.

Colours have to be unique across the whole file, not per repository. That is what lets the planner treat a colour as an identity: an unconfigured label found sitting on a configured colour is moved off it, onto a colour of its own from the generated palette.

groups

A group has exactly one source — org, user, repos, or include_groups. Setting two is an error, and so is setting none.

• include and exclude are globs over the repository name only, never owner/repo, and match case-insensitively — GitHub’s names do too. exclude runs after include.
• The five filter fields apply to org and user groups. A repos entry names a repository outright and is never filtered out from under you.
• include_groups is a union, and it may nest. Two groups including each other is an error, and the message prints the whole chain — a -> b -> c -> a.
• user sees private repositories only for the account the token belongs to. Asking for visibility: private for anybody else selects nothing, and says so on stderr rather than quietly doing nothing.

The rule the whole tool rests on: a repository gets every label whose groups contain a group that selects it — and if no group selects a repository, labelsync never touches it.

labelsync groups prints what each group actually resolves to, and on stderr why each filtered repository was dropped. Run it whenever a selector is doing something you did not expect.

defaults

defaults:
  groups: [specs-all]

A label with no groups: of its own gets these. It is the difference between repeating the same groups: [specs-all] on forty labels and writing it once — nothing more. A label that names its own groups ignores defaults entirely rather than adding to it.

renames

renames:
  - from: "bug"
    to: "type: bug"

A rename moves an existing label onto a configured name without losing anything: it becomes a PATCH carrying new_name, so the label keeps its id and every issue and pull request that carried it still carries it. A delete plus a create would look identical in the label list and would strip the label from all of them.

Both halves are needed. The renames: entry says which existing label to move; a labels: entry for the new name is what it is moved onto — a rename whose to: no label declares is rejected, because it would land on nothing.

Three rules decide whether a rename happens, and all three compare names case-insensitively, because GitHub’s label identity does:

Because a rename whose from no longer exists is skipped silently, an entry can be left in the file indefinitely: it is a migration that has already happened, and it is also what migrates the repository you add to the group next month. The worked end-to-end recipe is in Commands § Renaming labels.

That is why labelsync’s own labels.yml carries bug → type: bug and enhancement → type: feature: GitHub creates those two in every new repository, and both entries are already inert here — the targets exist — while being the thing that migrates the next repository instead of unlabelling its issues.

A case-only rename such as bug → Bug is rejected, and needs no entry: casing drift is converged anyway, by the same mechanism and with the same associations kept.

What is tidied up as the file is read

A few things are accepted in more than one spelling and mean the same thing, so export, edit, export shows your edits and nothing else:

Names are trimmed before any validation, so " bug " and "bug" are the same name, and a name that only fits within 50 characters once trimmed is fine.

What makes a file invalid

The whole file is checked as it is read, before any request is sent, and the run stops at the first problem with the rule it broke. Every rule here is one GitHub enforces anyway; checking locally is what turns a 422 halfway through a run into a message naming the line to fix.

labelsync init writes a file that satisfies every one of these, which is the quickest way to see what a valid one looks like. The scaffold goes through the same rules as part of the test suite, so it can never hand you a file the next command rejects.

Under --output=json, each of these carries a stable error_kind — duplicate_label_name, invalid_color, cyclic_group, and so on. The full list is in Error Handling.