SpunkArt
Command line and project setup

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

TermMeaning
WorkflowThe whole file: a name, its triggers and its jobs
EventWhat starts it, under the on: key
JobA group of steps that runs on one fresh machine (a runner)
StepOne shell command (run:) or one reusable action (uses:)
ActionPackaged 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:

  1. on: starts the workflow on pushes to main and on every pull request.
  2. permissions: limits the automatic token to reading the code. Grant more only to jobs that need it.
  3. runs-on: picks a GitHub-hosted Ubuntu runner.
  4. The matrix runs the job twice, once per Node version listed, and shows each as its own check.
  5. cache: npm asks the setup action to reuse downloaded packages between runs, keyed on the lock file.
  6. npm ci installs 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: with paths: ['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_target event. 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 an env: variable so the shell treats them as text.

Common mistakes

  • Forgetting checkout. Without actions/checkout the 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.10 written 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.