Skip to content

Governed authority — v0.12.0

This page describes v0.12.0, released October 15, 2026. The installed specs/auth-contract.md in your Runtime Home is the exact contract for your binary.

ENGRT resolves authority independently of the caller, applies it through admitted execution paths, verifies identity when the provider can prove it, and reports source, execution context and proof without returning credentials to the caller.

Who possesses authority

The invoking agent calls ENGRT operations. ENGRT resolves the selected source. A provider-owned transport can receive narrowly brokered authority, including GH_TOKEN in a prepared GitHub CLI subprocess. Runtime does not return that token to the agent. This is not a promise that no subprocess ever sees a credential.

Raw engrt command run gh and binary: gh capability steps use independently configured native gh authority. Their admitted mode remains repo list. They no longer receive an ENGRT token bridge: this is an intentional compatibility change. Use provider: github for work authorized through ENGRT. Native gh login/logout and ENGRT session login/logout have independent lifecycles.

Known limitation (v0.12.0)

Raw engrt command run gh cannot use a GitHub Actions job token (GH_TOKEN=${{ github.token }}); it refuses with auth_probe_failed. In Actions, use the curated engrt github … operations with the github_actions source, or give native gh a user token or login. Tracked for a later release.

Source selection

GitHub source Input and boundary
env Configured token_env (default ENGRT_GITHUB_TOKEN); caller environment exposure
file Exactly one derived <token_env>_FILE scalar file or ENGRT_GITHUB_CREDENTIALS_FILE JSON file
github_actions Explicit selection of GITHUB_TOKEN in observed CI; no automatic selection
github_app Positive app_id, installation_id, and exactly one private-key file or base64 input
os_secure_store Host-bound ENGRT session, eligible local use only; no plaintext fallback

An explicit source wins. Without one, exactly one present token, token-file or JSON-file input wins; duplicate inputs refuse. With none present, ENGRT looks for its own OS-store session. Failure does not silently select another source.

Credential JSON contains exactly string fields host and token. The host must match the configured GitHub host. Duplicate/unknown fields, invalid values and oversized files refuse. Scalar files trim one final LF or CRLF only. Projected Kubernetes Secret files are supported, but readability by the caller must be reported honestly. File inputs do not constitute a generic secret-manager API.

App private keys use ENGRT_GITHUB_APP_PRIVATE_KEY_FILE or ENGRT_GITHUB_APP_PRIVATE_KEY_B64 (strict base64 of unencrypted RSA PEM). Runtime creates a bounded JWT and transient installation token. The key is not stored in configuration or emitted in status. App sources do not fall back to a user session when repository scope is insufficient.

GitHub configuration lives under authentication.github: source, mechanism, app_id, installation_id, oauth_client_id, and optional absolute ca_bundle. On github.com, engrt auth login github uses the ENGRT-owned device-flow client built into the binary, so no OAuth setup is needed; set oauth_client_id only to override it. A GitHub Enterprise Server or *.ghe.com host has no default: register an OAuth App on that host and set its client ID, otherwise login refuses before sending any request. The built-in client is never sent to another host. The CA bundle extends system trust; it cannot disable TLS verification. Existing base_url and token_env remain. These selectors are local configuration in this release; they do not introduce new centrally managed enrollment authority.

GitHub App identifiers are declared as strings; quote them as the shipped config template does:

authentication:
  github:
    source: github_app
    app_id: "123456"
    installation_id: "78901234"

An invalid authentication.github.base_url (not https — literal loopback/localhost http:// is accepted only for local test fixtures — or carrying credentials, a query or a fragment) is refused before any request with auth_invalid_request, and the message names that setting. A token containing whitespace or control characters is refused before any request. With source: file and neither ENGRT_GITHUB_TOKEN_FILE nor ENGRT_GITHUB_CREDENTIALS_FILE set, Runtime reports auth_invalid_credential (a missing credential); setting both is auth_source_ambiguous. A GitHub App installation or Actions job token that GitHub rejects (401) reports auth_invalid_credential, as a rejected user token does; Runtime does not retry with another source.

engrt auth status --output json (and auth login) shows the resolved GitHub host. Runtime's own identity fields in results, MCP output and the audit record carry only execution_context.identities[].host_class: github.com, or custom for a GitHub Enterprise Server or *.ghe.com host. This does not hide the hostname everywhere: provider data that Runtime returns (for example a repository's html_url) still contains it.

