Skip to content

GitHub authentication setup — v0.12.0

Applies to v0.12.0 and later

Earlier releases do not read these source keys.

Goal: choose and configure GitHub authentication for your Mac, GitHub Actions or GKE, using a known repository and no secret values in config files, shell history, source control or agent prompts.

These are operator recommendations, not automatic Runtime selection.

Environment Recommended Alternative Avoid unless necessary
Local, interactive developer engrt auth login github, ENGRT-owned OS session (os_secure_store) github_app, then protected file PAT in env
GitHub Actions, current-repo operation github_actions with minimum GITHUB_TOKEN permissions github_app for approved cross-repository/organization installations; protected file PAT in env
Other headless CI github_app with protected key delivery Scoped, preferably short-lived token as file Static PAT in env
Kubernetes/GKE Broker-rotated short-lived installation token as a protected file github_app using a protected private-key mount Static PAT as file, then env

Important distinctions: GitHub App installations and Actions job tokens represent installation authority, not a user. Do not smoke-test those with a user-only operation such as engrt github user get. Use a permitted repository read like engrt github repo view OWNER/REPO, with the exact target selected in GitHub and permitted by ENGRT policy. A GitHub App's private RSA key is long-lived sensitive material even though its derived installation tokens are short-lived.

How selection works

A Community Runtime config file selects the source:

schema_version: 2
execution:
  surface: local # local | ci | kubernetes; declaration, not credentials
authentication:
  github:
    enabled: true
    source: os_secure_store

Retain unrelated fields in your actual config; the examples show only relevant keys. Choose the reviewed Home config.yaml or an absolute path in ENGRT_CONFIG_FILE. Runtime has no v0.12.0 ENGRT_AUTHENTICATION_GITHUB_SOURCE env override. Explicit source selection never falls through if it is invalid. With no configured source, exactly one present ENGRT_GITHUB_TOKEN, ENGRT_GITHUB_TOKEN_FILE or ENGRT_GITHUB_CREDENTIALS_FILE can select env/file; multiple inputs refuse as ambiguous. With none present, an eligible host-bound ENGRT secure session may be used. Neither ENGRT_EXECUTION_SURFACE nor observed CI/Pod markers select credentials. The explicit selector is unavailable after Enterprise enrollment under the v0.12.0 ClassLocalOnly limitation.

Always start with a checksum-verified binary and a safe target, run engrt config validate, then try a permitted read, a denied/invalid control and inspect sanitized audit evidence. Do not confuse a configuration PASS with verified provider access.

Local interactive machine

First choice — OAuth session in the OS secure store

Set execution.surface: local and authentication.github.source: os_secure_store. Remove unintended token/file environment inputs, then:

engrt auth login github                  # interactive browser/device authorization
engrt auth status                        # non-secret diagnostic
engrt github repo view OWNER/REPO        # permitted repository read

On GitHub.com v0.12.0 contains an ENGRT-owned OAuth client. A custom/GHES host requires its own configured oauth_client_id and GitHub host binding; the GitHub.com client is not reused. The ENGRT session is separate from gh authentication. Only an admitted local interactive login prompts. MCP, regular execution, CI and Pods do not.

A known macOS upgrade limitation may return auth_store_unavailable after upgrading an ad-hoc-signed binary because a newly built executable cannot access the old Keychain entry. See session limitations; do not attempt to fix this by printing or handing the token to an agent.

Second choice — GitHub App installation

  1. Register a GitHub App with the minimum repository permissions needed.
  2. Install it on your intended account and selected repositories. Find its numeric App ID in App settings and its numeric installation ID for that installation.
  3. Generate a private RSA PEM key, retain it in an approved restricted secret location, and never commit or display its contents.
  4. Configure its non-secret identifiers:
schema_version: 2
execution:
  surface: local
authentication:
  github:
    enabled: true
    source: github_app
    app_id: "123456"
    installation_id: "78901234"
# This references a file provisioned separately by your secret manager.
export ENGRT_GITHUB_APP_PRIVATE_KEY_FILE=/restricted/credentials/app-key.pem
engrt config validate
engrt github repo view OWNER/REPO

Use exactly one App key input: protected ENGRT_GITHUB_APP_PRIVATE_KEY_FILE (preferred), or strict base64 ENGRT_GITHUB_APP_PRIVATE_KEY_B64 (fallback). Never put the PEM into YAML or supply a caller-made App JWT. App repository permissions and installation scope determine the resources it can access. A successful installation identity is not authorization for every operation.

PAT fallback — protected token file, then environment

For user-only access, create a fine-grained PAT restricted to the needed repositories, permissions and lifetime. A classic PAT remains a compatibility alternative.

