Last synced: 2026-07-10T09:43:42Z (auto-sync workflow)

GitHub Variables & Secrets — Master Reference Guide¶

Last Updated: 2026-06-22

Version: 1.7.0 (W-142/S116 phase 3, 2026-03-07)
Owner: @mbaetiong
Status: ✅ Current — reflects live state as of 2026-03-07 (phase 3: REDIS_URL §6f added for SAR-G02 RedisBackend; DuckDB offline materialization evaluated; multivariate drift OTel spans added SAR-G05; autonomy CI matrix all 7 phases)
Audience: Human admins, Copilot agents, CI/CD authors
Auto-synced by: repo-var-sync-schedule.yml (daily 06:00 UTC → .codex/agent_context.json)

⚠️ This is the single source of truth. All other variable docs link here.

Table of Contents¶

1. Architecture Overview
2. How to Set Variables — Quick Links
3. Organization Secrets
4. Repository Secrets
5. Environment Secrets (Aries_Serpent_codex_)
6. Repository Variables
7. 6a. Cognitive Brain
8. 6b. Copilot Agent Runtime
9. 6c. CI/CD Health
10. 6d. Identity & Static Config
11. 6e. Runtime / Build Config
12. 6f. ML / HuggingFace / Weights & Biases
13. 6g. Webhook / Infra
14. 6h. 🤖 Autonomous Agent Config ⬅️ New (S116)
15. Environment Variables (Aries_Serpent_codex_)
16. Codespace Secrets
17. Workflow-Defined env: Variables
18. Known Issues & Inconsistencies
19. Troubleshooting
20. Related Documentation
21. ✅ Previously Missing — All Resolved (2026-03-07)

1. Architecture Overview¶

GitHub provides six distinct storage layers for variables and secrets. Choosing the wrong layer is the most common misconfiguration.

┌─────────────────────────────────────────────────────────────────────┐
│                    Variable Storage Hierarchy                        │
│                                                                      │
│  🏢 ORGANIZATION LEVEL  (Aries-Serpent)                             │
│  ├─ Org Secrets       → shared across all repos in org              │  # pragma: allowlist secret
│  └─ Org Variables     → [none currently, use repo vars instead]     │
│                                                                      │
│  📦 REPOSITORY LEVEL  (Aries-Serpent/_codex_)                       │
│  ├─ Repo Secrets      → encrypted, not readable by agents           │  # pragma: allowlist secret
│  └─ Repo Variables    → readable plaintext, writable via API        │
│                                                                      │
│  🌍 ENVIRONMENT LEVEL  (Aries_Serpent_codex_ environment)           │
│  ├─ Env Secrets       → override repo secrets for this env          │  # pragma: allowlist secret
│  └─ Env Variables     → override repo variables for this env        │
│                                                                      │
│  💻 CODESPACE LEVEL  (org or user-scoped)                           │
│  └─ Codespace Secrets → injected into interactive Codespace only    │  # pragma: allowlist secret
└─────────────────────────────────────────────────────────────────────┘

Resolution order (GitHub Actions): Env > Repo > Org (most specific wins)
Token access:  CODEX_MASTER_KEY > CODEX_BACKUP_KEY > GITHUB_TOKEN  # pragma: allowlist secret

Key constraints: - GITHUB_TOKEN cannot read/write the Variables API — requires CODEX_MASTER_KEY (classic PAT, repo scope). - Secrets are never readable by agents or logs — only injected as env vars. - Env-level values silently override repo-level values of the same name.

2. How to Set Variables — Quick Links¶

3. Organization Secrets¶

Location: Aries-Serpent → Settings → Security → Secrets → Actions
Referenced in workflows as: ${{ secrets.NAME }}
Access via API: Requires CODEX_MASTER_KEY or org-admin token

