Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 18 additions & 5 deletions .github/workflows/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,28 @@

## deploy-gh-pages.yml

Builds the Phaser game in `phaser-asteroids/` and publishes it as the GitHub Pages site,
<https://djblackett.github.io/asteroids-bootdev/>. It is the only workflow that deploys to Pages.
Builds the Phaser game in `phaser-asteroids/`, deploys and verifies its production Cloudflare Worker,
then publishes the already-built GitHub Pages site, <https://djblackett.github.io/asteroids-bootdev/>.
It is the only release workflow; both deployments use the same commit.

- **Push to `main`** touching `phaser-asteroids/**` (or this workflow): validate, then deploy.
- **Push to `main`** touching `phaser-asteroids/**` (or this workflow): validate, deploy Worker, verify health/versions, then deploy Pages.
- **Pull request:** validate only.
- **Manual run:** Actions → "Deploy to GitHub Pages" → Run workflow. Deploys only from `main`.

Validation (blocks deployment): `npm ci`, typecheck, unit tests, production build, and a headless-Chrome check of the build
(`phaser-asteroids/scripts/pages-check.mjs`).
Validation (blocks deployment): `npm ci`, typecheck, unit tests (including server tests), production build,
headless-Chrome check (`phaser-asteroids/scripts/pages-check.mjs`), locked server install and server typecheck,
and mocked tests of the production health gate. Full browser suites remain optional.

