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!

<h1 data-node-type="titlePlaceholder" class="titlePlaceholder">Continuous Integration with GitHub Actions</h1><p>Efficient developers implement CI/CD pipelines to automate all sorts of tasks:</p><ul><li><p>Linting</p></li><li><p>Testing</p></li><li><p>Code Coverage</p></li><li><p>Code Compilation</p></li><li><p>Deployment</p></li></ul><p>Cloud-based CI/CD services, such as <a href="https://travis-ci.org" rel="noopener noreferrer nofollow">Travis CI</a> and <a href="https://circleci.com" rel="noopener noreferrer nofollow">CircleCI</a>, 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 <code>.travis.yml</code>, and for CircleCI, there's <code>.circleci/config.yml</code>. 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.</p><p>Depending on the event, you may specify a unique workflow that runs its own set of tasks. For example, merging code to the <code>production</code> 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.</p><p>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.</p><p>If you already have your project hosted on GitHub, then you should consider automating the project's workflow with <strong><a href="https://github.com/features/actions" rel="noopener noreferrer nofollow">GitHub Actions</a></strong>, 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 <a href="https://github.blog/2018-10-17-action-demos/" rel="noopener noreferrer nofollow">late 2018</a>, 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 <a href="https://github.com/features/packages" rel="noopener noreferrer nofollow">GitHub Packages</a>.</p><p>For those who want to programmatically interact with GitHub Actions, the <a href="https://docs.github.com/en/rest/reference/actions" rel="noopener noreferrer nofollow">GitHub Actions API</a> provides access to GitHub Actions via a REST API.</p><p>Below, I'm going to show you how to set up and run a workflow with GitHub Actions.</p><h2 class="heading-anchor-text" id="getting-started"><span>Getting Started</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#getting-started">#</a></h2><p>In this tutorial, we will write an automated workflow for a <a href="https://github.com/newline-sandbox/rgb-hex" rel="noopener noreferrer nofollow">small utility library</a>. The library converts a color from its hexadecimal representation to its RGB representation and vice-versa.</p><p>When a contributor creates a new pull request, the workflow should...</p><ol><li><p>Checkout the code.</p></li><li><p>Install a stable version (latest LTS version) of Node.js.</p></li><li><p>Install npm dependencies.</p></li><li><p>Lint the library's code.</p></li><li><p>Test the library's code.</p></li><li><p>Generate a code coverage report.</p></li></ol><p>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.</p><p>To begin, clone this library to your local machine:</p><textarea data-iscodemirror="true" data-mode="text/x-sh" data-uniqueid="cm-53nLghNspbcBDV0Wh_-RH" id="cm-53nLghNspbcBDV0Wh_-RH">$ git clone https://github.com/newline-sandbox/rgb-hex.git</textarea><p>Within the library's directory, delete the <code>.git</code> directory so that you can create your own GitHub repository to try out GitHub Actions.</p><textarea data-iscodemirror="true" data-mode="text/x-sh" data-uniqueid="cm-EOaxmRKU5arRAjoev2TtJ" id="cm-EOaxmRKU5arRAjoev2TtJ">$ cd rgb-hex
$ rm -rf .git</textarea><h2 class="heading-anchor-text" id="configuring-the-pull-request-workflow"><span>Configuring the Pull Request Workflow</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#configuring-the-pull-request-workflow">#</a></h2><p>To enable a workflow for the library's GitHub repository, create a <code>.github/workflows</code> directory at the root of the library's directory and create a <code>pull-request.yml</code> file within it.</p><textarea data-iscodemirror="true" data-mode="text/x-sh" data-uniqueid="cm--EQ1mETLLJAG4BB1Bjbxm" id="cm--EQ1mETLLJAG4BB1Bjbxm">$ mkdir -p .github/workflows
$ touch .github/workflows/pull-request.yml</textarea><p>Inside of the <code>.github/workflows/pull-request.yml</code>, let's name the workflow "Pull Request."</p><p>(<code>.github/workflows/pull-request.yml</code>)</p><textarea data-iscodemirror="true" data-mode="text/x-yaml" data-uniqueid="cm-BBLhR61MRmBPPH7U1et1V" id="cm-BBLhR61MRmBPPH7U1et1V">name: Pull Request</textarea><p>We want GitHub to trigger this workflow whenever a pull request:</p><ul><li><p>Is created.</p></li><li><p>Is reopened (after being closed).</p></li><li><p>Is updated whenever it receives new commits.</p></li></ul><p>Essentially, we want to lint and test the code whenever we make any changes to it.</p><p>Using the <code>on</code> 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).</p><p>To run a workflow anytime a pull request event occurs, nest <code>pull_request</code> under <code>on</code>, like so:</p><p>(<code>.github/workflows/pull-request.yml</code>)</p><textarea data-iscodemirror="true" data-mode="text/x-yaml" data-uniqueid="cm-FzP6cLvXkfXH-YCa6Vb0M" id="cm-FzP6cLvXkfXH-YCa6Vb0M">name: Pull Request

