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:
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.