Runtime Context¶

Runtime Context is the execution state — where an operation runs. It exists so that commands only have to express engineering intent (what).

Location: <Runtime Home>/context.yaml. Ownership: yours. Seeded once, never overwritten by an upgrade.

The seeded file¶

current: default

contexts:
  default:
    environment: development
    github:
      organization: ""
    cloud:
      project: ""
    kubernetes:
      context: ""
      namespace: ""

One named context, default, with everything blank. Fill it in or add more.

Fields¶

Field	Used by
`environment`	Recorded on audit records; yours to interpret
`github.organization`	Fallback org for `repo list`, `issue list`, `team list` and other org-scoped operations
`cloud.project`	Injected as `--project=` for `gcloud`
`kubernetes.context`	The kubeconfig context this Runtime Context expects
`kubernetes.namespace`	Injected as `-n <namespace>` for `kubectl` and `oc`

Viewing and switching¶

runtime context show
runtime context show --output json

Shows the active context's name, its full target, and every context name available to switch to.

runtime context use staging

<name> must already exist under contexts.<name>. There is no context create verb — context.yaml is hand-edited, the same way config.yaml and policy-config.yaml are. That is what keeps it reviewable in version control.

Adding a context¶

cat >> "${ENGINEERING_RUNTIME_HOME:-$HOME/.engineering-runtime}/context.yaml" <<'EOF'
  staging:
    environment: staging
    github:
      organization: acme-staging
    cloud:
      project: acme-staging-project
    kubernetes:
      context: staging-cluster
      namespace: staging
EOF

runtime context use staging
runtime context show

What switching changes¶

Switching context changes the fallback values operations resolve against — without touching any command's flags:

runtime context use staging
runtime github repo list        # now defaults to acme-staging's org

An explicit argument always wins:

runtime github repo list some-other-org    # context is not consulted

Switching context never re-authenticates

Auth Engine identity and Runtime Context are resolved independently in the execution lifecycle. Changing the context does not change who you are — if staging names a GitHub org your token cannot see, you get an authorization error from GitHub, not an auth failure from the runtime.

Context injection into binaries¶

For runtime command run, context injection is deliberately narrow:

Binary	Injected
`gcloud`	`--project=<cloud.project>`
`kubectl`	`-n <kubernetes.namespace>`
`oc`	`-n <kubernetes.namespace>`
everything else	nothing

Injection happens after policy evaluation, so an injected flag can never be used to bypass a subcommand denial. See Policy.

Nothing is injected when the corresponding context field is empty.

Using context in capabilities¶

A capability should declare an input rather than hardcode an org, project or namespace:

inputs:
  organization:
    description: GitHub organization to audit
    required: true

workflow:
  - provider: github
    args: [repo, list, "${organization}"]

But when an operation already falls back to the active Runtime Context, let it:

workflow:
  - provider: github
    args: [repo, list]     # uses github.organization from the active context

The rule of thumb: if a value is genuinely where you are, it belongs in context. If it is what this run is about, it belongs in inputs.

Context in CI¶

Pipelines usually write a context file rather than switching one:

env:
  ENGINEERING_RUNTIME_HOME: ${{ github.workspace }}/runtime-home

cat > "$ENGINEERING_RUNTIME_HOME/context.yaml" <<EOF
current: ci
contexts:
  ci:
    environment: ci
    github:
      organization: "${ORG}"
    cloud:
      project: ""
    kubernetes:
      context: ""
      namespace: ""
EOF

runtime context show

The shared setup-runtime action does this for you when you pass github_organization.

Checking without executing¶

runtime resolve context show
runtime resolve context use staging

runtime resolve confirms a command line resolves to something real, with zero side effects — no auth, no policy evaluation, no execution.