Lesson 2 of 8 in CI/CD pipelines

Writing a GitHub Actions workflow

Core10 minWritten for GitHub Actions (hosted runners)

A GitHub Actions workflow is a YAML file in .github/workflows/ that names the events to react to and the jobs to run. Each job lists steps that either run a shell command with run or reuse a packaged action with uses.

Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.

Read these first: Git and collaboration, The anatomy of a pipeline

The problem this solves

Knowing that a pipeline has triggers, jobs and steps is not enough. You need the exact file shape that a CI service reads, and YAML is strict about indentation, so a small slip gives you a confusing result.

The goal here is the smallest workflow that is safe to push to a repository you can delete afterwards, and a clear picture of which line controls what.

How it works

How a push becomes a running job
How a push becomes a running jobYou push a commit that contains a workflow file, GitHub matches the push against the `on:` section, starts a runner for each job, and streams the logs back to the Actions tab.1 push commit2 push event3 start job4 streamoutputYougit pushWorkflow YAML.github/workflows/GitHub Actionsmatches on: filtersRunnerubuntu-latestRun logsActions tab
  • People and clients
  • Data
  • Control
  • Runs code

You push a commit that contains a workflow file, GitHub matches the push against the `on:` section, starts a runner for each job, and streams the logs back to the Actions tab.

  1. You to Workflow YAML: 1 push commit
  2. Workflow YAML to GitHub Actions: 2 push event
  3. GitHub Actions to Runner: 3 start job
  4. Runner to Run logs: 4 stream output

The file has a few top-level keys. name is a label. on lists the events that start the workflow, and can narrow them with filters such as branches and paths. permissions sets what the built-in GITHUB_TOKEN may do. jobs holds one or more jobs.

Under a job, runs-on picks the runner type, and steps is an ordered list. A step with run executes shell commands. A step with uses pulls in a reusable action, for example actions/checkout, which copies your repository onto the runner. Without checkout, the runner has none of your files.

Jobs run in parallel by default. needs: build makes a job wait for the build job to succeed. If the needed job fails or is skipped, the dependent job is skipped as well.

Other tools express the same ideas in different syntax. GitLab CI uses stages and script: lines in .gitlab-ci.yml, and Jenkins uses a Jenkinsfile. The trigger, job, step and runner model is the same.

Try it yourself

You need a free GitHub account and a throwaway repository. Create an empty repository named ci-demo on github.com first, and delete it when you finish all the concepts. Replace <you> with your username.

  1. 1
    Create the smallest safe workflow
    mkdir -p ~/ci-demo/.github/workflows && cd ~/ci-demo
    git init
    cat > .github/workflows/hello.yml <<'EOF'
    name: hello
    on:
      push:
        branches: [main]
      workflow_dispatch:
    permissions:
      contents: read
    jobs:
      hello:
        runs-on: ubuntu-latest
        timeout-minutes: 5
        steps:
          - uses: actions/checkout@v4
          - run: echo "commit $GITHUB_SHA on branch $GITHUB_REF_NAME"
          - run: ls -la
    EOF

    permissions: contents: read keeps the token read-only. timeout-minutes stops a stuck job from running for hours. workflow_dispatch adds a manual Run workflow button. No secrets or deployments are involved.

  2. 2
    Commit and push to your throwaway repository
    git add .
    git commit -m "Add hello workflow"
    git branch -M main
    git remote add origin https://github.com/<you>/ci-demo.git
    git push -u origin main

    Open the repository on GitHub and click the Actions tab. A run named after your commit should appear within a few seconds. Click it, then the hello job, then expand each step to read its log.

  3. 3
    Add a second job that waits for the first
    cat >> .github/workflows/hello.yml <<'EOF'
      after:
        needs: hello
        runs-on: ubuntu-latest
        timeout-minutes: 5
        steps:
          - run: echo "the hello job succeeded"
    EOF
    git commit -am "Add a dependent job"
    git push

    In the run graph, after starts only once hello is green. Optional: if you have the GitHub CLI installed, gh run list shows recent runs from the terminal.

What breaks, and where to look

  • The Actions tab shows an Invalid workflow file notice with a line number, and no run starts.

    WHY IT HAPPENS
    The YAML does not parse or a key is misplaced. The usual causes are tabs instead of spaces, a step indented at the wrong level, or a missing colon.
    CHECK FIRST
    Open the line GitHub points at and compare its indentation with the lines around it. Use spaces only, two per level.
  • A job shows as skipped and its steps never ran.

    WHY IT HAPPENS
    It lists needs: <other-job> and that job failed or was skipped. A dependent job does not run unless a condition such as if: always() allows it.
    CHECK FIRST
    Look at the job it needs in the run graph and fix that job first.
  • A step fails with Resource not accessible by integration or an HTTP 403.

    WHY IT HAPPENS
    The workflow asked the GITHUB_TOKEN to do something its permissions do not allow, for example creating a release with only contents: read.
    CHECK FIRST
    Read the failing step, find which API it called, and grant only that scope to that one job under its own permissions: block.

When not to use this

  • Copying a large workflow from a blog post you do not understand is risky. Each uses: line runs someone else's code with access to your repository.
  • Very long workflows become hard to read. Move repeated logic into a reusable workflow or a script in your repository once it appears in three places.

Check yourself

Which keyword makes one job wait for another?

needs. The dependent job runs only after the needed job succeeds.

Why do most workflows begin with a checkout step?

The runner starts empty, so actions/checkout is what copies your repository onto it.

Which file location does GitHub read workflows from?

YAML files directly inside .github/workflows/ in the repository.

Lesson 48 of 92 in the DevOps path

Search

Search cheat sheets and projects