Other places where the hostname can appear:

  • Network traffic: DNS lookups, TLS connections and HTTP requests to the configured host reveal it to the network and to that host.
  • Untested paths: engrt config validate, TLS and certificate error messages, and native tool error text have not been verified to omit it.
  • Your own files: the host is in your configuration (base_url) and in any output you choose to keep.

The audit record also stores keyed digests of the verified subject (identity_digest), the host (host_digest) and, for installation tokens, the repository scope (credential_scope_digest). Each record that carries one of them also names the privacy key it used in identity_key_id. That is a fingerprint of the key, which stays in your Runtime Home and is never shown. Compare two digests only when their identity_key_id values match: then equal digests mean the same subject, host or scope. Records from different Runtime Homes, or with different key IDs, cannot be compared. A CI job or Pod that starts with a fresh Runtime Home creates a new key each run. Records written by earlier releases have digests but no identity_key_id; they remain readable, but their key cannot be proven, so do not compare them. The host digest uses the lowercased hostname, keeping an explicit port as host:port, and maps api.github.com to github.com. github.com. (trailing dot) and non-ASCII hostnames are not normalized further and count as custom hosts.

Choosing a source

Step-by-step GitHub setup for each deployment surface

See GitHub authentication setup — local, Actions CI and GKE for recommended source priority, GitHub App registration, OAuth, PAT files, per-surface config and example commands. Its GKE material is not qualified in v0.12.0.

ENGRT never ranks sources for you: it uses the one you select (or the single input present) and refuses ambiguity. These are recommendations for operators.

Where ENGRT runs Recommended Fallback Last resort
Your machine (a person) engrt auth login github explicit github_app file, then env
GitHub Actions github_actions (GITHUB_TOKEN) github_app if the job token's scope is too narrow file, env
Kubernetes / GKE short-lived installation token delivered as a file by your secret broker github_app with a protected key file static token file, then env

A short-lived token the broker mints and rotates keeps the long-lived App key out of the pod. In Actions, a job token that is too narrow returns auth_scope_insufficient with recommended_source=github_app; ENGRT does not retry under another identity. This table is an operator recommendation, not a qualification statement: Kubernetes/GKE is not qualified in v0.12.0, and other surfaces (devcontainers, cloud IDEs, self-hosted runners, serverless) are not qualified either. The per-source qualification status of v0.12.0 is in the setup guide.

Credentials in env or file sources are readable by anything that can read that environment or file, including an agent sharing the process or pod. ENGRT's guarantee is narrower: on its own execution path, callers receive results and evidence, not the credential. It is not isolation from a same-user shell.

Honest identity and scope

User credentials require /user proof. Installation credentials use bounded installation-repository scope proof and cannot invoke user-only operations. An App exchange can establish the selected installation identity. A token alone does not justify inventing an installation subject from repository names. Repository-scope policy is separate from user-principal allowlists.

GCP retains explicit native, credential_file and gke_metadata sources. Runtime asks the fixed provider proof endpoint about the acquired token; a usable stable subject can establish verified identity. Otherwise it reports credential readiness. Account labels, service-account configuration and project output are not substitutes. Readiness cannot satisfy a policy requiring a verified principal. Actual token-class characterization remains a release qualification prerequisite.

Each capability step re-resolves authority. A verified principal mismatch stops later dispatch and retains earlier completed steps and their audit records. Identity verification never guarantees resource permission.

For an ENGRT OAuth session, engrt auth status (and --output json, as granted_scopes) lists the scopes GitHub reported for the token. These are the granted scopes, which can be fewer than the requested read:user repo offline_access; they are never the token. The default scopes do not include workflow, so adding or updating files under .github/workflows/ through an OAuth session is refused. GitHub reports that refusal as a plain 404 without naming the missing scope, so ENGRT cannot label it auth_scope_insufficient; use a GitHub App or a token with workflow-file permission for those capabilities. ENGRT does not guess a missing scope when GitHub gives no evidence of one.

