Github package registry from A to Z (nodejs)

Github package registry from A to Z (nodejs)

Throughout this post, you will know how to

  • Publish a package to the Github registry
  • Delete a package from Github registry (for a public and private package)
  • Install a package from Github registry

Github registry does support Javascript (npm, yarn), Ruby (gem), Java (mvn, gradle), docker, .NET (dotnet). In this post, everything will be about Javascript (yarn or npm) only.


Credential preparation

Goto to your GitHub profile (Settings entry at the menu) -> Developer settings -> Personal access tokens -> Generate new token.

Naming your token for future reference, and select the following scopes for the token

  • repo: Full control of private repositories
  • write:packages: Upload packages to Github package registry
  • read:packages: Download packages from GitHub package registry

Click "Generate token", copy the generated token, and store it in a secreted location. In the rest of this post, <TOKEN> will be referred to as this token.


Publish a package

Go to your project, add the following entry to package.json

"publishConfig": {
	"registry": "https://npm.pkg.github.com/"
}

Naming your package (via the "name" entry in package.json) in the following format @<username>/<package-name>, where <username> is your Github username, <package-name> is the package name.

Note that the package name my-package should be the same as your repository name.

Why do I say "should" instead of "must"? It is possible to make the package name different from the repository name. Github even allows you to publish a package name without the existence of the corresponding repository. However, the behavior, in this case, is uncontrollable and I believe this is a bug. So I recommend creating the repository and match it with the package name.

Next, run npm login --registry=https://npm.pkg.github.com, use your Github username as username and the generated <TOKEN> as the password to log in. This command is equivalent to adding //npm.pkg.github.com/:_authToken=<TOKEN> to $HOME/.npmrc.

Finally, yarn publish can be used to publish the package to your Github repository.

Question: Will my package be public or private?

Answer: if the associated repository is private (public), the package is private (public).


Delete a package

  • If the package is private.

Method 1: via the web. Go to the repository page, click "package", select the npm package. On the right side, open the "Edit package" menu. Select "Manage versions".

Iterate through all versions and delete them by clicking on the "Delete" button.

Method 2: via CLI. The package can be manipulated from CLI via graphql API.

curl -sL -X POST https://api.github.com/graphql \
-H "Authorization: bearer <TOKEN>" \
-d '{"query":"query{repository(owner:\"<username>\",name:\"<package-name>\"){registryPackages(first:10){nodes{packageType,registryPackageType,name,nameWithOwner,id,versions(first:10){nodes{id,version}}}}}}"}'
{"data":{"repository":{"registryPackages":{"nodes":[]}}}} | jq .

Copy the version id, and substitute <version-id> in the following command.

curl -X POST \
-H "Accept: application/vnd.github.package-deletes-preview+json" \
-H "Authorization: bearer <TOKEN>" \
-d '{"query":"mutation { deletePackageVersion(input:{packageVersionId:\"<version-id>\"}) { success }}"}' \
https://api.github.com/graphql
  • If the package is public

Convert the package to private, delete the package with the above steps, convert the package back to the public.

If the repository is deleted, the associated package also will be gone.


How to use the package

In another project, in the project root dir, add a file named .yarnrc with the following content

"@<username>:registry" "https://npm.pkg.github.com/"

Where <username>  is your github username.

Now, you can add your package with yarn add @<username>/<package-name>. All package under @<username> scope will be downloaded from Github registry npm.pkg.github.com.

Buy Me A Coffee