GCP Keyless

Remove human Google OAuth from the steady-state agent path. Prefer short-lived, auditable identity: attached metadata identity inside GCP, or a typed GitHub Actions workflow authenticated through Workload Identity Federation (WIF).

Start with diagnosis

Run:

python3 scripts/doctor.py --repo OWNER/REPO --workflow gcp-keyless-observe.yml

Read its JSON and follow exactly one route:

• managed-metadata: run directly with the attached service account. Verify the reported email is the intended identity before accessing the project.
• github-dispatch: dispatch a reviewed, typed workflow. Local Google credentials are neither needed nor consulted.
• human-oauth-fallback: credentials currently work, but they are not the durable solution. Use them only for the one-time WIF bootstrap or an explicitly approved emergency.
• bootstrap-required: stop and follow references/bootstrap.md.

Non-negotiable controls

1. Never create, download, accept, or recommend a service-account JSON key.
2. Never print access tokens, OIDC tokens, authorization headers, or credential JSON. The official auth action may create an ephemeral WIF external-account file on its short-lived runner for gcloud; it is not a private key and must never be archived.
3. Never treat a working GitHub login as proof of GCP authority. It only authorizes dispatch; the WIF provider and service-account binding authorize GCP.
4. Never expose arbitrary command, script, or shell workflow inputs. Operations must be an explicit choice list mapped to reviewed commands.
5. Pin every third-party GitHub Action to a full commit SHA.
6. Restrict the WIF provider with immutable numeric repository_id and repository_owner_id claims plus a protected GitHub environment.
7. Use distinct least-privilege observer and launcher service accounts. Do not let a read-only workflow impersonate the launcher.
8. Before paid, mutating, or GPU work, use the project's configured budget and approval authority. Preserve durable identity or authority changes in its canonical audit record.
9. A workflow dispatch is an external action. Dispatch only when the user authorized that exact operation and scope.

Install the observer workflow

Copy assets/gcp-keyless-observe.yml to .github/workflows/gcp-keyless-observe.yml. Configure the repository/environment variables named in the template, then validate it:

python3 scripts/validate_workflow.py .github/workflows/gcp-keyless-observe.yml

The supplied workflow is intentionally read-only. Create mutation workflows separately, with a narrow typed operation set, protected environment approval, budget receipt, and project-specific launch grant. Do not turn the observer workflow into a generic executor.

Dispatch without Google OAuth

gh workflow run gcp-keyless-observe.yml \
  --repo OWNER/REPO \
  --ref BRANCH \
  -f operation=instances

Follow the run with gh run watch and download its normal logs or explicit receipts. Do not echo credentials for debugging. A denied WIF exchange is an identity-policy failure, not a reason to create a key.

Inside GCP

Use the VM, Cloud Run, or GKE workload's attached service account through the metadata server or Application Default Credentials. Do not run gcloud auth login on workers. Refuse startup if the observed service-account email differs from the expected identity.

One-time boundary

WIF cannot bootstrap itself. A project administrator must perform one authenticated, audited setup to create the pool/provider, service accounts, attribute condition, IAM bindings, and GitHub variables. After the verification in references/bootstrap.md, recurring local Google OAuth is no longer part of ordinary agent operation.