Secrets and Environment Variables Documentation¶

Table of Contents¶

• Overview
• 📊 Full Inventory
• Environment Variables — Aries_Serpent_codex_ Environment
• Repository Variables
  • Agent & Autonomy Control
  • CI/CD & Quality Gates
  • Cognitive Brain & Session Management
  • Copilot Agent Configuration
  • Infrastructure & Runtime
  • LLM & ML Pipeline
  • Zendesk Integration
• Environment Secrets — Aries_Serpent_codex_
• Repository Secrets
• Organization Secrets
• 🔴 Gap Analysis — Variables Referenced in Code but NOT in Inventory
• Service API (services/api/main.py)
• Nox / ML Pipeline (noxfile.py, scripts/)
• Cognitive Brain & Session (.codex/CRITICAL_REPOSITORY_VARIABLES.md)
• CI/CD Timeouts & Parallelism (.codex/CRITICAL_REPOSITORY_VARIABLES.md)
• 🔧 Token Chain
• 🔄 Secret Rotation Schedule
• 🧩 settings/variables/agents — Recommended Additions
• Workflow Permissions Reference
• 🗺️ Workflow & Agent Variable Usage Map
• Copilot Sandbox Bootstrap Surface (.github/workflows/copilot-setup-steps.yml)
• Agents Settings Surface (settings/variables/agents)
• Workflow Automation / CI Surface
• Runtime / Service Guard Surface
• Variable Access Pattern in Workflows
• Agent Variable Expectations
• Security Best Practices
• Monitoring and Auditing
• What’s Next (After Variable Sync)
• References
• Change Log
• GITLEAKS_LICENSE
  • SESSION_ENCRYPTION_KEY
  • ENABLE_LIVE_TESTS
• Third-Party Integration Secrets
  • NOTEBOOKLM_WEBHOOK_URL
  • GOOGLE_CLIENT_SECRET
  • GDRIVE_SERVICE_ACCOUNT_JSON
  • GITHUB_OAUTH_CLIENT_ID
  • GITHUB_OAUTH_CLIENT_SECRET
• PyPI Publishing Secrets
  • PYPI_API_TOKEN
  • TEST_PYPI_API_TOKEN
• AWS Integration Secrets
  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
• Zendesk Integration Secrets
  • ZENDESK_TOKEN
  • ZENDESK_USER
  • ZENDESK_URL
• Environment Variables
• Runtime Configuration
  • CODEX_ENV_*
  • CODEX_SESSION_*
  • CODEX_LOG_DB_PATH / CODEX_DB_PATH
  • CODEX_SQLITE_POOL
• CI/CD Environment Variables
  • CARGO_TERM_COLOR
  • RUST_BACKTRACE
  • RUST_TEST_THREADS
• Workflow Permissions
• Required Permissions by Workflow
  • auth-token-rotation.yml
  • auth-secret-rotation.yml
  • auth-compliance-report.yml
  • phase10-automated-secrets-setup.yml
• Security Best Practices
• Secret Rotation Schedule
• Secrets Usage Matrix
• Secret Management Guidelines
• MFA and Authentication
  • MFA Enrollment Process
• Troubleshooting
• Missing Secret Errors

Last Updated: 2026-06-22

Last Full Audit: 2026-06-03T17:39:00Z | Auditor: @mbaetiong Total Tracked: 113 (14 env vars · 76 repo vars · 3 env secrets · 7 repo secrets · 13 org secrets) Current Pass Scope: Variables only (secrets unchanged in this pass) Next Review: 2026-09-03 (quarterly)

Overview¶

This document provides comprehensive documentation for all secrets and environment variables used in the Codex repository, covering authentication, CI/CD, cognitive-brain/agent orchestration, ML/AI pipeline, and runtime configuration.

📊 Full Inventory¶

Environment Variables — Aries_Serpent_codex_ Environment¶

These are injected into the Copilot agent sandbox via copilot-setup-steps.yml.

Repository Variables¶

Agent & Autonomy Control¶

CI/CD & Quality Gates¶

Cognitive Brain & Session Management¶

Copilot Agent Configuration¶

Infrastructure & Runtime¶

LLM & ML Pipeline¶

Zendesk Integration¶

Environment Secrets — Aries_Serpent_codex_¶

