GitHub | crates.io | Issues | Changelog

labelmaker is a Rust program for batch creation of labels in GitHub repositories, including updating and/or renaming existing labels to meet your specifications. Simply describe your desired labels in a configuration file and point labelmaker in the direction of your repositories.

Installation

Release Assets

Prebuilt binaries for the most common platforms are available as GitHub release assets. The page for the latest release lists these under "Assets", along with installer scripts for both Unix-like systems and Windows.

As an alternative to the installer scripts, if you have cargo-binstall on your system, you can use it to download & install the appropriate release asset for your system for the latest version of labelmaker by running cargo binstall labelmaker.

Installing from Source

If you have Rust and Cargo installed, you can build the latest release of labelmaker from source and install it in ~/.cargo/bin by running:

cargo install labelmaker

Usage

labelmaker [<global options>] <subcommand> ...

The labelmaker command has the following subcommands, each detailed below:

• apply — Apply a set of label specifications to one or more GitHub repositories

• fetch — Dump a repository's labels as a configuration file

• make — Create or update a single label

Each subcommand takes an argument or option for indicating what GitHub repositories to operate on. A repository can be specified in the form OWNER/NAME (or, when OWNER is the authenticated user, just NAME) or as a GitHub repository URL. If no repository is supplied, then the current directory must belong to a Git repository whose origin remote points to a GitHub repository; labelmaker will operate on this remote repository.

Global Options

• -l <level>, --log-level <level> — Set the log level to the given value. Possible values are "OFF", "ERROR", "WARN", "INFO", "DEBUG", and "TRACE" (all case-insensitive). [default value: INFO]

Authentication

labelmaker requires a GitHub access token with appropriate permissions in order to run. Specify the token via the GH_TOKEN or GITHUB_TOKEN environment variable or store it with the gh command.

Note that, if gh has stored the token in a system keyring, you may be prompted to unlock the keyring.

labelmaker apply

labelmaker [<global options>] apply [<options>] <config-file> [<repository> ...]

labelmaker apply takes a path to a configuration file (See "Configuration File" below) and a list of GitHub repositories as arguments. It then creates and/or updates the labels of each repository based on the specification in the configuration file.

For each repository, all changes are calculated before modifying anything, so if an error occurs based on the state of the configuration file and/or current repository labels, it will be caught before any changes to the repository are made.

Options

• --dry-run — Do not change anything in GitHub, but do emit log messages showing what would be changed.

• -F FILE/--repo-file FILE — Also operate on all repositories listed in the given file (or listed on standard input if FILE is -). Repositories must be listed one per line. Leading & trailing whitespace is ignored. Blank lines and lines starting with # are skipped.

• -P NAME/--profile NAME — Specify which profile in the configuration file to use. Defaults to the value of defaults.profile in the configuration file, or to default.

labelmaker fetch

labelmaker [<global options>] fetch [<options>] [<repository>]

labelmaker fetch fetches the labels currently defined for the given GitHub repository and dumps them as a labelmaker configuration file, ready for input into labelmaker apply.

The generated configuration file lists only label names, colors, and descriptions, no defaults, aside from the file-wide color setting having its default value included for use as a reference.

Options

• -o FILE/--outfile FILE — Output the configuration to the given file. By default, output is written to standard output, which can also be selected by supplying - as the outfile name.

  The format (JSON, JSON5, TOML, or YAML) of the output is determined based on the file's extension. When outputting to standard output, JSON is produced.

• -P NAME/--profile NAME — Set the name of the profile to place the labels under in the generated configuration file. The configuration file's default profile will also be set to this value. [default: default]

labelmaker make

labelmaker [<global options>] make [<options>] <label-name>

labelmaker make creates or updates the label with the given name in a GitHub repository, the same as if labelmaker apply had been run on that repository with a configuration profile containing a single label entry.

Options

• -c COLOR/--color COLOR — Specify the label's color. Colors are specified using the same formats as in the configuration file.

  This option can be specified multiple times, in which case one of the given colors will be picked at random when creating the label, and no change will be made to the label color when updating the label.

  The color defaults to a random selection from the same built-in list as used by the configuration file and apply.

• --create/--no-create — Whether to create the label if it doesn't already exist [default: --create]

• -d TEXT, --description TEXT — Specify the label's description.

• --dry-run — Do not change anything in GitHub, but do emit log messages showing what would be changed.

• --enforce-case/--no-enforce-case — Whether to rename an extant label if its name differs in case from the name given on the command line [default: --enforce-case]

• --on-rename-clash <ignore|warn|error> — Specify what to do if the label exists and one or more --rename-from labels also exist:

  • ignore: Do nothing
  • warn (default): Emit a warning
  • error: Fail with an error

• --rename-from LABEL — If LABEL exists, rename it to the label name provided as the argument to make.

  This option can be specified multiple times. If multiple --rename-from labels exist, an error will occur.

• -R REPO/--repository REPO — Specify the GitHub repository to operate on.

• --update/--no-update — Whether to update the label if its color and/or description do not match the values given on the command line [default: --update]

Configuration File

labelmaker's configuration file may be written in JSON, JSON5, TOML, or YAML; the file type is determined automatically based on the file extension. The file contains a top-level mapping with the following fields:

• defaults — A mapping of default label settings to apply to all labels in this configuration file. Any field that can be set on a label can be set here, other than name and rename-from. File-wide defaults can be overridden for specific profiles via the profiles.*.defaults mappings.

  • The defaults mapping may also contain a profile string field specifying the default profile for apply to use when no --profile option is given; the default profile is default.

• profiles — A mapping from profile names to profile definitions. A profile is a set of label definitions that can be selected when invoking apply. Each profile is defined by a mapping with the following fields:

  • defaults — A mapping of default label settings to apply to all labels in this profile. Any field that can be set on a label can be set here, other than name and rename-from. Settings set here override settings set in the top-level defaults mapping for the labels in this profile.

  • labels — A list of label specifications; each one is a mapping with the following fields:

    • name (required) — The name of the label. Leading & trailing whitespace will be trimmed; if the resulting string is empty, is it an error.

      • Note that GitHub treats label names case-insensitively; thus, the names "foo" and "Foo" refer to the same label. If you do or do not want your label names to enforce a specific casing, see the enforce-case option below.

      • It is an error if two or more labels in the same profile have the