What you can do after this lesson
You will recognise a GitHub Actions workflow file, read it, and understand how it fits with the Git habits you have learnt. This is an overview only. The curriculum has a separate course dedicated to Actions, so here we focus on the Git-related picture. Nothing in this lesson was run against GitHub, because that needs an account and a hosted repository. The workflow file below was parsed as valid YAML and its shell command was tested locally.
What problem it solves
Teams want certain things to happen every time code changes: run the tests, check the formatting, build the site, look for leftover conflict markers. People forget. A machine does not. GitHub Actions is GitHub's built-in automation service. You describe what to run and when, in a file in your repository, and GitHub runs it on a temporary machine when the event happens. Other hosting services offer similar systems under other names.
The vocabulary
- Workflow: one automation, defined by one YAML file in the
.github/workflowsfolder. - Event: what starts it, for example
push,pull_request, a schedule or a manual button. - Job: a group of steps that run on one machine. A workflow can have several jobs, running in parallel or in sequence.
- Runner: the machine that executes a job. GitHub provides hosted runners; you can also supply your own.
- Step: one task inside a job, either a shell command (
run) or a reusable action (uses). - Action: a packaged, reusable step, such as one that downloads your repository's code onto the runner.
A small workflow, line by line
YAML uses indentation to show structure, so keep it exact. Save this as .github/workflows/check.yml:
name: Check the site
on:
push:
branches: [main]
pull_request:
jobs:
check:
runs-on: ubuntu-latest
steps:
- name: Get the code
uses: actions/checkout@v4
- name: Look for leftover conflict markers
run: |
if grep -rn "<<<<<<<" --include="*.html" .; then
echo "Conflict markers found"
exit 1
fi
- name: List the files
run: ls -laReading it:
nameis a label shown in the interface.onlists the events. This workflow runs when someone pushes tomainand for every pull request.jobsholds the jobs. Ours has one, calledcheck.runs-on: ubuntu-latestasks for a hosted Linux machine.stepsrun in order. The first uses an action namedactions/checkout, which copies your repository onto the runner. Without a checkout step the machine has no files. The@v4part picks a version of that action; version numbers change over time, so check the action's page for the current recommendation.- The second step runs a small shell script. The
|afterrun:introduces a multi-line block. Ifgrepfinds a conflict marker it prints the location and the script exits with status 1. - The third step lists files, to show that later steps run only if earlier ones succeeded.
We tested the shell part of this locally: given an HTML file containing <<<<<<< HEAD it printed the location and Conflict markers found, and given a clean file it found nothing. The same exit-status rule you met in the hooks and bisect lessons applies here: zero is success, non-zero is failure.
How it connects to Git
When you push a branch or open a pull request, GitHub starts the workflow. The result appears as a green tick or a red cross on the pull request, with logs you can open. A failing step turns the check red, so you see the problem before merging, and you fix it by pushing another commit to the same branch, which runs the workflow again.
The link to team workflow comes from branch protection, which we mentioned in earlier lessons. A repository owner can require named checks to pass before a pull request can merge into main. Then nobody can merge a change that broke the build, whatever hooks they skipped on their own computer. That is why Actions and similar services are the proper place for rules that must always apply, while local hooks are a convenience.
Common uses
- Run the project's test suite on every pull request.
- Check code style and static analysis.
- Build the site or package and keep the result for download.
- Deploy automatically after a merge to
mainor after a release tag is pushed. - Run tasks on a schedule, such as nightly checks.
Tags tie in neatly: a workflow can be triggered by pushing a tag like v1.0.0, which is how many projects publish releases.
Safety basics
Automation runs code with access to your repository, so take care:
- Secrets (passwords, deploy keys, API tokens) belong in the repository's secrets settings on GitHub, from which workflows can read them, and never in the YAML file or the code. Do not echo them in logs.
- Be careful with pull requests from strangers. Workflows triggered by outside contributors have restricted permissions by default for good reason; read the documentation before changing those settings.
- Choose actions you trust. A third-party action runs inside your workflow. Prefer well-known, maintained ones, read what they do, and consider pinning to a specific version.
- Give the workflow the least permission it needs. The documentation describes how to restrict the token a workflow receives.
- Mind usage. Hosted runners have usage limits and costs that depend on your plan and repository type; check GitHub's current documentation rather than assuming.
Common mistakes
- Wrong indentation in YAML. A single misplaced space makes the file invalid; an editor with YAML support catches it.
- Forgetting the checkout step. The runner starts empty.
- Putting a secret in the file. Remove it, revoke it and use the secrets store.
- Expecting local hooks to replace server checks. Hooks can be skipped.
- Making the workflow slow. Slow checks make people avoid pull requests.
Exercise
- Copy the workflow above into a practice repository at
.github/workflows/check.ymland commit it. (It will only run if you push to a real GitHub repository; locally you can still check that the file is valid YAML.) - Change the
onsection so that it also runs when a tag starting withvis pushed. - Write down which of the three steps would fail if an HTML file contained a conflict marker, and why.
Show one possible answer
on:
push:
branches: [main]
tags: ["v*"]
pull_request:The second step, "Look for leftover conflict markers", fails: grep finds the marker, the script prints a message and exits with status 1, so the job stops and the check shows a red cross. The third step would not run, because a job stops at the first failing step unless told otherwise.
Key points
- GitHub Actions runs automation, such as tests or checks, in response to events in your repository like a push or a pull request.
- A workflow is a YAML file in .github/workflows; it contains jobs, and each job contains steps that run on a runner.
- A step either runs a shell command with run or uses a ready-made action with uses.
- A failing step marks the check as failed on the pull request, and branch protection can require checks to pass before merging.
- Never print or hard-code secrets; use the repository's secrets storage, and pin actions deliberately.