Skip to main content

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.yml whenever code is pushed to that collaborator branch.
  • Dynamically includes the branch in .github/workflows/sync-collaborators.yml to automatically open PRs against it when changes merge to main.
  • Eliminates the need to create redundant individual .github/workflows/deploy-<collaborator>.yml workflows.

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_URL
  • REACT_APP_GOOGLE_CLIENTID
  • REACT_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:

  • A record for IPv4.
  • AAAA record 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.