| # | Secret Name | Status | Last Updated | Purpose | Required By | |---|---|---|---|---|---| | 1 | CODECOV_TOKEN | ✅ Present | 2 months ago | Code coverage upload to codecov.io | coverage*.yml workflows | | 2 | CODEX_ADMIN_KEY | ✅ Present | 3 hours ago | Fine-grained PAT (Webhooks:write). Used for webhook_configurator.py least-privilege mode. | apply-webhooks job in agent_infrastructure_manager.yml | | 3 | CODEX_BACKUP_KEY | ✅ Present | 2 hours ago | Fallback GitHub PAT — auto-used on 401/403 from CODEX_MASTER_KEY. Same scope as master. | All auth-delegation workflows, variable_manager.py, brain_client.py, github_app.py | | 4 | CODEX_MASTER_KEY | ✅ Present | now (2026-03-06) | Primary full-scope GitHub PAT (classic, repo scope + admin:repo_hook). Required for Variables API, Secrets API, Webhooks API. Re-rotated 2026-03-06 — next rotation due ~2026-06-04. | agent-auth-delegation.yml, variable_manager.py, webhook_configurator.py, brain_client.py | | 5 | HF_TOKEN | ✅ Present | 2 months ago | HuggingFace API token for model downloads | ML training workflows | | 6 | NPM_TOKEN | ✅ Present | 2 months ago | npm publish authentication | Node.js package publish workflows | | 7 | PYPI_TOKEN | ✅ Present | 2 months ago | PyPI publish authentication | Python package publish workflows | | 8 | RAG_OPENAI_KEY | ✅ Present | 3 weeks ago | OpenAI API key for RAG embeddings | RAG index build workflows | | 9 | _CODEX_ACTION_RUNNER | ✅ Present | 2 months ago | Runner registration token for self-hosted Actions runners | Runner registration | | 10 | _GITHUB_APP_CLIENT_SECRET | ✅ Present | 8 hours ago | GitHub App OAuth client secret for web-flow App authentication | github_app.py, OAuth web-flow auth | | 11 | _GITHUB_APP_ID | ✅ Present | 8 hours ago | Numeric GitHub App ID for RS256 JWT generation | github_app.py, App JWT auth flows | | 12 | _GITHUB_APP_INSTALLATION_ID | ✅ Present | 8 hours ago | App installation ID for generating installation access tokens | github_app.py, installation token flows | | 13 | _GITHUB_APP_PRIVATE_KEY | ✅ Present | 8 hours ago | RSA-2048 PEM private key for signing GitHub App JWTs | github_app.py, RS256 JWT signing |

✅ CODEX_MASTER_KEY and CODEX_BACKUP_KEY rotated 2026-03-06 (latest rotation "now" per @mbaetiong — repo-level Codespace override removed, org secret active directly). Next rotation due ~2026-06-04 (90-day cycle).
See docs/ops/secrets_rotation_runbook.md for the full rotation procedure.

Token chain in code: CODEX_MASTER_KEY → CODEX_BACKUP_KEY → AGENT_GITHUB_TOKEN → GITHUB_TOKEN
This is enforced by _resolve_github_token() in src/codex/auth/github_app.py and scripts/tools/variable_manager.py.

GitHub App Authentication Secrets (_GITHUB_APP_*)¶

The four _GITHUB_APP_* secrets were added 2026-03-06 to support GitHub App–based authentication (RS256 JWT flow) as an alternative to PAT-based auth. They are consumed by src/codex/auth/github_app.py.

Codespace note: These org Actions secrets are separate from Codespace secrets. Codespace-based agent sessions that need GitHub App auth must also have these values set at the Codespace level (see §8). The naming convention (leading _) marks them as system/infrastructure secrets managed by the org admin.

4. Repository Secrets¶

Location: Settings → Secrets and variables → Actions → Secrets tab
Referenced in workflows as: ${{ secrets.NAME }}

