github-label-sync

Synchronize labels using a local labels.json file

$ github-label-sync --access-token [token] [repository_name]

$ github-label-sync --access-token [token] --labels [url|path/to/json_file] [repository_name]

$ github-label-sync --access-token [token] --dry-run [repository_name]

$ github-label-sync --access-token [token] --allow-added-labels [repository_name]

$ github-label-sync [repository_name]

github-label-sync [options] --config <config_file> --access-token <token> [--repository <owner>/<repo>...]

-c, --config <file>
    Specifies the path to the YAML or JSON configuration file that defines the desired state of labels.

-a, --access-token <token>, --token <token>
    Provides the GitHub Personal Access Token required for authentication with the GitHub API. This token must have sufficient permissions (e.g., repo scope).

-r, --repository <owner>/<repo>
    Designates one or more specific GitHub repositories to synchronize. This option can be repeated. If omitted, github-label-sync will use repositories defined within the configuration file.

-d, --dry-run
    Executes a trial run, showing exactly what changes would be made without actually modifying any labels on GitHub. This is highly recommended for previewing.

-A, --allow-added
    Prevents github-label-sync from deleting any labels that exist in the target repository but are not present in the configuration file. Labels are only added or updated.

-D, --disable-deletion
    An alias for --allow-added. Prevents the deletion of labels not defined in the configuration file.

-q, --quiet
    Suppresses all standard output, including progress messages, showing only errors if they occur.

-v, --version
    Displays the current version number of the github-label-sync utility and exits.

-h, --help
    Outputs a detailed usage message, including a list of available options and their descriptions, then exits.

github-label-sync is a powerful command-line utility designed to automate the management and synchronization of labels across one or more GitHub repositories. It reads a desired label configuration from a local YAML or JSON file and applies these definitions to specified repositories. The tool can intelligently create new labels, update existing ones (e.g., change color or description), and optionally delete labels that are present in the repository but not defined in the configuration file. This automation is crucial for maintaining consistent labeling conventions, which in turn improves issue tracking, project management, and reporting workflows across multiple projects or organizational teams. It features a robust dry-run mode to preview all planned changes before they are actually applied, providing a safe way to manage your labels. Authentication is handled securely via a GitHub Personal Access Token.

Using github-label-sync requires a GitHub Personal Access Token with appropriate permissions (at least the repo scope). Be cautious when running without the --dry-run option and without --allow-added (or --disable-deletion), as this can lead to unintended deletion of existing labels not defined in your configuration file. This utility is specifically designed for GitHub and does not support other Git hosting platforms like GitLab or Bitbucket. Always ensure your configuration file is correctly formatted to avoid errors.

The configuration file for github-label-sync must be in YAML or JSON format and contain an array of label objects. Each label object typically includes name, color, and an optional description.

Example (YAML):
- name: bug
color: "d73a4a"
description: "Something isn't working"
- name: enhancement
color: "a2eeef"
description: "New feature or request"
The configuration file can also optionally specify an array of repositories to apply the labels to, removing the need for the --repository command-line argument.

Access to GitHub is authenticated using a Personal Access Token (PAT) which must be passed via the --access-token (or --token) option. It is strongly recommended to use environment variables (e.g., GITHUB_ACCESS_TOKEN) or a secure secrets management system to avoid exposing the token directly in command-line history or scripts. The PAT needs appropriate scopes, typically the repo scope, to allow label creation, modification, and deletion in private and public repositories.

github-label-sync was originally developed by the Financial Times to streamline label management across their numerous GitHub repositories, addressing a common need for consistent project metadata. It was first published as an npm package on April 20, 2016, making it accessible to a wider developer community. Since its initial release, the utility has undergone continuous maintenance and updates, reflecting community contributions and evolving GitHub API features, ensuring its continued relevance for automated label synchronization.