Skip to main content

GitHub Secrets and Variables

Configure these values in GitHub under Settings > Secrets and variables > Actions.

warning

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

NameRequired forNotes
PROD_TERRAFORM_TFVARSTerraform CIComplete contents of production terraform.tfvars. Hydrated automatically into deployment/terraform/terraform.tfvars during CI runs to decouple environment inventory from Git.
PROJECT_IDGKE deploymentGoogle Cloud project ID for GKE authentication. Terraform uses its tracked configuration; bootstrap takes a shell environment variable.
DOCKERHUB_USERNAMEGKE deploymentDocker Hub account used to push and pull backend images.
DOCKERHUB_ACCESS_TOKENGKE deploymentDocker Hub token used by CI and Kubernetes image pull secret creation.
DEPLOYMENT_SERVICE_KEY_JSONGKE deploymentGoogle 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_JSONBackend runtime filesGoogle Cloud service account key JSON used by the backend for Cloud Storage only.
DOCUMENT_AI_SERVICE_KEY_JSONBackend runtime filesGoogle Cloud service account key JSON used by the backend for Document AI processing and processor administration.
K8S_DEPLOY_TARGETSDisabled Terraform CI rollout fallbackTarget JSON used only while ENABLE_TERRAFORM_CI is not true. Enabled deployments read live Terraform outputs.
RUNTIME_ENVGKE deploymentRuntime .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:

  • ENVIRONMENT
  • BACKEND_URL
  • LOG_DIR
  • LOCAL_STORAGE_ROOT
  • LOCAL_STORAGE_URL_BASE
  • STORAGE_BUCKET_NAME
  • STORAGE_SERVICE_KEY
  • DOCUMENT_AI_SERVICE_KEY
  • GOOGLE_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:

NamePurpose
ENABLE_GKE_DEPLOYMENTSControls automatic GKE deploys on push (enabled by default). Set to false to pause automatic deployments across all environments.
ENABLE_TERRAFORM_CIEnables 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_PROVIDERFull WIF provider resource name from bootstrap.
TF_PLAN_SERVICE_ACCOUNTPlan/no-change account email, with infrastructure reads and narrowly scoped state-lock and readiness-record writes.
TF_APPLY_SERVICE_ACCOUNTEnvironment-gated infrastructure apply account email.
TF_WORKSPACEExisting remote Terraform workspace, currently documented as ogrre.
TF_CI_BUCKETDedicated 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:

NameStatusNotes
DEPLOY_TARGETSRetiredJSON map of VM names and zones consumed by retired VM deployment workflows.
SSH_USERNAMERetiredSSH user for deployment commands against Compute Engine VMs.

Frontend repository​

Repository: CATALOG-Historic-Records/orphaned-wells-ui

NameRequired forNotes
DEPLOYMENT_SERVICE_KEY_JSONApp Engine deploymentGoogle 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_CLIENTIDFrontend buildGoogle OAuth client ID written to REACT_APP_GOOGLE_CLIENTID.
BACKEND_URLFrontend buildRecommended. Backend URL configured per environment in GitHub Environments (staging, isgs, newts, osage, rrc). Written to REACT_APP_BACKEND_URL.
DEV_BACKEND_URLStaging frontend deploymentLegacy/fallback backend URL used when BACKEND_URL is not set in the staging environment.
<COLLABORATOR>_BACKEND_URLCollaborator frontend deploymentsLegacy 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:

NamePurpose
ENABLE_APP_ENGINE_DEPLOYMENTSControls 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:

  1. Open the target repository on GitHub.
  2. Go to Settings > Secrets and variables > Actions.
  3. Select the secret or variable to create or update.
  4. Save the new value.
  5. Re-run the affected deployment workflow.