# 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](https://pages.github.com) 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](https://github.com), and the push triggers a
[workflow](https://docs.github.com/en/actions/writing-workflows/about-workflows).
A fresh, throwaway machine (a
[CI runner](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners))
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](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility)
and
[enabling Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site).
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](https://docs.github.com/en/pages/getting-started-with-github-pages/what-is-github-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? {#machines-map}

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](https://comp.anu.edu.au/courses/comp4020-agentic-coding-studio/topics/agent-loops/),
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](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/using-workflow-run-logs)
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](https://comp.anu.edu.au/courses/comp4020-agentic-coding-studio/topics/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`)](https://cli.github.com/), which means it's available to your
agent. This is why [onboarding](https://comp.anu.edu.au/courses/comp4020-agentic-coding-studio/topics/onboard/) 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.

Source: <https://comp.anu.edu.au/courses/comp4020-agentic-coding-studio/topics/github-pages-deployment/>\
Licence: [CC-BY-NC-SA-4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)\
Cite as: Swift, B. (2026). _COMP4020/COMP8020 Agentic Coding Studio_ [Course materials]. ANU School of Computing. https://doi.org/10.5281/zenodo.21395760