Capstone Part 1 — Pipeline Foundation

This is the first of six parts that build one continuous project: parcel-api, a small shipment-tracking service you'll stand up, wire, deploy, watch, break, and secure over the rest of this capstone. Part 1 lays the two things every later part depends on — a real branching strategy enforced by branch protection, not just written in a wiki, and a working CI pipeline that lints, tests, and builds parcel-api automatically on every single push. By the end of this page you will have watched, with your own eyes, a pull request get blocked by a failing test and a direct push get rejected by GitHub itself.

What this part assumes, and what it produces

☺ Like you're 10: Just the tools on your desk and a GitHub account — nothing built yet.

You need five things installed locally: git, the GitHub CLI (gh, authenticated with gh auth login), Node.js (version 22, the current LTS as of this writing — swap in whatever's current when you actually do this), and Docker (Desktop or Engine — GitHub's own ubuntu-latest runners already ship with it, but you'll want it locally too, to build the image before you ever push). You also need a GitHub account with permission to create a repository. Nothing else needs to exist yet: no registry, no cloud account, no server to deploy to. Those arrive starting in Part 2.

The world model this whole capstone shares

Six parts, one project, so it's worth naming the shape once, here, so nothing surprises you later:

Keep that table in your head across all six parts: whenever a later page says "the build-and-test check" or "the image this pipeline builds," this is where those names were born.

Standing up the parcel-api repo

☺ Like you're 10: Make the shelf before you decide who's allowed to stack boxes on it.

Create the repo now, empty except for a .gitignore. Deliberately, branch protection does not go on yet — GitHub can't require a status check that has never run once, so the very first commit has to land on main directly, unprotected, to give the pipeline something to run against. Every commit after that one follows the rules.

mkdir parcel-api && cd parcel-api
git init -b main
printf "node_modules/\ncoverage/\n" > .gitignore
git add .gitignore
git commit -m "chore: initial commit"

gh repo create parcel-api --private --source=. --remote=origin --push

This capstone uses trunk-based development, the same strategy Version Control & Branching correlates most strongly with elite delivery performance: one long-lived branch (main), short-lived feature branches measured in hours, and a pull request for every change. GitFlow's long-lived develop and release/* branches don't get used here — there's no scheduled release train for a service this capstone intends to deploy continuously.

Building parcel-api: the app this pipeline builds and tests

☺ Like you're 10: A tiny web service that remembers packages, plus a checklist proving it actually works.

parcel-api is deliberately small — an Express service with three routes, an in-memory store, and a real test suite. Small is the point: every later capstone part adds to this exact app, so Part 1's job is a working skeleton, not a finished product. Create package.json:

{
  "name": "parcel-api",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "start": "node src/index.js",
    "test": "jest",
    "lint": "eslint ."
  },
  "dependencies": {
    "express": "^4.19.2"
  },
  "devDependencies": {
    "@eslint/js": "^9.9.0",
    "eslint": "^9.9.0",
    "jest": "^29.7.0",
    "supertest": "^7.0.0"
  }
}

// src/index.js
const express = require("express");
const { randomUUID } = require("node:crypto");

const app = express();
app.use(express.json());

const shipments = new Map();

app.get("/healthz", (_req, res) => res.status(200).json({ status: "ok" }));

app.post("/shipments", (req, res) => {
  const { destination, weightKg } = req.body || {};
  if (!destination || typeof weightKg !== "number") {
    return res.status(400).json({ error: "destination and weightKg are required" });
  }
  const id = randomUUID();
  const shipment = { id, destination, weightKg, status: "created" };
  shipments.set(id, shipment);
  res.status(201).json(shipment);
});

app.get("/shipments/:id", (req, res) => {
  const shipment = shipments.get(req.params.id);
  if (!shipment) return res.status(404).json({ error: "not found" });
  res.status(200).json(shipment);
});

module.exports = { app };

if (require.main === module) {
  const port = process.env.PORT || 8080;
  app.listen(port, () => console.log(`parcel-api listening on :${port}`));
}

// tests/shipments.test.js
const request = require("supertest");
const { app } = require("../src/index");

describe("parcel-api", () => {
  test("GET /healthz returns 200", async () => {
    const res = await request(app).get("/healthz");
    expect(res.status).toBe(200);
  });

  test("POST /shipments creates a shipment, GET /shipments/:id reads it back", async () => {
    const created = await request(app)
      .post("/shipments")
      .send({ destination: "Pune, IN", weightKg: 2.4 });
    expect(created.status).toBe(201);
    expect(created.body.status).toBe("created");

    const fetched = await request(app).get(`/shipments/${created.body.id}`);
    expect(fetched.status).toBe(200);
    expect(fetched.body.destination).toBe("Pune, IN");
  });

  test("POST /shipments rejects a request missing destination", async () => {
    const res = await request(app).post("/shipments").send({ weightKg: 1 });
    expect(res.status).toBe(400);
  });
});

