pages.yml

# Publishes the beta landing page and the installable app to GitHub Pages.
#
# GitHub Pages is what makes this installable at all: a PWA needs HTTPS before
# any browser will offer "Install app", and Pages provides it for free.
#
# Three things land, at the paths the site is written to expect:
#
#   /         site/index.html         - the beta announcement and install steps
#   /app/     client/dist/            - the app itself
#   /status/  site/status/index.html  - "is it me or us?", checked live
#                                       in the visitor's browser (#467)
#
# Those are apex paths because `site/CNAME` moves this site onto `ourhike.org`
# (#733). It used to be a project site under `/OurHike/`, and the prefix was
# never in this file's assembly step - `_site/` has always had the landing page
# at its root and the app at `app/`. Only VITE_BASE_PATH below carried it, so
# the custom domain is the one-line change it looks like.
#
# The app's `base` has to match its serving path exactly, because a PWA's
# `scope` and `start_url` decide which pages the installed app owns - see the
# note in client/vite.config.ts. This is the half that CANNOT be wrong while
# the other half is right: a base of `/OurHike/app/` served at `ourhike.org`
# asks for assets nothing answers, and a base of `/app/` served at
# `ourhike.github.io` does the same. `.github/tests/test_pages_publish.py`
# holds them to `site/CNAME` so neither moves alone.
#
# Set the DATA_BASE_URL repository variable (Settings -> Secrets and variables
# -> Actions -> Variables) to the public R2 bucket URL. Without it the app
# still builds and installs; its Downloads screen says the data source is not
# configured rather than firing requests that would 404.
#
# Publishes by pushing to the `gh-pages` branch rather than through the native
# Pages-via-Actions deployment (`actions/deploy-pages`), because that
# mechanism only ever serves one live deployment and can't host anything else
# alongside it. pr-preview.yml needs a second thing alongside it - a preview
# per pull request, at /OurHike/pr-preview/pr-<n>/ - so both workflows publish
# to the same gh-pages branch instead, each to their own path.
#
# ONE-TIME MANUAL STEP: this only takes effect once a repo admin flips
# Settings -> Pages -> Build and deployment -> Source from "GitHub Actions" to
# "Deploy from a branch", branch `gh-pages`, folder `/ (root)`. Until that's
# done, Pages keeps serving whatever the old Actions-based deployment last
# published, and this workflow's pushes to gh-pages sit there unused.

name: Deploy Pages

# Production deploys from a TAG, not from `main`. RELEASING.md §2 is the whole
# argument; the short version is that this workflow used to run on every push to
# `main`, which made merging a pull request the act of shipping to hikers and
# left nowhere for a release candidate to wait. `main` now deploys to UA
# (ua.yml) and an annotated `v*` tag deploys here.
#
# workflow_dispatch stays, for the case it was added for - republishing after a
# repository variable changes, with no code change - and now also serves as the
# rollback: dispatch against a previous tag and production is that tag again
# (RELEASING.md §11b).
on:
  push:
    tags: ['v*']
  # So the site can be republished after setting DATA_BASE_URL, with no code
  # change - and so a previous tag can be re-deployed to roll back.
  workflow_dispatch:

permissions:
  contents: write

