Simple CLI tool to help manage labels across repos

Readme Card

License: MIT Go Report Card Coverage Status reference

Simple CLI tool to help manage labels across repos

Please see the docs for details on the commands.

$ bin/ghlabels 
   ghlabels - label sync for repos and organizations

   ghlabels [global options] command [command options] [arguments...]

   sync     sync labels - rename, sync, delete
   config   commands for viewing or generating configuration
   stats    prints out repository stats
   help, h  Shows a list of commands or help for one command

   --help, -h     show help (default: false)
   --version, -v  print the version (default: false)


To view the default configuration, run the ghlabels config defaults command.

$ ghlabels config defaults

The order of operations is:

  1. Rename
  2. Sync
  3. Delete

A custom configuration file can be provided using the --config, -c flag. The file passed to this config option must use the following structure. You do not need to have all 3 Top Level sections in the config file for the configuration to be valid.

By default, the --config, -c flag will overwrite the default configuration. You can merge the provided configuration with the default using the --merge-with-defaults, -m boolean flag. This will take the default configuration and merge in the user provided configuration, with the user config taking precedence.

Configuration Schema

Top Level Type Description Structure
rename List List of Label names to rename from a given name to a new name. { from: "string", to: "string" }
remove List List of Labels to be deleted from a Repo. string
sync List List of Label configuration that will be used to create or update a given Label. { name: "string", color: "sting", description: "string" }


Homebrew (for macOS users)

brew tap clok/ghlabels
brew install ghlabels

curl binary

$ curl! | bash


The compiled docker images are maintained on GitHub Container Registry ( We maintain the following tags:

  • edge: Image that is build from the current HEAD of the main line branch.
  • latest: Image that is built from the latest released version
  • x.y.z (versions): Images that are build from the tagged versions within GitHub.
docker pull
docker run -v "$PWD":/workdir --version


GitHub doesn’t support accessing the Organization Repository Defaults via their API (found here:<ORG>/settings/repository-defaults)

I would love to add commands that would allow:

  1. Generating a configuration based the Organization default settings.
  2. Sync the Organization defaults to Repos within it.
  3. Update the default settings based on a configuration manifest.

Unfortunately, the GitHub API does not support interacting with the Organization Repository Defaults, so these items have to remain on the wishlist for now. Please see the GitHub REST API Discussion thread that I opened to request this feature.


  1. Fork the clok/ghlabels repo
  2. Use go >= 1.16
  3. Branch & Code
  4. Run linters :broom: golangci-lint run
  5. Commit with a Conventional Commit
  6. Open a PR


We employ git-chglog to manage the For the versions available, see the tags on this repository.


See also the list of contributors who participated in this project.


This project is licensed under the MIT License - see the LICENSE file for details