This repository contains Terraform infrastructure configuration for the GBFS Validator service, intended for internal use at MobilityData.
Access to any MobilityData-managed Google Cloud environment is restricted unless explicitly authorized.

Deployments are fully automated via GitHub Actions. There is nothing to build or compile manually — the CI pipeline handles everything.

Note: dev and qa share the same GCP project (gbfs-validator-staging). Each environment gets its own Cloud Run service, Artifact Registry path, runtime service account, and Terraform state. prod lives in a separate dedicated project.

The staging and prod workflows can be triggered manually from the GitHub Actions UI.

Staging (gbfs-validator-staging.yml):

• target_environment — choose dev (default) or qa
• app_version — optional. The version of gbfs-validator-java to deploy (e.g. 2.0.68). Can also be a snapshot version (e.g. 2.0.69-SNAPSHOT). Leave empty to deploy the latest release from Maven Central.

Prod (gbfs-validator-prod.yml):

• app_version — optional, same as above.

Both workflows call the shared reusable deployer (gbfs-validator-deployer.yml) which:

1. Authenticates to GCP using the deployer service account JSON key
2. Builds and pushes a Docker image to Artifact Registry
3. Runs terraform apply to deploy or update the Cloud Run service

Each environment's state is stored under its own prefix in a shared bucket:

• Staging: mobilitydata-gbfs-validator-state-staging/{env}/terraform/state
• Prod: mobilitydata-gbfs-validator-state-prod/prod/terraform/state

This means terraform apply for one environment cannot affect another.

"All roads lead to Rome!"
There are many paths to reach the same destination. Use the following steps as a guideline and adapt them to your local or organizational requirements.

For more information, refer to the Google Cloud Platform documentation and the Terraform documentation.

These instructions apply when creating a new environment.
dev and qa already exist in gbfs-validator-staging. These steps apply when setting up prod (project gbfs-validator-prod) or any future environment.
For illustration purposes, the examples below use gbfs-validator-staging as the project and dev as the environment — substitute accordingly.

gcloud projects create gbfs-validator-staging --name="GBFS Validator Staging"

Link your billing account to the new project via GCP Console or CLI.

Create a Firebase project and link it to the GCP project.

Create OAuth client credentials via the APIs & Services > Credentials page.
These credentials will be passed as Terraform variables.

Google-managed SSL certificates are created automatically by scripts/setup-environment.sh (step 11 below).
They provision once the DNS A/AAAA records are in place and the load balancer is deployed.

Enable Identity Platform in the project and configure authentication providers as needed.

gcloud auth application-default login

gcloud config set project gbfs-validator-staging

gcloud storage buckets create gs://mobilitydata-gbfs-validator-state-staging \
  --project=gbfs-validator-staging \
  --location=northamerica-northeast1 \
  --uniform-bucket-level-access

Copy infra/backend.conf.rename_me to infra/backend.conf and populate it.
BUCKET_NAME is the full GCS bucket name (e.g. mobilitydata-gbfs-validator-state-staging).
ENVIRONMENT is the environment name (e.g. dev, qa) — it becomes the state prefix to isolate each environment's state within the shared bucket.

# Staging (dev or qa):
scripts/setup-environment.sh gbfs-validator-staging dev

# Prod (uses a separate AR repo):
scripts/setup-environment.sh gbfs-validator-prod prod northamerica-northeast1 gbfs-validator

This script:

• Creates the deployer service account and grants IAM roles
• Enables required Google APIs
• Creates (or verifies) the shared Artifact Registry repository
• Creates global static IPv4 and IPv6 addresses for the load balancer ({env}-lb-ipv4, {env}-lb-ipv6)
• Creates a Google-managed SSL certificate for {env}.gbfs.api.mobilitydatabase.org

At the end it prints the IP addresses you will need for DNS.

After running the setup script, ask your DNS administrator (Cloudflare) to create:

Note: DNS proxy must be disabled (grey cloud in Cloudflare) to allow Google-managed cert provisioning.
The SSL certificate will complete provisioning automatically once DNS resolves to the load balancer IP.

gcloud iam service-accounts keys create deployer-key.json \
  --iam-account=gbfs-deployer-service-account@gbfs-validator-staging.iam.gserviceaccount.com \
  --project=gbfs-validator-staging

Store the contents of deployer-key.json as the GitHub secret DEV_GCP_GBFS_VALIDATOR_SA_KEY. Delete the local file after.

Copy infra/vars.tfvars.rename_me to infra/vars.tfvars and populate it for local runs.
In CI, this is done automatically by scripts/replace-variables.sh.

cd infra
terraform init -backend-config=backend.conf

scripts/docker-build-validator.sh --push -version dev-$(($(date +%s)/60))

cd infra
terraform apply -var-file=vars.tfvars

Happy coding!

1. Locate the service list in the scripts/setup-environment.sh script
2. Execute the script:

scripts/setup-environment.sh gbfs-validator-staging dev