Automating Releases with GitHub Actions

Developing a static site generator (SSG) Command Line Interface (CLI) tool called TILvert was a fun experience. As I wrapped up the final lines of code, the next logical step was to share it with the world. This led me to publish TILvert to NPM, and in this blog post, I'll share the process, highlighting how I automated the release using GitHub Actions. You can find the npm package here.

Step 1: Preparing for NPM Publication

Before diving into the automation magic, I needed to make sure TILvert was polished and ready for public consumption. This involved thorough testing and ensuring that my package was not only functional but also user-friendly.

Testing and Validation

I reached out to friends and colleagues to act as beta testers, providing them with early versions of TILvert. Their feedback proved invaluable in identifying and fixing bugs, improving the user interface, and refining the overall user experience.

Step 2: Obtaining an NPM Access Token

To publish a package to NPM, you need to authenticate yourself. NPM provides access tokens for this purpose. Here’s how you can obtain one:

1. Visit the NPM website:
   Go to the NPM website and sign in or create an account if you haven’t already.

2. Access Tokens:
   Navigate to your account settings, and under the "Tokens" tab, generate a new token. Remember to give it the necessary permissions for publishing.

3. Keep it Secret:
   Treat your access token like a password. Never share it publicly, and keep it secure.

Step 3: Integrating GitHub Actions for Automation

With TILvert ready and the NPM access token in hand, the next step was to automate the release process using GitHub Actions. This would ensure a seamless and consistent deployment every time a new version was ready.

Creating the GitHub Actions Workflow

1. Create a .github/workflows directory:
   Inside your project, create a directory named .github/workflows.

2. Workflow YAML file:
   Create a YAML file within this directory, for example, release.yml. This file defines the workflow.
   

name: Release
on:
  push:
    branches:
      - "master"

jobs:
  release:
    timeout-minutes: 10
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.TOKEN }}
      - uses: pnpm/action-setup@v2
        with:
          version: 7
      - uses: actions/setup-node@v4
        with:
          node-version: "20.x"
          registry-url: "https://registry.npmjs.org"

      - name: Install dependencies
        run: pnpm install --no-frozen-lockfile

      - name: Lint
        run: pnpm run lint

      - name: Format
        run: pnpm run prettier

      - name: Test
        run: pnpm run test

      - name: Build
        run: pnpm run build

      - name: Create release branch
        run: |
          git config user.email "[e-mail]"
          git config user.name "Omar Hussein"
          git checkout -b release
          git add -f dist/ package.json
          git commit -m "Create release branch"
          git push origin release --force

      - name: Publish
        run: pnpm publish --no-git-checks
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

This workflow triggers on every push to the main branch, installs dependencies, and publishes the package to NPM.

Setting up GitHub Secrets:

In your GitHub repository, go to "Settings" -> "Secrets and variables" -> "actions" and add a secret named NPM_TOKEN with the value being your NPM access token.

Step 4: Documentation and User Instructions

A crucial aspect of a successful release is clear documentation. Ensure that users can easily understand how to install and use TILvert. This is all available in the README.md file.

Install

$ pnpm install -g tilvert
# or using the release branch
$ pnpm install -g https://github.com/omalk98/TILvert.git#release

Uninstall

$ pnpm uninstall -g tilvert

Usage

$ tilvert [flags/options] <path>

Conclusion

Publishing TILvert to NPM and automating the release with GitHub Actions has been a rewarding process. With each new version, users can benefit from the latest features and improvements without hassle. I hope this guide inspires you to share your creations with the world and streamline your release process.

Comments

[Daniel Einars]

Does this guide skip versioning?

[Omar Hussein]

It does. This was a test on deploying the project rather quickly and forgot to add automatic version updates! Whenever I get a chance I'll make sure to update the post. Thanks for the pointing it out!

[Daniel Einars]

Awesome! I look forward to reading it!