The previous lesson ended with a promise that now has to be kept: "what is left is for you to do it". For six modules you have read Reservalia's ci.yml line by line, you have seen how an artifact is promoted by digest and how a rollback happens in four minutes. All of that was somebody else's pipeline. From here on the pipeline is yours: you write it, you break it on purpose, you fix it and you break it again until you understand why each thing fails. This first lab builds from scratch a project called Mini-Reservalia —a reduced, self-contained version of Reservalia, with the same appointments and availability domain but with no database, no AWS and no production dependencies— and puts its first continuous integration workflow on top of it, in four increments you can watch run one by one. By the end you will have a repository on GitHub where no change can reach main unless the tests are green, and you will have proved it by trying to get round it.

The project you create here is not thrown away: lessons 07-02 to 07-06 extend it. Take the code in this first part seriously, because it is the substrate for the whole module.

1. Objective, prerequisites and starting point
2. Preparing the machine and checking the tools
3. Building Mini-Reservalia from scratch
4. Initialising the repository and pushing it to GitHub
5. Increment 1: the minimal workflow that just runs
6. Increment 2: install, check and test
7. Increment 3: two jobs in parallel with needs
8. Increment 4: dependency cache and measuring its effect
9. Breaking it on purpose and reading the red
10. The real flow: branch, pull request, checks, merge
11. Protecting main and checking that it blocks
12. The status badge in the README
13. Final verification
14. Common Mistakes and Tips
15. Exercises
16. Conclusion

Objective. By the end of this lesson you will have a GitHub repository with a working Node.js project and a GitHub Actions workflow that, on every push and every pull request, installs dependencies reproducibly, runs static analysis and the tests in parallel, and blocks the merge to main if anything fails.

Prerequisites.

Starting point. An empty directory. There is nothing beforehand: this is kilometre zero.

Cost. Zero. GitHub Actions is free with unlimited minutes for public repositories. If you make the repository private you will draw on the monthly free allowance of the Free plan, which is far more than enough for this module. Recommendation: make it public.

The real equivalent in Reservalia. Reservalia's repository is private, with Actions running on larger hosted runners for the test jobs. Nothing you do here changes conceptually: what changes is the bill.

Before writing a single line, check the environment. An uncomfortable proportion of real-world "the pipeline doesn't work for me" cases are really "I have Node 16 locally and 20 in CI".

