Richard Callaby

GitHub Actions is a feature offered by GitHub that allows you to automate tasks, and build, test, and deploy code directly from your repositories. Actions are event-driven and can be triggered by a variety of events such as push, pull request, issue comments, etc. The configuration file for GitHub Actions is written in YAML format. YAML is a human-readable data serialization format used to store configuration data in a structured way.

In this article, we’ll discuss the YAML format for GitHub Actions and explore the different keywords and triggers used by GitHub Actions.

YAML format for GitHub Actions

The YAML format for GitHub Actions is a structured configuration file that consists of a series of jobs. Each job defines a set of steps to perform, which can include building, testing, and deploying your code. Here’s an example YAML configuration file for GitHub Actions:

name: My GitHub Action
on:
  push:
    branches:
      - main
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Build
        run: |
          mkdir build
          cd build
          cmake ..
          make

In this example, the YAML file starts with a name key that defines the name of the GitHub Action. The on key specifies the event that triggers the GitHub Action, which in this case is a push to the main branch. The jobs key contains a list of jobs to run, and in this case, there is only one job called build. The build job runs on an ubuntu-latest virtual machine, and its steps include checking out the code, creating a build directory, running cmake, and finally building the code using make.

Keywords and triggers

Let’s take a closer look at some of the keywords and triggers used by GitHub Actions.

Name

The name key specifies the name of the GitHub Action. This is an optional key, but it’s a good practice to give your GitHub Actions a descriptive name.

On

The on key specifies the events that trigger the GitHub Action. There are many different events that you can use to trigger your GitHub Action, including push, pull_request, schedule, and many more. Here’s an example of how to use the on key to trigger a GitHub Action on a push to the main branch:

on:
  push:
    branches:
      - main

In this example, the GitHub Action will trigger whenever a push is made to the main branch.

Jobs

The jobs key contains a list of jobs to run. Each job can have its own set of steps to perform. Here’s an example of a job called build:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Build
        run: |
          mkdir build
          cd build
          cmake ..
          make

In this example, the build job runs on an ubuntu-latest virtual machine, and its steps include checking out the code, creating a build directory, running cmake, and finally building the code using make.

Steps

The steps key defines the set of steps to perform for a job. Each step can be a shell command or a reference to an action defined in a separate repository. Here’s an example of a step that runs a shell command:

steps:
  - name: Build
    run: |
      mkdir build
      cd build
      cmake ..
      make

In this example, the step is called Build, and it runs a series of shell commands to

create a build directory, change to the build directory, run cmake, and finally build the code using make.

You can also reference an action defined in a separate repository using the uses key. Here’s an example of how to use the uses key to reference an action from the actions/checkout repository:

steps:
  - uses: actions/checkout@v2

In this example, the step uses the actions/checkout@v2 action to checkout the code from the repository.

Runs-on

The runs-on key specifies the type of virtual machine to run the job on. GitHub Actions supports many different virtual machine types, including Ubuntu, Windows, and macOS. Here’s an example of how to use the runs-on key to run a job on an Ubuntu virtual machine:

jobs:
  build:
    runs-on: ubuntu-latest

In this example, the build job runs on an ubuntu-latest virtual machine.

Environment

The environment key specifies the environment variables to set for a job. Here’s an example of how to use the environment key to set the NODE_ENV environment variable:

jobs:
  build:
    runs-on: ubuntu-latest
    environment:
      NODE_ENV: production

In this example, the build job runs on an ubuntu-latest virtual machine and sets the NODE_ENV environment variable to production.

Secrets

The secrets key specifies the secrets to use in a job. Secrets are encrypted environment variables that you can use to store sensitive data, such as API keys and access tokens. Here’s an example of how to use the secrets key to specify a secret:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        uses: my-action/deploy@v1
        env:
          API_KEY: ${{ secrets.API_KEY }}

In this example, the deploy job uses an action called my-action/deploy@v1 and sets the API_KEY environment variable to the value of the API_KEY secret.

Outputs

The outputs key specifies the outputs of a job. Outputs are variables that can be used by other jobs or workflows. Here’s an example of how to use the outputs key to specify an output:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Build
        run: make
        id: build
      - name: Get version
        run: |
          echo "::set-output name=version::$(grep -oP 'version: \K.*' package.yaml)"
        id: version
    outputs:
      version: ${{ steps.version.outputs.version }}

In this example, the build job runs the make command and sets the output of the Get version step to the version variable. The outputs key specifies that the version output should be used in other jobs or workflows.

Conclusion

In this article, we discussed the YAML format for GitHub Actions and explored the different keywords and triggers used by GitHub Actions. The YAML format for GitHub Actions provides a flexible and powerful way to automate tasks, build, test, and deploy your code directly from your repositories. By understanding the different keywords and triggers used by GitHub Actions, you can create more advanced workflows that can help streamline your development process.