Set 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 labels
• setGitHubRepositoryLabels: sends the API requests to the repository to set its labels

determineLabelChanges

Takes two required parameters:

1. existingLabels: an array of the labels that currently exist on a repository
2. outcomeLabels: 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 Octokit
• bandwidth (optional): How many requests to send at once
• labels (required): Outcome labels to end with on the repository
• owner (required): Organization or user the repository is owned by
• repository (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-app using the Bingo engine.