README.md

ghlabel

CLI tool to help setup Github Labels from a yaml/json config file.

Report Bug · Request Feature · Ask Question

Installation and Setup

It is recommended to not install the CLI tool globally.

1. Create a new directory where you want the configuration to live

mkdir ghlabel

# this is where the labels config will be located
cd ghlabel

2. Create and activate virtual environment

python -m venv .venv

# Linux/Mac
. .venv/bin/activate

# Windows
.venv\Scripts\activate.bat

3. Install package

pip install ghlabel

# check if installed
ghlabel -v

4. Create .env and supply github credentials

# Linux/Mac
touch .env

# Windows
type nul > .env

GITHUB_PERSONAL_ACCESS_TOKEN=<your_github_personal_access_token>
GITHUB_REPO_OWNER=<target_github_repository_owner>
GITHUB_REPO_NAME=<target_github_repository_name>

Basic Usage

1. Generate yaml/json config files for GitHub labels

ghlabel dump

2. Dry-run to preview results and modify config files accordingly

ghlabel setup -p

3. Once satisfied, setup labels in GitHub

ghlabel setup

For advanced usage, see:

ghlabel -h

🔴 ghlabel

Setup Github Labels from a yaml/json config file.

Usage:

$ ghlabel [OPTIONS] COMMAND [ARGS]...

🔶 Options:

--version, -v

Show version and exit.

--debug, -D

Enable debug mode and show logs.

--help, -h

Show this message and exit.

Commands:

dump

Generate starter labels config files.

setup

Add/Remove Github labels from config files.

🔴 ghlabel dump

Generate starter labels config files.

Usage:

$ ghlabel dump [OPTIONS]

🔶 Options:

--new, -n / --keep-old-labels, -N [default: new]

Deletes all files in labels dir.

--dir, -d TEXT [default: labels]

Specify the dir where to find labels.

--ext, -e [json|yaml] [default: yaml]

Label file extension.

--app, -a [app|game|web] [default: app]

App to determine label template.

--help, -h

Show this message and exit.

🔴 ghlabel setup

Add/Remove Github labels from config files.

Usage:

$ ghlabel setup [TOKEN] [REPO_OWNER] [REPO_NAME] [OPTIONS]

🔷 Arguments:

TOKEN [optional]

REPO_OWNER [optional]

REPO_NAME [optional]

🔶 Options:

--directory, -d TEXT [default: labels]

Specify the directory where to find labels.

--preview, -p / --no-preview, -P [default: no-preview]

Dry run and preview result before adding/removing labels from repo.

--strict, -s / --no-strict, -S [default: no-strict]

Strictly mirror Github labels from labels config.

--add-labels, -a TEXT

Add more labels.

--remove-labels, -r TEXT

Remove more labels.

--remove-all, -R [disable|enable|silent] [default: disable]

Remove all Github labels.

--help, -h

Show this message and exit.

Example Usage

Overriding .env or Manually adding Environment Variables

REPO_NAME=medrec ghlabel setup

Removing more labels

# -r [comma-separated string]
# will be parsed as list[str]
ghlabel setup -r "Type: Feature Request, Type: Bug"

Adding more labels

# -a [valid json string]
# will be parsed as list[dict[str, str]]
ghlabel setup -a "[{'name': 'wontfix', 'color': '#ffffff'}, {'name': 'bug', 'color': '#d73a4a', 'description': 'Something isn't working'}]"

Adding Custom Github Labels

valid values (yaml/json)

# yaml
- name: <label_name>
  color: <label_color_hash>
  description: <label_description>

# json
[
    {
        "name": <label_name>,
        "color": <label_color_hash>,
        "description": <label_description>,
    },
]

labels/affects_labels.yaml

labels/close_labels.yaml

labels/default_labels.yaml

labels/needs_labels.yaml

labels/priority_labels.yaml

labels/state_labels.yaml

labels/type_labels.yaml

Removing labels

labels/_remove_labels.yaml

- bug
- dependencies
- documentation
- duplicate
- enhancement
- github_actions
- help wanted
- invalid
- python
- question
- wontfix

[Optional] Game Dev Additional Labels

labels/affects_labels.yaml