Deploying to GitHub Pages

StarryBio deploys to GitHub Pages through the committed GitHub Actions workflow at .github/workflows/deploy-github-pages.yml. The workflow builds the actual production site with the locked pnpm dependencies, packages dist/ with GitHub’s Pages artifact action, and deploys it with the official Pages deployment action. It does not publish generated files to a branch and does not need an Astro adapter.

GitHub Pages does not read _headers or vercel.json. StarryBio includes the compatible CSP directives in generated HTML, but use a host with response-header controls when you require the full header set.

Prerequisites

• A GitHub repository containing your configured StarryBio copy.
• Repository admin or maintainer access to configure Settings > Pages.
• GitHub Actions enabled for the repository.
• Node.js 24 and pnpm 12.3.4 only if you also want to verify the build locally. The Actions workflow reads .node-version, packageManager, and pnpm-lock.yaml itself.

GitHub Pages availability for private repositories depends on the repository owner’s GitHub plan. A Pages site is public on the internet by default even when its source repository is private or internal. Eligible GitHub Enterprise Cloud organizations can instead use Pages access control for a private project site. Never put secrets in config/starrybio.config.ts, public/, or the generated dist/ artifact.

Configure the site before the first deployment

1. Fork or create a copy of StarryBio, make your content changes, and push them to the repository’s main branch.

2. Replace the starter canonical URL and QR destination in config/starrybio.config.ts with the URL you intend to publish. For a project site named StarryBio, use the repository path:

   seo: {
     canonicalUrl: 'https://USERNAME.github.io/StarryBio/',
     image: '/og.png',
   },
   qr: {
     enabled: true,
     url: 'https://USERNAME.github.io/StarryBio/',
   },

   Replace USERNAME and StarryBio with the repository owner and repository name. Use the final https:// custom-domain URL instead when you already have a custom domain.

3. On GitHub, open the repository’s Settings tab. In the Code, planning, and automation section of the sidebar, choose Pages.

4. Under Build and deployment, set Source to GitHub Actions. Do not select Deploy from a branch.

The workflow has only the permissions it needs: the build job can read repository contents and Pages metadata; the deploy job can write a Pages deployment and request an OIDC token. GitHub creates the github-pages deployment environment when needed. Protect that environment in repository settings if your release process needs an approval or branch rule.

Deploy

Push the workflow and your changes to main:

git add .
git commit -m "feat: publish StarryBio on GitHub Pages"
git push origin main

Open the repository’s Actions tab and select Deploy to GitHub Pages to follow the build and deploy jobs. You can also choose Run workflow from that workflow’s page to publish the current main revision manually. A successful deployment records the public URL on the github-pages environment and in the workflow summary.

The workflow uses actions/configure-pages before its build. Its origin and base_path outputs set Astro’s site and base values only for this build. StarryBio then prefixes public assets, generated downloads, the 404 home link, and configured root-relative internal links correctly. Normal pnpm build runs without those values and remains a root-hosted, provider-neutral build for Cloudflare, Vercel, Netlify, and other static hosts.

Know the expected URL

Pages site type	Repository name	Default URL	Astro base path
Project site	Any name other than USERNAME.github.io	https://USERNAME.github.io/REPOSITORY/	/REPOSITORY
User site	USERNAME.github.io	https://USERNAME.github.io/	none
Organization site	ORGANIZATION.github.io	https://ORGANIZATION.github.io/	none
Custom domain	Any	https://YOUR-DOMAIN/	none

GitHub Pages determines the active URL, including a custom domain or private-organization Pages hostname, and configure-pages returns that value. Do not hard-code /StarryBio in components, astro.config.mjs, or vercel.json.

Verify a project-site build locally

The local preview server normally serves from /. To reproduce a project-site build before pushing, use the same values that GitHub Pages supplies and inspect the result:

$env:STARRYBIO_SITE_URL = 'https://USERNAME.github.io'
$env:STARRYBIO_BASE_PATH = '/StarryBio'
pnpm build
Select-String -Path dist\index.html -Pattern '/StarryBio/'

On macOS or Linux, use:

