Deploying to GitHub Pages

GitHub Actions can build your React app and push the result to GitHub Pages automatically — every push to main triggers a fresh deploy. No manual steps required after the initial setup.

The workflow file

.github/workflows/deploy.yml

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

Two jobs: build compiles and uploads the artifact; deploy publishes it to Pages. They run sequentially — deploy waits for build to succeed.

Enabling GitHub Pages in the repository

1. Go to your GitHub repo → Settings → Pages
2. Under Build and deployment, set Source to GitHub Actions
3. Save

GitHub Pages is now configured to accept deployments from the Actions workflow.

The deploy URL

Once the workflow runs, your app is live at:

https://your-github-username.github.io/bulletin/

(Or without the subpath if the repo is named username.github.io.)

npm ci vs npm install

The workflow uses npm ci instead of npm install. The difference:

Command	Behavior
npm install	Installs and may update package-lock.json
npm ci	Installs exactly from package-lock.json — faster, reproducible, fails if lock file is out of sync

CI environments always use npm ci — you want the exact same dependency versions every time.

Monitoring the deployment

After pushing to main, go to your repo’s Actions tab and watch the workflow run. Each step shows its output in real time. If the build fails, the error is in the npm run build step.

Common failures:

• TypeScript errors that pass locally but fail in CI (strict mode differences)
• Missing environment variables — CI doesn’t have your .env files

For env vars in CI, you can bake the production URL directly into the build command:

- run: VITE_API_URL=https://your-app.railway.app npm run build

Or use GitHub Actions secrets if the URL is sensitive.

Exercise

In your Bulletin frontend project (GitHub repo):

1. Create .github/workflows/deploy.yml with the workflow shown above.
2. Go to GitHub → Settings → Pages → set source to GitHub Actions.
3. Push the workflow file to main.
4. Watch the Actions tab — confirm the workflow completes successfully.
5. Visit https://your-username.github.io/bulletin/ and confirm the app loads and connects to your Railway backend.

Recap

• GitHub Actions builds and deploys on every push to main — no manual deploy steps.
• Two jobs: build (compiles + uploads artifact) and deploy (publishes to Pages).
• Enable Pages in repo settings → set source to GitHub Actions.
• Use npm ci in CI for reproducible installs.
• Pass VITE_API_URL as an environment variable in the build step if it’s not committed.