GitHub's GraphQL API reports a credential that lacks a permission as HTTP 200 with an error. ENGRT classifies that as auth_scope_insufficient, the same code the REST API produces, only when every error entry has the type FORBIDDEN and exactly one of GitHub's two documented messages ("Resource not accessible by integration" or "... by personal access token") and the response repeats no key. Any other GraphQL error, a mix of errors, a near-miss message or an ambiguous body stays graphql_errors. The classification never changes whether the operation may have taken effect: the effect stays unknown.

Session lifecycle and prompts

Only explicit eligible local terminal engrt auth login github can start device login. It uses the ENGRT-owned OAuth client (built in for github.com, or the configured oauth_client_id) and requires user confirmation. Status, ordinary execution, MCP, CI and pods never start login. Headless explicit login can resolve existing authority but cannot prompt. Expiry and refresh use a host-specific cross-process lease; logout removes only ENGRT's store entry and is not provider-side token revocation. Externally supplied credentials remain owned by their source.

Storage uses macOS Keychain, Windows Credential Manager or Linux Secret Service. Unavailable or locked stores refuse. Same-user read isolation depends on the OS store's actual behavior; an ENGRT namespace does not by itself make a credential non-exportable. Observed in v0.12.0 qualification: Linux Secret Service and Windows Credential Manager entries were readable by another same-user process (same_user_readable); macOS Keychain entries were caller_isolated on the tested runners. This is a per-platform observation, not a universal isolation guarantee. Exposure labels distinguish environment, readable file and Runtime surfaces from isolation that has actually been characterized.

macOS upgrades. The keychain ties an ENGRT session to the binary that created it, and released engrt binaries are ad-hoc signed. After an upgrade or rebuild, the new binary cannot read, replace or remove the old session: auth status, auth login github and auth logout github report auth_store_unavailable and say the session was created by another build. ENGRT cannot remove an entry it may not access. Remove it outside ENGRT with security delete-generic-password -s engineering-runtime.github.v1, then run engrt auth login github again. This is a known limitation of this release; a stable signing identity for macOS releases is planned separately.

Explicit local GCP login can offer a confirmed gcloud auth login handoff when native credentials are missing. Normal probes stay noninteractive. An optional absolute authentication.gcp.python pins an admitted interpreter for recognized SDK launchers; Runtime ignores ambient CLOUDSDK_PYTHON and checks compatibility.

Context and diagnostics

execution.surface or ENGRT_EXECUTION_SURFACE can declare local, ci or kubernetes. Observation can restrict source/prompt eligibility, but neither markers nor declaration select credentials or establish identity. Missing selection remains undeclared. Portable sources may report a harmless observation mismatch without gaining authority.

execution_context carries safe caller labels, declared and observed surfaces, source, proof, principal class, parity and exposure through direct, capability, MCP and audit paths. ENGRT_CONSUMER=ai with a self-chosen ENGRT_ACTOR_NAME (for example, your agent harness's name) identifies the caller as self-asserted metadata, never verified identity. No credential, token fingerprint or raw subject is included in this safe envelope.

config validate separates executable presence, semantic mode admission, policy, interpreter readiness and auth status. Capability validation warns about literal unsupported native modes. Neither an allowlisted binary nor successful grammar validation grants execution authority.

Release proof

Deterministic source builds and controlled fixtures establish implementation behavior. Release qualification uses a frozen source, pinned corpus and identical candidate bytes per native target across six OS/architecture lanes and actual local and GitHub Actions execution. Live GKE execution is excluded from v0.12.0 qualification and remains NOT_EXECUTED; the Kubernetes guidance on this page is unqualified. OS stores, OAuth scopes/client registration and GCP token classes need retained observations. Cloud Run cannot replace GKE pod proof. No fixture, cross-compile or documentation build closes those live gates.

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