repo view needs Metadata read. repo summary (GraphQL) also needs Contents, Issues and Pull requests read; for an Actions job token, add issues: read and pull-requests: read. Organizations that require approval of fine-grained tokens must approve permission changes before they take effect.

Use source: file and have your credential manager deliver a single token scalar into a protected file, then provide only its path:

export ENGRT_GITHUB_TOKEN_FILE=/restricted/credentials/github-token
engrt config validate
engrt github repo view OWNER/REPO

Alternatively, ENGRT_GITHUB_CREDENTIALS_FILE points to protected JSON containing exactly two string fields, host and token; it is mutually exclusive with the scalar token-file input. The JSON host must match the selected GitHub host. Never commit the JSON or log its values.

If a file cannot be used, choose source: env and inject ENGRT_GITHUB_TOKEN through the approved secret facility only into the invocation. Do not paste real tokens into shell history, screenshots, commands or agent messages. Environment and readable files do not provide isolation from another process with the same access.

GitHub Actions CI

No workflow job should prompt for OAuth. Use an isolated per-job Runtime Home, a pinned, checksum-verified engrt, reviewed config and only minimum GitHub permissions. github_actions is explicitly selected for the job token, not inferred from CI=true.

Commit a non-secret reviewed config such as .engrt-ci-config.yaml:

schema_version: 2
execution:
  surface: ci
authentication:
  github:
    enabled: true
    source: github_actions

Then in a trusted workflow (the runner must separately install and verify the pinned engrt; see Installation):

name: GitHub read through ENGRT
on:
  workflow_dispatch: {}
permissions:
  contents: read
jobs:
  smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Verify the pinned Runtime is installed
        run: engrt version
      - name: Read permitted repository
        env:
          ENGRT_CONFIG_FILE: ${{ github.workspace }}/.engrt-ci-config.yaml
          ENGRT_EXECUTION_SURFACE: ci
          ENGRT_HOME: ${{ runner.temp }}/engrt-home
          GITHUB_TOKEN: ${{ github.token }}
        run: |
          engrt config validate
          engrt github repo view OWNER/REPO

Replace OWNER/REPO with an actual job-token-accessible repository. A version display alone does not prove the pinned artifact checksum. GitHub's job token is installation-class and generally limited to its workflow repository. A scope/permission refusal stops with auth_scope_insufficient, often recommending github_app; Runtime never silently retries with another identity. See GitHub's job-token guidance.

GitHub App in Actions — for approved broader access

Use authentication.github.source: github_app with non-secret app_id and installation_id in your reviewed CI config. Deliver its PEM from CI secret custody to a protected file; do not pass both App key inputs. Example materialization on an Ubuntu runner:

- name: Prepare App key
  shell: bash
  env:
    APP_KEY_B64: ${{ secrets.ENGRT_GITHUB_APP_PRIVATE_KEY_B64 }}
  run: |
    umask 077
    printf '%s' "$APP_KEY_B64" | base64 --decode > "$RUNNER_TEMP/engrt-app.pem"
    echo "ENGRT_GITHUB_APP_PRIVATE_KEY_FILE=$RUNNER_TEMP/engrt-app.pem" >> "$GITHUB_ENV"
- name: Run scoped App read
  env:
    ENGRT_CONFIG_FILE: ${{ github.workspace }}/.engrt-ci-config.yaml
    ENGRT_EXECUTION_SURFACE: ci
  run: |
    engrt config validate
    engrt github repo view OWNER/REPO
- name: Cleanup key
  if: always()
  run: rm -f "$RUNNER_TEMP/engrt-app.pem"

This example still makes the PEM readable to the materialization step. Restrict workflow permissions, runner and secret access; don't run it from untrusted fork input. The key is not magically inaccessible to another job step with the same OS account.

PAT file or environment in CI

For an explicitly authorized user PAT, source: file reads an externally provisioned protected ENGRT_GITHUB_TOKEN_FILE. If a file cannot be supplied, source: env uses a step-scoped injected ENGRT_GITHUB_TOKEN secret. Do not put a long-lived PAT into top-level workflow env. The workflow GITHUB_TOKEN is not automatically a user PAT, and changing source requires an explicit config/owner decision.

Other CI platforms should prefer a scoped GitHub App; github_actions requires its actual Actions job-token prerequisites.

Kubernetes / GKE

Recommended: an approved broker (CSI, External Secrets or comparable secret-delivery process) rotates a short-lived, scoped installation token and mounts it read-only into the Pod. ENGRT consumes it through source: file; the broker, not Runtime, owns token minting and rotation.

schema_version: 2
execution:
  surface: kubernetes
authentication:
  github:
    enabled: true
    source: file

