GitHub Labels¶
xfg can manage GitHub labels declaratively using the sync command. Define labels in your config file, and xfg will create, update, rename, or delete them to match your desired state.
GitHub-Only Feature
Labels are only available for GitHub repositories. Azure DevOps and GitLab repos will be skipped when running xfg sync.
Quick Start¶
id: my-config
settings:
labels:
bug:
color: d73a4a
description: "Something isn't working"
enhancement:
color: a2eeef
description: "New feature or request"
documentation:
color: "0075ca"
description: "Improvements or additions to documentation"
repos:
- git: git@github.com:your-org/your-repo.git
# Preview changes (dry-run)
xfg sync -c config.yaml --dry-run
# Apply labels
xfg sync -c config.yaml
Label Properties¶
| Property | Required | Description |
|---|---|---|
color |
Yes | Hex color code, with or without # (e.g., d73a4a or #d73a4a) |
description |
No | Label description (max 100 characters) |
new_name |
No | Rename the label to this value |
Color Format¶
Colors can be specified with or without the # prefix. Both are normalized to bare hex during processing:
Renaming Labels¶
Use new_name to rename an existing label:
Once the rename has run, replace the entry with the new name:
Syncs that run before you do are safe. When the old label does not exist and new-label-name does, xfg treats the rename as done: the label is unchanged, or updated if its color or description differ from the entry, and it is never deleted as an orphan. If neither label exists, xfg creates new-label-name.
If both labels exist, xfg stops with a rename collision error and changes nothing, even when deleteOrphaned would delete new-label-name. Delete or rename the existing new-label-name yourself first.
When a new_name target is also the key of another entry with its own new_name (a to b plus b to c, or x to old while old still has new_name), the labels step fails for each repo with a Rename chain error and changes nothing. Run such renames in separate syncs, replacing each entry with its new name once it has been applied.
Deleting Orphaned Labels¶
When deleteOrphaned: true is set, every label in the repository that is not in the config is deleted, including labels created manually or by other tools. Labels named by a new_name whose source label is already renamed count as in the config:
Warning
Orphan detection compares the repository's labels with the config, not with a manifest of labels xfg created. List every label you want to keep, or leave deleteOrphaned unset. Use --no-delete to skip deletions for a run.
Inheritance¶
Labels from conditional groups merge after explicit group labels and before repo overrides. Per-repo inherit: false discards all inherited labels including those from conditional groups.
Labels support the same inheritance pattern as rulesets. Root-level labels are inherited by all repos:
id: labels
settings:
labels:
bug:
color: d73a4a
description: "Something isn't working"
enhancement:
color: a2eeef
repos:
- git: git@github.com:your-org/repo-a.git
# Inherits both labels
- git: git@github.com:your-org/repo-b.git
settings:
labels:
bug:
color: ff0000 # Override color for this repo
deploy:
color: "0e8a16" # Add a repo-specific label
- git: git@github.com:your-org/repo-c.git
settings:
labels:
inherit: false # Skip all root labels
custom-label:
color: "000000"
- git: git@github.com:your-org/repo-d.git
settings:
labels:
enhancement: false # Opt out of a single root label
Inside one label, inherit: false drops only that label's inherited fields, so the repo's label starts fresh and the other inherited labels stay:
id: labels
settings:
labels:
bug:
color: d73a4a
description: "Something isn't working"
repos:
- git: git@github.com:your-org/repo-e.git
settings:
labels:
bug:
inherit: false # drop the inherited description
color: ff0000
With inherit: false in the labels map, a label that has the same name as an inherited one is not merged with it. It replaces it, so restate it in full. To keep the other inherited labels, drop the map-level inherit: false and opt out of the ones you do not want with name: false. inherit is not allowed on a root-level label.
How It Works¶
The xfg sync command:
- Fetches current labels from the GitHub API
- Compares them against the desired state in config (case-insensitive matching)
- Shows a Terraform-style plan of changes
- Applies changes in order: deletes, then updates/renames, then creates
Label name matching is case-insensitive (GitHub treats label names as case-insensitive).
GitHub API Reference¶
Labels are managed via the GitHub Labels API:
GET /repos/{owner}/{repo}/labels- List labelsPOST /repos/{owner}/{repo}/labels- Create a labelPATCH /repos/{owner}/{repo}/labels/{name}- Update a labelDELETE /repos/{owner}/{repo}/labels/{name}- Delete a label