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.
Recommended source for each surface¶
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¶
- Register a GitHub App with the minimum repository permissions needed.
- 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.
- Generate a private RSA PEM key, retain it in an approved restricted secret location, and never commit or display its contents.
- 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.
Recommended — workflow GITHUB_TOKEN¶
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.
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.