The life of a code change

You fix a bug in Cart.tsx. You type git push. An hour later, a shopper in another country sees the correct total.

Between those two moments, your change passes through five stops. In this lesson you follow it through each one.

Stop 1: a commit on your laptop

A commit is where the journey starts. Git gives each commit a unique ID, called a hash. Every later step uses that ID to name your change.

┌────────────────────────────────────────────┐
│                                            │
│       your laptop                          │
│      ┌─────────────────────────────┐       │
│      │ commit   a1b2c3d            │       │
│      │ author   you                │       │
│      │ message  "Fix cart total"   │       │
│      │ files    Cart.tsx  +3  -1   │       │
│      └─────────────────────────────┘       │
│                                            │
└────────────────────────────────────────────┘

On your laptop, the change is safe but private. Nobody else can see it, and no robot checks it. The next step makes it public.

Stop 2: the pull request and the robots

You push the branch to GitHub and open a pull request. This starts CI. The robot gets a fresh, empty computer, copies your code onto it, and runs the checks your team chose.

name: CI
on: pull_request
jobs:
check:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: 22
    - run: npm ci
    - run: npm run lint
    - run: npm test
    - run: npm run build

• on: pull_request starts the workflow for every pull request.
• runs-on: ubuntu-latest asks GitHub for a clean Linux computer. It has none of your laptop's leftovers.
• The last four lines install packages, lint, test and build. If one step fails, the pull request shows a red cross.

┌────────────────────────────────────────────┐
│                                            │
│     pull request #1482  Fix cart total     │
│    ┌──────────────────────────────────┐    │
│    │ lint     passed            12s   │    │
│    │ test     passed            48s   │    │
│    │ build    failed            63s   │    │
│    ├──────────────────────────────────┤    │
│    │ Merging is blocked               │    │
│    └──────────────────────────────────┘    │
│                                            │
└────────────────────────────────────────────┘

At the same time, Vercel builds a preview deployment. This is a full copy of the app with your change, on its own URL. Your reviewer clicks the link and tests the real page, not a screenshot.

A teammate reads the code and approves it. The rule is simple: robots check what a computer can check, and people check the rest.

Stop 3: merge, then build once

You merge the pull request. Now main has your commit, and the pipeline starts again on main.

This time, the build output is the thing that ships. Teams call it an artifact.

For a Next.js app on Vercel, the artifact is the pages and functions that next build makes. For a team that uses containers, it is a Docker image with a tag like shop:a1b2c3d.

Two rules keep this step safe:

1. Build once. The same artifact goes to every later step. Nobody builds again on a server.
2. Never change an artifact. A new change makes a new artifact with a new name. Old ones stay on the shelf.

The second rule makes rollback easy, as you will see below.

Stop 4: deploy, a little at a time

To deploy means to start the new artifact in production. Small sites switch all traffic at once. Large sites switch in steps, because a bug then reaches only a few users.

┌─────────────────────────────────────────────┐
│                                             │
│   step 1   ▓▓▓▓▓▓▓▓▓░   1 server runs v42   │
│   step 2   ▓▓▓▓▓░░░░░   half run v42        │
│   step 3   ░░░░░░░░░░   all run v42         │
│                                             │
│   ▓ old version v41     ░ new version v42   │
│                                             │
└─────────────────────────────────────────────┘

The first small group has a name: the canary.

Miners once took a canary bird into the mine. If the bird got sick, the miners left. In the same way, if errors go up on the canary, the rollout stops and the old version keeps serving everyone else.

Stop 5: users, and the way back

Now your fix is live. The team watches error rates and page speed for a few minutes after each deploy.

Tools like Datadog or Grafana draw these numbers as graphs. Chapter 8 covers them.

Sometimes a deploy goes wrong. The fastest fix is often not a new commit. It is a rollback.

Because old artifacts never change, a rollback only points traffic back to the last good one.

┌────────────────────────────────────────────┐
│                                            │
│    before the rollback                     │
│    shop.com ──▶ v42   new, has a bug       │
│                 v41   last good version    │
│                                            │
│    after the rollback                      │
│                 v42   kept on the shelf    │
│    shop.com ──▶ v41   last good version    │
│                                            │
└────────────────────────────────────────────┘

The whole trip in one picture

Read more

• Understanding GitHub Actions from GitHub. Workflows, jobs and steps.
• How GitHub uses merge queue, the 2024 story above.
• Deployment reliability at GitHub. How a deploy stops itself before users notice.
• Deploying to Vercel and Instant Rollback. Preview, production and the way back.

Next, you see why the same app runs in three places: local, staging and production.