Set the repository Actions **secret** `CLOUDFLARE_API_TOKEN` to a token with **Editor access only to the existing
`asteroids-leaderboard` Worker** in account `620de0810a6cf29710d9fedb3a966d6f`. No D1 access is needed just to deploy
the existing binding. The account ID is already in `wrangler.toml`. Never use a Global API Key.
Exact token setup, verification, manual release and recovery instructions are in the
[deployment guide](../../phaser-asteroids/docs/deployment.md#one-time-setup-repository-owner).

The whole release is serialized without cancelling active runs. Stale commits fail before Worker deployment.
Worker deploy/health failures block Pages. If Pages fails after the Worker succeeds, the Worker remains updated;
rerun **all jobs on current main** (or revert on main to restore both). Do not rerun only Pages.
Production D1 migrations are explicit manual operations, never part of this workflow.

The build requires the repository Actions variable `VITE_LEADERBOARD_API_URL` (public HTTPS Worker origin, without `/api/v1`) and fails before building if it is missing or empty. The production value is `https://asteroids-leaderboard.davejandrea.workers.dev`. Backend `IP_HASH_SALT` and `ADMIN_TOKEN` are Cloudflare secrets and must never enter the frontend build; see [the backend deployment guide](../../docs/leaderboard-backend.md#14-production-setup-and-deployment).

Expand Down
102 changes: 94 additions & 8 deletions .github/workflows/deploy-gh-pages.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
name: Deploy to GitHub Pages

# Publishes the Phaser 4 port in phaser-asteroids/ as the whole GitHub Pages site, at the repository root:
# Releases the production Worker, verifies compatibility, then publishes the Phaser 4 port to GitHub Pages:
# https://djblackett.github.io/asteroids-bootdev/
#
# Pull requests only run the validation job. Nothing is deployed unless the run is on `main`; a manual run from
Expand All @@ -26,13 +26,21 @@ on:
permissions:
contents: read

# Hold the release lock through validation, Worker deployment/verification AND Pages publication.
# PRs and non-main manual runs have separate groups. Never cancel a release halfway through.
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: false

jobs:
# Blocks deployment: typecheck, unit tests, production build, and a real-browser check of that build served
# at the Pages URL path (/asteroids-bootdev/) and at "/". The larger browser suites run separately (browser-suites.yml).
phaser:
name: Phaser - validate and build
runs-on: ubuntu-latest
timeout-minutes: 15
outputs:
artifact_name: phaser-site-${{ github.run_attempt }}
defaults:
run:
working-directory: phaser-asteroids
Expand Down Expand Up @@ -75,36 +83,111 @@ jobs:
google-chrome --version
node scripts/pages-check.mjs

# npm test above already includes server/tests; do not run the same suite twice.
- name: Install locked server dependencies and typecheck
run: |
npm ci --prefix server
npm --prefix server run typecheck

- name: Test production health verification (mock HTTP only)
run: node --test scripts/production-health.test.mjs

- name: Upload build for deployment
if: ${{ github.event_name != 'pull_request' && github.ref == 'refs/heads/main' }}
uses: actions/upload-artifact@v7
with:
name: phaser-site
# Preserve earlier attempts' artifacts and avoid immutable-name conflicts on reruns.
name: phaser-site-${{ github.run_attempt }}
path: phaser-asteroids/dist
if-no-files-found: error
retention-days: 7

worker:
name: Deploy and verify production Worker
needs: phaser
if: ${{ github.event_name != 'pull_request' && github.ref == 'refs/heads/main' }}
runs-on: ubuntu-latest
timeout-minutes: 10
outputs:
release_attempt: ${{ steps.verification.outputs.release_attempt }}
defaults:
run:
working-directory: phaser-asteroids/server
steps:
- name: Checkout the validated commit
uses: actions/checkout@v7
with:
ref: ${{ github.sha }}

- name: Set up Node.js
uses: actions/setup-node@v7
with:
node-version: 22
cache: npm
cache-dependency-path: phaser-asteroids/server/package-lock.json

- name: Install locked Wrangler dependency
run: npm ci

- name: Download the validated build (includes shared replay versions)
uses: actions/download-artifact@v8
with:
name: ${{ needs.phaser.outputs.artifact_name }}
path: phaser-asteroids/dist

# Concurrency does not guarantee commit order. Reject old queued runs and old reruns.
# Once this passes, finish BOTH deployments even if main advances while releasing.
- name: Refuse a stale release
run: |
latest=$(git ls-remote --exit-code origin refs/heads/main | cut -f1)
if [ "$latest" != "$GITHUB_SHA" ]; then
echo "::error::This commit is no longer main. Run the release workflow on current main instead."
exit 1
fi

- name: Deploy the existing production Worker
env:
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
run: |
if [ -z "$CLOUDFLARE_API_TOKEN" ]; then
echo "::error::Set the repository Actions secret CLOUDFLARE_API_TOKEN before releasing."
exit 1
fi
npx wrangler deploy --env production

- name: Verify production health and replay compatibility
id: verification
run: |
node ../scripts/production-health.mjs
echo "release_attempt=$GITHUB_RUN_ATTEMPT" >> "$GITHUB_OUTPUT"

deploy:
name: Deploy to GitHub Pages
needs: phaser
needs: [phaser, worker]
if: ${{ github.event_name != 'pull_request' && github.ref == 'refs/heads/main' }}
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
pages: write # publish to Pages
id-token: write # prove to Pages that the deployment comes from this workflow
# Deployments are serialised and never cancelled half-way, so overlapping pushes cannot corrupt publication.
concurrency:
group: pages
cancel-in-progress: false
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
# A rerun of only Pages would otherwise reuse a prior attempt's successful Worker job.
- name: Require Worker verification in this release attempt
env:
WORKER_ATTEMPT: ${{ needs.worker.outputs.release_attempt }}
run: |
if [ "$WORKER_ATTEMPT" != "$GITHUB_RUN_ATTEMPT" ]; then
echo "::error::Re-run all jobs so the Worker and health gate run in this attempt before Pages."
exit 1
fi

- name: Download the build
uses: actions/download-artifact@v8
with:
name: phaser-site
name: ${{ needs.phaser.outputs.artifact_name }}
path: site

- name: Check the assembled site
Expand All @@ -120,8 +203,11 @@ jobs:
- name: Upload Pages artifact
uses: actions/upload-pages-artifact@v5
with:
name: github-pages-${{ github.run_attempt }}
path: site

- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v5
with:
artifact_name: github-pages-${{ github.run_attempt }}
37 changes: 31 additions & 6 deletions docs/leaderboard-backend.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Phaser Asteroids — Secure Online Leaderboard (Phase 2 backend, Phase 3 player experience)

> **Status:** Production Worker deployed with approval and verified on 2026-10-22 at **https://asteroids-leaderboard.davejandrea.workers.dev**. Production D1 has both migrations applied and both Worker secrets are configured. Frontend GitHub Actions wiring is prepared but has not been published.
> **Status:** Production Worker deployed with approval and verified on 2026-10-22 at **https://asteroids-leaderboard.davejandrea.workers.dev**. Production D1 has both migrations applied and both Worker secrets are configured. The coordinated Worker + Pages release workflow is prepared for review; see the [deployment guide](../phaser-asteroids/docs/deployment.md) for required CI credentials and recovery.
> Phase 3 (the ranked menu, nickname entry, High Scores, personal best, and the time-limited ending) is described in [§15](#15-the-player-facing-experience-phase-3); the 20-minute limit decision is in [§3](#timing-policy).
> **Code:** `phaser-asteroids/server/` (backend), `phaser-asteroids/src/ranked/` (browser client), builds on `phaser-asteroids/src/replay/` (Phase 1, see [deterministic-replay.md](deterministic-replay.md)).

Expand Down Expand Up @@ -399,13 +399,34 @@ Set-Clipboard -Value ''

On other platforms, use a password manager and Wrangler's `--secrets-file` with a protected, temporary JSON or dotenv file. For later secret rotation, `wrangler secret put IP_HASH_SALT --env production` and `wrangler secret put ADMIN_TOKEN --env production` prompt without putting values in shell history. **These commands create a new deployment**, so use them only after deployment is approved. Changing the IP salt resets per-IP rate-limit identities; changing the admin token invalidates the old moderation credential. Do not rotate either accidentally.

### GitHub Pages build wiring (prepared only)
### Coordinated GitHub Actions release

`.github/workflows/deploy-gh-pages.yml` supplies `${{ vars.VITE_LEADERBOARD_API_URL }}` to the existing production build step. For the separately approved frontend release, set the **repository Actions variable** `VITE_LEADERBOARD_API_URL` to `https://asteroids-leaderboard.davejandrea.workers.dev`, without `/api/v1`. The repository variable was not changed during backend deployment. This is a public URL, not a secret. Use a repository variable because the build job does not run in the `github-pages` environment. `IP_HASH_SALT` and `ADMIN_TOKEN` belong only in Cloudflare Worker secrets.
`.github/workflows/deploy-gh-pages.yml` validates and builds the frontend (including server unit tests), typechecks the
server, deploys the existing Worker with locked Wrangler, verifies public health against the shared rules/schema
versions in that build, then publishes the same frontend artifact. Worker deploy/verification failure blocks Pages.
Releases are serialized through both deployments and stale commits are rejected. PRs only validate.

Publishing the frontend is a separate release from backend setup. The GitHub Actions build fails if `VITE_LEADERBOARD_API_URL` is missing or empty, preventing publication with Ranked Play disabled. This guard applies only to the workflow; ordinary local builds can still omit the variable. The opt-in LAN config still selects its same-origin local proxy even when a production build URL exists.
Before merging/enabling this workflow, set the **repository Actions secret** `CLOUDFLARE_API_TOKEN` to a token with
Editor access scoped to this existing Worker, as detailed in the
[one-time setup](../phaser-asteroids/docs/deployment.md#one-time-setup-repository-owner). Deploying the existing D1
binding requires no D1 data permission. The account ID is already configured in `wrangler.toml`. Code-only deployments
preserve the existing Cloudflare-managed `IP_HASH_SALT` and `ADMIN_TOKEN`; neither secret belongs in GitHub or Vite.

### General deployment checklist
Set the **repository Actions variable** `VITE_LEADERBOARD_API_URL` to
`https://asteroids-leaderboard.davejandrea.workers.dev`, without `/api/v1`. This public URL is supplied to the existing
production build, which fails if it is missing or empty. Use a repository variable because the build job does not use
the `github-pages` environment. Ordinary local builds may omit it; the opt-in LAN config still selects its local proxy.

No production migrations are run by CI. V1/V2 score history needs no new migration. Schema changes are separately
reviewed, controlled operations; keep migration credentials out of the release workflow. Existing scores and the
`env.production.DB` binding are preserved. For verification, partial releases, manual fallback and rollback, use the
[release/recovery guide](../phaser-asteroids/docs/deployment.md#rolling-back). These changes do not configure repository
settings, commit, push or publish anything by themselves.

### Initial provisioning reference (already completed; not a release checklist)

Do not repeat database creation, first-deployment secret upload or migrations for a routine release. Use the
coordinated workflow above. The following records initial provisioning for a new installation only.

1. `cd phaser-asteroids/server && npx wrangler login` and upgrade the account to **Workers Paid** in the dashboard (US$5/month).
2. `npx wrangler d1 create asteroids-leaderboard` — paste the printed `database_id` into `[env.production]` in `wrangler.toml`.
Expand All @@ -419,7 +440,11 @@ Publishing the frontend is a separate release from backend setup. The GitHub Act

**Monitoring:** `npx wrangler tail --env production` (look for `run_rejected`, `verifier_threw`, `submit_failed`, `unhandled`); Cloudflare dashboard → Workers → Metrics (CPU time p50/p99, errors) and D1 metrics. Confirm real-world CPU per verification stays well under the 5 s cap.

**Rollback:** `npx wrangler rollback --env production` restores the previous Worker version (also available in the dashboard). Migrations are forward-only; 0001 is additive. For data problems, D1 Time Travel: `npx wrangler d1 time-travel restore asteroids-leaderboard --env production --timestamp=<RFC3339>`. Removing `VITE_LEADERBOARD_API_URL` from the site build turns ranked play off without touching the backend.
**Rollback:** Prefer reverting the change on `main` so the workflow restores both frontend and Worker together.
For an urgent Worker-only rollback after a partial release, first stop competing releases and confirm the version
matches the currently published client; see the [recovery procedure](../phaser-asteroids/docs/deployment.md#rolling-back).
Code rollback does not require D1 restore or migration changes. Removing `VITE_LEADERBOARD_API_URL` from a local build
disables ranked play, but the Actions production build deliberately rejects an empty value.

## 15. The player-facing experience (Phase 3)

Expand Down
Loading
Loading