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:
- Download and verify the new archive
- Replace
engrtonPATH - Run any command (Bootstrap refreshes
specs/andcommands/) - 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:
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:
- Read its page under Providers
- Enable auth if required (Authentication)
- Adjust policy only if you need denies from day one
- Prefer new provider operations over equivalent
command runcalls
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.