STARRYBIO_SITE_URL=https://USERNAME.github.io STARRYBIO_BASE_PATH=/StarryBio pnpm build
grep -F '/StarryBio/' dist/index.html

The generated HTML should reference /StarryBio/_astro/... and /StarryBio/assets/...; QR and vCard downloads should use the same prefix when enabled. Run an ordinary pnpm build afterward if you want dist/ restored to the normal root-hosted form.

Add a custom domain

Configure the custom domain in GitHub before the next Pages build so configure-pages receives the root custom-domain URL and removes the project base path.

1. Optionally verify the domain in your personal-account or organization Pages settings first. GitHub recommends verification to reduce domain-takeover risk.

2. In the repository, open Settings > Pages. Under Custom domain, enter links.example.com or example.com, then click Save.

3. Only after GitHub accepts the domain, create the DNS record at your DNS provider:

   Domain type	Record name	Record type	Exact target/value
   Subdomain, such as links.example.com	links	CNAME	USERNAME.github.io or ORGANIZATION.github.io
   Apex, such as example.com	@	ALIAS or ANAME	USERNAME.github.io or ORGANIZATION.github.io
   Apex when ALIAS/ANAME is unavailable	@	A	185.199.108.153, 185.199.109.153, 185.199.110.153, and 185.199.111.153

   A CNAME must point to the account’s USERNAME.github.io or ORGANIZATION.github.io host, never to USERNAME.github.io/REPOSITORY. Avoid wildcard DNS records.

4. Wait for GitHub to verify the DNS configuration and issue the certificate. Then select Enforce HTTPS in Settings > Pages when the option becomes available.

5. Change seo.canonicalUrl and qr.url to the exact custom-domain HTTPS URL, commit, and push to main.

Do not add public/CNAME for this workflow. GitHub’s current custom-workflow documentation says that CNAME files are ignored and are not required when Pages is published with a custom GitHub Actions workflow. The repository setting is the source of truth.

What happens after future pushes

Every push to main runs the workflow again: pnpm installs from pnpm-lock.yaml, StarryBio validates and builds, dist/ is uploaded as a Pages artifact, and the deploy job updates the github-pages environment. A pull request does not deploy from this workflow; use normal CI to validate it, then merge it to main to publish.

To republish without a code change, go to Actions > Deploy to GitHub Pages > Run workflow and select main. If a deployment fails, correct the source or Pages setting and rerun the failed workflow from the Actions page.

Troubleshooting

Configure GitHub Pages cannot find or read the Pages site

Confirm that Settings > Pages > Build and deployment > Source is GitHub Actions, then rerun the workflow. The workflow intentionally uses pages: read in the build job so configure-pages can read the configured URL, including private Pages repositories where the plan allows them.

The page loads but scripts, images, or downloads return 404

Confirm that the Pages URL matches the repository type above and inspect the Build site log. For a project site, the build must receive STARRYBIO_BASE_PATH=/REPOSITORY from configure-pages; do not add a second base path manually. Rebuild with the local check above and look for /REPOSITORY/_astro/ and /REPOSITORY/assets/ in dist/index.html.

The custom domain shows a project path or uses the old canonical URL

Set the domain in Settings > Pages before rebuilding, then update seo.canonicalUrl and qr.url to the custom-domain URL. A custom domain is a hostname-root deployment, so it must not use /REPOSITORY as its Astro base path.

The custom domain will not verify or HTTPS is unavailable

Make sure GitHub accepted the custom domain before you changed DNS, use the exact record GitHub requests, remove conflicting records, and allow DNS and certificate provisioning time. Keep any domain-verification TXT record in place. Do not use wildcard DNS. GitHub’s Pages settings and DNS provider are authoritative for this issue, not a CNAME file in the repository.

Response headers differ from Netlify, Vercel, or Cloudflare

This is expected: GitHub Pages does not apply public/_headers or vercel.json. It serves the static content and custom 404.html, but StarryBio cannot set a CSP, cache directives, or other custom response headers on GitHub Pages. Choose Netlify, Vercel, Cloudflare Workers, or another host with header controls if those are required.

For the official platform details, see GitHub’s custom Pages workflows, publishing-source, and custom-domain documentation, plus Astro’s GitHub Pages deployment guide.