GitHub Actions has grown in popularity since GitHub announced its availability on the platform for all developers and repositories. Many third-party platforms have speed and other limitations in the ecosystem that will further push developers to migrate their software automation to GitHub Actions.

In this article, I want to show you how I use GitHub Actions to publish npm packages that I maintain in open source projects. If you follow the GitHub process, which consists of a GitHub pull request workflow, this will further unify the workflow and improve the experience for your team and community contributors.

GitHub Actions

GitHub Actions is a technology developed by GitHub to provide developers with a way to automate their workflows around continuous integration - helping them build, deploy, schedule recurring tasks, etc. GitHub Actions is natively available and integrated into the GitHub repository repository, and features many reusable workflows from community contributors, such as publishing npm packages, publishing docker images, running security tests, and more.

Github Actions is essentially a continuous integration tool from Github. Each time you commit code to a Github repository, Github automatically creates a virtual machine (e.g. Mac / Windows / Linux) to execute one or more instructions, such as:

1
2
npm install
npm run build

The way we integrate Github Action is to create a .github folder in the root of our repository and put a *.yaml file inside, which is the file we use to configure Github Action.

Github Action usage limits

  • Each job in a Workflow can be executed for a maximum of 6 hours
  • Each Workflow can execute for up to 72 hours
  • A maximum of 24 hours per Workflow job can be queued
  • Up to 1000 API requests in an hour across all Actions in a repository
  • Number of concurrent jobs: Linux: 20, Mac: 5

What is GitHub Workflow?

A GitHub workflow is a set of jobs that run on a trigger-based or cron-based schedule. A job consists of one or more steps that make up an automated workflow. We create Workflow configurations by creating YAML files.

Building Npm package continuous integration from scratch

After understanding the basics, I will take you through a practical project to quickly get started with Github Action. The ultimate goal: after pushing our code to github, we will automatically package the project with Github Action and publish it to npm and a Github Page website with one click.

github action

Obtaining an Npm Access Token

To give Github Action the right to publish specific npm packages, you need to get an npm access token. This access token is the npm token, so we need to login to the npm website and generate a token.

Github accessToken

Get Personal Access Token

Click Generate new token to generate a new token and copy it. Note that this Personal Access Token, like the Npm Access Token above, will only be displayed when it is successfully generated and cannot be viewed once you exit.

Github accessToken

Setting up a Github Secret

After we get the npm token, we open the Github repository of the corresponding project, switch to the settings panel, find the secrets submenu, create a new secret, copy the npm token to the content area and name it.

Github Secret

Fill in the Name and Value fields, Name for ACCESS_TOKEN and NODE_AUTH_TOKEN, and Value for the Personal Access Token and Npm Access Token values you just saved.

Token Name Key Vale
Personal Access Token ACCESS_TOKEN ${{ secrets.ACCESS_TOKEN }}
Npm Access Token NODE_AUTH_TOKEN ${{secrets.NPM_TOKEN}}

Using the Workflows template

We switch to the actions panel to see a number of workflows templates, we select the following template:

Workflows template

Of course, if you have a yaml configuration, you can also create a workflow yourself for others to use.

After we click the install button, we will be redirected to the edit screen, where we can directly click the commit button on the top right.

Workflows template

At this point a workflow is created.

Configuring workflows

I’ll list the workflow for github-actions-tutorial here.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
name: Node.js Package

# 触发工作流程的事件
on:
  push:
    branches:
      - main
      - "releases/**"
      - dev

# 按顺序运行作业
jobs:
  publish-gpr:
    # 指定的运行器环境
    runs-on: ubuntu-latest
    # 设置 node 版本
    strategy:
      matrix:
        node-version: [16]
    steps:
      # 拉取 github 仓库代码
      - uses: actions/checkout@v3
      # 设定 node 环境
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
          # 设置发包 npm 地址仓库
          registry-url: https://registry.npmjs.org
      # 安装依赖,相当于 npm ci
      - name: Install dependencies 📦️
        run: npm install
      # 执行构建步骤
      - name: 构建
        run: |
                    npm run build
      # 执行部署
      - name: 部署
        # 这个 action 会根据配置自动推送代码到指定分支
        uses: JamesIves/github-pages-deploy-action@releases/v3
        with:
          # 指定密钥,即在第一步中设置的
          ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
          # 指定推送到的远程分支
          BRANCH: pages
          # 指定构建之后的产物要推送哪个目录的代码
          FOLDER: build
      - run: npm publish
        env:
          # 刚刚设置的 NPM_TOKEN
          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

There are a few terms to introduce to you:

  • name of the Workflow, Github displays the name of the Workflow on the Action page of the repository
  • on The name of the event that triggers the execution of a Workflow, such as on: push (single event), on: push, workflow_dispatch (multiple events)
  • jobs A Workflow consists of one or more jobs, meaning a single continuously integrated run that can accomplish multiple tasks
  • steps Each job consists of multiple steps, which are executed sequentially from top to bottom
  • env environment variable, secrets.NPM_TOKEN is the secret we defined before

Commit test

Let’s modify the project code, then execute the commit.

1
2
3
git add .
git commit -m '🆕 your first commit'
git push

After a successful commit we open the github action panel of the project.

github action panel of the project

Click on the Actions tab of the corresponding Github repository to see the build process for each step. You can see that the push event we defined in *.yml is triggered, executing all the steps in jobs, packaging and pushing the packaged content to the build folder to the pages branch of the github repository.

When the jobs option is complete, go to the Settings => Pages menu of the repository, set the Source Branch field to pages, and select the root root folder.

Github Pages

Click the Save button and wait for a moment until a notification appears on top that the build was successful. Click the link to see the finished application automatically built. From now on, you only need to push to the branch specified in the yml file to automatically trigger the build and update your site automatically.