Continuous Checks: What GitHub Actions Does
Understand a workflow file, run its steps with a small stand-in, watch a failure, and learn what to check before relying on CI.
In this lesson you will
- Explain continuous integration
- Read a simple workflow file
- Run a workflow’s commands with a stand-in
- List the cautions before relying on CI
About 32 minutes
Checks that run without anyone remembering
Hooks run on your own computer, and a determined person can skip them. The next step is a check that runs on a shared machine whenever work arrives, and that nobody can quietly skip. This idea is called continuous integration, often shortened to CI: every change is automatically built and tested the moment it is pushed or proposed. GitHub’s tool for it is called GitHub Actions.
What a workflow file looks like
Actions are controlled by YAML files in a folder named .github/workflows in the repository. At the time of writing, the shape is simple. A trigger says when to run, for example on a push, on a pull request, on a schedule or by hand. A job is a group of steps that runs on a fresh machine called a runner, which you choose with runs-on. Each step either runs a command or uses a ready made action, such as the one that checks out your code. The file below was written for real by the session, and the project it checks is a tiny calculator with two tests.
$ mkdir garden-notes
$ cd garden-notes
$ git init
Initialized empty Git repository in /home/nia/garden-notes/.git/
$ mkdir -p .github/workflows
$ echo 'name: Check' > .github/workflows/check.yml
$ echo 'on:' >> .github/workflows/check.yml
$ echo ' push:' >> .github/workflows/check.yml
$ echo ' branches: [main]' >> .github/workflows/check.yml
$ echo ' pull_request:' >> .github/workflows/check.yml
$ echo 'jobs:' >> .github/workflows/check.yml
$ echo ' test:' >> .github/workflows/check.yml
$ echo ' runs-on: ubuntu-latest' >> .github/workflows/check.yml
$ echo ' steps:' >> .github/workflows/check.yml
$ echo ' - uses: actions/checkout@v4' >> .github/workflows/check.yml
$ echo ' - run: python3 test_calc.py' >> .github/workflows/check.yml
$ echo 'def add(a, b):' > calc.py
$ echo ' return a + b' >> calc.py
$ echo 'from calc import add' > test_calc.py
$ echo 'assert add(2, 3) == 5' >> test_calc.py
$ echo 'assert add(-1, 1) == 0' >> test_calc.py
$ echo 'print("tests passed")' >> test_calc.py
$ python3 test_calc.py
tests passed
$ git add .
$ git commit -m "Add calc, tests and a check file"
[main (root-commit) 1e86c14] Add calc, tests and a check file
3 files changed, 17 insertions(+)
create mode 100644 .github/workflows/check.yml
create mode 100644 calc.py
create mode 100644 test_calc.py
name: Check
on:
push:
branches: [main]
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: python3 test_calc.py
GitHub itself cannot be reached from here, so this file is a labelled pattern: it was never run on GitHub. The version number after the checkout action is the kind of detail that changes, so check the action’s own page for the current one. Used together with the protected branch rules from lesson 18, a workflow can be made a requirement: a pull request cannot be merged until its checks pass.
Running the same checks ourselves
You can learn almost everything about a workflow by imitating it. The short program below reads the real file with a YAML library, lists the triggers, and runs every step that has a command. The steps that use a ready made action are skipped, because there is no hosted machine to supply it. The program needs the free PyYAML package, which you can install with pip.
import subprocess, yaml
REPO = "/home/nia/garden-notes"
text = open(REPO + "/.github/workflows/check.yml").read()
flow = yaml.safe_load(text)
print("top level keys:", list(flow))
triggers = flow.get("on", flow.get(True))
print("triggers:", ", ".join(triggers))
steps = flow["jobs"]["test"]["steps"]
failed = False
for number, step in enumerate(steps, 1):
if "run" in step:
done = subprocess.run(step["run"], shell=True, cwd=REPO, capture_output=True, text=True)
result = "pass" if done.returncode == 0 else "fail (exit " + str(done.returncode) + ")"
failed = failed or done.returncode != 0
print("step " + str(number) + ": " + step["run"] + " -> " + result)
else:
print("step " + str(number) + ": uses " + step["uses"] + " (skipped here)")
print("workflow result:", "FAILED" if failed else "passed")
top level keys: ['name', True, 'jobs']
triggers: push, pull_request
step 1: uses actions/checkout@v4 (skipped here)
step 2: python3 test_calc.py -> pass
workflow result: passed
Look at the first line of the output: the top level keys are [‘name’, True, ‘jobs’]. The word on turned into the value True. This is a famous trap in one YAML reading convention, where plain on and yes mean true. The program works around it, and GitHub’s own reader handles it for you, but it explains some confusing messages you may meet when you parse workflow files yourself. The run found two triggers and two steps, and the test step passed.
Watching a check fail, and fixing it
Now someone changes the addition function to subtract. The test command fails with a traceback and a failure code, and the same program, run again, reports the workflow as failed. On GitHub, a failed run puts a red mark on the pull request, and with a required check, the merge button stays blocked.
$ sed -i 's/a + b/a - b/' calc.py
$ python3 test_calc.py
Traceback (most recent call last):
File "/home/nia/garden-notes/test_calc.py", line 2, in <module>
assert add(2, 3) == 5
^^^^^^^^^^^^^^
AssertionError
top level keys: ['name', True, 'jobs']
triggers: push, pull_request
step 1: uses actions/checkout@v4 (skipped here)
step 2: python3 test_calc.py -> fail (exit 1)
workflow result: FAILED
Nia puts the file back with git restore, as in lesson 5, adds one more test, and commits. The new test is committed on its own, and it was run before the commit was made. Checks protect you best when running them is the habit that comes first.
$ git restore calc.py
$ python3 test_calc.py
tests passed
$ echo 'assert add(0, 0) == 0' >> test_calc.py
$ python3 test_calc.py
tests passed
$ git commit -am "Add a test for zero"
[main fcf2299] Add a test for zero
1 file changed, 1 insertion(+)
$ git log --oneline
fcf2299 Add a test for zero
1e86c14 Add calc, tests and a check file
Things to know before you rely on it
- Cost and limits. Hosted runners have usage limits that depend on your plan and on whether the repository is public. Check GitHub’s current pages before you build something heavy.
- Secrets. Never put a password or token in a workflow file. Store it in the repository’s secrets settings and refer to it by name.
- Trust. A ready made action is code written by someone else. Prefer well known actions, and read what a third party one does.
- Speed. A check that takes half an hour will be ignored. Keep the fast checks in the main workflow.
Treating a green tick as proof that the work is good. A check only tests what it was written to test, and a thin test suite passes bad code.
The calculator, the workflow and the runner are made up or simplified. The stand-in program is not GitHub’s runner, and no workflow was run on GitHub. Syntax, version numbers, limits and screens change over time, so follow GitHub’s current help pages.
Practice for this lesson
Check what you learned
Five quick questions. Pick an answer and you will see straight away whether it is right and why.
What does continuous integration mean?
- Everyone commits at the same time
- The project never has releases
- Every change is automatically built and tested when it arrives
- Only one person pushes
Pushes and pull requests trigger the same checks every time.
Where do GitHub Actions workflow files live?
- Inside the .git folder
- In the README
- On your desktop only
- In a folder named .github/workflows
The session created the file in that folder.
What are the three main parts of a simple workflow?
- A branch, a tag and a stash
- A trigger, a job and its steps
- A fork, a clone and a push
- A README, a licence and a log
The file named triggers, one job, and two steps.
Why does the word on show up as True when the file is parsed?
- The file is corrupt
- Python cannot read YAML
- One YAML reading convention treats plain on as true
- GitHub changed it
The top level keys listed True instead of on.
Where should a workflow get a password?
- From the repository secrets settings, never from the file
- Written inside the workflow file
- From the README
- From the commit message
A secret in a committed file stays in history.
Summary
- CI runs the same checks on every change, on a shared machine.
- A workflow has triggers, jobs and steps, in YAML files under .github/workflows.
- Required checks plus branch protection can block a failing merge.
- Keep secrets out of workflow files and read third party actions before using them.
Questions
Do I need Actions to test my project?
No. You can run the same commands by hand or in a hook. Actions add the shared machine and the visible result on every pull request.
Is it free to run workflows?
Plans include some usage, and limits differ between public and private repositories. Check GitHub's current pages before you rely on it.
What if my check passes on my computer but fails there?
The runner starts from a clean machine, so something your computer had, such as an installed tool or a local file, is missing. Making the workflow install what it needs fixes it.
