Frontend on App Engine
Frontend deployment lives in orphaned-wells-ui/deployment/app-engine.
Each collaborator frontend has its own App Engine service, backend URL secret, dispatch route, DNS records, custom domain, and OAuth configuration. Collaborator branch deployments and sync PRs are managed dynamically via collaborators.json.
Use <collaborator> as the short deployment key, such as isgs, newts, osage, or rrc. Use <COLLABORATOR> for uppercase GitHub secret names.
App Engine service configuration
deployment/app-engine/app.yaml is the single source of truth for all frontend deployments.
During deployment, the workflow automatically renders the service configuration dynamically (service: <collaborator>-uow prepended to deployment/app-engine/app.yaml). Separate app-<collaborator>.yaml files are not needed.
Collaborator services follow the <collaborator>-uow naming pattern:
service: <collaborator>-uow
runtime: python312
Enable dynamic collaborator deployment and sync
Add the collaborator branch key to collaborators.json at the root of orphaned-wells-ui:
[
"isgs",
"newts",
"osage",
"rrc",
"<collaborator>"
]
Listing the branch in collaborators.json:
- Automatically enables push-based deployments via
.github/workflows/deploy-collaborator.ymlwhenever code is pushed to that collaborator branch. - Dynamically includes the branch in
.github/workflows/sync-collaborators.ymlto automatically open PRs against it when changes merge tomain. - Eliminates the need to create redundant individual
.github/workflows/deploy-<collaborator>.ymlworkflows.
The shared .github/workflows/deploy-dispatch.yml workflow builds the React app and deploys the configured App Engine service.
The frontend repository must have DEPLOYMENT_SERVICE_KEY_JSON configured from
the deployment service account. Terraform CI uses separate WIF identities.
See Create Google service-account
keys and GitHub
Secrets and Variables.
The deployment account needs App Engine deploy and traffic-promotion access. The
frontend workflow runs gcloud app deploy with the default promotion behavior,
so roles/appengine.deployer alone is not enough. It also needs
roles/appengine.serviceAdmin to update the App Engine service traffic split,
plus the Cloud Build, Cloud Storage, and Service Account User roles listed in
the GCP setup guide.
Add the backend URL secret
Create the <collaborator> GitHub Environment and configure BACKEND_URL as an environment secret:
gh api --method PUT repos/CATALOG-Historic-Records/orphaned-wells-ui/environments/<collaborator>
gh secret set BACKEND_URL \
-R CATALOG-Historic-Records/orphaned-wells-ui \
--env <collaborator> \
--body "https://<collaborator>-server.uow-carbon.org"
The value should be the public backend URL and must not include a trailing slash. Configuring BACKEND_URL in the <collaborator> GitHub Environment works dynamically without modifying .github/workflows/deploy-dispatch.yml.
Deploy the frontend
Deploy by pushing to the collaborator branch in GitHub (which triggers .github/workflows/deploy-collaborator.yml), or manually run .github/workflows/deploy-dispatch.yml via GitHub Actions (workflow_dispatch).
To pause automatic deployments across all collaborator branches, set the repository variable ENABLE_APP_ENGINE_DEPLOYMENTS to false. Manual dispatch runs will still be permitted.
The deployment workflow writes the build-time React environment values:
REACT_APP_BACKEND_URLREACT_APP_GOOGLE_CLIENTIDREACT_APP_COLLABORATOR
If deployment uploads a new version but fails while promoting it to default,
grant roles/appengine.serviceAdmin to the deployment service account and rerun
the workflow. Deploying with --no-promote avoids that permission only when you
intentionally do not want the new version to receive traffic.
Add the App Engine dispatch route
Add the hostname to deployment/app-engine/dispatch.yaml:
- url: "<collaborator>.uow-carbon.org/*"
service: <collaborator>-uow
Deploy the dispatch file from the App Engine deployment directory:
cd orphaned-wells-ui/deployment/app-engine
gcloud app deploy dispatch.yaml
Configure DNS and custom domain
In Google Cloud DNS, add records for:
<collaborator>.uow-carbon.org
Use the same frontend IPv4 and IPv6 addresses as the other frontend instances:
Arecord for IPv4.AAAArecord for IPv6.
Then add <collaborator>.uow-carbon.org in App Engine custom domains.
Update OAuth
In Google OAuth credentials, add both frontend URLs wherever frontend origins are required:
https://<collaborator>.uow-carbon.org.
Use the exact URL format required by the OAuth client. Avoid trailing slashes unless the existing entries use them.
Verify
After deployment:
- Visit
https://<collaborator>.uow-carbon.org. - Confirm the frontend calls the expected backend URL.
- Confirm sign-in works for the custom domain.
- Confirm the App Engine dispatch route sends the host to the expected service.