Skip to content

Migration Guides

Engineering Runtime upgrades are binary replacements. There is no database migration and no daemon. Most "migrations" are about policy and capabilities staying compatible with a new surface.

Renamed to engrt in v0.10.0

v0.10.0 renames the binary to engrt, the Runtime Home to ~/.engrt, release archives to engrt-<version>-<os>-<arch>, and every Runtime-owned variable to ENGRT_* (RUNTIME_RUNTIME_NAME and RUNTIME_RUNTIME_LOG_LEVEL become ENGRT_NAME and ENGRT_LOG_LEVEL). Old names are ignored, not aliased, and ~/.engineering-runtime is not read by default. Capabilities need no change: the ```runtime block and version: v1 are unchanged.

Update scripts, shell profiles and CI in the same change as the binary, and copy ~/.engineering-runtime to ~/.engrt if you want to keep its audit history (pointing ENGRT_HOME at it instead upgrades it in place, with no rollback copy). See Upgrading.

Preparing capabilities for v0.9.9

Validate your complete source set against v0.9.9 before upgrading. The hardening keeps version: v1 but intentionally rejects extra/unclosed runtime blocks, trailing YAML documents, anchors/aliases, scalar coercion and malformed or undeclared references. Quote numeric argv values such as "-5".

Inserted input values are now opaque, not recursively substituted. Omitted optional values become empty strings, unknown supplied keys refuse, and $$ escapes a literal dollar. Change authored downstream ${NAME} or Actions ${{ github.ref }} expressions to $${NAME} / $${{ github.ref }} when they must survive into generated content. Such escaped templates require the new v0.9.9; an older binary will not remove the extra dollar. Do not mass-rewrite supplied values: only authored template text uses this escape syntax.

Matched-policy diagnostic wording also changes: it reports the rule family and one-based index, not raw arguments or rule values. Policy matching is unchanged. Do not parse the previous free-text reason as a machine contract.

The maintained corpus required two quoted -5 arguments and downstream-template escapes in platform/platform-service-bootstrap.md. Its validation fixture is not execution policy, and corpus validation does not prove live workflows. See admission limits and failed-step output compatibility.

Upgrading the binary

Terraform output safety in v0.9.9

The v0.9.9 compiled secret-export-operation floor refuses JSON/raw/named Terraform output, state pull, state show, and actual show rendering, with or without a path. Human and JSON rendering, including show -json=false and show -json=0, can expose secret-bearing infrastructure values even when individual values are not marked sensitive. Reviewed flag-order, global-option and empty-leading forms cannot bypass the floor; unknown/invalid output options fail closed. Help-only forms remain eligible where intentionally recognized. Runtime does not read state to exempt individual values.

Unnamed non-JSON output, state list, plan, apply, init, validate, fmt and providers still face normal admission and policy gates. This does not block all Terraform or provide universal secret detection. The exact grammar belongs to the compiled classifier and the binary's Terraform command contract.

Previously executable state/output rendering forms may now be refused. Treat this as intentional security tightening; permissive policy cannot override it. Review affected capabilities before upgrading.

Output compatibility in v0.9.9

cli is the default bounded human presentation; text remains its deprecated alias. json is the complete admitted sanitized canonical machine/agent result. Deprecated raw remains restricted to sanitized single-operation payloads, never untouched provider bytes. Human previews and presentation metadata do not change JSON. Explicit null is distinct from no content; opaque text does not become JSON merely because it starts with a brace or bracket.

A failure can mean execution succeeded but required evidence failed. Completed effects are not rolled back; reconcile the target and journal before retrying a side-effecting operation.

GCP project selection and Artifact Registry JSON in v0.9.9

For gcloud projects describe PROJECT, use the same ID or number in an optional --project flag. Conflicting values now refuse before probes; a missing flag is filled from the operand rather than the native default project. Policy evaluates that final argv. No ID-to-number lookup or stronger binding is implied; see target selection.

Artifact Registry invocations with --repository/--package and exact --format=json now return parsed data instead of text. Consumers must accept typed JSON and invalid_json_output on empty/malformed native output. The native argv and admission rules are otherwise unchanged. This does not certify GCP federation, GKE or fully qualified resource-name precedence across SDK versions.

Runtime v0.9.9's thirteen existing gcloud capabilities now also require a project input; pass it explicitly instead of relying on the native default. Every step requests --format=json, so successful step data is typed JSON, not display text. The footprint workflow explicitly uses --location=all to avoid a narrower native Artifact Registry location default. The new one-step project-read proof requires a project ID for exact response comparison; these descriptions do not add a new capability input-validation grammar. See the GCP corpus authoring contract. Existing projects list remains caller-wide, even with --project; it is not a replacement for that selected-project proof. Docker's workflow is unchanged.

Replace and verify

Follow Upgrading:

  1. Download and verify the new archive
  2. Replace engrt on PATH
  3. Run any command (Bootstrap refreshes specs/ and commands/)
  4. Run engrt config validate

What survives

Your config.yaml, policy-config.yaml, and existing capabilities are never overwritten.

What refreshes

specs/ and commands/ are rewritten to match the new binary. Do not store your own files there.

The upgrade trap: stale policy

New allowed_binaries / deny rules ship in the compiled default. Existing installs that explicitly select an older policy keep using that document.

Symptom: engrt command run helm … denied even though the release notes say helm is allowed.

Fix: Compare the effective policy to this binary's compiled default, then merge only the new binaries/rules you want:

engrt config validate
engrt config diff policy

Details: Upgrading — the upgrade trap.

Moving capabilities to a shared directory

From a legacy Home-local capability directory to an explicit team source:

# before
engrt capability execute my-cap

# after copying the files into /path/to/team-capabilities, add that directory
# to capabilities.sources in the selected external config
engrt capability execute my-cap

See Sharing a Capability Directory.

CI: pinning vs latest

Approach When
Empty version (or omit it) Default — tracks the latest release
a pinned version: on setup-runtime Reproducible production pipelines — bump deliberately

After pinning a newer version, use a fresh ENGRT_HOME so the job starts with only that release's contracts and empty working-state paths.

Provider surface changes

v0.9.9 HTTP compatibility corrections

Runtime v0.9.9 refuses redirects, bounds decoded response bytes and requires valid JSON except explicit no-content responses. Returned credential fields are redacted; GraphQL partial data is retained alongside a failure. Automation should inspect structured status/error codes rather than human text, and must not retry a timed-out mutation without reconciling its target. Review the HTTP contract before upgrading callers that depend on permissive response handling. No config, policy or capability schema migration is part of this HTTP change.

v0.9.9 authentication compatibility corrections

Auth JSON adds proof/source/class fields and preserves stable auth_* error categories. Treat only principal_verified as a verified identity. Native gh and gcloud readiness have no subject; Kubernetes context labels are no longer reported as principals. Identity allow-lists that relied on those labels now refuse and must not be bypassed by removing safety controls.

Use native gcloud auth login for the CLI credential path, not ADC login. Explicit Runtime logout targets one stored CLI account, never ADC, and refuses active native credential overrides/impersonation. Brokered GitHub installation, job, refresh and JWT credentials get explicit unsupported-class diagnostics; use the documented credential contract.

auth status and auth checks inside config validate now require writable, valid durable evidence. They may also refresh native caches. They are diagnostics, not effect-free reads. Direct gsutil/bq cannot use an unrelated default gcloud proof and remain unsupported without an invocation-bound contract. No config/policy schema or capability grammar migration is introduced here.

Operation compatibility

Providers ship compiled into the binary. A new operation arrives only by installing a new runtime version. Capabilities that named a removed or renamed operation fail at capability validate — fix the capability, do not bypass with raw CLIs.

When a new Runtime Provider appears in a release:

  1. Read its page under Providers
  2. Enable auth if required (Authentication)
  3. Adjust policy only if you need denies from day one
  4. Prefer new provider operations over equivalent command run calls

From ad-hoc scripts to capabilities

Before After
Shell script calling gh / kubectl Markdown capability with provider: / binary: steps
Credentials in the script Platform login + engrt auth / env tokens
No audit engrt audit tail after execute

Authoring: Capabilities.

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