The deploy path

GitHub Actions builds immutable image artifacts. A reviewed change to the IaC image pins makes them deployable; Terraform applies the selected roots in dependency order. Local fixes do not establish a successful production rollout.

For operators and contributors.

This section describes how the platform is built and released. Using the platform needs none of it.

Image promotion

The platform build and kagent runtime build both propose changes to iac/gcp/workloads/images.auto.tfvars. The platform build owns its tag/digest pair. The runtime build owns its tag/digest pair and the baked skills_package_commit. Digests identify the actual images; tags make the source revision readable.

The shared promotion helper fetches the current main branch and promotion branch, preserves unrelated pin edits, and uses an explicit expected-tip lease when pushing. Repeating a successful build reuses its branch and pull request, or returns a no-op if main already has the desired pins. Conflicts and lease failures stop promotion. The helper does not merge its own pull request.

Promotion uses a GitHub App installation token scoped to the target repository. This allows the resulting pull request to trigger its required checks. Missing App credentials fail the selected operation rather than silently omitting it.

Root selection and order

scripts/terraform-roots.json is the declarative root/path dependency graph. Selection includes consumers of changed producers: a gcp/platform change also selects github and gcp/workloads. The Substrate identity script selects workloads. Other CI/helper changes select the roots they may affect. Documentation-only changes still report required checks without applying infrastructure.

Root	Main responsibility	Dependency
`gcp/platform`	GCP APIs, identities, cluster, shared data services and network	First producer
`github`	Repository/Pages settings and Actions configuration	Platform outputs
`gcp/workloads`	Cluster services, controllers, observability, API and runtime configuration	Platform outputs and reachable cluster
`stripe`	Native collection configuration	Separate credentials and workflow treatment

Pull requests validate and plan selected roots. A consumer PR plan reads the currently applied producer outputs; a plan cannot simulate an unapplied producer’s remote state. On main, CI applies selected roots in producer-first order and checks platform drift. A failed producer stops downstream application. The operator reviews plans and required checks before merging a promotion.

Authentication

GCP access uses Workload Identity Federation. Image builds use the deployer identity; Terraform has its own identity. Trust is limited by repository and OIDC subject. The source includes subjects for pull-request plans, the production apply environment and main-branch manual plans. Manual plans are restricted to main. Actual subject formatting must match the repository’s configured GitHub OIDC subject policy.

GitHub App credentials, provider secret versions and initial identity/bootstrap prerequisites still need their documented setup. GCP federation does not eliminate Stripe, Alpaca or GitHub App secrets. A selected root missing required credentials fails rather than being reported as a successful skip.

Static sites and release evidence

web, admin and docs publish their own GitHub Pages artifacts from main. Their workflows run package checks/builds and use Pages deployment permissions. A source commit, an image build, an IaC merge and a successful rollout are distinct evidence. Record the relevant revision and outcome at each step; a local test or updated docs page cannot substitute for a deployed check.