Providers Overview¶

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

The runtime core owns exactly four things — authentication, configuration, policy and dispatch. It holds no per-operation knowledge of any platform.

Registered providers¶

Provider	Auth provider	Operations	Page
`github`	`github`	19 across REST, GraphQL and the `gh` CLI	github
`files`	none	5, all File Engine	files

runtime 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. The runtime never branches on it; it only maps the transport to an engine and records it in the audit log.

runtime github repo list       # REST
runtime github repo summary    # GraphQL — one round trip replaces four REST calls
runtime github pr list         # the gh CLI — the better surface for that job

You wrote the same shape of command each time. Moving an operation from REST to GraphQL changes no runtime code, no policy, and no capability.

runtime github --help          # every operation, plus the transport chosen for it

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 five engines. You never select one directly; the transport determines it.

Engine	Responsibility
Auth	Multi-provider platform-native credential validation
REST	Generic REST pass-through — method, path, fields, headers and base URL all supplied by a provider
GraphQL	Generic GraphQL pass-through — query and variables supplied by a provider
Command	Wraps any binary in `allowed_binaries`, with per-binary subcommand policy
File	read / write / append / delete / list

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.

Governance¶

Provider operations are governed by the providers: block in policy-config.yaml:

providers:
  github:
    enabled: true
    denied:
      - api DELETE

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 cli transport, allowed_binaries and command_policy still apply on top.

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

runtime command run terraform plan
runtime command run kubectl get pods

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 github provider's api and graphql operations 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 on engineering-runtime 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.