Skip to content

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:

  1. Download the matching linux-* / runner archive + SHA256SUMS.txt
  2. Verify checksum, extract, put engrt on PATH
  3. Export the env vars in Job contract
  4. engrt bootstrap
  5. 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
  6. engrt config validate then 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.