GitHub Pages deployment

You deploy from the first crit onwards, and GitHub Pages is how: push a commit, and a URL goes live

Every crit’s spec asks for a prototype live at its public URL by the cutoff; the live URL is the thing the crit points at. That’s the durable practice — deploy from day one, while the stakes are lowest, so shipping is routine by the time it matters for the assignments. GitHub Pages is the platform we’ll use, because it offers free static hosting (we’ll explain what all those words mean shortly) wired into the same git push you’re already familiar with.

Commit, push, live#

Here is what happens between git push and your page being on the internet. Your commit reaches GitHub, and the push triggers a workflow. A fresh, throwaway machine (a CI runner) boots, checks out your repo, and builds the site. The built files are handed to GitHub’s webservers, and a few seconds later https://<org>.github.io/<repo>/ serves them to anyone on earth.

The starter repo for every prototype already includes the workflow file; deploying is two switches, making the repo public and enabling Pages. The course plugin’s ship skill knows the steps: tell your agent to “ship it”, and it will flip both, watch the deploy, and check the URL serves.

One property of Pages shapes the first half of the course: it serves static files only. Every visitor gets the same HTML, CSS, and JavaScript, and anything dynamic happens in their browser. The constraint is why Pages is free, fast, and hard to break, and it’s less limiting than it sounds. What a static site can still do is a good first question for your agent. A server of your own arrives in week 8.

Which box does what?#

The deploy you just did touched four machines:

• your dev machine — where you and the agent read, edit, and run; the this machine serves the localhost preview, and it’s the only machine on this list you fully control
• the CI runner — the throwaway machine GitHub boots to build your site; it exists for about a minute per push (how its workflow actually works is week 5’s business)
• GitHub’s webserver — where the built files sit, served to anyone who asks
• the visitor’s browser — where the page actually runs: HTML parsed, CSS applied, and JavaScript executed on a device you’ve never seen

“Where does my code run?” already has four answers in week 1, and most web debugging starts by identifying the box where the problem occurs. A page that works on localhost but 404s at the live URL has failed between the runner and the webserver. A layout that’s fine on your laptop but broken on your phone has failed in the visitor’s browser, the box you control least. The agent can help with either, but only if you can tell it which box you’re pointing at.

Keep the picture handy — we call it the machines map, and we’ll redraw it as the course introduces more boxes.

The local dev server#

One of those boxes deserves a closer look before we move on. “Run the dev server” means starting a program on your own machine that builds the site and serves it at a localhost URL — an address that resolves to your machine and nowhere else. Point a browser at it and you’re looking at the current state of your working directory, usually with live reload: save a file and the page updates itself. Nobody else can see any of it; localhost is not on the internet.

That privacy is also speed. A live URL is available in minutes, after a push and a workflow run; the dev server responds in seconds, on every save. For most web work it’s the run in the agent’s read–edit–run loop, and starting one (pnpm dev in the starter repos) will be the first move of nearly every working session this semester. You’ll get plenty of practice.

Green checks and red#

The other thing that push did was give your commit a status. On the repo’s GitHub page you’ll see it beside the commit: amber while the workflow runs, then a green tick or a red cross. This is your first contact with checks, and two habits are worth forming from the very first push.

First, be precise about what green means: the machinery ran to completion, and every check that ran passed. It does not mean the site is good, or even that it looks right; a green deploy can still publish a broken layout.

Second, when it’s red, don’t squint at it: read it back to the agent. The repo’s Actions tab is where the details live — every run, and the full log of each (clicking the red cross takes you to the same place). Open the failing run, copy the log, and paste it into your session. A red check is a precise, machine-written account of what went wrong, and the agent is its cheapest, fastest reader. This habit — feeding those results into the loop rather than absorbing them yourself — is the seed of backpressure, week 3’s topic. For now: push, watch the check, and whatever colour comes back, make sure somebody reads it.

One last thing worth internalising early: nearly everything you just did through github.com — watching a run, reading a log, flipping a repo public, enabling Pages — is also available from the terminal through the GitHub CLI (gh), which means it’s available to your agent. This is why onboarding has you install gh and log in on day one: an agent that can reach GitHub can watch the checks and read the red logs, instead of waiting for you to paste them in.