| # | Secret Name | Status | Last Updated | Purpose | Notes | |---|---|---|---|---|---| | 1 | CODEX_GHP_TOKEN_BASE64 | ✅ Present | 2 months ago | Base64-encoded GitHub token for copilot-with-mcp workflow | Decoder priority #3 in copilot_token_decoder.py | | 2 | CODEX_GHP_TOKEN_HEX | ✅ Present | 2 months ago | Hex-encoded GitHub token (alternative encoding) | Decoder priority #4 | | 3 | CODEX_GHP_TOKEN_SHA256 | ✅ Present | 2 months ago | One-way SHA-256 hash of GHP token for integrity validation | Verification only — not a usable token | | 4 | CODEX_REPO_ID | ✅ Present | 6 hours ago | Repository numeric ID (GitHub internal) | Used in manifest generation | | 5 | CODEX_WEBHOOK_SECRET | ✅ Present | 12 minutes ago | HMAC-SHA256 shared secret for incoming webhook verification | WebhookVerifier in src/codex/auth/github_app.py | | 6 | OPENAI_API_KEY | ✅ Present | 5 hours ago | OpenAI API key for LLM agent operations | Consumed by brain_client.py and LLM-based CI workflows | | 7 | _CODEX_BOT_RUNNER | ✅ Present | 45 minutes ago | Bot runner registration token | ✅ Rotated 2026-03-06 |

Token Decoder Priority Order¶

1. CODEX_GHP_TOKEN_CONFIG   (Combined AES — not currently set)  # pragma: allowlist secret
2. CODEX_GHP_TOKEN_BASE64   ✅ (present — simplest, recommended)  # pragma: allowlist secret
3. CODEX_GHP_TOKEN_HEX      ✅ (present — alternative)  # pragma: allowlist secret
4. GITHUB_TOKEN             (auto-provided by Actions)  # pragma: allowlist secret

5. Environment Secrets (Aries_Serpent_codex_)¶

Location: Settings → Environments → Aries_Serpent_codex_
Override scope: These override org/repo secrets for jobs using environment: Aries_Serpent_codex_

| # | Secret Name | Status | Last Updated | Value | Notes | |---|---|---|---|---|---| | 1 | CODEX_ENVIRONMENT_RUNNER | ✅ Present | 48 minutes ago | (secret) | ✅ Rotated 2026-03-06 | | 2 | CODEX_RUNNER_SHA256 | ✅ Present | 50 minutes ago | (secret hash) | ✅ Rotated 2026-03-06 | | 3 | CODEX_RUNNER_TOKEN | ✅ Present | 50 minutes ago | (secret) | ✅ Rotated 2026-03-06 |

✅ Issue 1 resolved (2026-03-06): CODEX_ENV_NODE_VERSION was previously stored here as an environment secret. It has been deleted from env secrets and recreated as an environment variable (see §7). Node.js version strings are non-sensitive and should be variables, not secrets.
✅ Current runtime baseline (2026-06-05): Node.js 22 is the required active value; older 18/20 references in this document are historical records only.

6. Repository Variables¶

Location: Settings → Secrets and variables → Actions → Variables tab
Referenced in workflows as: ${{ vars.NAME }}
Readable by agents via: VariableManager (requires CODEX_MASTER_KEY)
Auto-synced to: .codex/agent_context.json daily

Variables are grouped by subsystem. Human-governance flags must never be overwritten by automation without explicit owner approval.

6a. 🧠 Cognitive Brain¶

6b. 🖥️ Copilot Agent Runtime¶

6c. ⚙️ CI/CD Health¶

6d. 🔒 Identity & Static Config¶

6e. 🐍 Runtime / Build Config¶

6f. 🤖 ML / HuggingFace / Weights & Biases¶

6g. Webhook / Infra¶

Both variables above are written atomically by step 4b in .devcontainer/scripts/post-start.sh on every Codespace start and resume.
gh variable set creates the variable if absent, so no manual seeding is required — the first Codespace start after this commit will provision both variables automatically.

Observability¶

OTel setup note¶

• Required Python packages (minimum): opentelemetry-sdk>=1.20.0 plus a protocol-specific OTLP exporter:
• gRPC (recommended for OTEL_EXPORTER_OTLP_ENDPOINT, e.g. :4317): opentelemetry-exporter-otlp-proto-grpc>=1.20.0
• HTTP (if using OTLP/HTTP): opentelemetry-exporter-otlp-proto-http>=1.20.0
• Optional convenience meta-package: opentelemetry-exporter-otlp>=1.20.0
• Install with (gRPC): pip install "opentelemetry-sdk>=1.20.0" "opentelemetry-exporter-otlp-proto-grpc>=1.20.0"
• Install with (HTTP): pip install "opentelemetry-sdk>=1.20.0" "opentelemetry-exporter-otlp-proto-http>=1.20.0"
• Leave OTEL_EXPORTER_OTLP_ENDPOINT unset for offline/local environments (no-op mode).

