Skip to content

Web Deploy Workflow

Jump to bottom
mdeguzis edited this page Jun 18, 2026 · 5 revisions

Web Deploy Workflow

This page covers the end-to-end release process for proton-pulse-web -- from local changes through staging review to production.

Contents

Branch and issue workflow

Every change needs a GitHub issue. This is the paper trail and the anchor for staging/prod comments.

Features

  1. Create a GitHub issue: gh issue create --repo mdeguzis/proton-pulse-web --title "..." --label enhancement
  2. Create a feature branch off main: git checkout -b feature/<short-name>
  3. Do all work on the feature branch. Reference the issue in commits: feat: ... (closes #N)
  4. Go through the normal staging review flow before merging to main.
  5. After the issue closes, delete the branch: git push origin --delete feature/<short-name>

Bugs

  1. Create a GitHub issue: gh issue create --repo mdeguzis/proton-pulse-web --title "..." --label bug
  2. Bugs may be fixed directly on main. Larger fixes can use a fix/<short-name> branch.
  3. Reference the issue in the commit: fix: ... (closes #N)

Branch naming: feature/<short-name> for features, fix/<short-name> for standalone bug branches.

Overview

All changes follow this path:

local changes -> pre-push checks -> push to main -> staging deploy -> staging review -> production

Production is never touched until staging has been reviewed and explicitly approved. The make gh-pages-only and make gh-run targets both enforce this by running check-staging-sync before doing anything -- they will refuse to deploy to production if staging is behind HEAD.

Before you start

The web app lives at:

~/src/decky-proton-pulse-project/proton-pulse-web/

All deploy targets require gh (GitHub CLI) and a valid session. Confirm before starting:

gh auth status

Step 1: make changes and pre-push

After editing JS or CSS, run:

make pre-push

This runs three things in sequence:

  1. cache-bust (make build) - recomputes ?v= hashes on all JS/CSS imports based on file content. Every file that changed gets a new hash; unchanged files keep theirs.
  2. Jest tests (make coverage) - unit tests, manifest completeness check, and coverage gate.
  3. Smoke render (make smoke) - headless render check that catches missing imports before they hit CI.

If any step fails, fix it before committing. Do not commit with a failing make pre-push.

Adding a new JS or CSS file

Two extra steps are required when adding a new file:

  1. Add it to gh-pages-manifest.txt -- the pages-only deploy only copies files listed there. A missing entry means the import 404s silently on production.
  2. Add it to every relevant deploy step in .github/workflows/update-data.yml.

The manifest test in Jest catches rule 1 automatically -- npm test will fail if a manifest JS file imports something not listed in the manifest.

Step 2: commit and push to main

git add <files>
git commit -m "feat: ..."
git push origin main

Commit messages must follow Conventional Commits: feat:, fix:, chore:, ci:, docs:, etc.

On push, CI runs automatically:

  • CI (ci.yml) - Jest tests with coverage, Supabase schema/RLS integration tests
  • Sync staging repo (sync-staging-main.yml) - mirrors main branch to proton-pulse-web-staging repo

Watch CI at: https://github.com/mdeguzis/proton-pulse-web/actions

Step 3: deploy to staging

make gh-staging

This triggers update-data.yml with staging_only=true. It copies all shell files from main to the staging repo's gh-pages branch via orphan commit (no shared history with production's gh-pages).

The target prints the Actions run URL and the staging preview URL when it fires.

Staging site: https://mdeguzis.github.io/proton-pulse-web-staging/

After triggering, wait for the run to finish before reviewing. Watch the run:

make gh-run-watch

Step 4: review on staging

Open the staging site and verify:

  • The change you made works as expected
  • No regressions on pages you did not touch (home, app, admin if relevant)
  • No console errors in browser DevTools

Post the staging run URL and staging preview URL as a comment on the relevant GitHub issue.

Do not make further commits or trigger another staging deploy until the user confirms the staging looks correct. One staging deploy per iteration.

Step 5: promote to production

This step must always be performed by a human. Never delegate it to an automated process or AI assistant.

Once staging is confirmed good:

make gh-pages-only

This deploys the current main branch content to the live site without re-running the data pipeline. Before firing the workflow it verifies that staging is in sync with HEAD -- if staging is behind, it will refuse and print the SHA mismatch.

Watch the run:

make gh-run-watch

Live site: https://www.proton-pulse.com/

Post the production run URL as a follow-up comment on the issue and close it.

Full pipeline deploy

Use this when game data also needs refreshing (new pipeline features, data format changes, or a scheduled full refresh):

make gh-run

This runs the full data pipeline (Steam catalog fetch, ProtonDB probe, finalize, search index) and then deploys to production. It also requires staging to be in sync with HEAD.

CI workflows

Workflow Trigger What it does
CI (ci.yml) push to main, daily Jest + coverage, Supabase schema/RLS tests
Update ProtonDB Data (update-data.yml) manual dispatch, staging/prod deploy targets Data pipeline and/or deploy to gh-pages
Content Moderation (content-moderation.yml) scheduled Scans submitted reports for banned phrases
Sync staging repo (sync-staging-main.yml) push to main, daily Mirrors main branch to staging repo
pages-build-deployment automatic on gh-pages push GitHub Pages build for the live site

Badges for all workflows are in the README.

Supabase schema tests

tests/supabaseSchema.test.js runs against the live Supabase Management API using SUPABASE_URL and SUPABASE_TOKEN secrets. Tests use describeIfCreds and skip automatically when credentials are absent (forked PRs). The tests include 2-attempt retry logic with 3s backoff for transient Supabase 5xx responses.

Skipping staging

Staging review may be skipped only for:

  • Typo-only README or docs changes
  • CI/workflow-only changes with no site impact
  • Hotfixes the user has already verified on the live site

For everything else, go through staging.

Emergency overrides

If you need to promote to production without going through the staging sync check (e.g. a hotfix that was already verified live):

FORCE_DEPLOY=1 make gh-pages-only

Use this sparingly. It bypasses the staging SHA check entirely.

Clone this wiki locally