Home / Guides / GitHub Pages

GitHub Pages

On this page
  1. 1. Activate GitHub Pages on a Repo
  2. 2. Your Personal Site
  3. 3. Project Sites
  4. 4. Check if Your Deploy Succeeded
  5. 5. Troubleshooting
  6. 6. Deploy on Vercel When Your API Needs a Key

GitHub Pages turns any GitHub repository into a live website. It is free, requires no server setup, and updates automatically when you push changes.

How GitHub Pages deploys your site: commit, push, build, then live

1. Activate GitHub Pages on a Repo#

  1. Go to your repository on github.com
  2. Click Settings (top menu bar, near the right)
  3. Click Pages (left sidebar, under "Code and automation")
  4. Under "Source," select Deploy from a branch
  5. Under "Branch," select main and / (root)
  6. Click Save
  7. Wait about two minutes. Refresh the page. A URL will appear at the top.
  8. Click Visit site and check that your page opens

Pages stays off in every new repository until you turn it on.

2. Your Personal Site#

To create a personal site at <your-github-username>.github.io:

  1. Create a new repository named exactly <your-github-username>.github.io, all lowercase, with your own username in place of the angle brackets
  2. Add an index.html file and push it
  3. GitHub Pages usually turns on by itself for this repo. Your site will be live at https://<your-github-username>.github.io
  4. If the URL still shows a 404 after a few minutes, open Settings > Pages as in step 1 and set the source to main and / (root)

3. Project Sites#

Any other repo with Pages enabled becomes a project site.

  • Repo named portfolio becomes https://<your-github-username>.github.io/portfolio
  • Repo named homework-1 becomes https://<your-github-username>.github.io/homework-1

You can have as many project sites as you want. Each one is its own repo.

Put the live link on the repo page. On the repo's page on github.com, click the gear next to About, check Use your GitHub Pages website, and click Save changes. The link appears at the top right, where a visitor finds it.

4. Check if Your Deploy Succeeded#

Option A: Go to your repo on GitHub. Look at the most recent commit. A green checkmark means the deploy finished. An orange dot means it is still building.

Option B: Go to Settings > Pages. If the deploy worked, you will see your site URL with a "Visit site" link.

5. Troubleshooting#

Page shows your README instead of your site

  • Your homepage must be named index.html (lowercase, exact spelling)
  • GitHub shows README.md by default if no index.html exists

404 error

  • For personal sites: double-check that the repo name matches your username exactly
  • For project sites: make sure Pages is enabled in Settings
  • Wait two minutes after your first push. GitHub needs time to build.

CSS or images not loading

  • File paths on GitHub are case-sensitive. Styles.css and styles.css are different files.
  • Use lowercase for all file and folder names
  • Use relative paths: css/styles.css, not /css/styles.css or C:\Users\...

Changes not showing up

  • Make sure you pushed your changes (check the commit on github.com)
  • Hard refresh your browser: Cmd+Shift+R (macOS) or Ctrl+Shift+R (Windows)
  • Wait two minutes for GitHub to rebuild the site

6. Deploy on Vercel When Your API Needs a Key#

GitHub Pages serves every file in your repo to every visitor, so an API key in your JavaScript can be read by anyone who opens DevTools. On Vercel, a function in your repo runs on Vercel's server instead: it holds the key, calls the API, and sends your page only the data. The free Hobby plan covers personal, non-commercial projects and has no billing.

  1. Get a free key from the API, with no payment method attached. Anyone can call your function, and every call uses your key's quota. For a model, use the course OpenRouter key from Canvas, or a key of your own with a credit limit set on the provider's site.

  2. Add a function. Make a folder named api in the root folder of your repo, and create quote.js inside it. Vercel runs only the files in api/ as functions, so with quote.js in the root folder, /api/quote answers 404. This one gets a stock price from Finnhub:

    export default {
  async fetch(request) {
    const symbol = new URL(request.url).searchParams.get("symbol");
    const key = process.env.FINNHUB_API_KEY;
    const url = "https://finnhub.io/api/v1/quote"
      + `?symbol=${encodeURIComponent(symbol)}&token=${key}`;
    const response = await fetch(url);
    const data = await response.json();
    return Response.json(data, { status: response.status });
  },
};

    process.env.FINNHUB_API_KEY reads the key from Vercel's settings, so the key is in no file in your repo. For another API, the function has the same shape: read what the page sent, add the key, call the API, and return what it answered. The function for a model is in Calling an LLM API.

  3. Call the function from your page, with a path on your own site:

    const response = await fetch(`/api/quote?symbol=${encodeURIComponent(symbol)}`);

  4. Import the repo and add the key. Sign in at vercel.com with GitHub, open vercel.com/new, and pick the repo. If the repo is not listed, or Vercel asks, install the Vercel app on your GitHub account and give it access to the repo. On the import page, under Environment Variables, type the variable's name, FINNHUB_API_KEY, in the Key box and paste the key itself in the Value box, choose Production and Preview, and click Deploy. To add a variable later, open Settings, then Environment Variables, and deploy again, because a variable reaches only the deployments made after it: push a commit, or open Deployments and choose Redeploy on the latest one.

  5. Use the vercel.app link. Your site is at https://<project-name>.vercel.app, and every push to main deploys it again. That link opens index.html, so add the file name for any other page: https://<project-name>.vercel.app/ai-chat.html. Paste the link into Website in the repo's About box.

Test before it goes live. Work on a branch, as Running a Project With an Agent does: ask the agent to create the branch, then Publish Branch in the Source Control tab. Vercel deploys every branch you publish as a preview with its own link, and your live site stays as it was. Find the link on your project's Deployments page in Vercel, open it in the browser where you are signed in to Vercel, and try every feature with the real key. When it works, merge the branch into main, as that guide describes. In step 4, add the key for Preview as well as Production, or the preview cannot read it.

When it does not work

  • Live Server cannot run a function. Test the page on its vercel.app link.
  • The GitHub Pages copy of the repo cannot run the function either, so share only the vercel.app link.
  • A 401 from your function usually means it has no key. Check the name in the Key box against process.env in your function, letter for letter, then deploy again.
  • A key that was ever committed stays in the repo's history. Generate a new one at the provider.

Last updated: Friday, 11/06/2026