CI/CD¶
v0.12.0 GitHub authentication — separate setup instructions
The examples below describe the previously released CI credential model.
For v0.12.0's explicitly selected github_actions, github_app,
protected token file, and env sources, including recommendation order,
job permissions, private-key custody and qualification limits, read the
GitHub CI/GKE setup guide.
Do not use these newer source keys with a v0.11.0 or earlier binary.
Engineering Runtime runs in pipelines on supported macOS/Linux hosts. Provision an installed, checksum-verified release binary, create a throwaway Runtime Home per job, authenticate, execute and retain evidence. v0.9.9 does not include Windows support.
GCP credential-file mode can use a native credential file provisioned by the CI platform's admitted WIF relationship. GitHub Actions is one environment; CI labels alone do not authenticate a workload. Do not upload credentials or raw auth output.
Job contract (minimum)¶
Every CI job should set:
env:
ENGRT_HOME: ${{ github.workspace }}/runtime-home
ENGRT_CONSUMER: ci
ENGRT_ACTOR_NAME: production-release
ENGRT_SESSION_ID: ${{ github.run_id }}
| Variable | Why |
|---|---|
ENGRT_HOME |
Per-job Home — never reuse a developer's ~/.engrt |
ENGRT_CONSUMER=ci |
Labels audit records as pipeline-driven |
ENGRT_ACTOR_NAME |
Self-asserted workload label for searching the audit trail |
ENGRT_SESSION_ID |
Maps the native pipeline run ID into Runtime correlation |
ENGRT_GITHUB_TOKEN |
Auth Engine/provider calls and explicitly authorized private source/target access |
Bootstrap creates no config, policy, context or capability definitions. Use the
compiled defaults unless the job selects an external document. Check out a
capability source at a tag or SHA and execute by full path, or declare it in
capabilities.sources for name resolution.
Provision the runner¶
Install the chosen release using Installation before the job starts, or use your organization's approved runner image. Pin and verify the version. For release access problems, contact the project.
Secrets and variables¶
| Kind | Name | Purpose |
|---|---|---|
| Secret | ENGRT_GITHUB_TOKEN |
Auth Engine/provider operations and explicitly selected private source checkout |
| Variable (optional) | GITHUB_ORG |
Explicit input for org-scoped operations; defaults to github.repository_owner |
Token scopes depend on the capabilities you run (org listing, secrets inventory, etc.). Scope the token only to the orgs/repos and operations those steps need.
Minimal workflow¶
name: Runtime smoke
on:
workflow_dispatch: {}
permissions:
contents: read
env:
ENGRT_HOME: ${{ github.workspace }}/runtime-home
ENGRT_CONSUMER: ci
ENGRT_ACTOR_NAME: runtime-ci-smoke
ENGRT_SESSION_ID: ${{ github.run_id }}
jobs:
smoke:
runs-on: [self-hosted, linux] # runner has the verified Runtime binary installed
steps:
- uses: actions/checkout@v4
- run: engrt version
- name: Checkout accessible capability source at a reviewed revision
uses: actions/checkout@v4
with:
repository: engineeringruntime/engineering-runtime-capabilities
token: ${{ secrets.ENGRT_GITHUB_TOKEN }}
ref: <reviewed-tag-or-sha>
path: engineering-runtime-capabilities
- run: engrt config validate
- run: |
engrt capability execute \
engineering-runtime-capabilities/capabilities/files/notes-roundtrip.md \
--input path=./notes.txt \
--input message="hello from CI"
- env:
ENGRT_GITHUB_TOKEN: ${{ secrets.ENGRT_GITHUB_TOKEN }}
run: |
engrt auth status
engrt github user get
- if: always()
run: engrt audit tail -n 50
Use the company capability source¶
Clone
engineering-runtime-capabilities
with repository read access at a reviewed tag or SHA. Authenticate Git with
that access before the illustrative clone below. The simplest CI path executes the exact checked-out
file:
- name: Clone capability registry
run: |
git clone \
https://github.com/engineeringruntime/engineering-runtime-capabilities.git \
capability-registry
git -C capability-registry checkout <reviewed-tag-or-sha>
- name: Validate / execute from registry
run: |
engrt capability validate \
capability-registry/capabilities/github/github-repo-health.md
engrt capability execute \
capability-registry/capabilities/github/github-repo-health.md \
--input repository=cli/cli
Reference workflow:
capabilities-from-registry.yaml.
Patterns from samples¶
| Workflow | Pattern |
|---|---|
runtime-ci.yaml |
Install → validate sample caps → auth-free + GitHub smoke → audit |
capabilities-from-registry.yaml |
Clone full registry → validate all → optional execute |
java-service-scaffold-and-ship.yaml |
Dispatch-only end-to-end demo (creates a fresh repo) |
github-*.yaml |
Scheduled / dispatch packs for org health, reviews, audits |
Destructive packs are dispatch-only or local — do not schedule them blindly.
Other CI systems¶
For other CI systems:
- Download the matching
linux-*/ runner archive +SHA256SUMS.txt - Verify checksum, extract, put
engrtonPATH - Export the env vars in Job contract
engrt bootstrap- Pass any organization/project/namespace explicitly on the command or as a capability input — Runtime keeps no context document, and a
context.yamlin the Home blocks every command engrt config validatethen your capability or provider commands
Local dry-run of a CI-shaped Home¶
export ENGRT_HOME="$PWD/runtime-home"
export ENGRT_CONSUMER=ci
export ENGRT_ACTOR_NAME=local-ci-verification
export ENGRT_SESSION_ID=local-$(date +%s)
engrt bootstrap
engrt config validate
runtime-home/ should stay gitignored.
Next¶
Operational examples on this site were verified against Runtime 0.14.0. After bootstrap, the version-exact files in Runtime Home win.