Lesson 2 of 8 in CI/CD pipelines
Writing a GitHub Actions workflow
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
- 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.
- You to Workflow YAML: 1 push commit
- Workflow YAML to GitHub Actions: 2 push event
- GitHub Actions to Runner: 3 start job
- 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.
- 1Create 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 EOFpermissions: contents: readkeeps the token read-only.timeout-minutesstops a stuck job from running for hours.workflow_dispatchadds a manual Run workflow button. No secrets or deployments are involved. - 2Commit 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
hellojob, then expand each step to read its log. - 3Add 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 pushIn the run graph,
afterstarts only oncehellois green. Optional: if you have the GitHub CLI installed,gh run listshows recent runs from the terminal.
What breaks, and where to look
The Actions tab shows an
Invalid workflow filenotice 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 asif: 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 integrationor an HTTP 403.- WHY IT HAPPENS
- The workflow asked the
GITHUB_TOKENto do something itspermissionsdo not allow, for example creating a release with onlycontents: 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.
Keep going
Lesson 48 of 92 in the DevOps path