{
  "id": "page:docs-github-actions-setup-codex",
  "_kind": "Page",
  "_file": "wiki/docs/github-actions-setup-codex.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/github-actions-setup-codex.md",
    "sourceKind": "repo-docs",
    "title": "Using Babysitter with Codex GitHub Actions",
    "displayName": "Using Babysitter with Codex GitHub Actions",
    "slug": "docs/github-actions-setup-codex",
    "articlePath": "wiki/docs/github-actions-setup-codex.md",
    "article": "\n# Using Babysitter with Codex GitHub Actions\n\nThis guide explains how to integrate the Babysitter plugin with [OpenAI's Codex GitHub Action](https://github.com/openai/codex-action) for automated orchestration workflows in your CI/CD pipeline.\n\n## Overview\n\nThe Babysitter plugin enables deterministic, event-sourced workflow orchestration for Codex. When combined with GitHub Actions, you can automate complex multi-step development processes with quality gates, human approval checkpoints, and iterative refinement.\n\nCodex uses the `openai/codex-action@v1` action, which runs Codex CLI in a sandboxed environment with a Responses API proxy sidecar for secure API key handling.\n\n## Quick Start\n\n### Basic Setup\n\nAdd the Babysitter plugin to your Codex GitHub Actions workflow:\n\n```yaml\nname: Codex with Babysitter\n\non:\n  issue_comment:\n    types: [created]\n  pull_request_review_comment:\n    types: [created]\n  issues:\n    types: [opened, assigned]\n\njobs:\n  codex:\n    if: |\n      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@codex')) ||\n      (github.event_name == 'issues' && contains(github.event.issue.body, '@codex'))\n    runs-on: ubuntu-latest\n    permissions:\n      contents: write\n      pull-requests: write\n      issues: write\n      id-token: write\n    steps:\n      - name: Checkout repository\n        uses: actions/checkout@v4\n        with:\n          fetch-depth: 1\n\n      - name: Install Babysitter SDK\n        run: npm install -g @a5c-ai/babysitter-sdk @a5c-ai/babysitter-agent\n\n      - name: Run Codex with Babysitter\n        uses: openai/codex-action@v1\n        with:\n          openai-api-key: ${{ secrets.OPENAI_API_KEY }}\n          prompt: |\n            You have the babysitter CLI available. Use it for orchestration.\n\n            ${{ github.event.comment.body || github.event.issue.body }}\n```\n\nFor comprehensive Codex Action setup instructions, see the [Codex Action README](https://github.com/openai/codex-action).\n\n## Configuration Options\n\n### Codex Action Parameters\n\n```yaml\n- uses: openai/codex-action@v1\n  with:\n    # Required\n    openai-api-key: ${{ secrets.OPENAI_API_KEY }}\n    prompt: \"Your task description\"\n\n    # Optional\n    model: \"o4-mini\"                    # Model override\n    sandbox: \"workspace-write\"          # workspace-write | read-only | danger-full-access\n    safety-strategy: \"drop-sudo\"        # drop-sudo | unprivileged-user | read-only | unsafe\n    codex-version: \"\"                   # Pin @openai/codex version\n    working-directory: \"\"               # Defaults to repo root\n    codex-args: \"\"                      # Extra CLI args (JSON array or shell string)\n    effort: \"\"                          # Reasoning effort level\n    allow-users: \"\"                     # Comma-separated GitHub usernames (or '*')\n    allow-bots: \"false\"                 # Allow bot-triggered runs\n```\n\n### Babysitter Plugin Setup\n\nSince Codex does not have a native plugin marketplace like Claude Code, install the Babysitter SDK as a build step:\n\n```yaml\n- name: Install Babysitter SDK\n  run: npm install -g @a5c-ai/babysitter-sdk @a5c-ai/babysitter-agent\n```\n\nThe `babysitter` CLI will then be available to Codex during execution.\n\n## Workflow Examples\n\n### Example 1: PR Review with Quality Gates\n\n```yaml\nname: Babysitter PR Review (Codex)\n\non:\n  pull_request:\n    types: [opened, synchronize, ready_for_review, reopened]\n\njobs:\n  review:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      pull-requests: write\n      id-token: write\n    steps:\n      - name: Checkout repository\n        uses: actions/checkout@v4\n        with:\n          fetch-depth: 1\n\n      - name: Install Babysitter SDK\n        run: npm install -g @a5c-ai/babysitter-sdk @a5c-ai/babysitter-agent\n\n      - name: Run Babysitter PR Review\n        uses: openai/codex-action@v1\n        with:\n          openai-api-key: ${{ secrets.OPENAI_API_KEY }}\n          sandbox: \"read-only\"\n          prompt: |\n            You have access to the babysitter CLI for orchestration.\n            Use it to orchestrate a thorough code review using TDD Quality Convergence methodology.\n\n            REPO: ${{ github.repository }}\n            PR NUMBER: ${{ github.event.pull_request.number }}\n\n            Analyze the PR changes for:\n            - Code quality and best practices\n            - Security vulnerabilities\n            - Performance implications\n            - Test coverage\n\n            Run: babysitter-agent call --harness codex --prompt \"review this PR\" --workspace .\n```\n\n### Example 2: Feature Development with TDD\n\n```yaml\nname: Babysitter TDD Feature (Codex)\n\non:\n  issues:\n    types: [labeled]\n\njobs:\n  develop:\n    if: github.event.label.name == 'feature-request'\n    runs-on: ubuntu-latest\n    timeout-minutes: 30\n    permissions:\n      contents: write\n      pull-requests: write\n      issues: write\n      id-token: write\n    steps:\n      - name: Checkout repository\n        uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n\n      - name: Install Babysitter SDK\n        run: npm install -g @a5c-ai/babysitter-sdk @a5c-ai/babysitter-agent\n\n      - name: Run Babysitter TDD\n        uses: openai/codex-action@v1\n        with:\n          openai-api-key: ${{ secrets.OPENAI_API_KEY }}\n          sandbox: \"workspace-write\"\n          prompt: |\n            You have the babysitter CLI available for orchestration.\n            Implement the feature described in issue #${{ github.event.issue.number }} using TDD Quality Convergence methodology.\n\n            REPO: ${{ github.repository }}\n            ISSUE NUMBER: ${{ github.event.issue.number }}\n\n            The process should:\n            1. Write failing tests first\n            2. Implement minimal code to pass tests\n            3. Refactor for quality\n            4. Iterate until 80% quality threshold is met\n\n            Create a PR when complete.\n```\n\n### Example 3: GSD Quick Tasks\n\n```yaml\nname: Babysitter GSD (Codex)\n\non:\n  issue_comment:\n    types: [created]\n\njobs:\n  gsd:\n    if: contains(github.event.comment.body, '/gsd')\n    runs-on: ubuntu-latest\n    timeout-minutes: 15\n    permissions:\n      contents: write\n      pull-requests: write\n      issues: write\n      id-token: write\n    steps:\n      - name: Checkout repository\n        uses: actions/checkout@v4\n        with:\n          fetch-depth: 1\n\n      - name: Install Babysitter SDK\n        run: npm install -g @a5c-ai/babysitter-sdk @a5c-ai/babysitter-agent\n\n      - name: Run Babysitter GSD\n        uses: openai/codex-action@v1\n        with:\n          openai-api-key: ${{ secrets.OPENAI_API_KEY }}\n          sandbox: \"workspace-write\"\n          allow-users: \"*\"\n          prompt: |\n            You have the babysitter CLI available.\n            Use GSD methodology for the following task:\n\n            ${{ github.event.comment.body }}\n\n            Focus on rapid, working implementation with minimal overhead.\n```\n\n### Example 4: Structured Output\n\nCodex supports structured output via JSON schemas:\n\n```yaml\n- name: Run Babysitter with Structured Output\n  uses: openai/codex-action@v1\n  id: codex\n  with:\n    openai-api-key: ${{ secrets.OPENAI_API_KEY }}\n    sandbox: \"workspace-write\"\n    output-schema: |\n      {\n        \"type\": \"object\",\n        \"properties\": {\n          \"summary\": { \"type\": \"string\" },\n          \"files_changed\": { \"type\": \"array\", \"items\": { \"type\": \"string\" } },\n          \"tests_passed\": { \"type\": \"boolean\" }\n        },\n        \"required\": [\"summary\", \"files_changed\", \"tests_passed\"]\n      }\n    prompt: |\n      You have the babysitter CLI available.\n      Implement the requested feature and report results.\n\n- name: Use structured output\n  run: echo \"${{ steps.codex.outputs.final-message }}\"\n```\n\n## Sandbox Modes\n\nCodex offers several sandbox configurations:\n\n| Mode | Description | Use Case |\n|------|-------------|----------|\n| `workspace-write` | Read/write to workspace only | Default; feature development, refactoring |\n| `read-only` | No filesystem writes | Code review, analysis |\n| `danger-full-access` | Full system access | Complex builds requiring system packages |\n\n## Environment Variables\n\n```yaml\n- uses: openai/codex-action@v1\n  with:\n    openai-api-key: ${{ secrets.OPENAI_API_KEY }}\n    prompt: \"...\"\n  env:\n    # Babysitter configuration\n    BABYSITTER_RUNS_SCOPE: repo\n    BABYSITTER_MAX_ITERATIONS: 100\n    BABYSITTER_QUALITY_THRESHOLD: 85\n    BABYSITTER_LOG_LEVEL: debug\n```\n\n## Artifacts and Outputs\n\n### Preserving Run State\n\n```yaml\n- uses: actions/upload-artifact@v4\n  if: always()\n  with:\n    name: babysitter-runs\n    path: .a5c/runs/\n    retention-days: 7\n```\n\n### Codex Output\n\nThe action exposes a `final-message` output:\n\n```yaml\n- uses: openai/codex-action@v1\n  id: codex\n  with:\n    openai-api-key: ${{ secrets.OPENAI_API_KEY }}\n    prompt: \"...\"\n\n- name: Check results\n  run: echo \"${{ steps.codex.outputs.final-message }}\"\n```\n\n## Best Practices\n\n### 1. Choose the Right Sandbox Mode\n\nUse the most restrictive sandbox that works for your task:\n- `read-only` for reviews and analysis\n- `workspace-write` for most development tasks\n- `danger-full-access` only when system-level access is required\n\n### 2. Set Reasonable Iteration Limits\n\n```yaml\nenv:\n  BABYSITTER_MAX_ITERATIONS: 50\n```\n\n### 3. Use Safety Strategies\n\nCodex supports multiple safety strategies for sandboxed execution:\n\n| Strategy | Description |\n|----------|-------------|\n| `drop-sudo` | Default; drops sudo privileges |\n| `unprivileged-user` | Runs as unprivileged user |\n| `read-only` | Read-only filesystem |\n| `unsafe` | No sandboxing (not recommended) |\n\n### 4. Handle Failures Gracefully\n\n```yaml\n- uses: openai/codex-action@v1\n  id: codex\n  continue-on-error: true\n  with:\n    openai-api-key: ${{ secrets.OPENAI_API_KEY }}\n    prompt: \"...\"\n\n- name: Handle failure\n  if: steps.codex.outcome == 'failure'\n  run: echo \"Codex run failed - check artifacts\"\n```\n\n## Troubleshooting\n\n### Babysitter CLI Not Found\n\nEnsure the SDK is installed before the Codex step:\n\n```yaml\n- name: Install Babysitter SDK\n  run: npm install -g @a5c-ai/babysitter-sdk @a5c-ai/babysitter-agent\n```\n\n### Sandbox Permission Errors\n\nIf Codex cannot write files, check the sandbox mode:\n- Use `workspace-write` for tasks that modify code\n- Use `danger-full-access` if system packages are needed\n\n### Runs Timing Out\n\n1. Reduce `BABYSITTER_MAX_ITERATIONS`\n2. Use simpler methodology (GSD vs TDD)\n3. Break task into smaller pieces\n\n## Related Documentation\n\n### Codex Action\n- [Codex Action Repository](https://github.com/openai/codex-action)\n- [OpenAI Codex CLI](https://github.com/openai/codex)\n\n### Babysitter Plugin\n- [Getting Started](./reference/GETTING_STARTED.md)\n- [Process Selection Guide](https://github.com/a5c-ai/babysitter/blob/main/docs/reference/PROCESS_SELECTION.md)\n- [Troubleshooting](https://github.com/a5c-ai/babysitter/blob/main/docs/reference/TROUBLESHOOTING.md)\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": []
}