Creating packages is fun...but sometimes we need help to manage them! In part one of the GitHub series, Cogworks Dev, Adrian Ochmann, takes us through a step-by-step set-up of GitHub packages and gives us the low-down on all the benefits.
Innerworks is coming soon...
This blog was originally published on our previous Cogworks blog page. The Cogworks Blog is in the process of evolving into Innerworks, our new community-driven tech blog. With Innerworks, we aim to provide a space for collaboration, knowledge-sharing, and connection within the wider tech community. Watch this space for Innerworks updates, but don't worry - you'll still be able to access content from the original Cogworks Blog if you want.
GitHub introduced a great new functionality to manage packages in repositories called GitHub Packages. It allows many packages, including npm packages, docker images, and NuGet packages. This is a great feature if you have GitHub repositories for your project (either for client or open-source projects), as you can use this repository to store package-related items.
What are the benefits of keeping Github packages in a repository?
- One single place to maintain packages.
- Packages are associated with the repository.
- Simple process for building and releasing packages.
- Access management is easy to control in one location.
- Flexible publishing options for publishing; make a repository private or public.
- No need to purchase additional package managers (excellent support from free to a Github one).
How to publish and manage npm packages with Github: configure your PAT and publish.
1. Create two access tokens:
- A read-and-write access token (for storing all package versions).
- A read access token (to gain access to this package from another project).
2. Log in to your GitHub organization or your profile account.
3. Go to [developer settings] and then personal access tokens.
4. In the [note] field, enter the description of your personal token, then select checkboxes [write: packages], [read: packages], and [delete: packages].
Repeat steps from point 4 just for the read-only token [read:packages].
5. Add the values that need to be provided in package.json:
"version": "1.0.0", "name": "@yourOrganizationOrAccount/yourPackageName", "description": "description", "author": { "name": "authorName", "email": "email", }, "repository": { "type": "git", "url": "urlToYourRepository" }, "publishConfig": { "registry": "https://npm.pkg.github.com/yourOrganizationOrAccount" },
It's a good idea to add the .npmrc file so they can easily add all access settings (although you can also do this manually); this is used for updating the package when sending a new version to the repository.
Keeping the .npmrc with write access locally for development, testing, or releasing using GitHub Actions and the publish process is good practice. This is to avoid storing the write token in the repository instead of using GITHUB_TOKEN in the workflow. We can easily store .npmrc in another project's repository for the read token.
registry=https://npm.pkg.github.com/yourOrganizationOrAccount//npm.pkg.github.com/:_authToken=readWriteToken
After everything is configured, you can easily publish your package using the command npm publish.
That's it for publishing; you should now see this package in your repository and package details.
How to manage the GitHub repository.
An example of a package:
An example of package details:
How to upload your package to another project.
Install it from the command line:
$ npm install @yourOrganizationOrAccount/[email protected]
Then install via package.json:
"@yourOrganizationOrAccount/yourPackageName": "1.0.0"
In your project, you can also store the .npmrc file with configuration and read token (this is the same file as on upper setup example...but with a read token). You can find more information about how to use npm with GitHub here.
How to remove packages from GitHub for private repositories.
'You can only delete a specified version of a private package on GitHub or with the GraphQL API. To remove an entire private package from appearing on GitHub, you must delete every package version first' (GitHub).
How to remove packages from GitHub for public repositories.
'To avoid breaking projects that may depend on your packages, you cannot delete an entire public package or specific versions of a public package.
Under special circumstances, such as for legal reasons or to conform with GDPR standards, you can ask GitHub Support to delete a public package for you using our contact form.' - (GitHub).
How to delete GitHub packages via a browser.
1. Go to your package repository, go to [packages] and click your package name.
2. use the [edit package] drop-down on the right and select [manage versions]
3. To the right of the version you need to delete, click [delete].
How to delete packages via GraphQL.
'Use the deletePackageVersion mutation in the GraphQL API. You must use a token with the read:packages, delete:packages, and repo scopes. ...
curl -X POST \-H "Accept: application/vnd.github.package-deletes-preview+json" \-H "Authorization: bearer TOKEN" \-d '{"query":"mutation { deletePackageVersion(input:{packageVersionId:\"216072\"}) { success }}"}' \https://api.github.com/graphql
It's also worth remembering, 'you cannot delete an entire package, but if you delete every version of a package, the package will no longer show on GitHub'. - (GitHub)
It's easy to set up and use npm!
You can see how easy it is to set up and use npm in existing GitHub repositories and the benefits it brings.
Applying careful configuration and attention to detail from the start in our projects has undoubtedly helped us continue to improve our workflow and efficiency day-to-day, and we hope you like using GitHub packages as much as we do.
Stay tuned to our blog for more tutorials on things like GitHub and Nuget! If you have any comments, message us.
- Build
- Package
- npm
- GitHub Packages