Publish

You already pushed the final commit

At this point, you are not starting a project. You came from the build chapter, executed the phases, validated locally, created reports, made the final commit, and pushed the code to GitHub. Now one thing is missing: open the project at a public URL.

This is not the moment to invent a new feature. The goal of this chapter is to reduce friction for the first GitHub Pages deploy: take the project that already works, publish it, and validate the main flow as a user.

The main reference here is GitHub's official documentation for configuring a Pages publishing source.

What GitHub Pages needs

GitHub Pages publishes static files: HTML, CSS, JavaScript, and assets ready for the browser. It can publish from a branch, using either the branch root or the /docs folder.

In projects with a build step, the generated folder is often dist, but GitHub Pages does not let you simply choose dist inside the main branch. That is why the simplest first deploy path is to put the generated output at the root of a separate branch called gh-pages.

Yes, this creates two versions of the project in the repository. In this chapter, that is an intentional choice: first we want a working public URL. Automating the process can come later.

1. Prepare the deploy branch

Now ask your coding agent to prepare the deploy. It needs to inspect the real project, find the build command, confirm the output folder, and check whether there is a base or public path setting for GitHub Pages URLs.

You will help me publish this project to GitHub Pages for the first time using a deploy branch.

Before changing any files, read:
- package.json
- astro.config.mjs, if it exists
- vite.config.js, vite.config.ts, or equivalent framework config, if it exists
- README.md
- PLAN.md
- AGENTS.md or CLAUDE.md

CONTEXT
- I have already finished the project, made the final commit, and pushed it to GitHub.
- Now I want the lowest-friction path to see the project at a public URL.
- GitHub Pages should publish from a deploy branch.
- The main branch keeps the source code.
- The gh-pages branch should contain only the generated static site at the branch root.
- Use the current official documentation as reference:
  - GitHub Pages publishing source: https://docs.github.com/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
  - Astro GitHub Pages: https://docs.astro.build/en/guides/deploy/github/
  - Vite static deploy: https://vite.dev/guide/static-deploy

TASK
Prepare the first GitHub Pages deploy using the gh-pages branch.

Do the following:
1. Check which build command exists in package.json.
2. Confirm the build output folder. It is usually dist, but verify the actual project config.
3. Check whether the framework config needs base, public path, or site for:
   https://[GITHUB_USERNAME].github.io/[REPO_NAME]/
4. Run, or tell me to run, the production build.
5. Prepare a safe procedure to publish the generated output to the root of the gh-pages branch.
6. Explain exactly which settings I should choose in Settings > Pages:
   - Source: Deploy from a branch
   - Branch: gh-pages
   - Folder: / (root)
7. Explain how to validate the public URL after publishing.

IMPORTANT RULES
- Do not publish secrets.
- Do not change the project stack.
- Do not use GitHub Actions now; that is a later upgrade.
- Do not use destructive commands without explaining first.
- Do not rewrite an existing deploy branch without asking for confirmation.
- If the build folder is not dist, adapt the procedure to the real config.
- Before running any command that changes branches, show me the plan.

The important point: do not accept a command only because it looks familiar. The agent needs to confirm the build output folder and explain how it will land at the root of the gh-pages branch.

2. Check URL, base, and paths

For regular repositories, GitHub Pages publishes at: https://[GITHUB_USERNAME].github.io/[REPO_NAME]/.

This is where many first deploys break. If the site opens without CSS, images, or correct routes, the problem is usually base, public path, or absolute paths. The Astro and Vite docs explain this adjustment for GitHub Pages.

3. Configure GitHub Pages

After the gh-pages branch exists on GitHub with the generated files at its root, configure Pages from the GitHub UI:

1. Open the repository on GitHub.
2. Go to Settings → Pages.
3. Under Build and deployment, choose Deploy from a branch.
4. For branch, select gh-pages.
5. For folder, select / (root).
6. Click Save.

4. Open the public URL

GitHub may take a few minutes to publish. The Settings → Pages page usually shows the URL once the site is available.

The URL will usually be: https://[GITHUB_USERNAME].github.io/[REPO_NAME]/. If it still shows 404 right after saving, wait a few minutes before changing everything.

5. Validate as a user

Now validate the published project as someone opening the link for the first time:

1. Open the published home page.
2. Search for an artist.
3. Open the discography.
4. Open album details.
5. Test on a phone or narrow viewport.
6. Refresh the page and confirm it still loads.
7. Open the browser console and check for obvious errors.

When something breaks

If the URL returns 404, check whether the gh-pages branch exists on GitHub, whether Pages is using Deploy from a branch, whether the folder is / (root), and whether you waited a few minutes.

If the page opens without styles, images, or correct routes, investigate base, public path, and absolute paths. If the site opens but data does not load, investigate the API, CORS, and the browser console.

The next chapter exists for this: Where it breaks. Use it when you have a specific error, log, or clear behavior to investigate.

When to automate with GitHub Actions

The gh-pages path is good for the first deploy because it reduces new concepts. After you have seen the project working in public, GitHub Actions starts to make more sense.

Automate when you want to publish on every push, avoid updating the deploy branch manually, work with a team, or keep a clear build history. For that, use the official docs for Astro on GitHub Pages or custom workflows with GitHub Pages.

What to take from here

• First public URL first, automation can come later
• GitHub Pages publishes static files, not the full app source code
• main and gh-pages have different roles, one keeps the code and the other keeps the generated site
• Path configuration matters, many sites break because of base or assets pointing to the wrong place
• Official references matter, Astro Docs and GitHub Docs are the main source for publishing and automating later

The full flow now closes: prepare context, plan, build in phases, validate locally, push, and publish. The first deploy does not need perfect infrastructure; it needs to work, be understood, and create a path for automation when automation makes sense.

git add .
git commit -m "[summarize what changed in this chapter]"
git push