on: pull_request</textarea><p>Under <code>pull_request</code>, nest <code>types</code> to specify the types of pull request events to trigger on and <code>branches</code> to narrow the pull requests to listen for events on by target branch.</p><p>The workflow should run for pull requests with a target branch of <code>main</code> and that have been created (<code>created</code>), reopened (<code>reopened</code>) or received a commit (<code>synchronize</code>).</p><p>(<code>.github/workflows/pull-request.yml</code>)</p><textarea data-iscodemirror="true" data-mode="text/x-yaml" data-uniqueid="cm-AAlydXWOvXTgzo1hXjyU1" id="cm-AAlydXWOvXTgzo1hXjyU1">name: Pull Request

on:
  pull_request:
    branches:
      - main
    types: [opened, reopened, synchronize]</textarea><p>The workflow will run one job named <code>pull-request</code> (ID of the job). This job runs on a fresh virtual machine with the latest Ubuntu operating system installed.</p><p>(<code>.github/workflows/pull-request.yml</code>)</p><textarea data-iscodemirror="true" data-mode="text/x-yaml" data-uniqueid="cm-1RZjlbNMBezORVbU_qXAJ" id="cm-1RZjlbNMBezORVbU_qXAJ"># ...

jobs:
  pull-request:
    runs-on: ubuntu-latest</textarea><p>The <code>pull-request</code> job consists of several steps. The first step is to checkout the code with the <a href="https://github.com/actions/checkout" rel="noopener noreferrer nofollow">checkout action</a>, like so:</p><p>(<code>.github/workflows/pull-request.yml</code>)</p><textarea data-iscodemirror="true" data-mode="text/x-yaml" data-uniqueid="cm-eud5jAxKBAa8MpEYUvA7q" id="cm-eud5jAxKBAa8MpEYUvA7q"># ...

jobs:
  pull-request:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2</textarea><p>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 <a href="https://github.com/actions/setup-node" rel="noopener noreferrer nofollow">setup-node action</a>, like so:</p><p>(<code>.github/workflows/pull-request.yml</code>)</p><textarea data-iscodemirror="true" data-mode="text/x-yaml" data-uniqueid="cm-WulAHXioRCe9QPTEK6bxM" id="cm-WulAHXioRCe9QPTEK6bxM"># ...

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"</textarea><p>Replace <code>@GITHUBUSERNAME</code> with your own GitHub username (must include the <code>@</code> prefix). Once installed, the job installs the library's npm dependencies via the <code><a href="https://docs.npmjs.com/cli/v7/commands/npm-ci" rel="noopener noreferrer nofollow">npm ci</a></code><a href="https://docs.npmjs.com/cli/v7/commands/npm-ci" rel="noopener noreferrer nofollow"> command</a>, which works similarly to <code>npm install</code>, but is used in CI/CD environments to ensure a clean installation of the dependencies.</p><p>(<code>.github/workflows/pull-request.yml</code>)</p><textarea data-iscodemirror="true" data-mode="text/x-yaml" data-uniqueid="cm-364AN7uQo32gorrarUWSr" id="cm-364AN7uQo32gorrarUWSr"># ...

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</textarea><p>Notice that the <code>uses</code> syntax applies to GitHub actions and the <code>run</code> syntax applies to single commands.</p><p>With the environment prepared, the job lints and tests the library's code, like so:</p><p>(<code>.github/workflows/pull-request.yml</code>)</p><textarea data-iscodemirror="true" data-mode="text/x-yaml" data-uniqueid="cm-RdO3zLxOImzzZMu2kqhli" id="cm-RdO3zLxOImzzZMu2kqhli"># ...

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</textarea><p>Finally, the job uses the <a href="https://github.com/ArtiomTr/jest-coverage-report-action" rel="noopener noreferrer nofollow">Jest Coverage Report action</a> to generate a comment within the pull request that tabulates the statements, branches, functions and lines covered by tests.</p><p>(<code>.github/workflows/pull-request.yml</code>)</p><textarea data-iscodemirror="true" data-mode="text/x-yaml" data-uniqueid="cm-8saYH8XvgzVOLy-ijPeQc" id="cm-8saYH8XvgzVOLy-ijPeQc"># ...

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 }}</textarea><p>The action must be provided an action parameter of <code>github-token</code> to have permission to the repository.</p><p>Altogether...</p><p>(<code>.github/workflows/pull-request.yml</code>)</p><textarea data-iscodemirror="true" data-mode="text/x-yaml" data-uniqueid="cm-h-F6T7GNK3VwpdTh6GKQ0" id="cm-h-F6T7GNK3VwpdTh6GKQ0">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 }}</textarea><p>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:</p><textarea data-iscodemirror="true" data-mode="text/x-sh" data-uniqueid="cm-CoiWk2EpoyRK_-1gDoFTx" id="cm-CoiWk2EpoyRK_-1gDoFTx">! [remote rejected] main -&gt; main (refusing to allow a Personal Access Token to create or update workflow `.github/workflows/pull-request.yml` without `workflow` scope)</textarea><figure class="photo figure-position-inline"><img src="https://www.dl.dropboxusercontent.com/s/s15baq2l9t5v7x7/3y278y123fsdagyfdas.png" contenteditable="false"><div></div></figure><p>This means your personal access token does not include the <code>workflow</code> scope. You should visit your <a href="https://github.com/settings/tokens" rel="noopener noreferrer nofollow">GitHub tokens</a>, select your personal access token (the one currently stored on your local machine) and check the <code>workflow</code> checkbox under the list of available scopes:</p><figure class="photo figure-position-inline"><img src="https://www.dl.dropboxusercontent.com/s/ws7q5rv26ecs97f/hfdas9889218912gfa.png" contenteditable="false"><div></div></figure><p><em>Note</em>: If you have not set up a personal access token, then please set one up by following the directions in the official documentation <a href="https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token" rel="noopener noreferrer nofollow">here</a>.</p><p>Now push to the <code>main</code> branch of the remote GitHub repository.</p><p>Under the "Actions" tab of the library's GitHub repository page, you will find the "Pull Request" workflow listed under "Workflows."</p><figure class="photo figure-position-inline"><img src="https://www.dl.dropboxusercontent.com/s/3dj17smsw235irk/h2191239fhfd.png" contenteditable="false"><div></div></figure><p>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 <code>main</code> branch.</p><p>Once the pull request is created, GitHub triggers the "Pull Request" workflow.</p><figure class="photo figure-position-inline"><img src="https://www.dl.dropboxusercontent.com/s/czf4nq5beewxx5y/1289y3y12797ffuadusdfhf.png" contenteditable="false"><div></div></figure><p>Click "Details" to view the logs of the job as it's in progress.</p><figure class="photo figure-position-inline"><img src="https://www.dl.dropboxusercontent.com/s/7u6k46p00v3q63q/ery8912y8e29ededqwe.png" contenteditable="false"><div></div></figure><p>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 <a href="https://github.com/ArtiomTr/jest-coverage-report-action" rel="noopener noreferrer nofollow">Jest Coverage Report action</a>.</p><figure class="photo figure-position-inline"><img src="https://www.dl.dropboxusercontent.com/s/obz07zoi3tybf8b/fdahuosfd8y9389yy349.png" contenteditable="false"><div></div></figure><figure class="photo figure-position-inline"><img src="https://www.dl.dropboxusercontent.com/s/99ma8tm207avt53/fhdua219y12978fa.png" contenteditable="false"><div></div></figure><h2 class="heading-anchor-text" id="next-steps"><span>Next Steps</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#next-steps">#</a></h2><p>Workflow jobs in GitHub Actions can be composed from smaller actions. Visit GitHub's marketplace <a href="https://github.com/marketplace?type=actions" rel="noopener noreferrer nofollow">here</a> to explore the many open-source actions that can be integrated into your CI/CD pipeline.</p><p>Try out GitHub Actions on your next project!</p><h2 class="heading-anchor-text" id="sources"><span>Sources</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#sources">#</a></h2><ul><li><p><a href="https://docs.github.com/en/actions" rel="noopener noreferrer nofollow">GitHub Actions Documentation</a></p></li></ul><p></p>

Learn

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

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Continuous Integration with GitHub Actions

Responses (0)

Masterclasses

Tutorials

Fullstack React with TypeScript