Configure Providers¶
Goal: understand which providers this binary exposes and how to govern their operations.
A Runtime Provider owns one platform's operation surface and decides, per operation, how to reach it.
Runtime (auth, config, policy, dispatch)
│
▼
GitHub Provider repo list / pr list / workflow run / issue create
│
│ decides internally, per operation
▼
gh CLI OR REST API OR GraphQL
Runtime owns authentication, configuration, policy and dispatch. It also owns the reviewed native semantics and transport checks a provider cannot override.
Registered providers¶
| Provider | Auth provider | Operations | Page |
|---|---|---|---|
github |
github |
20 across REST, GraphQL and the gh CLI |
github |
files |
none | 5 direct file operations plus 21 typed structured edits, all File Engine | files |
gcp (v0.9.9) |
gcp |
One project describe <project-id> REST read, fixed Resource Manager origin |
native auth and REST binding |
Counts above verified against engrt config validate on the release this site documents
(github 20 = 10 rest + 2 graphql + 8 cli; files 5 file). Your binary is
authoritative if they disagree:
engrt config validate # lists each provider, its auth provider, and its
# operation count broken down by transport
You never choose the transport¶
A provider picks a transport per operation — rest, graphql, cli or
file. Runtime validates the selected transport's contract, applies its safety
and governance checks, dispatches to the engine and records the result.
engrt github repo list # REST
engrt github repo summary cli/cli # GraphQL summary
engrt github pr list --repo cli/cli # curated gh CLI operation
You wrote the same shape of command each time. A transport change must preserve the operation's authorization and result contracts; the name alone does not guarantee compatibility.
The transport column is shown for transparency. It is information, not a choice — nothing you write should depend on it. A capability that depends on "the REST one" breaks when the provider changes its mind.
Runtime Engines¶
Execution is performed by four engines. You never select one directly; the transport determines it.
| Engine | Responsibility |
|---|---|
| REST | Generic REST pass-through — method, path, fields, headers and endpoint all supplied by a provider |
| GraphQL | Generic GraphQL pass-through — query, variables and endpoint supplied by a provider |
| Command | Runs one pinned binary from allowed_binaries, with per-binary subcommand policy, in an environment Runtime builds |
| File | read / write / append / delete / list, inside a granted root only |
Authentication is a service, not a fifth engine. Runtime validates your
platform-native credential (GitHub token, the admitted gcloud source (not ADC), kubeconfig, oc session)
before the engine runs. It executes no operation and nothing dispatches to it,
which is why the transport= in your audit log is always one of the four
above.
The REST and GraphQL Engines are genuinely generic: they carry no default host and refuse an unrooted path or any URL that would change host. A missing base URL is an error, not a silent redirect. The endpoint arrives on the provider's own invocation, so one provider can never send its requests — or its bearer token — to another provider's host.
Extensibility, stated honestly. Providers are compiled into the binary.
Registering a provider requires a package/import and a new release. A new native
tool or identity mode may also need reviewed auth, context and tool contracts.
There is no plugin ABI, and Runtime will not load a third-party provider at
runtime. engrt <provider> --help lists what your installed release has.
Runtime v0.9.9 installs
<Runtime Home>/specs/provider-conformance.md: the engine/entrypoint support
table and contributor checklist for transport validation, auth proof, prepared
targets/artifacts, results/evidence, and direct/capability plus local/enterprise
tests. The small test-only provider is an integration example, not an additional
production provider. Its synthetic tests do not certify live GCP CI or GKE auth.
Governance¶
Provider operations are governed by the providers: block in
policy-config.yaml:
- A provider with no entry is fully allowed. Operations are discovered from the provider, so nothing has to be listed before it can run.
- Rules are evaluated on the operation, never the transport — a denial cannot be sidestepped by a provider changing how it reaches the platform.
- When a provider picks the
clitransport,allowed_binariesandcommand_policystill apply on top.
For v0.9.9, both provider-operation and CLI binary/argument policy complete before authentication. A CLI policy denial does not probe credentials, and its audit policy decision is a denial. Runtime also prepares the CLI artifact/environment before auth and reuses them at dispatch; replacement of the prepared executable is refused before launch. Direct commands and provider CLI now share target/floor preparation; capability plans reuse it without probes. Gcloud/Kubernetes stay selector-bound, so native mutations remain refused. Curated GitHub repository modes have a separate finite explicit-target contract, not blanket raw-gh admission. Maintained examples and onboarding guidance now state these targets. Synthetic lifecycle tests cover four engines under local and signed-generation policy, prepared native authentication, and actual sticky enrollment operating offline. They distinguish kubeconfig/credential readiness from verified principals. Compiled-floor refusals persist a denied coarse journal decision even when the document permits the command. Installed-tool/cloud/CI/GKE proof and final release gates are separate; synthetic coverage is not a release.
Authentication¶
Each provider declares its Auth Engine provider once, for every operation it
exposes, whatever transport it picks. A CLI-backed GitHub operation
authenticates as github exactly like a REST-backed one.
files declares none — its operations never touch a network or a credential,
so the Auth Engine is skipped entirely.
Two senses of provider
A Runtime Provider is an operation surface (github, files, and gcp). An
Auth Engine provider is a credential source (github, gcp,
kubernetes, openshift). A Runtime Provider names the Auth Engine
provider it uses.
When no provider covers a platform¶
Use the Command Engine escape hatch:
It is governed by allowed_binaries and command_policy, and every invocation
is audited — but it pins you to one tool's exact CLI, with no curated surface
above it.
What if your platform isn't listed?¶
Providers ship compiled into the binary, so a new operation only arrives by installing a new Runtime version. That is deliberate: the same binary always exposes the same surface, which is what makes execution reproducible.
You have three options today, in order of preference:
- Check whether an existing operation already covers it. The
githubprovider'sapiandgraphqloperations reach any endpoint on that platform, curated or not. - Use the Command Engine. Twenty-one CLI tools are permitted out of the box — Terraform, kubectl, Helm, the cloud CLIs and more. Governed and audited like everything else.
- Compose a capability. Operations sequenced into a reusable workflow, with no new runtime release required.
If none of those fit, a new provider is a genuine gap worth raising — open an Issue describing the platform and the operations you need.
When a new provider does ship, it arrives here with a full page of its own —
operations, transports, auth, governance and capability usage — the same shape
as github and files.
Next¶
Operational examples on this site were verified against Runtime 0.14.0. After bootstrap, the version-exact files in Runtime Home win.