Throughout this post, you will know how to

  • Publish a package to github registry
  • Delete a package from github registry (for 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 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 in to a secreted location. In the rest of this post, <TOKEN> will be referred as this token.


Publish a package

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

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

Naming your package (via the "name" entry in package.json) in 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 password to login. This command is equivalent to adding //npm.pkg.github.com/:_authToken=<TOKEN> to $HOME/.npmrc.

Finally, yarn publish can be used to published 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 web. Go to the repository page, click "package", select the npm package. In the right side, open the "Edit package" menu. Select "Manage versions".

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

Method 2: via cli. 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 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.