Add a minimal flat-config eslint.config.js (ESLint 9's default format) so npm run lint has something to check against, and a Dockerfile so the pipeline has something to build:

// eslint.config.js
const js = require("@eslint/js");
module.exports = [js.configs.recommended];

# Dockerfile
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY src ./src
EXPOSE 8080
CMD ["node", "src/index.js"]

Run npm install && npm test locally once before you push anything — three passing tests, no red output. See Testing in the Pipeline for how this same suite grows into the layered test strategy real pipelines run at scale.

Wiring the CI pipeline: lint, test, and build on every push

☺ Like you're 10: One robot, three checks, triggered the instant anyone pushes anything, anywhere.

Per CI/CD Pipelines, this is pipeline-as-code: the definition below is a plain YAML file, checked into the same repo it builds, reviewed and diffed exactly like the application code. Create .github/workflows/ci.yml:

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: ["**"]
  pull_request:
    branches: [main]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: "npm"

      - run: npm ci
      - run: npm run lint
      - run: npm test -- --ci --coverage

      - name: Build the image (no push yet — Part 2 wires the registry)
        run: docker build -t parcel-api:${{ github.sha }} .

Two trigger blocks are doing different jobs. push: branches: ["**"] is the part the content brief for this page is really about — it fires on every push to any branch, so nothing you commit ever runs untested on your own machine before someone else sees it. pull_request: branches: [main] is what makes the result show up as a status check directly on a pull request against main, which is what branch protection below actually reads. You need both: push alone never populates a PR's checks list the way reviewers expect to see it.

Notice the job is named build-and-test — that exact string is the "context" branch protection will require in the next section, and the four steps map straight onto the front of the pipeline stages from CI/CD Pipelines: lint, unit test, build. Nothing here deploys, scans, or pushes an image anywhere — this pipeline stops at a verified local build, on purpose, because there's no registry to push to and nowhere to deploy until Part 2 builds one.

Turning on branch protection: making the pipeline a gate, not a suggestion

☺ Like you're 10: A checklist nobody's forced to follow gets skipped the first busy afternoon — this nails it to the door.

Push the scaffold above straight to main once — this is the one and only commit in this whole capstone that goes there unreviewed, and only because branch protection can't require a check that has never run:

git add .
git commit -m "chore: scaffold parcel-api with CI pipeline"
git push -u origin main

gh run watch     # follow the first Actions run live until it's green

Once that first run is green, GitHub has seen the build-and-test context and can require it. Turn on branch protection with the GitHub CLI (GitHub's newer "Rulesets" UI does the same job through a friendlier form under Settings → Rules — either path lands on the same enforcement):

gh api --method PUT repos/{owner}/{repo}/branches/main/protection \
  --input - <<'JSON'
{
  "required_status_checks": { "strict": true, "contexts": ["build-and-test"] },
  "enforce_admins": true,
  "required_pull_request_reviews": { "required_approving_review_count": 0 },
  "restrictions": null,
  "allow_force_pushes": false,
  "allow_deletions": false
}
JSON

{owner} and {repo} are literal — gh api fills them in from the repo you're sitting in. enforce_admins: true means even the repo owner can't bypass this, which is exactly what makes the direct-push proof later in this page work. required_approving_review_count is set to 0 deliberately: GitHub won't let you approve your own pull request, so a solo capstone with a nonzero count here would lock you out entirely. In a real team, set it to 1 or more — the build-and-test check is still doing the real gating work either way.

Proving the pipeline actually gates every push

☺ Like you're 10: Break something on purpose and watch the inspector actually stop you, not just watch.

Everything from here on follows trunk-based development for real: a short branch, a small commit, a pull request, a green check, a squash merge. First, the ordinary path:

git checkout -b add-version-to-healthz
# edit src/index.js: include a version field in the /healthz response
git commit -am "feat: report version in /healthz response"
git push -u origin add-version-to-healthz

gh pr create --fill --base main
gh pr checks --watch      # watch build-and-test populate on the PR itself

Now break it on purpose, on the same branch, to prove the gate is real and not decorative:

git commit -am "test: (temporary) break the shipment test on purpose"
git push

gh pr checks               # build-and-test now shows failing
gh pr merge                # GitHub refuses — something like:
                            # X Required status check "build-and-test" is failing — merge not allowed.

That refusal is the entire point of this page. Fix it, watch the check turn green, and merge for real:

git revert HEAD --no-edit
git push
gh pr checks --watch

gh pr merge --squash --delete-branch
gh run list --branch main --limit 1   # confirm the pipeline reran on main too, post-merge

Last, prove the gate applies even to you, even with admin rights, even on main itself:

git checkout main && git pull
echo "manual edit" >> README.md
git commit -am "test: direct push to main"
git push origin main
# remote: error: GH006: Protected branch update failed for refs/heads/main.
# remote: error: Required status check "build-and-test" is expected.

git reset --hard origin/main   # nothing landed remotely — drop the local commit

Nothing about that last command sequence is special-cased — it's the identical rule that blocked the broken pull request, applied to a push that skipped pull requests entirely. That's what "the pipeline gates every push," said precisely, actually means: not "usually," not "for pull requests specifically," but for every single ref update main ever receives.

What "done" looks like for Part 1, and where Part 2 picks up

☺ Like you're 10: A shelf that's actually guarded, and an inspector who's actually watching every box.

At the end of this part you have: a parcel-api repo with a working Express service and a passing Jest suite; a .github/workflows/ci.yml pipeline that lints, tests, and builds a Docker image tagged by commit SHA on every push and every pull request; branch protection on main requiring build-and-test to pass, enforced even against admins; and firsthand proof — not a claim — that a failing test blocks a merge and a direct push gets rejected. Nothing here gets thrown away:

Milestones

☺ Like you're 10: Tick each box only once you've actually watched it happen on your own screen, not because the step "sounds right."

Work these in order — each depends on the repo and pipeline state from the one before. Progress saves in this browser.

Part 1 gave you a repo, a branching strategy actually enforced by GitHub instead of just written down, and a pipeline that gates every push with proof, not a promise. Continue to Capstone Part 2 — Infrastructure as Code, where the image this pipeline builds finally gets somewhere to go. Or step back to Ship It — Start Here to see how this capstone's six parts fit the rest of the hands-on labs, and revisit Version Control & Branching and CI/CD Pipelines for the concepts behind what you just built.