Repository Secrets¶

Organization Secrets¶

🔴 Gap Analysis — Variables Referenced in Code but NOT in Inventory¶

The following variables are referenced in source code, workflow files, or .codex/ docs but are not present in the active repository/environment variable inventory. The maintainer should evaluate each for creation.

Service API (services/api/main.py)¶

Nox / ML Pipeline (noxfile.py, scripts/)¶

Cognitive Brain & Session (.codex/CRITICAL_REPOSITORY_VARIABLES.md)¶

CI/CD Timeouts & Parallelism (.codex/CRITICAL_REPOSITORY_VARIABLES.md)¶

🔧 Token Chain¶

All write operations in this repository use the following fallback chain:

GH_TOKEN = CODEX_MASTER_KEY || CODEX_BACKUP_KEY || github.token  # pragma: allowlist secret

Defined in COPILOT_AGENT_PREFLIGHT_RULES.token_rule. Never use git push directly — always use report_progress tool.

🔄 Secret Rotation Schedule¶

🧩 settings/variables/agents — Recommended Additions¶

The Copilot agents settings page currently shows only the firewall defaults. The following variables MUST or SHOULD be added at https://github.com/Aries-Serpent/_codex_/settings/variables/agents:

Workflow Permissions Reference¶

🗺️ Workflow & Agent Variable Usage Map¶

This section maps each key repository variable to the GitHub Actions workflows and custom agents that read it. Reference this when changing a variable value to understand downstream impact.

Copilot Sandbox Bootstrap Surface (.github/workflows/copilot-setup-steps.yml)¶

Agents Settings Surface (settings/variables/agents)¶

Workflow Automation / CI Surface¶

Runtime / Service Guard Surface¶

Variable Access Pattern in Workflows¶

All variables should be accessed using the safe fallback pattern:

env:
  CODEX_CACHE_VERSION: ${{ vars.CODEX_CACHE_VERSION || 'v2' }}
  # NODE_VERSION is a workflow-level alias that reads vars.NODE_JS_VERSION:
  #   env: { NODE_VERSION: "${{ vars.NODE_JS_VERSION || '22' }}" }
  CODEX_TEST_TIMEOUT: ${{ vars.CODEX_TEST_TIMEOUT_MINUTES || '60' }}
  COGNITIVE_BRAIN_INJECTION_ENABLED: ${{ vars.COGNITIVE_BRAIN_INJECTION_ENABLED || 'true' }}

Note on Node.js version variables: - NODE_JS_VERSION — repo var (create in GitHub UI → Settings → Actions → Variables). CI workflows (e.g., copilot-setup-steps.yml) read it as env.NODE_VERSION: ${{ vars.NODE_JS_VERSION || '22' }}. - CODEX_ENV_NODE_VERSION — environment var (Aries_Serpent_codex_ environment). Injected into the Copilot agent sandbox. These are two separate mechanisms serving different scopes. - CODEX_ENV — runtime env value exported by copilot-setup-steps.yml (copilot-agent today). This is distinct from any optional repository variable fallback used by services outside the Copilot sandbox. - CODEX_DB_PATH vs CODEX_LOG_DB_PATH — the setup workflow currently exports CODEX_DB_PATH=${GITHUB_WORKSPACE}/.codex/codex.db for cognitive/pattern state, while logging tools still default to CODEX_LOG_DB_PATH=.codex/session_logs.db.

For integer fields (e.g., timeout-minutes):

timeout-minutes: ${{ fromJSON(vars.CODEX_TEST_TIMEOUT_MINUTES || '60') }}

For action inputs:

- uses: ./.github/actions/setup-python-cached
  with:
    cache-version: ${{ vars.CODEX_CACHE_VERSION || 'v2' }}
- uses: actions/setup-node@v6
  with:
    node-version: ${{ vars.NODE_JS_VERSION || '22' }}

Agent Variable Expectations¶

Every custom Copilot coding agent MUST: 1. Check AGENT_KILL_SWITCH (vars.AGENT_KILL_SWITCH == '1' → abort immediately) 2. Read COPILOT_AGENT_PREFLIGHT_RULES for pre-commit compliance rules 3. Reference COPILOT_WEC_SELECTION_MATRIX for WEC item routing 4. Respect COPILOT_AGENT_MAX_AUTONOMY_LEVEL (ceiling: D) 5. Use token chain: CODEX_MASTER_KEY || CODEX_BACKUP_KEY || github.token