What you should see: three versions that meet the minimums. If node --version shows v18.x or lower, install a recent version (with nvm install 20 && nvm use 20, with the official installer or with your system's package manager). The native test runner has existed since Node 18, but the --test-shard option we will use in 07-02 requires Node 20.6+.

Set up your Git identity as well if you have not already, because commits with no author cause problems when computing metrics later on:

Optionally, install the GitHub CLI (gh). It is not mandatory —everything can be done from the web— but it shortens the steps considerably, and in 07-04 we will use it to compute the DORA metrics:

Mini-Reservalia solves Reservalia's central problem —given a set of opening hours and some appointments already booked, which slots are still free?— with zero production dependencies. That constraint is deliberate: a project with no dependencies starts in milliseconds, can run on any runner and keeps the focus on the pipeline, which is what we are learning.

Create the structure:

Four decisions that matter:

• "type": "module": we use ESM (import/export), just like the real Reservalia.
• "engines": documents the minimum version. It does not enforce it on its own, but npm ci warns about it and in 07-02 we will use it as the reference for the matrix.
• The four scripts (lint, test, build, start) are the contract between the project and the pipeline. This is what 06-07 called "logic in scripts and thin YAML": the workflow will not know how linting is done, only that npm run lint exists. If tomorrow you swap ESLint for something else, ci.yml does not get touched.
• Zero production dependencies: dependencies does not even appear.

This is the heart of the domain. Read it carefully, because in 07-02 you will write its edge cases.

Three details that are a common source of real bugs and are worth seeing now, because in 07-02 you will turn them into tests:

An HTTP server with no dependencies and two routes: /health (which the pipeline will use as a smoke test in 07-03) and /api/slots.

The guard at the end (process.argv[1] === fileURLToPath(import.meta.url)) is the ESM equivalent of the classic if __name__ == "__main__". Without it, any test importing the module would open a port and the test process would never finish: a classic and bewildering CI hang.

Six tests is not many: in 07-02 we will climb to the three layers of the pyramid with edge cases. For a first pipeline it is enough to have a real signal that can turn red.

Notice the await import(...) at the end: it is a verification of the artifact inside the build itself. If someone leaves a broken import, the build fails in 200 ms instead of the smoke test discovering it three stages later.

node_modules/ and dist/ out of the repository, of course. And .env from day one: 07-05 will explain in detail what a committed secret costs, but prevention starts here.

What you should see when running npm test:

And with the server running, in another terminal:

If this works on your machine, you already have the hard part: a project that knows how to verify itself with a single command. The pipeline is only going to run those commands on a machine that is not yours.

With the GitHub CLI, in one command:

What you should see: https://github.com/<your-username>/mini-reservalia and, when you open it, the files you have just created.

Without gh: create the empty repository from the web (no README, no .gitignore, no licence, to avoid a divergent history) and then:

Check that package-lock.json is in the repository. It is the requirement for the reproducible build from 02-03: without a lockfile, npm ci does not work and every pipeline run could install different versions.

We are going to build ci.yml in four steps, watching each one run. The temptation is to write the whole workflow in one go; resist it. When an 80-line workflow fails on the first attempt, you do not know which of the 80 lines is to blame.

File .github/workflows/ci.yml — version 1:

What you should see. Go to the Actions tab of your repository. A run called "ci: minimal runner check workflow" should appear, with the CI workflow. Open it, go into the Runner check job and expand the "Show the environment" step. You will see something like:

Three things you have just learnt empirically and that no amount of reading replaces:

1. The runner does not have your code by default. If you remove the actions/checkout@v4 step, ls -la comes back almost empty. Try it if you like.
2. Node is already installed on the ubuntu-latest runner, but at whatever version GitHub decides. That is why increment 2 pins the version explicitly.
3. The context travels in environment variables: GITHUB_SHA, GITHUB_REF_NAME and dozens more, exactly as we saw in 06-06.

Expected duration: between 5 and 15 seconds. Make a note of it; we will use it as a reference.

Now the pipeline does real work.

What you should see. The run now takes about 35-60 seconds. Every step green. Pay particular attention to the log of "Install dependencies":

And to the one for "Tests":

Why npm ci and not npm install. We saw this in 02-03, but now you can verify it: npm ci deletes node_modules, installs exactly what package-lock.json says and fails if the lockfile does not match package.json. npm install can update the lockfile silently, which means the pipeline would be testing a different dependency tree from the one you tested. Check it for yourself:

Undo that change before carrying on.

A single job is a single file queue: if the lint takes 20 seconds, the tests wait 20 seconds. Worse still: if the lint fails, you do not see the test results, so you fix the lint, wait again and discover there is a broken test too. Two round trips where there should have been one.

04-01 called this "feedback in a single pass". Let us split things up.

What you should see. In the run view, GitHub draws the graph: Quality and Tests side by side, and Build to their right with the dependency arrows. The first two start at the same time. At the end, at the bottom of the run page, the Artifacts section appears with a downloadable dist-<sha>.

What you have gained:

It is the classic trade-off: parallelising reduces wall-clock time and increases minute consumption. In public repositories the minutes are free, so the decision is obvious; in a private one with hundreds of daily runs it needs thinking about. Note as well that npm ci is repeated three times —once per job, because each job is a clean machine—. That is what increment 4 attacks.

actions/setup-node knows how to cache the npm directory. A two-line change:

Apply it in all three jobs. The complete file, the version that closes this lesson:

How to measure the effect properly. The first run with the cache is slower, because it has to save it. The honest measurement compares the second run with the cache against the baseline:

1. Note the time of the npm ci step from increment 3 (no cache). It is right there in the log: Run npm ci ... 8s.
2. Push the change. First run: in the setup-node log you will see Cache not found for input keys: node-cache-Linux-npm-... and at the end Cache saved with key: ....
3. Make a second, trivial push (change the README). Now the log will say Cache restored from key: node-cache-Linux-npm-<hash>.

Typical table for a project this size:

Five seconds per job does not sound like much. Multiply it by three jobs, by 40 runs a day and by 250 working days: that is roughly 40 machine hours a year on a project with no production dependencies. At Reservalia, with a node_modules of hundreds of megabytes, the cache saves minutes per run, not seconds. 04-04 quantified it; now you have seen it.

An important detail about the cache key. cache-dependency-path: package-lock.json makes the key include the hash of the lockfile. When you change a dependency, the key changes and everything is downloaded again: that is exactly what you want. A cache whose key does not depend on the lockfile is a cache that serves stale dependencies, and that is the "false green" 04-04 talked about.

A pipeline you have never seen fail is not a pipeline: it is decoration. Let us break it.

Edit src/availability.js and change a single line inside sliceIntoSlots:

It is a realistic bug: a final slot is now generated that sticks out past closing time. A business would take bookings at 11:30 when it closes at 12:00 and the service lasts 50 minutes.

What you should see locally:

Push it anyway, because that is what we want to observe:

Now open the pull request:

What you should see in the PR:

1. A checks box at the bottom of the conversation with three entries: Quality, Tests, Build.
2. Quality green (ESLint does not detect logical bugs: it only looks at the shape of the code; this is exactly the warning from 02-05).
3. Tests red, with the cross.
4. Build grey, marked as skipped: it never got to run because its needs was not satisfied. You have saved a job.
5. The merge button greyed out with the message "Some checks were not successful".

Click Details on the red check. GitHub takes you to the log of the failed step, already expanded and with the error line highlighted. On top of that, in the PR's Files changed tab a red annotation appears over the line of the test file: Node's test runner emits the failure in a format Actions recognises, so the error is shown on the code, not just in the log.

Now fix it inside the same PR:

What you should see: the PR re-runs the checks automatically (thanks to the pull_request trigger, which also fires on synchronize), all three turn green and the merge button becomes enabled. Merge it:

You have just walked the full cycle: branch → PR → red → diagnosis → fix → green → merge. It is the cycle a team repeats twenty times a day.

Let us formalise what you have just done, because the order matters and there is one step almost everybody skips.

The step people skip is npm test locally before the push. Using CI as a command interpreter —pushing to see whether it passes— turns a 3-second cycle into a 3-minute one and fills the history with commits called "fix CI", "really fix CI", "now yes". Rule of thumb: if you cannot run the command the pipeline is going to run, the pipeline is badly designed. That is why the four package.json scripts are the contract.

So far the checks are informational: nothing stops you merging when red, or pushing straight to main. Let us close that door, which is the "stop the line" of 02-01 turned into configuration.

From the web: Settings → Rules → Rulesets → New ruleset → New branch ruleset.

• Name: protect-main
• Enforcement status: Active
• Target branches: Add target → Include default branch
• Tick Require a pull request before merging (with Required approvals: 0 if you work alone; on a team, 1).
• Tick Require status checks to pass, then search for and add Quality, Tests and Build. Also tick Require branches to be up to date before merging.
• Tick Block force pushes.

With gh, in a single command (it creates the file and applies it):

Checking that it fails when it should fail. A protection you have never tried to violate is one you do not know exists. Two tests:

Test A — direct push to main:

What you should see:

Undo the local commit: git reset --hard origin/main.

Test B — merging a red PR:

Break the test again (change assert.equal(slots.length, 3) to 4 in test/availability.test.js), commit, push, open the PR and try to merge:

What you should see:

or, from the web, the merge button disabled with "Required statuses must pass before merging". Close the PR and delete the branch:

This negative check —that the system prevents what it is supposed to prevent— is as important as the positive one, and it is the one almost nobody does. A badly written required check (for example, with the name test instead of Tests) stays eternally "pending" and blocks everything; or, worse, if you configure it on a job that can be skipped, it lets anything through.

The detail that costs everybody half an hour: the name of the required check is the job's name:, not the job key in the YAML. Our test: job is called Tests because it has name: Tests. If you add the check with the wrong name, GitHub waits for it forever and the PR is never mergeable. If it happens to you, the list of exact names is in the checks box of any recent PR.

Create README.md:

npm ci npm test npm start # http://localhost:3000

Push it through a PR (you can no longer push to main, precisely):

What you should see: on the repository front page, a green badge saying CI: passing. The ?branch=main matters: without it, the badge reflects the latest run of any branch, so a broken experiment on a personal branch would turn the badge red and it would stop meaning anything.

Work through this list. Everything must hold before moving on to 07-02.

The three in bold are the ones that really prove the pipeline is worth something. A pipeline you have only ever seen green is an untested hypothesis.

Symptom: the workflow does not appear in the Actions tab after the push. Cause: the file path is wrong. It must be exactly .github/workflows/ci.yml, at the root of the repository. github/workflows/, .github/workflow/ or .github/actions/ will not do. Fix: git ls-files .github must show .github/workflows/ci.yml. If it does not, move the file and push again.

Symptom: Error: Dependencies lock file is not found in /home/runner/work/.... Cause: you have put cache: 'npm' in setup-node but package-lock.json is not committed (probably because of an overly aggressive .gitignore). Fix: check that package-lock.json is not in .gitignore, run npm install to generate it and commit it. The lockfile always goes into the repository.

Symptom: npm error code EUSAGE — npm ci can only install packages when your package.json and package-lock.json are in sync. Cause: you edited package.json by hand without regenerating the lockfile. Fix: locally, npm install (which does update the lock) and commit both files together. A package.json and a lock that do not match are the number one cause of "it works on my machine".

Symptom: the test job hangs until the 6-hour timeout. Classic cause in Node: some module imported by the tests opens a port or a timer and the process never ends. That is why src/server.js has the process.argv[1] === fileURLToPath(import.meta.url) guard. Fix: add timeout-minutes: 10 to every job —it should be a reflex— and investigate locally with node --test --test-reporter=spec test/. If the process does not end, the culprit is an open resource.

Symptom: the required check stays at Expected — Waiting for status to be reported forever. Cause: the check name configured in the ruleset does not match the job's name:, or the job does not run in that context (for example, you have a paths filter that skips it). Fix: copy the exact names from the checks box of a recent PR. And beware of paths filters: a required job that gets skipped by filters blocks the PR indefinitely; the usual solution is a "permanently green" job that always runs and that the others depend on.

Symptom: two runs of the same branch, the first cancelled with "Canceling since a higher priority waiting request exists". Cause: it is not an error. It is your concurrency block with cancel-in-progress: true doing its job. Tip: do not put this in the deployment workflow with cancel-in-progress: true; cancelling a deployment halfway can leave the system in an inconsistent state. In CI it is fine; in CD, 07-03 will use cancel-in-progress: false.

Symptom: ESLint fails with Parsing error: 'import' and 'export' may appear only with 'sourceType: module'. Cause: "type": "module" is missing from package.json, or sourceType: 'module' from eslint.config.js. Fix: both must be there. In this project, both of them.

Hygiene tip: small, frequent commits. 02-07 justified it in terms of continuous integration; here you will notice it immediately: when the pipeline turns red after a 400-line commit, the diagnosis is archaeology; after a 20-line one, it is obvious.

Add to the pipeline a formatting check with Prettier that fails if the code is not formatted, plus a format script that fixes it. The job must be called Format and run in parallel with Quality and Tests. Check that it fails by unformatting a file on purpose.

A change to README.md does not need to run three jobs. Configure the workflow to skip changes that only touch Markdown, without breaking branch protection. Think it through: if the required checks do not run, the PR is blocked forever. Explain in a YAML comment why your solution does not fall into that trap.

Make the Build job write a table into $GITHUB_STEP_SUMMARY with the commit, the version, the size of dist/ and the number of tests run, so that it is visible on the run's front page without opening any log.

Solution 1.

.prettierrc.json:

.prettierignore:

In package.json, two new scripts:

Run npm run format once to normalise the whole project and commit the result in its own commit (an isolated "formatting commit", so that it does not pollute future diffs). Then, the job:

And add format to the needs of the build job: needs: [quality, format, test].

Checking that it fails: put odd spacing into src/server.js and push. You will see:

The difference between --write and --check is exactly the difference between a development tool and a quality gate: the pipeline never modifies the code, it only reports. A pipeline that autoformats and commits generates phantom commits, triggers new runs and can end up in a loop.

Solution 2.

The trap: if you add paths-ignore: ['**.md'] to the trigger, then on a PR that only touches Markdown the jobs do not run, the required checks never report and the PR is stuck at Expected forever.

There are two correct solutions. The simple and robust one:

The key point, and what has to go in the YAML comment: the required job always runs and always reports green; what gets skipped are its expensive steps. A job that exists and does nothing costs ~5 seconds and keeps branch protection working. A job that does not exist blocks the PR forever.

The advanced alternative —and what Reservalia does— is the one from 04-04: paths on the trigger plus an aggregator job ci-ok with if: always() that evaluates the result of the others and is the only required check.

Solution 3.

Add this to the build job, after building:

A better version avoids re-running the tests: make the test job write the number into an output and consume it here with needs.test.outputs.tests. Re-running the suite just to count it is the kind of waste 04-04 called "duplicated work for convenience".

$GITHUB_STEP_SUMMARY is Markdown that gets rendered on the run's front page. It is the most underrated tool in GitHub Actions: it turns a pipeline into something a tech lead can read in ten seconds without opening a log. We will use it heavily in 07-02 (coverage) and in 07-04 (DORA metrics).

Make the pipeline run also against Node 22 without duplicating the job, using a two-entry matrix. It is a preview of 07-02, so if you get it right you already have half an exercise done. Hint: strategy.matrix.node: [20, 22] and node-version: ${{ matrix.node }}. And a warning: when you use a matrix, the check names change to Tests (20) and Tests (22), so you will have to update the branch protection ruleset or your PR will be stuck waiting for a check called Tests that no longer exists. That discovery is worth more than the exercise.

A GitHub repository with:

• Mini-Reservalia: a Node.js project with a real domain (slot calculation), an HTTP server with /health and /api/slots, tests, lint and build, all with no production dependencies.
• A three-job ci.yml with parallelisation, concurrency, a dependency cache and artifact publishing, built in four increments you have watched run.
• A real gate: main protected, with three required checks, verified from the positive side and the negative one.
• The experience of seeing it red, diagnosing it from the log and the annotation, and fixing it inside the same PR.

What you have just put together is, in miniature, the prepare → quality/test → build stage of the Reservalia ci.yml you read in 02-02. The difference is that now you know why every line is there, because you have seen what happens when it is missing: without checkout the runner is empty, without setup-node the version is whatever comes up, without a lockfile the installation is not reproducible, without needs you build code you already know is broken, without a cache everything is reinstalled three times, and without branch protection none of the above obliges anyone to do anything.

That pipeline, however, has a weakness that does not show up in green: its signal is weak. Seven unit tests over a pure function say nothing about whether the /api/slots endpoint responds correctly, nor whether the server starts, nor what percentage of the code is actually being exercised. A green pipeline with insufficient tests gives exactly the same feeling of safety as a good one, and that is its peculiar danger —the "false green" of 04-04—.

In 07-02 we attack precisely that: we will add a persistence layer to Mini-Reservalia, write the three layers of the testing pyramid on top of it (unit tests with genuine edge cases, integration tests against the real persistence, and an end-to-end test against the running server), measure coverage and publish it in the run summary, put a threshold in place that breaks the build, run the suite across a matrix of Node versions and in two parallel shards, and —the most instructive part— manufacture a flaky test on purpose to watch it fail intermittently and apply the quarantine policy to it. Do not close the repository: we carry on right here.