# Never let two deploys race; let a newer commit supersede an in-flight one.
# This is most of what keeps the branch to one writer at a time, but not all of
# it: cancellation is not instant, and workflow_dispatch can start a run
# whenever someone asks for one. The retry in the publish step covers the rest.
concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    # Room for a build plus a publish waiting its turn behind several previews,
    # without letting a wedged job bill all day.
    timeout-minutes: 20
    steps:
      # Production deploys from a tag, and both sanctioned dispatch uses -
      # republishing after a variable change, rolling back (RELEASING.md §11b)
      # - are dispatches against a tag that already shipped. The two tag gates
      # below skip on a non-tag ref rather than failing, which left the
      # default dispatch (the Run workflow button offers the default branch
      # first) building main and pushing it to production with every gate
      # silently skipped (#644). Refused here by name instead. After this
      # step the only dispatch that proceeds is a tag's, where the gates run
      # - and pass, because every tag that ever shipped passed them to ship.
      - name: Refuse a dispatch that is not a tag
        if: github.event_name == 'workflow_dispatch' && !startsWith(github.ref, 'refs/tags/')
        run: |
          echo "::error::Deploy Pages was dispatched on '$GITHUB_REF'. Production deploys from a v* tag - dispatch against the release tag to republish or roll back (RELEASING.md §11b)."
          exit 1

      - uses: actions/checkout@v4

      # Gate 12 (RELEASING.md §8): a tag with no notes committed beside it is a
      # release nobody wrote down, and the notes file is canonical rather than
      # the GitHub release body (§7a). Checked here rather than trusted, because
      # the failure is silent in the direction that matters - the site deploys
      # perfectly well and the release has no record.
      #
      # Only on a tag. A workflow_dispatch run is a republish or a rollback of
      # something already released, and re-asserting its paperwork would make
      # the rollback path fail exactly when it is needed.
      - name: Confirm this tag has its release notes
        if: startsWith(github.ref, 'refs/tags/')
        env:
          VERSION: ${{ github.ref_name }}
        run: |
          # Nullglob so a pattern that matches nothing is an empty list rather
          # than the literal pattern, which would otherwise "exist" as a name.
          shopt -s nullglob
          notes=(releases/"$VERSION"-*.md)
          if [ ${#notes[@]} -eq 0 ]; then
            echo "::error::No release notes for $VERSION. Expected releases/$VERSION-<name>.md - see RELEASING.md §7a."
            exit 1
          fi
          echo "Release notes: ${notes[0]}"

      # RELEASING.md §4 makes client/package.json the single source for the
      # version, and the app now reads it back to a hiker (#378,
      # client/src/lib/buildInfo.ts). A tag that disagrees with that file ships
      # an app confidently reporting a version nobody released - and the whole
      # value of the About line is somebody quoting it and being believed.
      #
      # A gate rather than deriving the version from the tag, because "single
      # source" and "read it from whichever of two places is convenient" are
      # different claims, and only one of them survives a build done anywhere
      # other than a tagged CI run. package.json is in the tree; the tag is
      # not, and a laptop, a preview and UA all have to answer this too.
      - name: Confirm this tag matches the app's version
        if: startsWith(github.ref, 'refs/tags/')
        env:
          VERSION: ${{ github.ref_name }}
        run: |
          set -euo pipefail
          packaged="$(jq -r '.version' client/package.json)"
          if [ "$VERSION" != "v$packaged" ]; then
            echo "::error::Tag $VERSION does not match client/package.json ($packaged). Bump the version in the same commit the tag points at - see RELEASING.md §4."
            exit 1
          fi
          echo "Version: $packaged"

      - uses: actions/setup-node@v4
        with:
          node-version: '24'
          cache: npm
          cache-dependency-path: client/package-lock.json

      - name: Install
        working-directory: client
        run: npm ci

      # The data URL is not secret - Vite inlines it into a public JS bundle, so
      # it is readable by anyone who opens the app either way. A variable is the
      # right home for it, and the only one whose value survives into a build
      # log where it can be checked. But "Secrets and variables" is one settings
      # page with two tabs, picking the wrong one is easy, and the failure was
      # silent: an empty string built a working app that could not download
      # anything. Accepting either is worth more than being right about which.
      - name: Resolve the data source
        id: data
        env:
          FROM_VAR: ${{ vars.DATA_BASE_URL }}
          FROM_SECRET: ${{ secrets.DATA_BASE_URL }}
        run: |
          URL="${FROM_VAR:-$FROM_SECRET}"
          if [ -z "$URL" ]; then
            echo "::warning::DATA_BASE_URL is set as neither a variable nor a secret. Building anyway; the app will say its data source is not configured."
          elif [ -z "$FROM_VAR" ]; then
            echo "::warning::DATA_BASE_URL is a secret. It works, but GitHub masks it in logs - move it to the Variables tab to keep it readable here."
          else
            echo "Data source: $URL"
          fi
          echo "url=$URL" >> "$GITHUB_OUTPUT"

      # Same variable-or-secret shape as the data source above, and for the same
      # reason: neither of these is secret. The anon key is designed to be
      # public and ships inside the bundle, so hiding it in a secret buys
      # nothing and costs a readable log. What is NOT here, deliberately, is
      # SUPABASE_JWT_SECRET - that one is real, it belongs only to the backend,
      # and a VITE_-prefixed copy would be inlined into a public file.
      #
      # Absent entirely is a supported state: the app builds, the map works, and
      # the sign-in controls say this build has no project rather than offering
      # a round trip that cannot finish.
      - name: Resolve the Supabase project
        id: supabase
        env:
          URL_FROM_VAR: ${{ vars.SUPABASE_URL }}
          URL_FROM_SECRET: ${{ secrets.SUPABASE_URL }}
          KEY_FROM_VAR: ${{ vars.SUPABASE_ANON_KEY }}
          KEY_FROM_SECRET: ${{ secrets.SUPABASE_ANON_KEY }}
        run: |
          URL="${URL_FROM_VAR:-$URL_FROM_SECRET}"
          KEY="${KEY_FROM_VAR:-$KEY_FROM_SECRET}"
          if [ -z "$URL" ] || [ -z "$KEY" ]; then
            echo "::warning::SUPABASE_URL and/or SUPABASE_ANON_KEY are not set. Building anyway; the app will say signing in is not configured."
          elif [ -z "$URL_FROM_VAR" ] || [ -z "$KEY_FROM_VAR" ]; then
            echo "::warning::A Supabase value is a secret. It works, but GitHub masks it in logs - move it to the Variables tab to keep it readable here."
          else
            echo "Supabase project: $URL"
          fi
          {
            echo "url=$URL"
            echo "key=$KEY"
          } >> "$GITHUB_OUTPUT"

      - name: Build the app
        working-directory: client
        env:
          # Trailing slash matters - Vite joins this to asset paths directly.
          #
          # A literal, not `/${{ github.event.repository.name }}/app/` as it
          # was while this was a project site: the serving path is now decided
          # by `site/CNAME`, which has nothing to do with what the repository
          # is called. Deriving it from the repo name would silently follow a
          # rename that the domain would not.
          VITE_BASE_PATH: /app/
          VITE_DATA_BASE_URL: ${{ steps.data.outputs.url }}
          VITE_SUPABASE_URL: ${{ steps.supabase.outputs.url }}
          VITE_SUPABASE_ANON_KEY: ${{ steps.supabase.outputs.key }}
          # Only the providers whose credentials actually exist in the Supabase
          # dashboard. A name here without them is a button that reaches an
          # error page. Unset means the client's own default (google,email).
          VITE_AUTH_PROVIDERS: ${{ vars.AUTH_PROVIDERS }}
          # Where queued reports are sent. Empty until the backend is deployed
          # anywhere (#95), which is a supported state: reports stay in the
          # outbox with their authored timestamps rather than being lost, and
          # sending begins the day this variable has a value. Wired now so that
          # day is a Variables-tab edit and not a code change.
          VITE_API_BASE_URL: ${{ vars.API_BASE_URL }}
        run: npm run build

      # Proves what actually got inlined, rather than trusting that it did. The
      # bundle is the artifact that ships, so it is the only honest place to
      # check - and a bundle with no bucket in it is the exact state that
      # produced "No data source is configured" in production.
      - name: Confirm the data source reached the bundle
        working-directory: client
        # Through env, not interpolated into the script body. `${{ }}` is
        # substituted as literal text before bash ever sees the line, so a
        # value containing a quote or a `$(...)` would be parsed as script
        # rather than data. This one is set by a repo admin so it is not much
        # of a threat, but the step above already does it the safe way and
        # there is no reason for these two to differ.
        env:
          DATA_URL: ${{ steps.data.outputs.url }}
        run: |
          if [ -z "$DATA_URL" ]; then
            echo "No data source configured - skipping the check."
            exit 0
          fi
          if grep -rqF -- "$DATA_URL" dist/assets/*.js; then
            echo "Data source is present in the built bundle."
          else
            echo "::error::DATA_BASE_URL was set but is absent from the built bundle - the app would ship unable to download anything."
            exit 1
          fi

      # Same proof for the same reason, one step later. Setting a variable and
      # having it reach the bundle are different claims, and the gap between
      # them is invisible from outside: the app builds, the map works, and the
      # only symptom is that signing in reports no project configured.
      #
      # Only the URL is checked. The anon key is public but there is no reason
      # to grep for a credential and print the surrounding line on failure, and
      # the two are set and passed together - a build with one and not the
      # other is not a case that arises.
      - name: Confirm the Supabase project reached the bundle
        working-directory: client
        env:
          SUPABASE_PROJECT_URL: ${{ steps.supabase.outputs.url }}
        run: |
          if [ -z "$SUPABASE_PROJECT_URL" ]; then
            echo "No Supabase project configured - skipping the check. Signing in will say so."
            exit 0
          fi
          if grep -rqF -- "$SUPABASE_PROJECT_URL" dist/assets/*.js; then
            echo "Supabase project is present in the built bundle."
          else
            echo "::error::SUPABASE_URL was set but is absent from the built bundle - the app would ship unable to sign anyone in."
            exit 1
          fi

      - name: Assemble the site
        env:
          DATA_URL: ${{ steps.data.outputs.url }}
        run: |
          mkdir -p _site/app
          # Carries site/CNAME with it, which is what moves this site onto
          # ourhike.org (#733). Not copied by name on purpose: a second
          # spelling of the hostname here is a second place for it to be
          # wrong, and site/CNAME is the one the test reads.
          cp -r site/. _site/
          cp -r client/dist/. _site/app/
          cp client/public/favicon.svg _site/favicon.svg
          # Pages runs Jekyll by default, which skips files beginning with an
          # underscore - Vite does not emit any today, but a build tool changing
          # its naming should not silently break the deploy.
          touch _site/.nojekyll

          # The status page checks the bucket from the visitor's own browser
          # (#431 tier 2, #467), so it needs the same URL the app is built
          # with. Substituted here rather than committed, so site/ never holds
          # a bucket URL that can drift from the app's - which is the class of
          # drift #457 was about.
          #
          # DATA_URL goes through the environment and then through a python
          # replace rather than sed: a URL contains `/`, and a sed delimiter
          # collision would silently produce a mangled page rather than fail.
          # Read from os.environ inside python rather than interpolated into
          # the source, so the value is data and never code.
          #
          # An unset DATA_URL leaves the placeholder alone on purpose - the
          # page detects it and says it is unconfigured, which is true and is a
          # different sentence from "the map is down".
          if [ -n "$DATA_URL" ]; then
            python3 -c 'import os, pathlib; p = pathlib.Path("_site/status/index.html"); p.write_text(p.read_text().replace("__DATA_BASE_URL__", os.environ["DATA_URL"]))'
            echo "Status page points at $DATA_URL"
          else
            echo "::warning::No DATA_BASE_URL, so /status/ will say it is unconfigured rather than checking anything."
          fi

      # Through the local action rather than peaceiris/actions-gh-pages, which
      # pushes exactly once and fails the whole deploy on a rejected push. See
      # the action for when that can still happen now that this workflow is the
      # only thing writing this branch.
      #
      # This deploy owns `gh-pages` outright: everything on the branch and not
      # in _site is deleted. That is new - previews used to live under
      # pr-preview/ on this same branch and had to be worked around here - and
      # it is what clears out the last of them, since they are served from
      # Cloudflare Pages now (pr-preview.yml).
      - name: Publish to GitHub Pages
        uses: ./.github/actions/publish-to-pages
        with:
          source-dir: _site
          commit-message: "Deploy the site from ${{ github.sha }}"
          # Passed rather than left to the action's default of `github.token`,
          # which resolves to the same thing. Both are the run's own token, but
          # only this spelling is visible to the settings manifest, whose test
          # reads `secrets.` references out of this directory - and a deploy
          # that pushes without appearing to need a token to push with is the
          # kind of quiet that the manifest exists to prevent.
          token: ${{ secrets.GITHUB_TOKEN }}

      # Handed to the release job below rather than rebuilt there. The point of
      # attaching a build to a release is to be able to answer a question about
      # the bytes that shipped in three months' time, and a second build of the
      # same commit is not those bytes - it is a build that agrees with them
      # until some day it does not.
      - name: Keep the built app for the release
        if: startsWith(github.ref, 'refs/tags/')
        uses: actions/upload-artifact@v4
        with:
          name: app-dist
          path: _site/app
          retention-days: 7

  # The record of the release, drafted and left for a human. RELEASING.md §12:
  # an agent - or a workflow, which is the same thing wearing a hat - may
  # prepare everything and may not publish. So this creates a DRAFT and stops.
  #
  # Three attachments, each because a question gets asked later and rebuilding
  # is not an answer: the app exactly as deployed, the backend's OpenAPI
  # document (which is the baseline the next release's compatibility diff reads,
  # #374), and the data manifest naming the artifacts this build pins.
  release:
    if: startsWith(github.ref, 'refs/tags/')
    needs: build
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4

      - uses: actions/download-artifact@v4
        with:
          name: app-dist
          path: app-dist

      - uses: actions/setup-python@v5
        with:
          python-version: '3.14'

      # Importing the app is enough to render its schema, but its settings are
      # required fields - so this needs values, and deliberately fake ones. A
      # real project URL here would be a live credential in a workflow whose
      # only job is to write a document.
      - name: Dump the backend's OpenAPI document
        working-directory: backend
        env:
          SUPABASE_URL: https://openapi-dump.invalid
          SUPABASE_ANON_KEY: not-a-real-key
        run: |
          python -m pip install --quiet -r requirements.txt
          python -c "import json, sys; from app.main import app; json.dump(app.openapi(), sys.stdout, indent=2)" > ../openapi.json
          echo "Paths: $(python -c "import json; print(len(json.load(open('../openapi.json'))['paths']))")"

      - name: Collect the assets
        env:
          VERSION: ${{ github.ref_name }}
          DATA_BASE: ${{ vars.DATA_BASE_URL }}
        run: |
          tar -czf "ourhike-app-$VERSION.tar.gz" -C app-dist .

          # Best effort, and said out loud when it fails. The manifest is a
          # public object, so this needs no credentials - but a release whose
          # data manifest could not be fetched is still a release, and failing
          # here would block shipping over a record rather than over a defect.
          if [ -n "$DATA_BASE" ] && curl -fsS --max-time 30 "$DATA_BASE/latest.json" -o data-manifest.json; then
            echo "Attached the data manifest."
          else
            echo "::warning::Could not fetch $DATA_BASE/latest.json, so the release carries no data manifest."
          fi

          # The build job already refused to deploy a tag with no notes, so this
          # cannot normally fail. It is here because the two jobs check the same
          # thing from different checkouts, and a release drafted with an empty
          # body would be a worse outcome than a red job.
          shopt -s nullglob
          notes=(releases/"$VERSION"-*.md)
          if [ ${#notes[@]} -eq 0 ]; then
            echo "::error::No release notes for $VERSION - see RELEASING.md §7a."
            exit 1
          fi
          echo "NOTES=${notes[0]}" >> "$GITHUB_ENV"

      # Through the API rather than an action, because the only thing that needs
      # to be exactly right here is `draft: true`, and that is easier to see in
      # four lines of JSON than in someone else's inputs.
      - name: Draft the release
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          VERSION: ${{ github.ref_name }}
          REPO: ${{ github.repository }}
        run: |
          set -euo pipefail

          # The name after the version, read from the notes filename rather than
          # kept anywhere a second time: releases/v1.0.0-springer-mountain.md is
          # "v1.0.0 — Springer Mountain".
          slug="$(basename "$NOTES" .md)"
          slug="${slug#"$VERSION"-}"
          title="$VERSION — $(echo "$slug" | tr '-' ' ' | sed -E 's/(^| )([a-z])/\1\u\2/g')"

          jq -n \
            --arg tag "$VERSION" \
            --arg name "$title" \
            --rawfile body "$NOTES" \
            '{tag_name: $tag, name: $name, body: $body, draft: true, prerelease: false}' > payload.json

          id="$(curl -fsS -X POST \
            -H "Authorization: Bearer $GH_TOKEN" \
            -H "Accept: application/vnd.github+json" \
            "https://api.github.com/repos/$REPO/releases" \
            -d @payload.json | jq -r '.id')"

          echo "Drafted release $id ($title)."

          for asset in "ourhike-app-$VERSION.tar.gz" openapi.json data-manifest.json; do
            [ -f "$asset" ] || continue
            curl -fsS -X POST \
              -H "Authorization: Bearer $GH_TOKEN" \
              -H "Content-Type: application/octet-stream" \
              --data-binary "@$asset" \
              "https://uploads.github.com/repos/$REPO/releases/$id/assets?name=$asset" > /dev/null
            echo "Attached $asset."
          done

          {
            echo "### Release drafted"
            echo
            echo "**$title** is a draft at https://github.com/$REPO/releases"
            echo
            echo "Publishing it is a human action - RELEASING.md §12. Read the notes first;"
            echo "they were generated and then edited, and the draft is the last chance to"
            echo "notice a claim the release does not actually support."
          } >> "$GITHUB_STEP_SUMMARY"