Data Store / Feature Backend¶

⚠️ Security note (REDIS_URL): If authentication is required, do not store credentials in a repository variable. Set REDIS_URL from a GitHub Actions Secret or Codespaces Secret containing the full authenticated URL (including credentials if needed). Repository variables are visible to users with read access, while runtime environment variables injected from secrets are appropriate for credentialed values.

REDIS_URL implementation notes¶

• Backend selection logic is implemented in src/codex_ml/features/feast_compat.py via create_backend().
• When REDIS_URL is set, the Redis backend path is selected for online-store usage.
• When unset, the system falls back to default local backends (SQLiteBackend / InMemoryBackend).

6h. 🤖 Autonomous Agent Config¶

Variables controlling the 7-phase autonomous agent framework introduced in S116 (PR #3508). All scripts fall back to safe coded defaults when variables are unset.

Set via: gh variable set <NAME> --body "<VALUE>" --repo Aries-Serpent/_codex_

AGENT_KILL_SWITCH operational notes¶

• Checked at loop entry before any work runs.
• If unset, scripts explicitly fall back to coded default "0" so CI passes by default.
• Workflow steps invoking autonomy_scheduler.py or agent_runner.py with AGENT_KILL_SWITCH=1 receive exit code 1.
• For non-blocking execution in that mode, use continue-on-error: true on the relevant step.

Governance note: AGENT_KILL_SWITCH is analogous to AUTONOMOUS_ACTIONS_ENABLED — both are human-governance flags. AGENT_KILL_SWITCH=1 provides a fast path to halt agent loops without changing AUTONOMOUS_ACTIONS_ENABLED, which gates the broader token delegation workflow.

Quick-set all agent config vars:

gh variable set AGENT_KILL_SWITCH            --body "0"   --repo Aries-Serpent/_codex_
gh variable set AUTONOMY_BUDGET_SECONDS      --body "60"  --repo Aries-Serpent/_codex_
gh variable set AUTONOMY_MAX_ITERATIONS      --body "3"   --repo Aries-Serpent/_codex_
gh variable set AUTONOMY_DRY_RUN             --body "0"   --repo Aries-Serpent/_codex_
gh variable set AGENT_RUNNER_BUDGET_SECONDS  --body "120" --repo Aries-Serpent/_codex_
gh variable set AGENT_RUNNER_ITERATIONS      --body "2"   --repo Aries-Serpent/_codex_
gh variable set AGENT_RUNNER_DRY_RUN         --body "0"   --repo Aries-Serpent/_codex_
gh variable set UNCERTAINTY_BUDGET_SECONDS   --body "10"  --repo Aries-Serpent/_codex_

7. Environment Variables (Aries_Serpent_codex_)¶

Location: Settings → Environments → Aries_Serpent_codex_
Override scope: These override repository variables of the same name for jobs using environment: Aries_Serpent_codex_

8. Codespace Secrets¶

Location (org): Settings → Codespaces → Secrets
Location (user): github.com/settings/secrets/codespaces
Injected by: .devcontainer/devcontainer.json "secrets": block
When: Only available inside an active GitHub Codespace session

🚀 Quick Start — Active Codespace¶

The Codespace name changes when a new Codespace is created. CODEX_ACTIVE_CODESPACE is always kept in sync by post-start.sh automatically.

These secrets mirror the Actions org secrets but are injected into Codespace containers for interactive agent sessions.

⚠️ Codespace secrets are NOT automatically mirrored from org Actions secrets — they must be set separately at the Codespace level even when the same secret exists as an Actions org secret.

| # | Secret Name | Status | Purpose | Where to Set | Actions Org Secret Equivalent | |---|---|---|---|---|---| | 1 | CODEX_MASTER_KEY | ✅ Confirmed (org-level, 2026-03-06) | Primary GitHub PAT for Variables API, Secrets API, Webhooks API | Org Codespace secrets | CODEX_MASTER_KEY (org secret ✅) | | 2 | CODEX_BACKUP_KEY | ✅ Confirmed (user secret, 2026-03-06) | Fallback PAT for 401/403 retries | User Codespace secrets | CODEX_BACKUP_KEY (org secret ✅) | | 3 | CODEX_ADMIN_KEY | ✅ Confirmed (user secret, 2026-03-06) | Fine-grained PAT (Webhooks:write) for webhook management | User Codespace secrets | CODEX_ADMIN_KEY (org secret ✅) | | 4 | _GITHUB_APP_ID | ✅ Confirmed (user secret, 2026-03-06) | Numeric GitHub App ID for RS256 JWT auth | User Codespace secrets | _GITHUB_APP_ID (org secret ✅) | | 5 | _GITHUB_APP_PRIVATE_KEY | ✅ Confirmed (user secret, 2026-03-06) | PEM RSA-2048 private key for GitHub App | User Codespace secrets (multi-line value) | _GITHUB_APP_PRIVATE_KEY (org secret ✅) | | 6 | _GITHUB_APP_INSTALLATION_ID | ✅ Confirmed (user secret, 2026-03-06) | App installation ID for generating installation tokens | User Codespace secrets | _GITHUB_APP_INSTALLATION_ID (org secret ✅) | | 7 | _GITHUB_APP_CLIENT_SECRET | ✅ Confirmed (user secret, 2026-03-07) | GitHub App OAuth client secret | User Codespace secrets | _GITHUB_APP_CLIENT_SECRET (org secret ✅) | | 8 | WEBHOOK_SECRET | ✅ Confirmed (user secret, 2026-03-06) | HMAC-SHA256 shared secret for webhook signature verification | User Codespace secrets | CODEX_WEBHOOK_SECRET (repo secret ✅) | | 9 | WEBHOOK_RECEIVER_URL | ✅ Confirmed (user secret + repo var, 2026-03-06) | Webhook receiver URL (also auto-set as repo var by post-start.sh) | User Codespace secrets | Repo variable WEBHOOK_RECEIVER_URL ✅ |

✅ SAR-G01 COMPLETE (2026-03-07) — All 9 Codespace secrets confirmed set by @mbaetiong. Secrets are stored as user-level Codespace secrets (not org-level), which works identically for personal Codespace sessions.

Note: Secrets 4–7 use the same _GITHUB_APP_* naming as the corresponding org Actions secrets (leading underscore is the standard convention for these system/infrastructure secrets).
See docs/agent/CODESPACE_COPILOT_AGENT_GUIDE.md for detailed setup instructions.

Note (2026-03-06): CODEX_MASTER_KEY was briefly set as a repository-level Codespace secret (overriding the org secret). That repo-level override has been removed by @mbaetiong — the org-level Codespace secret is now active directly. Secret was re-rotated at this time.

✅ All Codespace secrets confirmed (SAR-G01 COMPLETE 2026-03-07)¶

All 9 Codespace secrets were set by @mbaetiong as user-level Codespace secrets on 2026-03-06/07. No further admin action is required for Codespace agent sessions.

For reference, the CLI commands used were:

# All secrets are now set — commands below are for documentation/recovery only
gh secret set CODEX_BACKUP_KEY             --app codespaces  # user-level
gh secret set CODEX_ADMIN_KEY              --app codespaces  # user-level
gh secret set _GITHUB_APP_ID              --app codespaces  # user-level
gh secret set _GITHUB_APP_PRIVATE_KEY     --app codespaces  # user-level
gh secret set _GITHUB_APP_INSTALLATION_ID --app codespaces  # user-level
gh secret set _GITHUB_APP_CLIENT_SECRET   --app codespaces  # user-level
gh secret set WEBHOOK_SECRET               --app codespaces  # user-level
gh secret set WEBHOOK_RECEIVER_URL         --app codespaces  # user-level

9. Workflow-Defined env: Variables¶

These are not stored in GitHub Settings — they are defined inline in workflow files and can reference secrets/variables.

Reference: docs/agent/COPILOT_TOKEN_GUIDE.md — complete token permission matrix.

10. Known Issues & Inconsistencies¶

✅ Issue 1 — CODEX_ENV_NODE_VERSION stored as a Secret — RESOLVED 2026-03-06¶

✅ Issue 2 — Python version conflict: 3.12 vs 3.11 — RESOLVED 2026-03-06¶

✅ Issue 3 — Duplicate path variable: CODEX_D365_POLICIES_PATH and D365_SLA_POLICY_PATH — RESOLVED 2026-03-06¶

✅ Issue 4 — Stale secrets (> 90-day rotation guideline) — RESOLVED 2026-03-06¶

| Secret | Previous Age | Resolution | |---|---|---| | CODEX_MASTER_KEY | Rotated 2026-03-05 | ✅ Re-rotated 2026-03-06 (~2 h before export). Next due ~2026-06-04. | | CODEX_BACKUP_KEY | 5+ days | ✅ Re-rotated 2026-03-06 (~2 h before export). | | _CODEX_BOT_RUNNER | 7 months | ✅ Rotated 2026-03-06 (~45 min before export). | | CODEX_ENVIRONMENT_RUNNER | 7 months | ✅ Rotated 2026-03-06 (~48 min before export). | | CODEX_RUNNER_TOKEN | 7 months | ✅ Rotated 2026-03-06 (~50 min before export). | | CODEX_RUNNER_SHA256 | 7 months | ✅ Rotated 2026-03-06 (~50 min before export). |

✅ Issue 5 — CODEX_ADMIN_KEY missing — RESOLVED 2026-03-06¶

✅ Issue 6 — WEBHOOK_RECEIVER_URL missing — RESOLVED 2026-03-06¶

✅ Issue 7 — Codespace secrets confirmation — RESOLVED 2026-03-07¶

11. Troubleshooting¶

"Variables API returns 403 / 404"¶

Symptom: VariableManager or brain_client raises AuthenticationError on variable read/write
Cause:   GITHUB_TOKEN used instead of CODEX_MASTER_KEY  # pragma: allowlist secret
Fix:
  1. Confirm CODEX_MASTER_KEY is set as an org secret (§3)  # pragma: allowlist secret
  2. Confirm copilot-setup-steps.yml "🔑 Export Auth Tokens" step is running  # pragma: allowlist secret
  3. In code, use: from scripts.tools.variable_manager import VariableManager; vm = VariableManager()
  Reference: docs/agent/COPILOT_TOKEN_GUIDE.md — Permission Matrix  # pragma: allowlist secret

"Webhooks return 403 on create/update"¶

Symptom: webhook_configurator.py fails with HTTP 403 on webhook API calls
Cause:   GITHUB_TOKEN cannot manage webhooks; CODEX_ADMIN_KEY / CODEX_MASTER_KEY needed  # pragma: allowlist secret
Fix:
  1. Confirm CODEX_MASTER_KEY has admin:repo_hook scope, OR
  2. Create CODEX_ADMIN_KEY (fine-grained, Webhooks:write) and set as org secret  # pragma: allowlist secret
  Reference: docs/agent/COPILOT_TOKEN_GUIDE.md — Webhook operations section  # pragma: allowlist secret

"Python version mismatch between jobs"¶

Symptom: Tests pass in some jobs, fail in others due to Python syntax/type differences
Status:  ✅ RESOLVED (2026-03-06) — CODEX_ENV_PYTHON_VERSION updated to 3.12 (Issue 2)
Both CODEX_PYTHON_VERSION (repo var) and CODEX_ENV_PYTHON_VERSION (env var) are now 3.12.
If you still see version mismatches, confirm no other variable overrides exist.

"CODEX_ENV_NODE_VERSION appears as *** in logs"¶

Symptom: Node.js version appears masked in CI logs
Status:  ✅ RESOLVED (2026-03-06) — CODEX_ENV_NODE_VERSION deleted from env secrets and  # pragma: allowlist secret
         recreated as an env variable. Value is now readable in logs and by the Variables API.
Current required value: `22` (major-only).

"Codespace starts but CLI API server not running"¶

Symptom: post-start.sh health check fails; uvicorn :8765 not reachable
Cause:   CODEX_MASTER_KEY or CODEX_BACKUP_KEY not set as Codespace secrets  # pragma: allowlist secret
Fix:     All 9 Codespace secrets are now set (SAR-G01 COMPLETE 2026-03-07) — see §8  # pragma: allowlist secret
         Reference: docs/agent/CODESPACE_COPILOT_AGENT_GUIDE.md

"CODEX_CI_FAILURE_RATE shows stale value"¶

Symptom: CODEX_CI_FAILURE_RATE hasn't updated in > 24 hours
Cause:   ci-health-monitor.yml workflow not running, or CODEX_MASTER_KEY lacked write access
Fix:
  1. Check .github/workflows/ci-health-monitor.yml is enabled
  2. Verify CODEX_MASTER_KEY has variables:write permission
  Format: "<float>:<status>" — e.g. "6.3:ok", "15.2:degraded", "22.1:critical"

"Secret rotation — CODEX_MASTER_KEY / CODEX_BACKUP_KEY"¶

Full runbook: docs/ops/secrets_rotation_runbook.md  # pragma: allowlist secret
Quick summary:
  1. Generate new 32-byte base64 key offline
  2. Copy current CODEX_MASTER_KEY → set as CODEX_BACKUP_KEY (opens grace window)
  3. Set new key as CODEX_MASTER_KEY
  4. Wait 48 hours (grace window) then verify
  5. Update CODEX_BACKUP_KEY to new value (closes grace window)

"Incorrect variable format"¶

Variable: CODEX_CI_FAILURE_RATE
Required format: "<float>:<status>" (e.g. "6.3:ok")
Invalid examples: "6.3", "ok", "6.3-ok", "6.3 ok"
Fix: gh variable set CODEX_CI_FAILURE_RATE --body "6.3:ok" --repo Aries-Serpent/_codex_

Variable: COGNITIVE_BRAIN_SESSION_NUMBER
Required format: Integer (e.g. "120")
Invalid examples: "S120", "session-120", "120.0"
Fix: gh variable set COGNITIVE_BRAIN_SESSION_NUMBER --body "120" --repo Aries-Serpent/_codex_

12. Related Documentation¶

13. ✅ Previously Missing — All Resolved (2026-03-07)¶

All previously-blocked items are now resolved. This section is retained as an audit trail.

✅ WEBHOOK_RECEIVER_URL (Repo Variable) — RESOLVED 2026-03-06¶

Resolution: WEBHOOK_RECEIVER_URL is now auto-set on every Codespace start/resume by .devcontainer/scripts/post-start.sh. The URL format is: https://${CODESPACE_NAME}-8765.app.github.dev/webhook/github

The POST /webhook/github endpoint is implemented in cognitive_app/src/server/cli_api_server.py. For webhook delivery to work, port 8765 must be set to public visibility in the Codespace Ports panel.

✅ Issue 3 — Delete duplicate D365_SLA_POLICY_PATH repo variable — RESOLVED 2026-03-06¶

D365_SLA_POLICY_PATH is absent from the 2026-03-06 live export — the variable has been deleted.

✅ Codespace Secrets (9 items) — RESOLVED 2026-03-07 (SAR-G01 COMPLETE)¶

All 9 Codespace secrets confirmed set by @mbaetiong as user-level Codespace secrets. See §8 for the complete confirmed status table.

| Codespace Secret | Resolution | |---|---| | CODEX_MASTER_KEY | ✅ Org-level (2026-03-06) | | CODEX_BACKUP_KEY | ✅ User secret (2026-03-06) | | CODEX_ADMIN_KEY | ✅ User secret (2026-03-06) | | _GITHUB_APP_ID | ✅ User secret (2026-03-06) | | _GITHUB_APP_PRIVATE_KEY | ✅ User secret (2026-03-06) | | _GITHUB_APP_INSTALLATION_ID | ✅ User secret (2026-03-06) | | _GITHUB_APP_CLIENT_SECRET | ✅ User secret (2026-03-07) | | WEBHOOK_SECRET | ✅ User secret (2026-03-06) | | WEBHOOK_RECEIVER_URL | ✅ User secret + repo var (2026-03-06) |

✅ Autonomous Agent Config Variables (8 items) — RESOLVED 2026-03-07¶

All 8 §6h autonomous agent repo variables confirmed set by @mbaetiong. See §6h for details.

Note: If any of these need to be re-provisioned in the future (e.g., after secret rotation), refer to the historical CLI commands preserved in the sub-sections above.

Summary Checklist¶

✅ Previously Blocked — All Resolved (2026-03-07)¶

• ~~Set 9 Codespace secrets~~ — RESOLVED 2026-03-07 (SAR-G01 COMPLETE) — all set as user Codespace secrets by @mbaetiong; see §8
• ~~Set 8 autonomous agent repo variables~~ — RESOLVED 2026-03-07 — all 8 set: AGENT_KILL_SWITCH=0, AUTONOMY_BUDGET_SECONDS=90, AUTONOMY_MAX_ITERATIONS=3, AUTONOMY_DRY_RUN=0, AGENT_RUNNER_BUDGET_SECONDS=180, AGENT_RUNNER_ITERATIONS=2, AGENT_RUNNER_DRY_RUN=0, UNCERTAINTY_BUDGET_SECONDS=20; see §6h

✅ Resolved¶

• ~~Fix Issue 1: Delete CODEX_ENV_NODE_VERSION env secret; recreate as env variable~~ — Done 2026-03-06
• ~~Fix Issue 2: Update CODEX_ENV_PYTHON_VERSION env variable from 3.11 → 3.12~~ — Done 2026-03-06
• ~~Fix Issue 3: Remove duplicate D365_SLA_POLICY_PATH repo variable~~ — Done 2026-03-06 (deleted from GitHub; absent in live export)
• ~~Fix Issue 4: Rotate stale runner secrets (7 months old)~~ — Done 2026-03-06 (_CODEX_BOT_RUNNER, CODEX_ENVIRONMENT_RUNNER, CODEX_RUNNER_TOKEN, CODEX_RUNNER_SHA256 all rotated; CODEX_MASTER_KEY + CODEX_BACKUP_KEY re-rotated)
• ~~Fix Issue 5: Create CODEX_ADMIN_KEY org secret (fine-grained PAT, Webhooks:write)~~ — Done 2026-03-06
• ~~Fix Issue 6: Set WEBHOOK_RECEIVER_URL repo variable~~ — Done 2026-03-06 (auto-set by Codespace post-start.sh)
• ~~Document autonomous agent env vars (§6h)~~ — Done 2026-03-07 (S116 PR #3508, 8 variables: AGENT_KILL_SWITCH, AUTONOMY_BUDGET_SECONDS, AUTONOMY_MAX_ITERATIONS, AUTONOMY_DRY_RUN, AGENT_RUNNER_BUDGET_SECONDS, AGENT_RUNNER_ITERATIONS, AGENT_RUNNER_DRY_RUN, UNCERTAINTY_BUDGET_SECONDS)

🟢 Monitor / Maintenance¶

• Rotate CODEX_MASTER_KEY + CODEX_BACKUP_KEY before 2026-06-04 (rotated 2026-03-06 — 90-day window)
• Rotate _CODEX_BOT_RUNNER, CODEX_ENVIRONMENT_RUNNER, CODEX_RUNNER_TOKEN, CODEX_RUNNER_SHA256 before 2026-06-04

Supersedes: .codex/runtime_variables.md · docs/security/CURRENT_EXPECTED_VARIABLES.md · .codex/QUICK_REFERENCE_TOKEN_STATUS.md
Maintained by: @mbaetiong · Last reviewed: 2026-03-07 (S116/W-142 phase 3 — §6f REDIS_URL added (SAR-G02); DuckDB offline backend evaluated; §6h all 8 autonomous agent vars confirmed ✅; SAR-G01 all 9 Codespace secrets confirmed ✅; §13 converted to resolved archive; v1.7.0)