Every agent SHOULD: 6. Read COGNITIVE_BRAIN_INJECTION_ENABLED before calling cognitive brain APIs 7. Honor CODEX_LINT_STRICT when running linters 8. Respect CODEX_COVERAGE_THRESHOLD (default: 80) for coverage gates 9. Check CODEX_MAX_HEALER_RUNS_PER_HOUR before triggering self-healing loops 10. Log telemetry if CODEX_TELEMETRY_ENABLED is true

Full per-agent variable expectations: agents/VARIABLE_EXPECTATIONS.md

Security Best Practices¶

1. Never commit secrets to the repository
2. Token chain for write ops: CODEX_MASTER_KEY → CODEX_BACKUP_KEY → github.token
3. Rotate compromised secrets immediately — see .codex/security/rotation_schedule.md
4. Use least privilege for workflow permissions
5. Audit secret access via GitHub → Settings → Security → Audit log
6. DISABLE_SECRET_FILTER — must never be set to true in production
7. AGENT_KILL_SWITCH — set to 1 to immediately halt all autonomous agent activity

Monitoring and Auditing¶

• Audit Log: Settings → Security → Audit log → Filter by "secret"
• CI Failure Rate: CODEX_CI_FAILURE_RATE (auto-updated by CI agent, thresholds via CODEX_CI_FAILURE_THRESHOLD)
• Secret Access Patterns: docs/accountability/.codex/archive/reports/AGENT_ACCOUNTABILITY_REPORT.md
• Usage Matrix: .codex/security/secrets_usage_matrix.json

What’s Next (After Variable Sync)¶

1. Secrets pass (pending): update/verify repo, environment, and org secrets inventory and rotation state.
2. WEC drift verification: keep COPILOT_WEC_TEMPLATE_DRIFT aligned with the remediated _WEC_ITEMS state (count=0 expected after the 2026-06-03 update).
3. Agent settings alignment: verify /settings/variables/agents mirrors critical runtime variables (COPILOT_AGENT_*, COPILOT_WEC_*, COGNITIVE_BRAIN_*, CODEX_LINT_STRICT, CODEX_COVERAGE_THRESHOLD).
4. DISABLE_SECRET_FILTER hardening: keep default/effective value false, add explicit CI/policy guard to block any promotion flow that attempts true.
5. Post-secrets refresh: regenerate totals and audit timestamp once secrets are synchronized.

References¶

• GitHub Encrypted Secrets
• Fernet Encryption
• PR Lifecycle Spec — referenced by CODEX_PR_LIFECYCLE_VERSION
• Codebase Agency Policy — mandatory load per COPILOT_AGENT_PREFLIGHT_RULES

Change Log¶

Last Updated: 2026-06-03T22:09:48Z Maintainer: @mbaetiong Review Frequency: Quarterly

GITLEAKS_LICENSE¶

