Understanding GitHub Actions

Learn the basics of GitHub Actions, including core concepts and essential terminology.

Overview

GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline. You can create workflows that build and test every pull request to your repository or deploy merged pull requests to production.

GitHub Actions goes beyond just DevOps and lets you run workflows when other events happen in your repository.

For example, you can run a workflow to automatically add the appropriate labels whenever someone creates a new issue in your repository.

GitHub provides Linux, Windows, and macOS virtual machines to run your workflows, or you can host your own self-hosted runners in your own data center or cloud infrastructure.

The components of GitHub Actions

You can configure a GitHub Action workflows to be triggered when an event occurs in your repositories, such as a pull request being opened or an issue being created. Your workflow can contain one or more jobs that can run in sequential order or in parallel. Each job will run inside its own virtual machine runner, or inside a container, and has one or more steps that either run a script that you define, or run an action, which is a reusable extension that can simplify your workflow.

1. Workflow

A workflow is a configurable automated process that will run one or more jobs. Workflows are defined by a YAML file checked in to your repository and will run when triggered by an event in your repository, or they can be triggered manually, or at a defined schedule.

2. Events

An event is a specific activity in a repository that triggers a workflow run. For example, activity can originate from GitHub when someone creates a pull request, opens an issue, or pushes a commit to a repository. You can also trigger a workflow run on a schedule, by posting to a REST API, or man

3. Jobs

A job is a set of steps in a workflow that execute on the same runner. Each step is either a shell script that will be executed, or an action that will be run. Steps are executed in order and are dependent on each other.

4. Actions

An action is a custom application for the GitHub Actions platform that performs a complex but frequently repeated task. Use an action to help reduce the amount of repetitive code that you write in your workflow files.

5. Runners

A runner is a server that runs your workflows when they’re triggered. Each runner can run a single job at a time.

Example of a Workflow

1. In your repository, create the .github/workflows/ directory to store your workflow files.

2. In the .github/workflows/ directory, create a new file called first-github-action.yml and add the following code.

name: learn-github-actions
on: [push]
jobs:
check-bats-version:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- 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.

Your new GitHub Actions workflow file is now installed in your repository and will run automatically each time someone pushes a change to the repository. For details about a job’s execution history, see “Viewing the workflow’s activity.”

Understanding the workflow file

To help you understand how YAML syntax is used to create a workflow file, this section explains each line of the introduction’s example:

name: learn-github-actions

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

on: [push]

Specifies the trigger for this workflow. This example uses the push event, so a workflow run is triggered every time someone pushes a change to the repository or merges a pull request. This is triggered by a push to every branch; for examples of syntax that runs only on pushes to specific branches, paths, or tags, see "Workflow syntax for GitHub Actions."

jobs:

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

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 script.

uses: actions/checkout@v2

The uses keyword specifies that this step will run v2 of the actions/checkout action. This is an action that checks out your repository onto the runner, allowing you to run scripts or other actions against your code (such as build and test tools). You should use the checkout action any time your workflow will run against the repository's code.

To understand more about the workflow file, please refer to the official GitHub documentation.

Visualizing the workflow file

In this diagram, you can see the workflow file you just created and how the GitHub Actions components are organized in a hierarchy. Each step executes a single action or shell script. Steps 1 and 2 run actions, while steps 3 and 4 run shell scripts. To find more prebuilt actions for your workflows, see “Finding and customizing actions.”

Viewing the workflow’s activity

Once your workflow 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.

Billing

GitHub Actions usage is free for both public repositories and self-hosted runners. For private repositories, each GitHub account receives a certain amount of free minutes and storage, depending on the product used with the account. Any usage beyond the included amounts is controlled by spending limits. For more information, see About billing for GitHub Actions.