How to write a GitHub Actions workflow
A GitHub Actions workflow is a YAML file in your repository that runs commands when something happens, such as a push or a pull request. You can write a useful one in about twenty lines. This guide builds one up and explains each key.
Where the file goes
Workflows live in .github/workflows/ at the root of the repository. Any file there ending in .yml or .yaml is a separate workflow. GitHub reads them from the commit that triggered the run, so a change to a workflow takes effect as soon as it is pushed.
The vocabulary
| Term | Meaning |
|---|---|
| Workflow | The whole file: a name, its triggers and its jobs |
| Event | What starts it, under the on: key |
| Job | A group of steps that runs on one fresh machine (a runner) |
| Step | One shell command (run:) or one reusable action (uses:) |
| Action | Packaged steps published in a repository, such as actions/checkout |
Jobs run in parallel by default. Steps inside one job run in order and share the same files, which is why checkout comes first.
A complete test workflow
name: CI
on:
push:
branches: [main]
pull_request:
permissions:
contents: read
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
node: [20, 22]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node }}
cache: npm
- run: npm ci
- run: npm test
Reading it from the top:
on:starts the workflow on pushes tomainand on every pull request.permissions:limits the automatic token to reading the code. Grant more only to jobs that need it.runs-on:picks a GitHub-hosted Ubuntu runner.- The matrix runs the job twice, once per Node version listed, and shows each as its own check.
cache: npmasks the setup action to reuse downloaded packages between runs, keyed on the lock file.npm ciinstalls exactly what the lock file says, which is what you want in automation.
Indentation is the syntax
YAML uses spaces, never tabs, and the depth of each line decides what it belongs to. A list item under steps: starts with a dash; keys of that step line up under the first letter after the dash. If a workflow fails to load, the Actions tab usually names the line. Run the file through a YAML linter before you push when you are unsure.
Other useful triggers
workflow_dispatch:adds a manual “Run workflow” button.schedule:with- cron: '0 6 * * 1'runs at 06:00 UTC every Monday. Scheduled runs use UTC and can start late when the service is busy.push:withpaths: ['docs/**']runs only when matching files change.
Secrets and safety
Store tokens in the repository settings under secrets and read them as ${{ secrets.DEPLOY_TOKEN }}. GitHub masks known secret values in logs, but a script can still leak a transformed copy, so never print them. Three more habits are worth adopting:
- Pin third-party actions to a full commit hash rather than a moving tag, so the code you run cannot change under you.
- Be careful with the
pull_request_targetevent. It runs with access to secrets, so never use it to build untrusted code from a fork. - Do not insert values such as an issue title straight into a
run:line. Pass them through anenv:variable so the shell treats them as text.
Common mistakes
- Forgetting checkout. Without
actions/checkoutthe runner has no copy of your code, and every later step fails to find files. - Expecting jobs to share files. Each job gets a new machine. Use
needs:to order jobs and upload or download artifacts to pass files. - Quoting numbers. A version like
3.10written without quotes is read as the number 3.1. Write'3.10'.
Questions
Can I test a workflow without pushing?
Third-party tools can run many workflows locally in containers, but behaviour is not identical. A scratch branch is the most faithful test.
How do I run a job only on the main branch?
Add if: github.ref == 'refs/heads/main' to the job.