Synchronise your GitHub labels with as few destructive operations as possible – similar labels get renamed.
- Requirements
- Command-Line Interface
- JavaScript Interface
- Label Config File
- Configuration
- Contributing
- License
You'll need Node.js 12+ installed to run GitHub Label Sync. You'll also need a GitHub access token ready so that the tool will have access to your repositories. You can generate an access token here, be sure to allow the "repo" scope.
Install GitHub Label Sync globally with npm:
npm install -g github-label-syncThis installs the github-label-sync command-line tool:
Usage: github-label-sync [options] <repository>
Options:
-h, --help output usage information
-V, --version output the version number
-a, --access-token <token> a GitHub access token (also settable with a GITHUB_ACCESS_TOKEN environment variable)
-l, --labels <path> the path or URL to look for the label configuration in. Default: labels.json
-d, --dry-run calculate the required label changes but do not apply them
-A, --allow-added-labels allow additional labels in the repo, and don't delete them
Run GitHub Label Sync on a repo (reading label data from a local labels.json):
github-label-sync --access-token xxxxxx myname/myrepoRun GitHub Label Sync using a different label config file:
github-label-sync --access-token xxxxxx --labels my-labels.json myname/myrepoLabel config file can be also specified as YAML:
github-label-sync --access-token xxxxxx --labels my-labels.yml myname/myrepoPerform a dry run, only making safe "read" requests to the GitHub API:
github-label-sync --access-token xxxxxx --dry-run myname/myrepoNormally any additional labels found on the repo are deleted. Run GitHub label sync and ignore additional labels, leaving them as-is:
github-label-sync --access-token xxxxxx --allow-added-labels myname/myrepoInstall GitHub Label Sync with npm or add to your package.json:
npm install github-label-sync
Require GitHub Label Sync:
var githubLabelSync = require('github-label-sync');The githubLabelSync function returns a promise that resolves to a JSON diff between the labels found on GitHub, and the labels in your label config.
Run GitHub Label Sync on a repo (passing in options):
githubLabelSync({
accessToken: 'xxxxxx',
repo: 'myname/myrepo',
labels: [
// label config
]
}).then((diff) => {
console.log(diff);
});The available options are documented below.
When the promise resolves successfully, its value will be set to a diff between the labels found on GitHub, and the labels in your label config. The diff will look like this:
[
// This is a "missing" diff, it indicates that a label
// present in your local config is not present on GitHub.
{
name: 'local-label-name',
type: 'missing',
actual: null,
expected: {
name: 'local-label-name',
color: 'ff0000'
}
},
// This is a "changed" diff, it indicates that a label
// present on GitHub has diverged from your local config.
// This could mean that either somebody has modified the
// label manually on GitHub, or the local config has
// been updated.
{
name: 'local-label-name',
type: 'changed',
actual: {
name: 'remote-label-name',
color: '00ff00'
},
expected: {
name: 'local-label-name',
color: 'ff0000'
}
},
// This is an "added" diff, it indicates that a label
// is present on GitHub but not in your local config.
{
name: 'remote-label-name',
type: 'added',
actual: {
name: 'remote-label-name',
color: 'ff0000'
},
expected: null
}
]The labels to sync with are defined as an array in either JavaScript, JSON or YAML. The array must contain only label objects, which look like this:
As JSON:
{
"name": "mylabel",
"color": "ff0000",
"aliases": [],
"description": "optional description",
"delete": false
}As YAML:
- name: mylabel
color: "ff0000"
aliases: []
description: optional description
delete: false- The
nameproperty refers to the label name. - The
colorproperty should be a hex code, with or without the leading#. - The
deleteproperty is optional. When set totrue, matches for this label will always be deleted. This can be used in conjunction with allowAddedLabels to flag specific labels for deletion while leaving non-specified labels intact. Defaults tofalse.
The aliases property is optional. When GitHub Label Sync is determining whether to update or delete/create a label it will use the aliases property to prevent used labels from being deleted.
For example, given the following config, GitHub Label Sync will look for labels on GitHub named either "feature" or "enhancement" then update them to match the newer config rather than deleting them.
{
"name": "type: feature",
"color": "00ff00",
"aliases": [
"enhancement",
"feature"
]
}You can find a full example label configuration in this repository (JSON / YAML).
String. The GitHub access token to use when fetching/updating labels. This must be an access token that has permission to write to the repository you want to sync labels with.
githubLabelSync({
accessToken: 'xxxxxx'
});On the command-line this can be set with either the access-token flag or the GITHUB_ACCESS_TOKEN environment variable:
github-label-sync --access-token xxxxxx
GITHUB_ACCESS_TOKEN=xxxxxx github-label-syncBoolean. Whether to allow labels on GitHub which are not specified in your label config. If true, they are allowed and will be left alone. If false, they will be deleted. Default: false.
githubLabelSync({
allowAddedLabels: true
});The command-line allow-added-labels flag corresponds to this option:
github-label-sync --allow-added-labels
Boolean. Whether to perform a dry run, only making safe "read" requests to the GitHub API. If true, label changes will not be executed on GitHub. If false, label changes will be executed. Default: false.
githubLabelSync({
dryRun: true
});The command-line dry-run flag corresponds to this option:
github-label-sync --dry-run
Array. Your label configuration. See the section on label config file.
githubLabelSync({
labels: []
});On the command-line this can be set with the labels flag which should point to a JSON or YAML file.
String. The GitHub repo to sync labels to. This should include the user and repo names, e.g. "Financial-Times/ft-origami".
githubLabelSync({
repo: 'Financial-Times/ft-origami'
});The command-line accepts the repo as an argument after the options:
github-label-sync Financial-Times/ft-origami
To contribute to GitHub Label Sync, clone this repo locally and commit your code on a separate branch.
Please write unit tests for your code, and check that everything works by running the following before opening a pull-request:
npm test # run the full test suite
npm run lint # run the linter
npm run test-unit # run the unit tests
npm run test-coverage # run the unit tests with coverage reportingThis software is published by the Financial Times under the MIT licence.
![dependabot-preview[bot] avatar](https://avatars.githubusercontent.com/in/2141?v=4 "dependabot-preview[bot]")
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent