Skip to main content

GitHub Actions

Original Author: Sumon C, December 6, 2021

What is GitHub Actions?​

For some software, there are build, test, and deployment workflows that need to happen before the software is ready for consumption. GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate such workflows, such that they do not need to happen manually. You can create workflows that build and test every pull request to your repository, or deploy merged pull requests to production.

Below, we will show and outline the specific GitHub Actions used to publish this handbook.

Manual Handbook Deployment​

Docusaurus, the specific static website generator used for this handbook, is built on React and requires the single-page application to be built before the website can be deployed and published. The entire process is usually done through the terminal on the local machine.

Building the handbook​

Building the application is done with the following commands:

# Build the single page application
yarn run build

# Test the single page application on localhost
yarn run serve

Deploying the handbook​

At REDCap@Yale, the built application is then published and deployed on GitHub Pages.

This is done manually with the following command:

GIT_USER=<GITHUB_USERNAME> yarn deploy

Automated Deployment​

GitHub Actions allows us to automate the above commands, triggered by certain conditions.

In our case, the build and deployment process is triggered when a pull request or push is made to the production branch of the repository. All changes are made in the dev branch until ready for publication.

Setting up the GitHub Actions​

To set up this automation, a workflow YAML file must be created in the /.github/workflow directory.

In our case, the file is called /.github/workflow/docusaurus-deployment.yml.

The specific workflow can be found below.

docusaurus-deployment.yml
name: docusaurus-deployment

on:
  push:
    branches: [production]
  pull_request:
    branches: [production]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - name: Check out repo
        uses: actions/checkout@v2
      # Node is required for npm
      - name: Set up Node
        uses: actions/setup-node@v2
        with:
          node-version: "12"
      # Install and build Docusaurus website
      - name: Build Docusaurus website
        run: |
          npm install 
          npm run build
      - name: Deploy to GitHub Pages
        if: success()
        uses: crazy-max/ghaction-github-pages@v2
        with:
          target_branch: gh-pages
          build_dir: build
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

This specific workflow checks out the changes in the repo, builds the new Docusaurus website, and then deploys the newly built site to GitHub Pages. All of this runs on GitHub's cloud Ubuntu instances, and thus no manual commands are needed.

Learn more​

You can learn more about GitHub Actions through its documentation.

Many other workflows are pre-packaged and can be found in the GitHub Marketplace.