Introduction

GitHub Actions (GHA) is a service for continuous integration & deployment.

A simple Continuous Integration workflow. Image from https://semaphoreci.com/continuous-integration

But you don’t have to consider yourself a software engineer to use it! Any repetitive task can potentially be automated with GitHub Actions. Just a few examples:

How to write GitHub Actions workflows

Workflows are defined as YAML files in a specific directory in your repo: .github/workflows/.

Create this directory if you haven’t already:

mkdir -p .github/workflows/

Create a YAML file:

touch .github/workflows/hello-world.yml

And open it in your favorite text editor.

Anatomy of a GHA workflow

.github/workflows/hello-world.yml
1name: Hello world!

2on: push

jobs:
3  myjob1:
4    runs-on: ubuntu-latest
5    steps:
6      - run: echo "🎉 Hello world!"
7      - run: |
          echo "The job was triggered by"
          echo "a ${{ github.event_name }} event."
1
Name of the workflow
2
Triggers: events that cause the workflow to run
3
Name of a job. Jobs can run sequentially or in parallel.
4
Which virtual machine to run the job on
5
List of steps in the job
6
A single step or action that runs bash code
7
A multiline step

How to run your first workflow

Copy the above YAML code to .github/workflows/hello-world.yml and save the file.

Add, commit, and push your workflow file to GitHub:

git add .github/workflows/hello-world.yml
git commit -m 'ci: create hello-world workflow'
git push

In a web browser, navigate to your repo’s Actions tab. On the left sidebar you’ll see the name of your action: click on it and you’ll see a list of the workflow runs (i.e. times it was executed). Click on the most recent run to see the details of the execution and the logs for each step.

log for the “Hello world” workflow

Actions steps

Writing custom steps for your workflows is powerful, but you’re not limited to only what you can implement. You can reuse Actions created by others’, including many that are maintained by GitHub.

.github/workflows/hello-checkout.yml
name: hello checkout

on: push

jobs:
  myjob1:
    runs-on: ubuntu-latest
    steps:
1      - uses: actions/checkout@v4
2      - name: List files in the repository
3        run: |
          ls ${{ github.workspace }}
1
Use the action from actions/checkout to checkout the repo. The version is specified with @v4.
2
Name of the run step (optional).
3
List the files in the repo, which was checked out to the github.workspace variable.

github.workspace is a variable defined by GHA1. You can access variables in workflows with a dollar sign and double curly braces: ${{ variable }}.

The current working directory is github.workspace by default, and this is where your repo is checked out.

Triggers

So far we’ve used the push trigger, which triggers the workflow to run every time a commit is pushed to the repo on GitHub. There are a myriad of triggers2 you can use, and you can mix-and-mitch in the same workflow. Here are a few of the most common triggers:

.github/workflows/demo-triggers.yml
name: demo triggers

on:
1  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]
2  workflow_dispatch:
3  schedule:
    - cron: '0 12 * * 1'

jobs:
  myjob1:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 
        run: |
4          echo "Event: ${{ github.event_name }}"
1
Triggers the workflow on push or pull request events, but only for the “main” branch.
2
Allows you to run this workflow manually from the Actions tab.
3
Triggers the workflow on a cron schedule3. This one runs at 12:00 UTC on every Monday.
4
Print the event that triggered the run.

Let’s try running this workflow manually! After you add this workflow to your repo, navigate to the Actions tab and click on the workflow name. A button will appear: run workflow. Click it and select the branch you want to run on. Refresh the page and you will see your manually triggered run in the log. What is the value in github.event_name when you run the workflow manually?

log for “demo triggers” when triggered by a push

log for “demo triggers” when trigged by a manual workflow_dispatch

What now?

So far, we’ve learned the basics of how to write Github Actions workflows. Next you’ll see some useful examples of GHA in practice and learn about more advanced features along the way.