• Purpose: License key for Gitleaks Pro/Enterprise for enhanced secret scanning capabilities
• Format: Gitleaks license key string
• Used In:
• security-suite.yml
• Generation: Obtained from Gitleaks subscription (https://gitleaks.io)
• Security Level: LOW - Does not grant access to sensitive data, only enables scanning features
• Required: No (Gitleaks works without it in free mode with limited features)
• Rotation: As needed when subscription is renewed
• Note: Free version of Gitleaks works without this secret; this is only required for Pro/Enterprise features

SESSION_ENCRYPTION_KEY¶

• Purpose: Encrypt session data for secure storage
• Format: Base64-encoded Fernet key
• Used In: auth-secret-rotation.yml
• Generation: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
• Security Level: HIGH - Rotate every 90 iterations
• Required: Yes (for session security features)

ENABLE_LIVE_TESTS¶

• Purpose: Feature flag to enable live integration tests
• Format: Boolean string ("true" or "false")
• Used In: integration-gated.yml
• Security Level: LOW (configuration flag)
• Required: No (defaults to false)

Third-Party Integration Secrets¶

NOTEBOOKLM_WEBHOOK_URL¶

• Purpose: NotebookLM webhook URL for documentation sync
• Format: HTTPS webhook URL
• Used In: notebooklm-sync.yml
• Security Level: LOW - Regenerate webhook as needed
• Required: No (sync skipped if not available)

GOOGLE_CLIENT_SECRET¶

• Purpose: Google OAuth client secret for API access
• Format: Google OAuth 2.0 client secret
• Used In: notebooklm-sync.yml
• Security Level: MEDIUM - Rotate every 180 iterations
• Required: No (for Google Drive integration features)

GDRIVE_SERVICE_ACCOUNT_JSON¶

• Purpose: Google Drive service account credentials
• Format: JSON key file content (base64 or raw JSON)
• Used In: notebooklm-sync.yml
• Security Level: MEDIUM - Rotate annually
• Required: No (for automated Drive operations)

GITHUB_OAUTH_CLIENT_ID¶

• Purpose: GitHub OAuth app client ID (public identifier)
• Format: 20-character hex string
• Used In: auth-oauth-app-sync.yml
• Security Level: LOW (public identifier, not secret)
• Required: Yes (for OAuth flow)

GITHUB_OAUTH_CLIENT_SECRET¶

• Purpose: GitHub OAuth app client secret
• Format: 40-character hex string
• Used In:
• auth-oauth-app-sync.yml
• auth-secret-rotation.yml
• Generation: Via GitHub OAuth App settings
• Security Level: HIGH - Rotate every 180 iterations
• Required: Yes (for OAuth authentication)

PyPI Publishing Secrets¶

PYPI_API_TOKEN¶

• Purpose: PyPI API token for publishing packages to production PyPI
• Format: pypi- prefixed token string from PyPI account settings
• Used In:
• pypi-publish.yml
• Package publishing workflows
• Generation: Via PyPI Account Settings → API tokens → Generate new token
• Security Level: HIGH - Rotate every 90 iterations or after each use
• Required: Yes (for production PyPI publishing)
• Rotation: Recommended after each release or every 90 iterations
• Note: Use with username __token__ in Twine configuration

TEST_PYPI_API_TOKEN¶

• Purpose: TestPyPI API token for testing package uploads before production
• Format: pypi- prefixed token string from TestPyPI account settings
• Used In:
• pypi-publish.yml
• Pre-release testing workflows
• Generation: Via TestPyPI Account Settings → API tokens → Generate new token
• Security Level: MEDIUM - Rotate every 90 iterations
• Required: No (recommended for testing releases before production)
• Rotation: Recommended every 90 iterations
• Note: Separate token from production PYPI_API_TOKEN for security isolation

AWS Integration Secrets¶

AWS_ACCESS_KEY_ID¶

• Purpose: AWS IAM access key ID (public identifier)
• Format: 20-character uppercase alphanumeric
• Used In: zendesk-knowledge-sync.yml
• Security Level: LOW (public identifier, paired with SECRET)
• Required: Yes (for AWS S3/service access)

AWS_SECRET_ACCESS_KEY¶

• Purpose: AWS IAM secret access key
• Format: 40-character base64-encoded string
• Used In: zendesk-knowledge-sync.yml
• Generation: Via AWS IAM Console
• Security Level: HIGH - Rotate every 90 iterations
• Required: Yes (for AWS authentication)

Zendesk Integration Secrets¶

ZENDESK_TOKEN¶

• Purpose: Zendesk API authentication token
• Format: Zendesk API token string
• Used In: zendesk-knowledge-sync.yml
• Generation: Via Zendesk Admin → API settings
• Security Level: MEDIUM - Rotate annually
• Required: Yes (for knowledge base sync)

ZENDESK_USER¶

• Purpose: Zendesk account email for API authentication
• Format: Email address
• Used In: zendesk-knowledge-sync.yml
• Security Level: LOW (username, public)
• Required: Yes (paired with ZENDESK_TOKEN)

ZENDESK_URL¶

• Purpose: Zendesk instance URL
• Format: HTTPS URL (e.g., https://company.zendesk.com)
• Used In: zendesk-knowledge-sync.yml
• Security Level: LOW (public URL)
• Required: Yes (to specify Zendesk instance)

Environment Variables¶

Runtime Configuration¶

CODEX_ENV_*¶

• Purpose: Select language versions during environment setup
• Variables:
• CODEX_ENV_PYTHON_VERSION (default: 3.12)
• CODEX_ENV_NODE_VERSION (default: 22)
• CODEX_ENV_RUST_VERSION (default: 1.92)
• CODEX_ENV_GO_VERSION (default: 1.21)
• CODEX_ENV_SWIFT_VERSION (default: 5.9)

CODEX_SESSION_*¶

• Purpose: Session management and logging
• Variables:
• CODEX_SESSION_ID: Unique session identifier
• CODEX_SESSION_LOG_DIR: Log directory (default: .codex/sessions)

CODEX_LOG_DB_PATH / CODEX_DB_PATH¶

• Purpose: SQLite database path for logging
• Default: CODEX_LOG_DB_PATH=.codex/session_logs.db; copilot-setup-steps.yml currently overrides CODEX_DB_PATH to ${GITHUB_WORKSPACE}/.codex/codex.db
• Usage split: Use CODEX_LOG_DB_PATH for session-log storage/query/export flows, and use CODEX_DB_PATH for cognitive-brain / pattern-recorder state when the Copilot sandbox override is active

CODEX_SQLITE_POOL¶

• Purpose: Enable per-session SQLite connection pooling
• Values: 1 (enabled) or 0 (disabled)
• Default: 0

CI/CD Environment Variables¶

CARGO_TERM_COLOR¶

• Purpose: Enable colored output in Cargo
• Value: always
• Used In: Rust CI workflows

RUST_BACKTRACE¶

• Purpose: Enable full backtraces for Rust panics
• Value: 1 or full
• Used In: Rust testing and debugging

RUST_TEST_THREADS¶

• Purpose: Control test parallelism
• Value: 1 (sequential) for deterministic tests
• Used In: rust_swarm_ci.yml

Workflow Permissions¶

Required Permissions by Workflow¶

auth-token-rotation.yml¶

permissions:
  contents: write     # Read/write repository contents
  issues: write       # Create audit issues
  secrets: write      # Update GitHub secrets

auth-secret-rotation.yml¶

permissions:
  contents: write     # Read/write repository contents
  secrets: write      # Rotate secrets
  issues: write       # Create audit trail

auth-compliance-report.yml¶

permissions:
  contents: read      # Read repository data
  issues: write       # Post compliance reports

phase10-automated-secrets-setup.yml¶

permissions:
  contents: read      # Read configuration
  actions: write      # Manage workflow state
  secrets: write      # Initialize secrets

Security Best Practices¶

Secret Rotation Schedule¶

Comprehensive rotation schedule with all 18 secrets: .codex/security/rotation_schedule.md

Secrets Usage Matrix¶

Complete mapping of all secrets to workflows: .codex/security/secrets_usage_matrix.json

Summary: - Total Secrets: 18 - Total Workflows: 86 - Secret References: 108 - Most Used: GITHUB_TOKEN (20 workflows) - Newly Documented: SESSION_ENCRYPTION_KEY, ENABLE_LIVE_TESTS, GITLEAKS_LICENSE, AWS/Zendesk/Google integration secrets

Secret Management Guidelines¶

1. Never commit secrets to the repository
2. Use environment-specific secrets for dev/staging/prod
3. Rotate compromised secrets immediately (see emergency procedures in https://github.com/Aries-Serpent/codex/blob/main/.codex/security/rotation_schedule.md)
4. Audit secret access via GitHub audit logs
5. Use least privilege for workflow permissions
6. Document all secrets in this file
7. Test rotation procedures regularly
8. Review usage matrix monthly for unauthorized secret sprawl

MFA and Authentication¶

MFA Enrollment Process¶

The MFA enrollment automation (scripts/mfa_enrollment_automation.py) generates TOTP secrets and backup codes but does not store or transmit them automatically. In production:

1. Credentials must be delivered via secure, authenticated channels:
2. Encrypted email with PGP
3. SMS to verified numbers
4. Secure internal portal with authentication

5. Physical security keys

6. The current implementation is a placeholder - implement secure delivery before production use.

7. Never log or expose MFA secrets in plain text.

Troubleshooting¶

Missing Secret Errors¶

Last Updated: 2026-06-03T18:02:00Z Maintainer: @mbaetiong Review Frequency: Quarterly