Reading and writing a GitHub Actions workflow

Why this matters

If your team is on GitHub, this file is where the checks on your pull requests are defined. It looks different from GitLab's but does the same things, and the differences are worth two minutes each.

The real file

This site's own workflow, entire. Same three jobs as the GitLab file: check the committed HTML is current, check the links, publish the site.

name: Site

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build-is-current:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
      - run: pip install --quiet markdown
      - run: python tools/build.py
      - name: Fail if the committed HTML is out of date
        run: git diff --exit-code || (echo "Run 'python tools/build.py' and commit the result." && exit 1)

  links:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
      - run: pip install --quiet markdown
      - run: python tools/build.py
      - run: python tools/check-links.py

  deploy:
    if: github.ref == 'refs/heads/main'
    needs: [build-is-current, links]
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
      - run: pip install --quiet markdown
      - run: python tools/build.py
      - uses: actions/upload-pages-artifact@v3
        with:
          path: .
      - id: deployment
        uses: actions/deploy-pages@v4

Line by line

name is what appears in the Actions tab. The file's own name does not matter; a repository can have many workflow files, each with its own triggers.

on is the trigger list. Here: pushes to main, and every pull request. Other common ones are schedule with a cron expression, workflow_dispatch for a manual run button, and release for publishing.

jobs contains the jobs, and each has a name you choose.

runs-on is the runner's operating system: ubuntu-latest, macos-latest, windows-latest, or a self-hosted label.

steps is the list of things the job does. A step is either:

• run: — a shell command, exactly like a GitLab script line.
• uses: — an action, a reusable step someone else published, with inputs given under with:.

actions/checkout@v4 is the one every job needs: it clones the repository into the runner. GitLab does this automatically; GitHub does not, and a job that mysteriously cannot find any files is almost always missing this step.

needs: expresses order. GitLab has stages; GitHub has dependencies between jobs, so needs: [build-is-current, links] makes deploy wait for both, and everything without a needs runs in parallel.

if: limits when a job runs, the equivalent of GitLab's rules.

permissions: grants the automatic GITHUB_TOKEN only what this job needs. Pages deployment needs pages: write and id-token: write; most jobs need nothing extra.

environment: records the job as a deployment to a named environment, which is what puts the site's URL on the repository page (lesson 14.6).

Actions, and why the version is pinned

actions/checkout@v4 means "the action published at github.com/actions/checkout, major version 4". The @v4 matters: without it there is no telling what the step will do next month. Repositories with strict security requirements pin to a full commit hash instead of a tag, because a tag can be moved.

Actions are the biggest practical difference from GitLab. There is a large public catalogue, so many jobs are three lines of uses: rather than twenty lines of shell. The trade is that each one is third-party code running with access to your repository, which is why organizations often restrict which actions are allowed.

GitLab and GitHub, side by side

Adding a check of your own

  spelling:
    runs-on: ubuntu-latest
    continue-on-error: true
    steps:
      - uses: actions/checkout@v4
      - run: npx --yes cspell "docs/**/*.md"

continue-on-error: true is the equivalent of GitLab's allow_failure: the check reports without blocking, which is the right way to introduce one to a team.

Testing a change before pushing

1. Run the run: lines yourself. They are ordinary commands.
2. Let the editor validate the YAML. VS Code and IntelliJ both know the workflow schema.
3. Push to a branch and open a pull request. Workflows triggered by pull_request run the version on your branch, so you see your change immediately.

One caveat worth knowing: a workflow triggered by pull_request from a fork does not receive secrets, so jobs needing them are skipped or fail on outside contributions. That is a deliberate protection, not a misconfiguration (lesson 10.12).

How to do it

$ cat .github/workflows/*.yml
$ python tools/build.py && python tools/check-links.py

Common mistakes

• Forgetting actions/checkout, so the job runs against an empty directory.
• Not pinning an action's version.
• Expecting stages. Order comes from needs:.
• Assuming secrets are available on fork pull requests. They are not.
• A new check added as blocking before the existing problems are cleared.
• Editing a workflow on main directly, which most rulesets prevent.