New Github Repository

Creates a new repository on GitHub, including waiting for initialization. 🆕

Usage

npm i new-github-repository

import { newGitHubRepository } from "new-github-repository";

await newGitHubRepository({
	owner: "YourUsername",
	repository: "a-great-new-repository",
});

newGitHubRepository returns an object containing:

• data: response data from the GitHub OpenAPI REST call to create the repository
• initialized: whether polling the GitHub API (see: Why Polling?) seemed to show the repository done being created

newGitHubRepository allows the following properties in its parameter object:

• Required:
  • owner (string): owning user or organization to create the repository under
  • repository (string): name of the repository to create
• Optional:
  • octokit (Octokit): Octokit instance to use for requests
  • template ({ owner, string }): locator of a GitHub template repository to create from

octokit

Octokit instance to use for requests. If not provided, defaults to creating one with octokit-from-auth.

Manually passing an octokit can be useful if you already have one created separately and/or wish to customize how the GitHub API is interacted with:

import { newGitHubRepository } from "new-github-repository";
import { Octokit } from "octokit";

const octokit = new Octokit({ auth: "personal-access-token123" });

await newGitHubRepository({
	octokit,
	owner: "YourUsername",
	repository: "a-great-new-repository",
});

template

Locator of a GitHub template repository to create from.

Repositories created by a template repository show a "generated from ..." notice in their homepage header that links to their template.

import { newGitHubRepository } from "new-github-repository";

await newGitHubRepository({
	owner: "YourUsername",
	repository: "a-great-new-repository",
	template: {
		owner: "JoshuaKGoldberg",
		repository: "create-typescript-app",
	},
});

Why?

Or: why not create repositories by directly calling the GitHub API?

new-github-repository smooths over two areas of GitHub repository creation:

• There are three different APIs to create a new repository, depending on how it should be formed:
  • Creating from a template repository
  • Creating a repository for the authenticated user
  • Creating an organization repository
• GitHub asynchronously initializes default repository metadata such as labels after the creation API call completes

It also handles creating an authenticated Octokit for you with octokit-from-auth.

Why Polling?

At time of writing, GitHub does not provide an API to determine whether a repository's asynchronous initialization is complete. Most noticeably, repository labels aren't created immediately, or even all at once. Labels are added in over several seconds after a repository is created.

Organization repositories may change default labels -including during repository creation- so it is not enough to check whether the number of repository labels matches an expected number. The only known way to determine whether labels have finished being populated seems to be to check whether they've stopped being added over multiple API calls.

After creating a repository, newGitHubRepository continuously polls the repository labels API up to an arbitrary 35 times. It waits until the number of labels is the same non-zero number three times in a row.

Development

See .github/CONTRIBUTING.md, then .github/DEVELOPMENT.md. Thanks! 🆕

Contributors

Josh Goldberg ✨ 💻 🖋 📖 🤔 🚇 🚧 📆 🔧

💝 This package was templated with create-typescript-app using the Bingo framework.