The Complete GitHub Actions & Workflows Guide

GitHub Actions helps you automate tasks within your software development life cycle. GitHub Actions are event-driven, meaning that you can run a series of commands after a specified event has occurred. For example, every time someone creates a pull request for a repository, you can automatically run a command that executes a software testing script.

This enables you to include Continuous Integration (CI) and continuous deployment (CD) capabilities and many other features directly in your repository.

In this article, we are going to look at the core concepts of Github Actions and even dive into creating your own custom workflows.

Why Github actions?

Build into GitHub:

Github Actions is fully integrated into Github and therefore doesn’t require other CI/CD tools like CircleCI and Jenkins. This means that it can be managed in the same place as all your other repository-related features like pull requests and issues.

Multi-container testing:

Actions allow you to test multi-container setups by adding support for Docker and docker-compose files to your workflow.

Multiple CI Templates:

Github provides multiple templates for all kinds of CI (Continuous Integration) configurations which make it extremely easy to get started. You can also create your own templates which you can then publish as an Action on the Github Marketplace.

Great free plan:

Actions are entirely free for every open-source repository and include 2000 free build minutes per month for all your private repositories which is comparable with most CI/CD free plans. If that is not enough for your needs you can pick another plan or go the self-hosted route.

Core Concepts on Github Actions

Workflow:

A Workflow is an automated process that is made up of one or multiple jobs and can be triggered by an event. Workflows are defined using a YAML file in the .github/workflows directory.

Event:

Events are specific activities that trigger a workflow run. For example, a workflow is triggered when somebody pushes to the repository or when a pull request is created. Events can also be configured to listen to external events using Webhooks.

on: 
   push:
       branches:
         - develop

Job:

By default, a workflow with multiple jobs will run those jobs in parallel. You can also configure a workflow to run jobs sequentially. For example, a workflow can have two sequential jobs that build and test code, where the test job is dependent on the status of the build job. If the build job fails, the test job will not run.

Step:

A step is an individual task that can run commands in a job. A step can be either an action or a shell command. Each step in a job executes on the same runner, allowing the actions in that job to share data with each other.

Each step can be provided with the name.

Actions:

Actions are standalone commands that are combined into steps to create a job.

Actions are the smallest portable building block of a workflow and can be combined as steps to create a job. You can create your own Actions or use publicly shared Actions from the Marketplace.

Runner:

A runner is a machine with the Github Actions runner application installed. Then runner waits for available jobs it can then execute. After picking up a job they run the job’s actions and report the progress and results back to Github. Runners can be hosted on Github or self-hosted on your own machines/servers.

The components of GitHub Actions

Below is a list of the multiple GitHub Actions components that work together to run jobs. You can see how these components interact with each other.

An example workflow for Github Actions

1 . Let’s create .github/workflows directory in our project root

2. Inside workflows directory lets create github-actions.yaml file

name: learn-github-actions
on: [push]
  branches:
    - develop
jobs:
  check-bats-version:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
        
      - name: Setup node
        uses: actions/setup-node@v2
        with:
          node-version: '14'
          
      - run: npm install -g bats
      - run: bats -v

3. Commit these changes and push them to your GitHub repository

Understanding the above workflow file

name: learn-github-actions

Optional — The name of the workflow as will appear in the Actions tab of the GitHub repository.

on: [push]

Specify the event that automatically triggers the workflow file. This example uses the push event so that the jobs run every time someone pushes a change to the repository. You can set up the workflow to only run on certain branches, paths, or tags. For syntax examples including or excluding branches, paths, or tags, see “Workflow syntax for GitHub Actions.”

jobs:

Groups together all the jobs that run in the learn-github-actions workflow file.

check-bats-version:

Defines the name of the check-bats-version job stored within the jobs section.

runs-on: ubuntu-latest

Configures the job to run on an Ubuntu Linux runner. This means that the job will execute on a fresh virtual machine hosted by GitHub. For syntax examples using other runners, see “Workflow syntax for GitHub Actions.”

steps:

Groups together all the steps that run in the check-bats-version job. Each item nested under this section is a separate action or shell command.

- uses: actions/checkout@v2

The uses keyword tells the job to retrieve v2 of the community action named actions/checkout@v2. This action checks out your repository and downloads it to the runner, allowing you to run actions against your code (such as testing tools). You must use the checkout action any time your workflow will run against the repository’s code or you are using an action defined in the repository.

- uses: actions/setup-node@v2
      with:
        node-version: '14'

This step uses the actions/setup-node@v2 action to install the specified version of the node software package on the runner, which gives you access to the npm command.

- run: npm install -g bats

The run keyword tells the job to execute a command on the runner. In this case, you are using npm to install the bats software testing package.

- run: bats -v

Finally, you’ll run the bats command with a parameter that outputs the software version.

Visualizing the workflow file

Once your job has started running, you can see a visualization graph of the run’s progress and view each step’s activity on GitHub.

1. On GitHub.com, navigate to the main page of the repository.
2. Under your repository name, click Actions.

3. In the left sidebar, click the workflow you want to see.

4. Under “Workflow runs”, click the name of the run you want to see.

5. Under Jobs or in the visualization graph, click the job you want to see.

6. View the results of each step.

Other Important Topics

Dependent Jobs:

By default, a workflow with multiple jobs will run those jobs in parallel. You can also configure a workflow to run jobs sequentially. Suppose we have 3 jobs but need to run jobs sequentially.

jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]

Add Github Secrets

We can add our environment variables to the GitHub secret as follows:

1. Go to your project on Github
2. Select the Settings tab
3. Click the Secrets section in the left-hand menu

Add a new secret and provide a name (e.g. SLACK_WEBHOOK_URL) and a value.

Environment segregation

We can create different environments in our repository and segregate secrets(environment variables) to specific environments.

Let’s create environments: development, Preview, and Production by going into repository > settings > Environments.

Then under your desired environment, you can add environment variables as secrets. And then for a specific job in your workflow, you can specify the environment and the secrets we use in that specific job are retrieved from the environment specified.

To access these secrets(environment variables) stored under our environment file, we need to specify the environment we are going to use in our ‘job’ just under the ‘runs-on’ as below.

Then you can access the environment secrets just like we accessed normal secrets stored in our Github Repository.

name: build-app

on:
  push: 
    branches: [develop]

jobs:
  build-the-app: 
    runs-on: ubuntu-latest
    environment: development
    steps: 
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Get environment variables
        run: echo ${{ secrets.SLACK_WEBHOOK_URL }}

Conclusion

The best platform for you all depends on your specific needs. If you host your code somewhere other than GitHub.com or GitHub Enterprise, you will be better off using CircleCI. However, if you host your code on GitHub.com or GitHub Enterprise, the choice can be a little more difficult.

If you have complex projects or projects that need the hefty boost of GPU builds, I would suggest trying out or sticking with CircleCI. They have a few more options to help with more complex build scenarios since they are the mature CI/CD, service provider.

For most people, if they have a small number of projects whose CI/CD config files are relatively simple, I would suggest moving over to try GitHub Actions. Don’t disconnect or delete your current pipelines until you try GA out for a project or two, however. Just add the config files in for GA and see how you like the flow and feel of it. Once you verify that GA has everything you need to do your builds properly and successfully, and they have been running for at least a week or two successfully, you can delete your other config files and cancel your previous CI/CD service.