Manual Deployment¶
Infrastructure stacks that are deployed manually (not via CI/CD).
Global Terraform Stacks¶
Located in platform/terraform/global/. These stacks manage cross-cutting infrastructure that must exist before CI/CD can run or that require careful manual control.
| Stack | Purpose |
|---|---|
iam/ |
GitHub OIDC provider, CI/CD IAM roles |
github-runner/ |
Self-hosted GitHub Actions runner infrastructure |
dev-box/ |
Windows development workstation |
IAM Stack¶
GitHub OIDC authentication and IAM roles for CI/CD pipelines live in platform/terraform/global/iam. This stack is now applied by the bootstrap CLI, not by a manual terraform apply.
What it creates:
- GitHub OIDC identity provider
- IAM roles for GitHub Actions (
github-actions-shifter-dev,github-actions-shifter-prod) - Scoped IAM policies for infrastructure management
Deploy:
scripts/bootstrap/deploy.py bootstrap creates the S3 state backend (with native locking) and applies the global/iam stack (OIDC provider plus CI/CD roles) in one step:
# Dev environment
./scripts/bootstrap/deploy.py bootstrap --env dev --profile <dev account profile>
# Prod environment
./scripts/bootstrap/deploy.py bootstrap --env prod --profile <prod account profile>
After deployment:
Add the role ARN to GitHub repository secrets. Read it with terraform output -raw github_actions_role_arn in platform/terraform/global/iam:
AWS_ROLE_ARN_DEV- Output from the dev bootstrapAWS_ROLE_ARN- Output from the prod bootstrap
GitHub Runner Stack¶
Self-hosted GitHub Actions runners. The current architecture is the github-runner-network module plus a persistent aws_instance runner fleet in platform/terraform/global/github-runner, provisioned and registered by the bootstrap CLI. The older terraform-aws-github-runner Lambda and webhook module is no longer used.
What it creates:
- A dedicated, isolated runner VPC (
github-runner-networkmodule) - Persistent EC2 runner instances
- IAM roles and security groups
Prerequisite:
Run scripts/bootstrap/deploy.py bootstrap --env <env> first so the shared S3 state backend that the runner root reuses exists.
Deploy:
This provisions the runner network and instances, mints a single-use registration token per runner, registers each runner over SSM, and verifies each one online through the GitHub API.
Reference:
The authoritative runbook for standup, network isolation, health monitoring, removal, and gotchas is aws-runner-provisioning-runbook.md.
Dev Box Stack¶
Windows Server 2022 development workstation for remote development work.
What it creates:
- EC2 spot instance (Windows Server 2022)
- IAM role with S3, ECR, and Secrets Manager access
- Security group for RDP access
- Scheduled shutdown at 11 PM Pacific (cost control)
- Admin password in Secrets Manager
Deploy:
cd platform/terraform/global/dev-box
AWS_PROFILE=<dev account profile> terraform init
AWS_PROFILE=<dev account profile> terraform apply
Management:
Use the helper script from repo root:
./scripts/dev-box.sh status # Check instance status
./scripts/dev-box.sh start # Start the instance
./scripts/dev-box.sh stop # Stop (saves costs)
./scripts/dev-box.sh connect # Open Fleet Manager RDP
./scripts/dev-box.sh password # Get admin password
./scripts/dev-box.sh tunnel # Start SSM port forwarding for local RDP client
Pre-installed tools: Git, Python 3.12, Node.js LTS, AWS CLI, Terraform, VS Code, Chrome, Claude Code.
See platform/terraform/global/dev-box/README.md for full documentation.
Deployment Order¶
For a fresh environment:
- Bootstrap (IAM + state backend) - Must be first.
deploy.py bootstrapcreates the OIDC provider, CI/CD roles, and shared S3 state backend. - GitHub Runner - Optional. Only needed for self-hosted runners (
deploy.py runners). - Dev Box - Optional. Only needed for Windows development.
After bootstrap, CI/CD can manage all other infrastructure automatically.
GCP¶
GCP manual setup is separate from the AWS stacks above. A GCP deployment can run without GitHub (ADR-070). The GitHub-less GCP deployment guide gives the commands for each step:
- GCP project setup - Create the project and configure billing.
- Foundation - Run
scripts/bootstrap/deploy.py gcp-foundationin its GitHub-less mode. It creates the state bucket, the purpose identities, the release-evidence bucket, and the deployment config bucket. It grants the namedimpersonation_principalsthe right to impersonate the deploy, release-scan, and destroy identities. It creates no Workload Identity pool or provider. - Release access - The release registry is public. A deployment that
cannot reach it fills a mirror and passes
--release-source. - Initial secrets - Store the first operator password in Secret Manager.
Name that secret in
settings.operator_bootstrap.admin_password_secret_ref. - Deployment inputs - Write
bigrae.yamland the Terraform values. Leavegke_master_authorized_cidrs = []for Connect Gateway, or use connected RFC1918 networks only. Publish the inputs withgcp-config publish. - Range images - Import the guest images that the release selects with
gcp-images --store gs://<deployment config bucket>. - First install - Run
gcp-deploy --store gs://<deployment config bucket> --first-installfrom the deployer image of the release. - DNS - Point the public hostname at the reserved ingress IP if DNS is
managed outside Terraform, then run
gcp-deployagain without--first-install.
The deploy command expects and enforces:
- a managed-TLS public hostname from
deployment.domain - a private GKE control-plane endpoint that it reaches through Connect Gateway
- Cloud Armor on the public ingress backends
- Terraform-managed Identity Platform for corporate login, with browser-side Google auth and server-side verified-token exchange
- a first operator account that it seeds from
settings.operator_bootstrap - the ADR-037 release gates: the exact-digest scan, the provenance check, and the running-image check
scripts/bootstrap/deploy.py gdc-bootstrap builds only the legacy GDC VM
Runtime substrate for the gdc range backend.