GitHub Secrets and Variables
Configure these values in GitHub under Settings > Secrets and variables > Actions.
Never commit secret values, service account keys, OAuth credentials, or runtime env files to either repository.
Create the Google service accounts and JSON keys before adding these secrets. See Create Google service-account keys for the storage runtime, Document AI runtime, and deployment account definitions. Terraform CI accounts use WIF and need no JSON key secrets.
Backend repository
Repository: CATALOG-Historic-Records/orphaned-wells-ui-server
| Name | Required for | Notes |
|---|---|---|
PROD_TERRAFORM_TFVARS | Terraform CI | Complete contents of production terraform.tfvars. Hydrated automatically into deployment/terraform/terraform.tfvars during CI runs to decouple environment inventory from Git. |
PROJECT_ID | GKE deployment | Google Cloud project ID for GKE authentication. Terraform uses its tracked configuration; bootstrap takes a shell environment variable. |
DOCKERHUB_USERNAME | GKE deployment | Docker Hub account used to push and pull backend images. |
DOCKERHUB_ACCESS_TOKEN | GKE deployment | Docker Hub token used by CI and Kubernetes image pull secret creation. |
DEPLOYMENT_SERVICE_KEY_JSON | GKE deployment | Google Cloud service account key JSON used by GitHub Actions for deployment only. Use the same deployment service account as the frontend repo if it has both GKE and App Engine deploy roles. |
STORAGE_SERVICE_KEY_JSON | Backend runtime files | Google Cloud service account key JSON used by the backend for Cloud Storage only. |
DOCUMENT_AI_SERVICE_KEY_JSON | Backend runtime files | Google Cloud service account key JSON used by the backend for Document AI processing and processor administration. |
K8S_DEPLOY_TARGETS | Disabled Terraform CI rollout fallback | Target JSON used only while ENABLE_TERRAFORM_CI is not true. Enabled deployments read live Terraform outputs. |
RUNTIME_ENV | GKE deployment | Runtime .env content configured per environment in GitHub Environments (staging, isgs, newts, osage, rrc), or as a repository-level secret for standalone single-tenant instances. |
The runtime env secrets should contain backend runtime values such as database settings, storage settings, OAuth settings, and collaborator configuration. The GKE workflow overrides:
ENVIRONMENTBACKEND_URLLOG_DIRLOCAL_STORAGE_ROOTLOCAL_STORAGE_URL_BASESTORAGE_BUCKET_NAMESTORAGE_SERVICE_KEYDOCUMENT_AI_SERVICE_KEYGOOGLE_APPLICATION_CREDENTIALS
Keep COLLABORATOR in the runtime secret if the backend uses collaborator-specific processors or configuration.
Configuring environment secrets
Because GitHub's secrets API requires an environment to exist before retrieving its encryption public key, create the environment before setting RUNTIME_ENV via the CLI:
# Create the environment (e.g. staging, isgs, newts, osage, rrc)
gh api --method PUT repos/CATALOG-Historic-Records/orphaned-wells-ui-server/environments/<ENV>
# Set the RUNTIME_ENV secret
gh secret set RUNTIME_ENV \
-R CATALOG-Historic-Records/orphaned-wells-ui-server \
--env <ENV> < path/to/.env
Backend repository variables
Use repository variables to control automatic GKE deploys:
| Name | Purpose |
|---|---|
ENABLE_GKE_DEPLOYMENTS | Controls automatic GKE deploys on push (enabled by default). Set to false to pause automatic deployments across all environments. |
ENABLE_TERRAFORM_CI | Enables upstream WIF planning, automatic no-change completion, approval-gated changes, and live deploy targets. Leave disabled until bootstrap and apply protection are configured. |
TF_WIF_PROVIDER | Full WIF provider resource name from bootstrap. |
TF_PLAN_SERVICE_ACCOUNT | Plan/no-change account email, with infrastructure reads and narrowly scoped state-lock and readiness-record writes. |
TF_APPLY_SERVICE_ACCOUNT | Environment-gated infrastructure apply account email. |
TF_WORKSPACE | Existing remote Terraform workspace, currently documented as ogrre. |
TF_CI_BUCKET | Dedicated private plan/readiness bucket name, without gs://. |
Set these variables in the upstream backend repository. Collaborator
deployments are dynamically managed via collaborators.json and
.github/workflows/deploy-k8s-collaborator.yml. Fork pushes skip staging jobs even if flags are enabled.
Follow the backend Terraform CI setup guide
to create WIF and configure terraform-apply with required reviewers, a
main-only branch restriction, and administrator bypass disabled. PRs only run
credential-free checks; the terraform-plan Environment is retired. Normal PR
merge approvals and the apply Environment's self-review policy are independent.
Referencing an Environment in YAML does not configure its protection rules.
Rerun the updated bootstrap before enabling automatic no-change completion on
an existing installation. Reuse the existing variable values; the added grant
allows only this workspace's readiness record to be replaced. For first rollout,
update active collaborator workflows to read live targets before enabling CI.
Phase one retains DEPLOYMENT_SERVICE_KEY_JSON; Terraform CI needs no new JSON key.
When adding a new collaborator, add their branch to collaborators.json and configure RUNTIME_ENV in their <collaborator> GitHub Environment (or as a repository secret for single-tenant forks). If manual dropdown dispatch via deploy-k8s-dispatch.yml is needed, add the collaborator to workflow_dispatch.inputs.DEPLOY_ENV.options.
Retired backend VM secrets (Historical)
These were only needed for the legacy Compute Engine VM deployment path, which has been retired:
| Name | Status | Notes |
|---|---|---|
DEPLOY_TARGETS | Retired | JSON map of VM names and zones consumed by retired VM deployment workflows. |
SSH_USERNAME | Retired | SSH user for deployment commands against Compute Engine VMs. |
Frontend repository
Repository: CATALOG-Historic-Records/orphaned-wells-ui
| Name | Required for | Notes |
|---|---|---|
DEPLOYMENT_SERVICE_KEY_JSON | App Engine deployment | Google Cloud service account key JSON used by frontend deployment workflows. Use the same deployment service account as the backend repo if it has both App Engine and GKE deploy roles. |
GOOGLE_CLIENTID | Frontend build | Google OAuth client ID written to REACT_APP_GOOGLE_CLIENTID. |
BACKEND_URL | Frontend build | Recommended. Backend URL configured per environment in GitHub Environments (staging, isgs, newts, osage, rrc). Written to REACT_APP_BACKEND_URL. |
DEV_BACKEND_URL | Staging frontend deployment | Legacy/fallback backend URL used when BACKEND_URL is not set in the staging environment. |
<COLLABORATOR>_BACKEND_URL | Collaborator frontend deployments | Legacy fallback backend URL for existing collaborators (ISGS_BACKEND_URL, NEWTS_BACKEND_URL, OSAGE_BACKEND_URL, RRC_BACKEND_URL) used only when BACKEND_URL is not set in the collaborator's GitHub Environment. New collaborators should use BACKEND_URL in their <collaborator> GitHub Environment. |
Backend URL values must not include a trailing slash.
Configuring environment secrets
Configure BACKEND_URL per environment using the GitHub CLI:
# Create the environment (e.g. staging, isgs, newts, osage, rrc)
gh api --method PUT repos/CATALOG-Historic-Records/orphaned-wells-ui/environments/<ENV>
# Set the BACKEND_URL secret
gh secret set BACKEND_URL \
-R CATALOG-Historic-Records/orphaned-wells-ui \
--env <ENV> \
--body "https://<ENV>-server.uow-carbon.org"
Frontend repository variables
Use repository variables to control automatic App Engine deployments:
| Name | Purpose |
|---|---|
ENABLE_APP_ENGINE_DEPLOYMENTS | Controls automatic App Engine deploys on collaborator branch push (enabled by default). Set to false to pause automatic deployments across all collaborator branches. Manual dispatch runs will still proceed. |
Updating secrets
For command-line secret updates, first authenticate the GitHub CLI with an account that can edit repository Actions secrets:
gh auth login
gh auth status --hostname github.com
Set or update the three service-account key secrets:
gh secret set DEPLOYMENT_SERVICE_KEY_JSON \
--repo CATALOG-Historic-Records/orphaned-wells-ui-server \
< /secure/path/ogrre-deployment-ci-service-key.json
gh secret set STORAGE_SERVICE_KEY_JSON \
--repo CATALOG-Historic-Records/orphaned-wells-ui-server \
< /secure/path/ogrre-storage-runtime-service-key.json
gh secret set DOCUMENT_AI_SERVICE_KEY_JSON \
--repo CATALOG-Historic-Records/orphaned-wells-ui-server \
< /secure/path/ogrre-document-ai-service-key.json
gh secret set DEPLOYMENT_SERVICE_KEY_JSON \
--repo CATALOG-Historic-Records/orphaned-wells-ui \
< /secure/path/ogrre-deployment-ci-service-key.json
To update the Terraform production inventory secret:
From the shared GCS configuration directly (no local file needed):
# Using the sync script
./orphaned-wells-ui-server/deployment/terraform/scripts/sync_tfvars.sh sync-secret
# Or directly streaming from GCS into gh
gcloud storage cat gs://tidy-outlet-412020-ogrre-terraform-state/config/terraform.tfvars | \
gh secret set PROD_TERRAFORM_TFVARS --repo CATALOG-Historic-Records/orphaned-wells-ui-server
Or from a local terraform.tfvars file:
gh secret set PROD_TERRAFORM_TFVARS \
--repo CATALOG-Historic-Records/orphaned-wells-ui-server \
< orphaned-wells-ui-server/deployment/terraform/terraform.tfvars
Only for the disabled Terraform CI rollout fallback, refresh the target secret
after target changes from orphaned-wells-ui-server/deployment/terraform:
env -u TF_WORKSPACE terraform workspace select ogrre
gh secret set K8S_DEPLOY_TARGETS \
--repo CATALOG-Historic-Records/orphaned-wells-ui-server \
--body "$(terraform output -json kubernetes_deploy_targets | jq -c .)"
For manual updates in GitHub:
- Open the target repository on GitHub.
- Go to
Settings > Secrets and variables > Actions. - Select the secret or variable to create or update.
- Save the new value.
- Re-run the affected deployment workflow.