A complete illustrative Pod configuration follows. Your platform team must first provision the short-lived token via an approved broker, CSI/External Secrets integration or equivalent. The example references a previously provisioned Kubernetes Secret as one possible delivery mechanism; it does not create a Secret, mint a GitHub token or configure a broker. Substitute your approved CSI volume if that is your delivery model. Pin the ENGRT image to the exact qualified digest and replace the placeholders before using an approved test namespace.

apiVersion: v1
kind: ConfigMap
metadata:
  name: engrt-github-config
data:
  config.yaml: |
    schema_version: 2
    execution:
      surface: kubernetes
    authentication:
      github:
        enabled: true
        source: file
---
apiVersion: v1
kind: Pod
metadata:
  name: engrt-github-read-smoke
spec:
  serviceAccountName: APPROVED_KUBERNETES_SERVICE_ACCOUNT
  restartPolicy: Never
  securityContext:
    runAsNonRoot: true
    runAsUser: 10001
    runAsGroup: 10001
    fsGroup: 10001
  containers:
    - name: engrt
      image: REPLACE_WITH_APPROVED_IMAGE_AT_SHA256_DIGEST
      command: ["engrt", "github", "repo", "view", "OWNER/REPO"]
      env:
        - name: ENGRT_CONFIG_FILE
          value: /etc/engrt/config.yaml
        - name: ENGRT_EXECUTION_SURFACE
          value: kubernetes
        - name: ENGRT_GITHUB_TOKEN_FILE
          value: /var/run/engrt/github/token
      volumeMounts:
        - name: config
          mountPath: /etc/engrt
          readOnly: true
        - name: github-token
          mountPath: /var/run/engrt/github
          readOnly: true
  volumes:
    - name: config
      configMap:
        name: engrt-github-config
    - name: github-token
      secret:
        secretName: PREPROVISIONED_ROTATED_GITHUB_TOKEN
        defaultMode: 0440
        items:
          - key: token
            path: token

This is a read-only example, not a tested deployment recipe. It assumes a provisioned namespace, permission-scoped GitHub installation credential, matching ENGRT policy, an image containing the candidate binary, a token volume readable by the specified process user/group, an approved Kubernetes service account, and broker-managed expiration/rotation. Test actual file permissions and rotation behavior in your cluster. An ordinary Kubernetes Secret reference is not itself evidence that a broker rotates short-lived tokens.

Mount permissions must permit ENGRT to read the file without making it broadly readable. A same-Pod agent with matching file permissions may still read it; record that exposure honestly. Do not embed a Kubernetes Secret payload in source control or treat Workload Identity alone as a GitHub credential.

Alternative: explicitly set source: github_app and mount a protected PEM at ENGRT_GITHUB_APP_PRIVATE_KEY_FILE; this makes a longer-lived App private key available inside the pod, so access must be tighter. Last resort: scoped PAT file or env. GKE is noninteractive: neither login nor an agent can initiate OAuth device authorization.

A valid GKE acceptance test runs a real agent/ENGRT workload inside a Pod, confirms kubernetes declared/observed surface, selected source, one permitted GitHub read and one denied operation, safe audit, secret redaction and resource cleanup. Linux Actions or a simulated Pod cannot replace GKE evidence.

Troubleshooting and verification

Observation Action
Explicit source has no usable credential Fix that selected source; no fallback
More than one process token/file/JSON input without an explicit source Remove ambiguity; don't guess precedence
Both App PEM file and base64 key provided Keep exactly one
Host/JSON binding doesn't match github.com or your GHES host Correct the trusted target and matching credentials; never send to another host
App/job token reaches a user-only operation Use an installation-permitted operation; auth_principal_class_unsupported is correct
401, 403 or misleading 404 Check selected host, installation repository access, account/org policy and specific operation; don't infer absence
auth_store_unavailable after macOS binary change Use the documented host-bound secure-store recovery; don't export a token
CI/Pod tries to prompt Fix the noninteractive source and required configuration; no login fallback

v0.12.0 qualification status

Released v0.12.0 (source 222c16e) was qualified on these surfaces:

Surface Source Status
GitHub Actions github_actions, github_app, file, env, native gh qualified
Local (macOS) ENGRT session, github_app, file, env, native gh; GCP native qualified
GitHub Actions GCP credential_file (Workload Identity Federation) qualified
Kubernetes / GKE all sources not qualified in v0.12.0

Not qualified in v0.12.0: GCP permission-denial and principal-consistency cases, and raw engrt command run gh with an Actions job token (it refuses; see the known limitation in Governed authority).

Related: governed authority, released GitHub instructions, CI/CD, GCP/Kubernetes sources.

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