From bb94e34627276edde830b045311b89decdf08768 Mon Sep 17 00:00:00 2001 From: Hillary Jeffrey Date: Tue, 15 Dec 2020 12:57:49 -0500 Subject: [PATCH 1/8] Add label management documentation --- config/label-management.md | 126 +++++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 config/label-management.md diff --git a/config/label-management.md b/config/label-management.md new file mode 100644 index 0000000..6065527 --- /dev/null +++ b/config/label-management.md @@ -0,0 +1,126 @@ +# Managing cross-organization labels in existing repositories # + +This is a step-by-step guide/script for managing organization-wide github +issue labels across all repositories. + +## Prerequisites ## + +- User has access to the github organization's repositories +- User can generate a GitHub [Personal access token](https://github.com/settings/tokens) + +## Initial Setup ## + +1. Clone the repository locally + +```console +git clone https://github.com/alta3/github-label-management.git +cd github-label-management +``` + +1. Activate the virtual environment and install the requirements + +```console +python3.8 -m venv venv +source venv/bin/activate +python -m pip install --upgrade pip wheel +python -m pip install -r requirements.txt +``` + +1. Create a local configuration file by running `touch config` +1. Open `config` in your favorite editor for editing +1. Create a GitHub [Personal access token](https://github.com/settings/tokens) + +- Give it a descriptive name like "label management" +- **Only** select the `repo` scope +- Copy the generated token into `GITHUB_USER_TOKEN` + +```sh +export GITHUB_USER_TOKEN="" +export LABELS_TOKEN=${GITHUB_USER_TOKEN} +export LABELS_USERNAME="" +export LABELS_ORGNAME="cisagov" +``` + +1. Save your changes and run `source config` + +## Label management operations ## + +There are several operations you'll probably want to do, now that you've +set up the environment and have the script ready. + +### Re-initializing the environment ### + +When you return to the directory in a new shell, remember to: + +```console +source venv/bin/activate +source config +``` + +### List all organization repositories ### + +```console +python list-all-repos.py +``` + +This will yield a list of all repositories you have access to in the specified +GitHub organization. If you have not specified a token, this will yield a list +of all public repositories. + +### Back up all current repository labels ### + +This will generate a `.toml` file for each repository in a directory of your +choosing. Each `.toml` file will contain the details of the repository's +labels, including names, colors, and descriptions. + +Please note these output files are the same format as the `default-labels.toml` +file, so you can use one as a template if you have a repository set up with +the labels you want organization-wide. + +```console +# Make the directory if it doesn't already exist +# The -p option specifies to create intermediate directories as required +mkdir -p repo-labels-backup + +# Use the output of list-all-repos.py to fetch each repository's labels +python list-all-repos.py | xargs -I {} labels fetch --owner $LABELS_ORGNAME --repo {} --filename repo-labels-backup/{}-labels.toml +``` + +### Apply default labels across the organization ### + +View and edit `default-labels.toml` to specify the default labels and their +attributes such as name, color, and description. This is the same format as +the output `.toml` files from the "back up" step, so if you have an example +repository, you can copy straight from that repository's file. + +Please note that the `labels ... sync` operation is **destructive** and will +reduce the set of labels in each repository to _only_ those specified. + +The label history of each issue and PR will show the removal of the previous +labels in case you need to restore some. + +Once you've set up your `default-labels.toml` file, create a list of all the +repositories in a file so you can edit the list to remove any repositories you +do not want to alter labels for. + +```console +python list-all-repos.py > repolist.txt +``` + +Make any edits to the list to exclude repositories that are special or that +you don't want to sync the labels for whatever reason, and then apply the +labels to the remaining list of repositories. + +```console +cat repolist.txt | xargs -I {} labels --verbose sync --owner $LABELS_ORGNAME --repo {} --filename default-labels.toml +``` + +#### Dangerous operation: Apply labels in one step #### + +The following is **not recommended**, but to apply the `sync` without an +interstitial `repolist.txt` file (and live dangerously), you can instead run +the `sync` in one step. + +```console +python list-all-repos.py | xargs -I {} labels sync --owner $LABELS_ORGNAME --repo {} --filename default-labels.toml +``` From 5152901aedc80124d55a1b333d0d03508188a120 Mon Sep 17 00:00:00 2001 From: Hillary Jeffrey Date: Tue, 15 Dec 2020 12:58:52 -0500 Subject: [PATCH 2/8] Add default labels file --- config/default-labels.toml | 74 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 config/default-labels.toml diff --git a/config/default-labels.toml b/config/default-labels.toml new file mode 100644 index 0000000..61acad2 --- /dev/null +++ b/config/default-labels.toml @@ -0,0 +1,74 @@ +["blocked"] +color = "eb6420" +name = "blocked" +description = "This issue or pull request is blocked" + +["breaking change"] +color = "000000" +name = "breaking change" +description = "This issue or pull request will cause existing functionality to change" + +["bug"] +color = "d73a4a" +name = "bug" +description = "This issue or pull request addresses broken functionality" + +["code.gov"] +color = "07648d" +name = "code.gov" +description = "This issue will be advertised on code.gov's \"Open Tasks\" page (https://code.gov/open-tasks)" + +["documentation"] +color = "5319e7" +name = "documentation" +description = "This issue or pull request involves improvements or additions to documentation" + +["duplicate"] +color = "cfd3d7" +name = "duplicate" +description = "This issue or pull request already exists" + +["epic"] +color = "b005bc" +name = "epic" +description = "This issue is an epic" + +["good first issue"] +color = "0e8a16" +name = "good first issue" +description = "Good for newcomers" + +["improvement"] +color = "a2eeef" +name = "improvement" +description = "This issue or pull request will add new or improve existing functionality" + +["invalid"] +color = "fef2c0" +name = "invalid" +description = "This doesn't seem right" + +["need info"] +color = "a4fc5d" +name = "need info" +description = "This issue or pull request requires further information" + +["question"] +color = "ef476c" +name = "question" +description = "Further information is requested" + +["upstream update"] +color = "1d76db" +name = "upstream update" +description = "This issue or pull request relates to pulling in upstream updates" + +["version bump"] +color = "d4c5f9" +name = "version bump" +description = "This issue or pull request involves a version bump" + +["wontfix"] +color = "ffffff" +name = "wontfix" +description = "This issue will not be worked on" From 3c197665b2fdd61e3125e1ee1c086a425916a6d1 Mon Sep 17 00:00:00 2001 From: Hillary Date: Tue, 15 Dec 2020 15:57:23 -0500 Subject: [PATCH 3/8] Apply suggestions from code review Co-authored-by: Shane Frasier --- config/label-management.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/config/label-management.md b/config/label-management.md index 6065527..070ab3b 100644 --- a/config/label-management.md +++ b/config/label-management.md @@ -1,11 +1,11 @@ # Managing cross-organization labels in existing repositories # -This is a step-by-step guide/script for managing organization-wide github +This is a step-by-step guide/script for managing organization-wide GitHub issue labels across all repositories. ## Prerequisites ## -- User has access to the github organization's repositories +- User has access to the GitHub organization's repositories - User can generate a GitHub [Personal access token](https://github.com/settings/tokens) ## Initial Setup ## @@ -23,12 +23,12 @@ cd github-label-management python3.8 -m venv venv source venv/bin/activate python -m pip install --upgrade pip wheel -python -m pip install -r requirements.txt +python -m pip install --requirement requirements.txt ``` 1. Create a local configuration file by running `touch config` 1. Open `config` in your favorite editor for editing -1. Create a GitHub [Personal access token](https://github.com/settings/tokens) +1. Create a GitHub [personal access token](https://github.com/settings/tokens) - Give it a descriptive name like "label management" - **Only** select the `repo` scope From 105129a08608094e93141604071ab63eabb2dae1 Mon Sep 17 00:00:00 2001 From: Hillary Jeffrey Date: Tue, 15 Dec 2020 16:01:41 -0500 Subject: [PATCH 4/8] Convert to pyenv and fix bullets --- config/label-management.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/config/label-management.md b/config/label-management.md index 070ab3b..c26c987 100644 --- a/config/label-management.md +++ b/config/label-management.md @@ -17,22 +17,22 @@ git clone https://github.com/alta3/github-label-management.git cd github-label-management ``` -1. Activate the virtual environment and install the requirements +1. Activate/create the virtual environment and install the requirements ```console -python3.8 -m venv venv -source venv/bin/activate -python -m pip install --upgrade pip wheel -python -m pip install --requirement requirements.txt +pyenv local 3.8.3 +pyenv virtualenv github-label-management +pyenv activate github-label-management +python3 -m pip install --upgrade pip setuptools wheel +python3 -m pip install --requirement requirements.txt ``` 1. Create a local configuration file by running `touch config` 1. Open `config` in your favorite editor for editing 1. Create a GitHub [personal access token](https://github.com/settings/tokens) - -- Give it a descriptive name like "label management" -- **Only** select the `repo` scope -- Copy the generated token into `GITHUB_USER_TOKEN` + - Give it a descriptive name like "label management" + - **Only** select the `repo` scope + - Copy the generated token into `GITHUB_USER_TOKEN` ```sh export GITHUB_USER_TOKEN="" From e89098d912fa874b2e522672afefbffdb68a66e7 Mon Sep 17 00:00:00 2001 From: Hillary Date: Tue, 15 Dec 2020 16:04:21 -0500 Subject: [PATCH 5/8] Apply suggestions from code review Co-authored-by: Shane Frasier --- config/label-management.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/config/label-management.md b/config/label-management.md index c26c987..3224813 100644 --- a/config/label-management.md +++ b/config/label-management.md @@ -77,7 +77,7 @@ Please note these output files are the same format as the `default-labels.toml` file, so you can use one as a template if you have a repository set up with the labels you want organization-wide. -```console +```sh # Make the directory if it doesn't already exist # The -p option specifies to create intermediate directories as required mkdir -p repo-labels-backup @@ -103,7 +103,7 @@ Once you've set up your `default-labels.toml` file, create a list of all the repositories in a file so you can edit the list to remove any repositories you do not want to alter labels for. -```console +```sh python list-all-repos.py > repolist.txt ``` @@ -111,7 +111,7 @@ Make any edits to the list to exclude repositories that are special or that you don't want to sync the labels for whatever reason, and then apply the labels to the remaining list of repositories. -```console +```sh cat repolist.txt | xargs -I {} labels --verbose sync --owner $LABELS_ORGNAME --repo {} --filename default-labels.toml ``` @@ -121,6 +121,6 @@ The following is **not recommended**, but to apply the `sync` without an interstitial `repolist.txt` file (and live dangerously), you can instead run the `sync` in one step. -```console +```sh python list-all-repos.py | xargs -I {} labels sync --owner $LABELS_ORGNAME --repo {} --filename default-labels.toml ``` From 59da33d22408331ad21b329707ed8e83cb254391 Mon Sep 17 00:00:00 2001 From: Hillary Jeffrey Date: Tue, 15 Dec 2020 16:21:14 -0500 Subject: [PATCH 6/8] Convert to pyenv continued pyenv all the things --- config/label-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/label-management.md b/config/label-management.md index 3224813..4ed9a7f 100644 --- a/config/label-management.md +++ b/config/label-management.md @@ -53,7 +53,7 @@ set up the environment and have the script ready. When you return to the directory in a new shell, remember to: ```console -source venv/bin/activate +pyenv activate github-label-management source config ``` From c6b0764dfd25147e15cc89e07140e05436d65d53 Mon Sep 17 00:00:00 2001 From: Hillary Jeffrey Date: Tue, 15 Dec 2020 16:28:02 -0500 Subject: [PATCH 7/8] Fix numbering and formatting Stop starting over at 1 all the time. --- config/label-management.md | 40 +++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/config/label-management.md b/config/label-management.md index 4ed9a7f..be919e3 100644 --- a/config/label-management.md +++ b/config/label-management.md @@ -12,35 +12,35 @@ issue labels across all repositories. 1. Clone the repository locally -```console -git clone https://github.com/alta3/github-label-management.git -cd github-label-management -``` + ```console + git clone https://github.com/alta3/github-label-management.git + cd github-label-management + ``` 1. Activate/create the virtual environment and install the requirements -```console -pyenv local 3.8.3 -pyenv virtualenv github-label-management -pyenv activate github-label-management -python3 -m pip install --upgrade pip setuptools wheel -python3 -m pip install --requirement requirements.txt -``` + ```console + pyenv local 3.8.3 + pyenv virtualenv github-label-management + pyenv activate github-label-management + python3 -m pip install --upgrade pip setuptools wheel + python3 -m pip install --requirement requirements.txt + ``` 1. Create a local configuration file by running `touch config` -1. Open `config` in your favorite editor for editing +1. Open `config` in your favorite editor and start from this template + + ```sh + export GITHUB_USER_TOKEN="" + export LABELS_TOKEN=${GITHUB_USER_TOKEN} + export LABELS_USERNAME="" + export LABELS_ORGNAME="cisagov" + ``` + 1. Create a GitHub [personal access token](https://github.com/settings/tokens) - Give it a descriptive name like "label management" - **Only** select the `repo` scope - Copy the generated token into `GITHUB_USER_TOKEN` - -```sh -export GITHUB_USER_TOKEN="" -export LABELS_TOKEN=${GITHUB_USER_TOKEN} -export LABELS_USERNAME="" -export LABELS_ORGNAME="cisagov" -``` - 1. Save your changes and run `source config` ## Label management operations ## From 2a038d6c86c757805e75673e4861afe3eb1b369f Mon Sep 17 00:00:00 2001 From: Hillary Date: Fri, 18 Dec 2020 10:31:20 -0500 Subject: [PATCH 8/8] Apply suggestions from code review Co-authored-by: dav3r Co-authored-by: Nick M. <50747025+mcdonnnj@users.noreply.github.com> --- config/label-management.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/config/label-management.md b/config/label-management.md index be919e3..e493501 100644 --- a/config/label-management.md +++ b/config/label-management.md @@ -6,7 +6,7 @@ issue labels across all repositories. ## Prerequisites ## - User has access to the GitHub organization's repositories -- User can generate a GitHub [Personal access token](https://github.com/settings/tokens) +- User can generate a GitHub [personal access token](https://github.com/settings/tokens) ## Initial Setup ## @@ -20,9 +20,8 @@ issue labels across all repositories. 1. Activate/create the virtual environment and install the requirements ```console - pyenv local 3.8.3 - pyenv virtualenv github-label-management - pyenv activate github-label-management + pyenv virtualenv 3.8.3 github-label-management + pyenv local github-label-management python3 -m pip install --upgrade pip setuptools wheel python3 -m pip install --requirement requirements.txt ``` @@ -60,7 +59,7 @@ source config ### List all organization repositories ### ```console -python list-all-repos.py +python3 list-all-repos.py ``` This will yield a list of all repositories you have access to in the specified @@ -83,15 +82,16 @@ the labels you want organization-wide. mkdir -p repo-labels-backup # Use the output of list-all-repos.py to fetch each repository's labels -python list-all-repos.py | xargs -I {} labels fetch --owner $LABELS_ORGNAME --repo {} --filename repo-labels-backup/{}-labels.toml +python3 list-all-repos.py | xargs -I {} labels fetch --owner "$LABELS_ORGNAME" --repo {} --filename repo-labels-backup/{}-labels.toml ``` ### Apply default labels across the organization ### View and edit `default-labels.toml` to specify the default labels and their attributes such as name, color, and description. This is the same format as -the output `.toml` files from the "back up" step, so if you have an example -repository, you can copy straight from that repository's file. +the output `.toml` files from the ["back up" step](#Back-up-all-current-repository-labels), +so if you have an example repository, you can copy straight from that +repository's file. Please note that the `labels ... sync` operation is **destructive** and will reduce the set of labels in each repository to _only_ those specified. @@ -104,7 +104,7 @@ repositories in a file so you can edit the list to remove any repositories you do not want to alter labels for. ```sh -python list-all-repos.py > repolist.txt +python3 list-all-repos.py > repolist.txt ``` Make any edits to the list to exclude repositories that are special or that @@ -112,15 +112,15 @@ you don't want to sync the labels for whatever reason, and then apply the labels to the remaining list of repositories. ```sh -cat repolist.txt | xargs -I {} labels --verbose sync --owner $LABELS_ORGNAME --repo {} --filename default-labels.toml +cat repolist.txt | xargs -I {} labels --verbose sync --owner "$LABELS_ORGNAME" --repo {} --filename default-labels.toml ``` -#### Dangerous operation: Apply labels in one step #### +#### ⚠️ Dangerous operation: Apply labels in one step #### The following is **not recommended**, but to apply the `sync` without an interstitial `repolist.txt` file (and live dangerously), you can instead run the `sync` in one step. ```sh -python list-all-repos.py | xargs -I {} labels sync --owner $LABELS_ORGNAME --repo {} --filename default-labels.toml +python3 list-all-repos.py | xargs -I {} labels sync --owner "$LABELS_ORGNAME" --repo {} --filename default-labels.toml ```