JoshuaKGoldbergSet GitHub Repository Labels
Sets labels for a GitHub repository, including renaming existing similar labels. 🏷️
Usage
Sets a collection of labels on a repository.
For each outcome label, if its name, the same words excluding its prefix:, or any of its aliases already exists, that existing label is updated.
Otherwise, a new label is created.
Node.js API
npm i set-github-repository-labels
set-github-repository-labels provides two functions:
determineLabelChanges: describes the changes a repository's labels would need to get to the outcome labelssetGitHubRepositoryLabels: sends the API requests to the repository to set its labels
determineLabelChanges
Takes two required parameters:
existingLabels: an array of the labels that currently exist on a repositoryoutcomeLabels: an array of the labels that you want to exist on the repository
Returns an array of change objects describing the network requests that would be needed to change the repository's existing labels to the outcome labels.
For example, determine label changes on an existing repository with only one label to having two:
import { determineLabelChanges } from "set-github-repository-labels";
const changes = determineLabelChanges(
[{ color: "ff0000", description: "Something isn't working.", name: "bug" }],
[
{
color: "d73a4a",
description: "Something isn't working 🐛",
name: "type: bug",
},
{
aliases: ["enhancement"],
color: "a2eeef",
description: "New enhancement or request 🚀",
name: "type: feature",
},
],
);
for (const change of changes) {
switch (change.type) {
case "delete":
console.log(`DELETE: ${change.name}`);
break;
case "patch":
console.log(`PATCH: ${change.originalName} to ${change.newName}`);
break;
case "post":
console.log(`POST: ${change.name}`);
break;
}
}
See src/types.ts for the specific properties that exist on the change objects.
setGitHubRepositoryLabels
Takes a parameters object with the following properties corresponding to Shell options:
auth(optional): Auth token to create a new GitHub Octokitbandwidth(optional): How many requests to send at oncelabels(required): Outcome labels to end with on the repositoryowner(required): Organization or user the repository is owned byrepository(required): Name of the repository
It returns a Promise for sending requests to the GitHub API to update the repository's labels.
import { setGitHubRepositoryLabels } from "set-github-repository-labels";
await setGitHubRepositoryLabels({
labels: [
{
color: "d73a4a",
description: "Something isn't working 🐛",
name: "type: bug",
},
{
aliases: ["enhancement"],
color: "a2eeef",
description: "New enhancement or request 🚀",
name: "type: feature",
},
],
owner: "JoshuaKGoldberg",
repository: "create-typescript-app",
});
Shell
set-github-repository-labels can be run as an npx command.
| Option | Type | Default or Required | Description |
|---|---|---|---|
--auth |
string |
process.env.GH_TOKEN or executing gh auth token |
Auth token for GitHub from octokit-from-auth |
--bandwidth |
number |
6 |
Maximum parallel requests to start at once |
--labels |
string |
(required) | Raw JSON string |
--owner |
string |
(required) | Owning organization or username for the repository |
--repository |
string |
(required) | Title of the repository |
Because labels takes in data as a raw JSON string, so you'll most likely want to pipe data to it from a JSON source:
npx set-github-repository-labels --labels "$(cat labels.json)" --owner JoshuaKGoldberg --repository "create-typescript-app"
To call it programmatically, you can use something like execa:
import $ from "execa";
import fs from "node:fs/promises";
const labels = (await fs.readFile("labels.json")).toString();
await $`npx set-github-repository-labels --labels ${labels} --owner JoshuaKGoldberg --repository "create-typescript-app"`;
Development
See .github/CONTRIBUTING.md, then .github/DEVELOPMENT.md.
Thanks! 🏷
Contributors
 Josh Goldberg ✨ 💻 🖋 📖 🤔 🚇 🚧 📆 🔧 |
💝 This package was templated with
create-typescript-appusing the Bingo engine.