Lately, I've been diving deep into GitHub APIs and GitHub Actions to help improve the workflows of an open-source project that had some issues with their GitHub Action files. To expand my knowledge, I attended a workshop presented by Chris Reddington on automating repetitive tasks with GitHub Actions and made some insightful discoveries. I'd like to share what I've learned, used and love about GitHub Actions.

Resources

• GitHub Actions extension for VS Code - help edit and build yaml files

• Marketplace - where developers/organization share GitHub Actions (repos) they created

  • Example: https://github.com/marketplace/actions/upload-a-build-artifact

Prerequisite

• In your repository, create the .github/workflows/ directory to store your workflow files, such as your_workflow_name.yml.

• Set up your repo on GitHub and if you make changes locally, push them to your remote repo.

Choose your trigger

You can configure your workflows to run when specific activity on GitHub happens, at a scheduled time, or when an event outside of GitHub occurs.

Events that trigger workflows

GitHub Actions Workflow Syntax

Jobs

• Jobs are the fundamental building blocks of GHA.

• A workflow can have one or more jobs.

• on specifies the trigger for this workflow. check all events that can trigger a workflow.

• Jobs can run parallel or in sequence.

  • If a job needs to wait for other jobs to finish before it starts, use needs: [] and add dependencies in the array.

• runs-on states the platform we want to run the job. GitHub Actions supports several different operating systems and environments.

• steps groups the steps, each of which is a separate action or shell script.

• uses specifies that this step will run a specific version of the actions/checkout action.

  • Example: - uses: actions/checkout@v3 is an action that checks out your repository, which allows you to run scripts or other actions against your repo. You should use the checkout action any time your workflow needs to access the repository's code.

  • Sometimes there is a with under uses (see example below), which supplies the action/script with some required or optional property:value pair(s).

      steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 16
      - run: npm ci
      - run: npm test
      # https://github.com/actions/setup-node#usage
    

• run tells the job to execute a command on the runner, such as echo a string.

Variables

GitHub sets default variables for each GitHub Actions workflow run. You can also set custom variables for use in a single workflow or multiple workflows.

Default Environment Variables

Example from GitHub Docs:

Environment variables for a single workflow

• Specify variable: value under env:

  • Note: we cannot use any of the default environment variable names

  • Naming Conventions

• Syntax: $Variable

• Example from GitHub Docs:

    name: Greeting on variable day
  
    on:
      workflow_dispatch
  
    env:
      DAY_OF_WEEK: Monday
  
    jobs:
      greeting_job:
        runs-on: ubuntu-latest
        env:
          Greeting: Hello
        steps:
          - name: "Say Hello Mona it's Monday"
            run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!" # Hello Mona. Today is Monday!
            env:
              First_Name: Mona
  

Using context to access variable values

The example below shows how to use a context in an if conditional statement to access the value of a variable:

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        if: ${{ env.DAY_OF_WEEK == 'Monday' }}
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

Demo

I created a workflow file repo-name/.github/workflows/test.yml for testing. In this workflow, there are 3 jobs: the 1st job and 3rd jobs run in parallel, and the 2nd job has the 1st job as a dependency.

# When editing yaml files on GitHub, you can use opt+space (ctrl+space for windows?) to get prompts/hints for yaml syntax

name: "my test workflow" # The name of the action/workflow, will appear under "All Workflows" in "Actions" on GitHub
on:
  workflow_dispatch # enable a workflow to be triggered manually
jobs: 
  first-job: # name of the job
    runs-on: ubuntu-latest # specifies that this job will run on a virtual machine that runs Ubuntu as its operating system
    steps: 
      - run: echo "This is the first job 🌟"

  second-job:
    needs: [first-job] # wait for first-job to finish, then run this job
    runs-on: ubuntu-latest
    steps:
      - run: echo "This is the second job"

  third_job_matrix: # runs in parallel to the first job
    # A matrix strategy lets you use variables in a single job definition to automatically create multiple job runs that are based on the combinations of the variables.
    strategy: 
      matrix: # Within your matrix, define one or more variables followed by an array of values. Details on matrix: https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs
        nth_job: [3, 4, 5]
    runs-on: ubuntu-latest
    steps:
     - run: echo "This is job ${{ matrix.nth_job }}" # use ${{}} for variables

I set the workflow to be manually triggered, then, in Actions, I clicked on the testing workflow, and Run the workflow (from my testing branch).

We can see that the first and third job started, and the second job was patiently (or impatiently?) waiting for the first job to finish:

...and that was the intro to GitHub Actions! I'm super intrigued by the power of GitHub Actions and I hope you find it helpful too!

Next Steps

With a basic understanding of how workflows are designed and written, I'm excited to continue exploring GitHub Actions, including 'shopping' in the GHA marketplace for cool actions published by the open-source community, keeping my actions up to date with Dependabot, and researching how to deploy code and use GHA to get or update tokens from cloud providers. Do you have any advice or suggestions on what I should experiment with next?

Cheer,

Bitian

Cover Photo by Markus Spiske: https://www.pexels.com/photo/close-up-photo-of-matrix-background-1089438/