Continuous Integration with GitHub Actions

Efficient developers implement CI/CD pipelines to automate all sorts of tasks:

, simplify the complex process of automating builds, testing and deployments. Developers define the build environment (e.g., programming language, type and version of runtime engine and operating system) and tasks to execute all within a single configuration file, often formatted using YAML. For Travis CI, there's 

. The configuration file guides the CI/CD service as it provisions virtual machines with the proper environment and runs tasks sequentially and/or in parallel upon triggering certain repository events.

Depending on the event, you may specify a unique workflow that runs its own set of tasks. For example, merging code to the 

 branch automatically tells the CI/CD service to spin up a new isolated virtual machine and kick off a workflow that builds and deploys your application. Another common event is creating a pull request. This event also automatically tells the CI/CD service to spin up a new isolated virtual machine. However, it may kick off a workflow that lints and tests code and generates a code coverage report.

Workflows can be customized to streamline whatever tedious tasks you (and your collaborators) may forget to run. To remain productive while shipping code with confidence, you should add as many of these tasks to a CI/CD pipeline so that you can focus more on the application code.

If you already have your project hosted on GitHub, then you should consider automating the project's workflow with 

, GitHub's CI/CD solution. Choosing GitHub Actions over Travis CI or CircleCI gives you one less third-party service to worry about and store your GitHub token. Despite being launched in 

, GitHub Actions' free tier for open-source software (and monthly credits for private repositories) rivals the plans offered by other well-established services. Plus, being natively integrated with GitHub lets you automate issue triaging, hook into any GitHub event and connect with other GitHub platforms and tools like 

For those who want to programmatically interact with GitHub Actions, the 

 provides access to GitHub Actions via a REST API.

Below, I'm going to show you how to set up and run a workflow with GitHub Actions.

In this tutorial, we will write an automated workflow for a 

. The library converts a color from its hexadecimal representation to its RGB representation and vice-versa.

When a contributor creates a new pull request, the workflow should...

This way, we can check if the changes made in a new pull request unintentionally introduce bugs that break existing functionality even if the submitter forgets to lint and test their changes.

To begin, clone this library to your local machine:

$ git clone https://github.com/newline-sandbox/rgb-hex.git

Within the library's directory, delete the 

 directory so that you can create your own GitHub repository to try out GitHub Actions.

To enable a workflow for the library's GitHub repository, create a 

 directory at the root of the library's directory and create a 

$ mkdir -p .github/workflows
$ touch .github/workflows/pull-request.yml

, let's name the workflow "Pull Request."

We want GitHub to trigger this workflow whenever a pull request:

Essentially, we want to lint and test the code whenever we make any changes to it.

 workflow syntax, we can define which GitHub event/s trigger the workflow. Events range from repository events (e.g., creating a pull request) to workflow events (e.g., after a workflow has completed).

To run a workflow anytime a pull request event occurs, nest 

 to specify the types of pull request events to trigger on and 

 to narrow the pull requests to listen for events on by target branch.

The workflow should run for pull requests with a target branch of 

name: Pull Request

on:
  pull_request:
    branches:
      - main
    types: [opened, reopened, synchronize]

 (ID of the job). This job runs on a fresh virtual machine with the latest Ubuntu operating system installed.

# ...

jobs:
  pull-request:
    runs-on: ubuntu-latest

 job consists of several steps. The first step is to checkout the code with the 

# ...

jobs:
  pull-request:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

This lets the workflow access your repository. Then, the job must install the latest LTS version of Node.js (16.x) on the virtual machine with the 

# ...

jobs:
  pull-request:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: "16.x"
          registry-url: "https://npm.pkg.github.com"
          scope: "@GITHUBUSERNAME"

 with your own GitHub username (must include the 

 prefix). Once installed, the job installs the library's npm dependencies via the 

, but is used in CI/CD environments to ensure a clean installation of the dependencies.

# ...

jobs:
  pull-request:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: "16.x"
          registry-url: "https://npm.pkg.github.com"
          scope: "@GITHUBUSERNAME"
      - run: npm ci

 syntax applies to GitHub actions and the 

With the environment prepared, the job lints and tests the library's code, like so:

# ...

jobs:
  pull-request:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: "16.x"
          registry-url: "https://npm.pkg.github.com"
          scope: "@GITHUBUSERNAME"
      - run: npm ci
      - run: npm run lint
      - run: npm run test

 to generate a comment within the pull request that tabulates the statements, branches, functions and lines covered by tests.

# ...

jobs:
  pull-request:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: "16.x"
          registry-url: "https://npm.pkg.github.com"
          scope: "@GITHUBUSERNAME"
      - run: npm ci
      - run: npm run lint
      - run: npm run test
      - uses: artiomtr/jest-coverage-report-action@v2.0-rc.5
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

The action must be provided an action parameter of 

name: Pull Request

on:
  pull_request:
    branches:
      - main
    types: [opened, reopened, synchronize]

jobs:
  pull-request:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: "16.x"
          registry-url: "https://npm.pkg.github.com"
          scope: "@GITHUBUSERNAME"
      - run: npm ci
      - run: npm run lint
      - run: npm run test
      - uses: artiomtr/jest-coverage-report-action@v2.0-rc.5
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          #   threshold: 80 # optional parameter auto-reject if below.
      - run: npm run build
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

When you initialize a new GitHub repository and try to push the library to a new remote GitHub repository, you may run into the following error message:

! [remote rejected] main -> main (refusing to allow a Personal Access Token to create or update workflow `.github/workflows/pull-request.yml` without `workflow` scope)

This means your personal access token does not include the 

, select your personal access token (the one currently stored on your local machine) and check the 

 checkbox under the list of available scopes:

: If you have not set up a personal access token, then please set one up by following the directions in the official documentation 

Under the "Actions" tab of the library's GitHub repository page, you will find the "Pull Request" workflow listed under "Workflows."

Suppose you add a new function to the library and decide to create a new pull request to have it reviewed before being merged to the 

Once the pull request is created, GitHub triggers the "Pull Request" workflow.

Click "Details" to view the logs of the job as it's in progress.

Once the job finishes, revisit the pull request. You will notice that the checks have passed and a code coverage report has been generated by the 

Workflow jobs in GitHub Actions can be composed from smaller actions. Visit GitHub's marketplace 

 to explore the many open-source actions that can be integrated into your CI/CD pipeline.

Try out GitHub Actions on your next project!

AUTHOR

Ken Chan

Efficient developers implement CI/CD pipelines to automate all sorts of tasks: Cloud-based CI/CD services, such as Travis CI and CircleCI, simplify the complex process of automating builds, testing and deployments. Developers define the build environment (e.g., programming language, type and…

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Free Tools

Continuous Integration with GitHub Actions

Responses (0)

Free AI Career Tools

AI Job Listings

ATS Resume Checker

Startup Perks

Masterclasses

Tutorials

Fullstack React with TypeScript