GitHub Actions Fundamentals
⚙️ GitHub Actions Fundamentals
Where Workflows Live
Workflow files sit at .github/workflows/*.yml in a repository — each file is one workflow, and a repo can have several.
A Quick YAML Primer
Key-value pairs, nesting via indentation, lists via a - prefix — YAML is whitespace-sensitive and never uses tabs. Indentation mistakes are a very common early source of confusing workflow errors.
🏗️ The Core Structure
| YAML Key | Maps to Chapter 2's Concept |
|---|---|
on: | Triggers — push, pull_request, schedule, workflow_dispatch |
jobs: | A map of job-id → job definition — Chapter 2's "jobs" |
runs-on: | Which OS/runner image a job uses |
steps: | A list of commands/actions within a job — Chapter 2's "steps" |
Two Kinds of Steps
run: Steps
Execute a shell command directly — npm install, npm test.
uses: Steps
Invoke a reusable, versioned action from the marketplace — actions/checkout@v4, actions/setup-node@v4.
actions/checkout is almost always the very first step in any real job — Chapter 2's "isolated machine" point resurfaces concretely here: a fresh runner starts with a completely empty filesystem. Without checking out the repo, there's no code to build or test at all.
🛒 The Actions Marketplace
| Action | Purpose |
|---|---|
actions/checkout | Pulls the repo's code onto the runner |
actions/setup-node / setup-go / setup-python | Installs a specific language runtime version |
actions/cache | Caches dependencies between runs |
actions/upload-artifact / download-artifact | Passes files between jobs — Chapter 2's artifact fix |
Hand-Rolled vs Marketplace Action
Hand-Rolled
Writing raw shell commands to clone the repo and install a specific Node version — more to get wrong, no community maintenance.
actions/checkout + actions/setup-node
Two well-tested, versioned, widely-used actions — less code, fewer edge cases to handle yourself.
🎬 A First Complete Workflow
Tying directly back to Chapter 1's framing — automating the tests already covered in the Node.js/Express courses:
.github/workflows/ci.yml
💻 Coding Challenges
Challenge 1: Write a Workflow for a Go Project
Write a complete GitHub Actions workflow that triggers on push, checks out the repo, sets up Go 1.22 via actions/setup-go, and runs go test ./....
Goal: Practice adapting this chapter's Node.js example to a different language's marketplace action.
Challenge 2: Identify run vs uses
For each of (a) actions/checkout@v4, (b) npm run build, and (c) actions/setup-python@v5, state whether it belongs under run: or uses:, and why.
Goal: Practice distinguishing the two step types quickly and correctly.
Challenge 3: Diagnose a Missing Checkout
A workflow's first step is run: npm install (no actions/checkout beforehand), and it fails immediately with an error about a missing package.json. Explain exactly why, referencing this chapter's and Chapter 2's material.
Goal: Practice diagnosing the single most common first-workflow mistake.
actions/checkout as the First StepIt's easy to assume a runner already has the repo's code, the way a local development machine does — it doesn't. Chapter 2's "fresh, isolated machine" point applies here concretely: without actions/checkout@v4 as the very first step, the runner has no package.json, no source files, nothing at all — every subsequent step (npm install, npm test) fails immediately, not because those commands are wrong, but because there's simply no repository present to run them against. Make actions/checkout the first step in any job that needs the repo's own files, every time.
🎯 What's Next
With a first working workflow in hand, the next chapter goes deeper on the build/test stages themselves: Building & Testing in CI — matrix builds, dependency caching, and running real test suites inside a workflow.