CI/CD¶

Engineering Runtime is designed for pipelines: install a release binary, bootstrap a throwaway Runtime Home per job, authenticate with secrets, execute provider operations or capabilities, then read the audit trail.

Working examples live in engineering-runtime-ci. Prefer copying those workflows over inventing a new install path.

Job contract (minimum)¶

Every CI job should set:

env:
  RUNTIME_HOME: ${{ github.workspace }}/runtime-home
  RUNTIME_CONSUMER: ci
  RUNTIME_ACTOR_NAME: production-release
  RUNTIME_SESSION_ID: ${{ github.run_id }}

Variable	Why
`RUNTIME_HOME`	Per-job Home — never reuse a developer's `~/.engineering-runtime`
`RUNTIME_CONSUMER=ci`	Labels audit records as pipeline-driven
`RUNTIME_ACTOR_NAME`	Self-asserted workload label for searching the audit trail
`RUNTIME_SESSION_ID`	Maps the native pipeline run ID into Runtime correlation
`RUNTIME_GITHUB_TOKEN`	Set only on steps that call GitHub. Not needed to download the release — the artifacts are public

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.

`setup-runtime` composite action¶

From engineering-runtime-ci:

- uses: engineeringruntime/engineering-runtime-ci/.github/actions/setup-runtime@main
  with:
    github_organization: ${{ vars.GITHUB_ORG || github.repository_owner }}
    # omit version (or "") to install latest
    version: v0.9.1   # pin only for reproducible production pipelines (any published tag)

What it does:

Run the public installer, which downloads the matching artifact and verifies SHA256SUMS.txt before putting runtime on PATH
runtime bootstrap into the job's Home
Optionally export the GitHub organization as RUNTIME_GITHUB_ORG for later steps to pass explicitly; it never writes Runtime Context

The release download needs no token

engineering-runtime-releases is public, so the download step requires no credential at all. The compatibility runtime_github_token action input is deprecated; put RUNTIME_GITHUB_TOKEN only on later steps that perform GitHub provider operations.

Secrets and variables¶

Kind	Name	Purpose
Secret	`RUNTIME_GITHUB_TOKEN`	Auth Engine / `github` provider operations only
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:
  RUNTIME_HOME: ${{ github.workspace }}/runtime-home
  RUNTIME_CONSUMER: ci
  RUNTIME_ACTOR_NAME: runtime-ci-smoke
  RUNTIME_SESSION_ID: ${{ github.run_id }}

jobs:
  smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: engineeringruntime/engineering-runtime-ci/.github/actions/setup-runtime@main

      - name: Checkout public capability source at a reviewed revision
        uses: actions/checkout@v4
        with:
          repository: engineeringruntime/engineering-runtime-capabilities
          ref: <reviewed-tag-or-sha>
          path: engineering-runtime-capabilities

      - run: runtime config validate

      - run: |
          runtime capability execute \
            engineering-runtime-capabilities/capabilities/files/notes-roundtrip.md \
            --input path=./notes.txt \
            --input message="hello from CI"

      - env:
          RUNTIME_GITHUB_TOKEN: ${{ secrets.RUNTIME_GITHUB_TOKEN }}
        run: |
          runtime auth status
          runtime github user get

      - if: always()
        run: runtime audit tail -n 50

Use the company capability source¶

Clone engineering-runtime-capabilities at a reviewed tag or SHA. 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: |
    runtime capability validate \
      capability-registry/capabilities/github/github-repo-health.md
    runtime 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¶

The composite action is GitHub Actions-specific. Elsewhere, mirror its steps:

Download the matching linux-* / runner archive + SHA256SUMS.txt
Verify checksum, extract, put runtime on PATH
Export the env vars in Job contract
runtime bootstrap
Pass any organization/project/namespace explicitly on the command or as a capability input — Runtime keeps no context document, and a context.yaml in the Home blocks every command
runtime config validate then your capability or provider commands

Local dry-run of a CI-shaped Home¶

export RUNTIME_HOME="$PWD/runtime-home"
export RUNTIME_CONSUMER=ci
export RUNTIME_ACTOR_NAME=local-ci-verification
export RUNTIME_SESSION_ID=local-$(date +%s)
runtime bootstrap
runtime config validate

runtime-home/ should stay gitignored.

Next¶

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