Skip to content

Authenticate Runtime

Goal: give the runtime the platform credentials it needs, using each platform's own login — the runtime never issues or stores credentials of its own.

Engineering Runtime never issues or stores credentials. It validates that a credential the platform's own tooling already manages is present and valid.

Authenticate using the platform. Govern using the runtime.

There is no runtime login that opens a browser, no credential store, no token file the runtime owns. If a session is missing or expired, the runtime tells you which platform command to run yourself.

Two provider shapes

REST providers

For services with an HTTP API. The token lives in an environment variable — never in config.yaml. The Auth Engine calls a known validation endpoint and treats HTTP 2xx as success.

Provider Environment variable Validation call
github RUNTIME_GITHUB_TOKEN GET <base_url>/user

CLI providers

For tools that manage their own credential store. The Auth Engine runs the tool's own auth check — the runtime handles no token at all.

Provider Binary Auth check
gcp gcloud gcloud auth print-access-token for validity, gcloud config get-value account for the subject
kubernetes — Reads the kubeconfig's current-context directly, no shell-out
openshift oc oc whoami

Current provider status

Provider Kind Status
GitHub REST Implemented
GCP CLI Implemented (ADC)
Kubernetes CLI Implemented
OpenShift CLI Implemented
AWS CLI Not yet implemented
Azure CLI Not yet implemented
OIDC (CI workload identity) — Not yet implemented

Binaries with no auth provider mapping — terraform, aws, az, vault, docker, pulumi and others — still run through command run. They simply manage their own credentials, which is a declaration, not a gap.

Enabling a provider

authentication:
  github:
    enabled: true
  gcp:
    enabled: true       # after `gcloud auth application-default login`

enabled: false means Runtime does not probe a credential, resolve an identity or run that provider's operations — it stops before any of it. Enforced since 0.6.0. Earlier releases applied the switch to auth status display only, so a provider you had turned off still ran its credential probe the moment an operation asked for one, which for the CLI-backed providers means a process and a token refresh.

It is a feature switch, not a sandbox

It governs Runtime provider operations. It does not stop you running the native CLI yourself through runtime command run — that path is governed by command policy and the local execution boundary instead, which are different controls with different rules. Turning a provider off is not a way to make its CLI unreachable.

See config.yaml.

What Runtime keeps

Nothing. Runtime holds a credential in memory for the length of one operation and writes it nowhere — not to the Runtime Home, not to a cache, not to the Control Plane.

What it records instead is a projection: which platform authenticated the operation, in full, and the account as a keyed digest. That answers "was this the same principal?" without putting an employee's login in a file that gets copied to a collector. You will see it in an audit record as auth_provider and identity_digest.

Credential values never appear in output, errors, logs or audit records. Where one has to be shown at all — auth status — it is fingerprinted (ghp_...789a), which is enough to tell two tokens apart and not enough to use either.

The lifecycle: login → execute → logout

runtime auth status                  # unaudited health check across every enabled provider
runtime auth login <provider>        # validate one provider explicitly; audited
runtime auth logout <provider>       # revoke where possible; audited

auth status is a diagnostic, not a prerequisite. There is no pre-flight auth check anywhere in the execution path — each execution validates the provider its operation needs, inline. Nothing is cached between commands, and no session is established.

Full command reference: runtime auth.

How a provider is chosen

Dispatch is resolved two different ways, and the distinction matters.

Runtime Providers declare their Auth Engine provider once, for every operation they expose:

Runtime Provider Auth provider
github github
files none — never touches a network or a credential

This applies whatever transport the provider picks. A CLI-backed GitHub operation authenticates as github exactly like a REST-backed one — and the Command Engine forwards the validated token to provider-chosen gh operations. For the direct gh.repo.list mode it can instead delegate to an existing native gh session. Runtime never initiates gh auth login itself.

Command Engine binaries invoked directly through runtime command run declare their provider in config.yaml's command_providers map:

command_providers:
  gcloud: gcp
  kubectl: kubernetes
  oc: openshift
  # terraform intentionally has no entry — it manages its own credentials

An unmapped binary skips the Auth Engine entirely. There is no silent fallback to a default provider: omission is treated as a "doesn't need auth" declaration.

Two senses of the word provider

An Auth Engine provider is a credential source (github, gcp, kubernetes, openshift). A Runtime Provider is an operation surface (github, files). A Runtime Provider names the Auth Engine provider it uses. See Providers.

Policy runs before authentication

The execution lifecycle evaluates policy before authentication, deliberately. A policy-denied operation is rejected and audited without ever spending a credential-validation round trip against the platform — and nothing is lost by it, since an audit record carries the OS user as executor, not a platform identity.

Diagnosing

runtime config validate

Reports every provider's enabled state, whether its CLI binary is installed, and its live auth status:

Auth Providers:
  PROVIDER    ENABLED  BINARY   INSTALLED  AUTH STATUS
  github      yes      -        -          ✓ subject=your-login
  gcp         yes      gcloud   yes        ✗ no ADC — run: gcloud auth application-default login
  kubernetes  no       -        -          -
  openshift   no       oc       no         -

Per-provider setup

Next

Connect GitHub

Operational examples on this site were verified against Runtime 0.9.8. After bootstrap, the version-exact files in Runtime Home win.