{
  "id": "page:docs-github-actions-setup-babysitter",
  "_kind": "Page",
  "_file": "wiki/docs/github-actions-setup-babysitter.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/github-actions-setup-babysitter.md",
    "sourceKind": "repo-docs",
    "title": "Using the Babysitter GitHub Action",
    "displayName": "Using the Babysitter GitHub Action",
    "slug": "docs/github-actions-setup-babysitter",
    "articlePath": "wiki/docs/github-actions-setup-babysitter.md",
    "article": "\n# Using the Babysitter GitHub Action\n\nThis guide explains how to use the official [Babysitter GitHub Action](https://github.com/a5c-ai/babysitter) (`a5c-ai/babysitter@main`) for automated, AI-orchestrated workflows in your CI/CD pipeline.\n\n## Overview\n\nThe Babysitter action is **harness-agnostic** — it supports multiple AI harnesses (pi, claude-code, codex, gemini-cli, and more) through a single action interface. It builds the local `babysitter-agent` runtime from the action repository, resolves credentials for the selected provider, and runs `babysitter-agent yolo` to execute deterministic, event-sourced orchestration with quality gates, iterative refinement, and multi-step process management.\n\nUnlike harness-specific actions (`anthropics/claude-code-action`, `openai/codex-action`, `google-github-actions/run-gemini-cli`), this action lets you switch harnesses with a single input change while keeping the same workflow structure.\n\n## Quick Start\n\n### Basic Setup\n\n```yaml\nname: Babysitter\n\non:\n  issue_comment:\n    types: [created]\n  issues:\n    types: [opened, assigned]\n\njobs:\n  babysitter:\n    if: |\n      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@babysitter')) ||\n      (github.event_name == 'issues' && contains(github.event.issue.body, '@babysitter'))\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: Run Babysitter\n        uses: a5c-ai/babysitter@main\n        with:\n          prompt: |\n            ${{ github.event.comment.body || github.event.issue.body }}\n          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}\n```\n\n### With a Specific Harness and Model\n\n```yaml\n- name: Run Babysitter\n  uses: a5c-ai/babysitter@main\n  with:\n    prompt: 'Review this PR for code quality and security issues'\n    harness: codex\n    model: openai:gpt-4.1\n    openai-api-key: ${{ secrets.OPENAI_API_KEY }}\n```\n\n### Using the Internal Harness (Default)\n\nThe `internal` harness uses a programmatic pi-coding-agent — no external CLI needed. It reads credentials from environment variables and resolves models via the `provider:modelId` pattern:\n\n```yaml\n- name: Run Babysitter\n  uses: a5c-ai/babysitter@main\n  with:\n    prompt: 'Implement the feature described in this issue'\n    model: anthropic:claude-sonnet-4-20250514\n    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}\n```\n\n## Authentication\n\n### Provider Credentials\n\nPass the API key matching your model's provider:\n\n| Provider | Input | Environment Variable |\n|----------|-------|---------------------|\n| Anthropic | `anthropic-api-key` | `ANTHROPIC_API_KEY` |\n| OpenAI | `openai-api-key` | `OPENAI_API_KEY` |\n| Google Gemini | `gemini-api-key` | `GEMINI_API_KEY` |\n| Azure OpenAI | `azure-openai-api-key` | `AZURE_OPENAI_API_KEY` |\n\n### Azure OpenAI Configuration\n\nAzure requires additional configuration beyond the API key:\n\n```yaml\n- uses: a5c-ai/babysitter@main\n  with:\n    prompt: 'Your task'\n    model: azure-openai-responses:gpt-4.1\n    azure-openai-api-key: ${{ secrets.AZURE_OPENAI_API_KEY }}\n    azure-openai-project-name: ${{ vars.AZURE_OPENAI_PROJECT_NAME }}\n    azure-openai-deployment: ${{ vars.AZURE_OPENAI_DEPLOYMENT }}\n    azure-openai-base-url: ${{ vars.AZURE_OPENAI_BASE_URL }}\n```\n\n### Model Selection\n\nModels use the `provider:modelId` format. The provider determines which API key is required:\n\n```yaml\n# Anthropic\nmodel: anthropic:claude-sonnet-4-20250514\nmodel: anthropic:claude-opus-4-5\n\n# OpenAI\nmodel: openai:gpt-4.1\nmodel: openai:o4-mini\n\n# Azure OpenAI\nmodel: azure-openai-responses:gpt-4.1\n\n# Bare model ID (auto-detected from available credentials)\nmodel: claude-sonnet-4-20250514\n```\n\n## Configuration Options\n\n### Action Inputs\n\n| Input | Required | Default | Description |\n|-------|----------|---------|-------------|\n| `prompt` | No | — | Task prompt. GitHub context vars available via shell expansion. |\n| `harness` | No | `internal` | AI harness: internal, pi, claude-code, codex, gemini-cli |\n| `model` | No | — | Model in `provider:modelId` format |\n| `process-path` | No | — | Path to process definition (skips Phase 1) |\n| `workspace` | No | `$GITHUB_WORKSPACE` | Working directory |\n| `max-iterations` | No | `65000` | Max orchestration iterations |\n| `runs-dir` | No | `~/.a5c/runs` | Run state directory |\n| `timeout-minutes` | No | `30` | Step timeout |\n| `verbose` | No | `false` | Enable debug output |\n| `anthropic-api-key` | No | — | Anthropic API key |\n| `openai-api-key` | No | — | OpenAI API key |\n| `gemini-api-key` | No | — | Google Gemini API key |\n| `azure-openai-api-key` | No | — | Azure OpenAI API key |\n| `azure-openai-project-name` | No | — | Azure resource name |\n| `azure-openai-deployment` | No | — | Azure deployment name |\n| `azure-openai-base-url` | No | — | Azure endpoint URL |\n| `github-token` | No | `${{ github.token }}` | GitHub API token |\n\n### Action Outputs\n\n| Output | Description |\n|--------|-------------|\n| `run-id` | Babysitter run ID |\n| `run-dir` | Path to the run directory |\n| `status` | Final status: completed, failed, or unknown |\n| `iterations` | Number of orchestration iterations |\n\n## Workflow Examples\n\n### Issue Comment Handler\n\n```yaml\nname: Babysitter Issue Handler\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  babysitter:\n    if: |\n      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@babysitter')) ||\n      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@babysitter')) ||\n      (github.event_name == 'issues' && contains(github.event.issue.body, '@babysitter'))\n    runs-on: ubuntu-latest\n    permissions:\n      contents: write\n      pull-requests: write\n      issues: write\n      id-token: write\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 1\n\n      - uses: a5c-ai/babysitter@main\n        with:\n          prompt: ${{ github.event.comment.body || github.event.issue.body }}\n          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}\n```\n\n### PR Review\n\n```yaml\nname: Babysitter PR Review\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      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 1\n\n      - uses: a5c-ai/babysitter@main\n        with:\n          prompt: |\n            Review PR #${{ github.event.pull_request.number }} in ${{ github.repository }}.\n            Analyze for code quality, security vulnerabilities, performance, and test coverage.\n          harness: internal\n          model: anthropic:claude-sonnet-4-20250514\n          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}\n```\n\n### Feature Development (TDD)\n\n```yaml\nname: Babysitter TDD Feature\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: 60\n    permissions:\n      contents: write\n      pull-requests: write\n      issues: write\n      id-token: write\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n\n      - uses: a5c-ai/babysitter@main\n        with:\n          prompt: |\n            Implement the feature described in issue #${{ github.event.issue.number }}\n            in ${{ github.repository }} using TDD methodology.\n            Write failing tests first, implement, refactor, iterate until quality threshold is met.\n            Create a PR when complete.\n          max-iterations: '50'\n          timeout-minutes: '60'\n          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}\n```\n\n### GSD Quick Tasks\n\n```yaml\nname: Babysitter GSD\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      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 1\n\n      - uses: a5c-ai/babysitter@main\n        with:\n          prompt: |\n            Use GSD methodology for rapid implementation:\n            ${{ github.event.comment.body }}\n          max-iterations: '20'\n          timeout-minutes: '15'\n          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}\n```\n\n### Spec-Driven Development\n\n```yaml\nname: Babysitter Spec-Kit\n\non:\n  workflow_dispatch:\n    inputs:\n      spec_file:\n        description: 'Path to specification file'\n        required: true\n        type: string\n\njobs:\n  implement:\n    runs-on: ubuntu-latest\n    timeout-minutes: 60\n    permissions:\n      contents: write\n      pull-requests: write\n      id-token: write\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n\n      - uses: a5c-ai/babysitter@main\n        with:\n          prompt: |\n            Implement the specification at ${{ inputs.spec_file }} using Spec-Kit methodology.\n            Parse the spec, generate an implementation plan, implement with continuous validation,\n            and generate a compliance report.\n          timeout-minutes: '60'\n          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}\n```\n\n### Security Scanning\n\n```yaml\nname: Babysitter Security\n\non:\n  workflow_dispatch:\n  schedule:\n    - cron: '0 0 * * 1'\n\njobs:\n  security:\n    runs-on: ubuntu-latest\n    timeout-minutes: 30\n    permissions:\n      contents: write\n      pull-requests: write\n      security-events: write\n      id-token: write\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n\n      - uses: a5c-ai/babysitter@main\n        with:\n          prompt: |\n            Run a comprehensive security scan of ${{ github.repository }}.\n            Perform SAST analysis, dependency vulnerability scanning, and secret detection.\n            Report findings and create a PR with fixes where possible.\n          timeout-minutes: '30'\n          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}\n```\n\n### Architecture Documentation\n\n```yaml\nname: Babysitter Architecture Docs\n\non:\n  workflow_dispatch:\n  push:\n    paths: ['src/**', 'packages/**']\n\njobs:\n  docs:\n    runs-on: ubuntu-latest\n    timeout-minutes: 30\n    permissions:\n      contents: write\n      pull-requests: write\n      id-token: write\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n\n      - uses: a5c-ai/babysitter@main\n        with:\n          prompt: |\n            Generate architecture documentation for ${{ github.repository }}.\n            Create C4 model diagrams, system overview, data flow docs, and API docs.\n            Update the docs/ directory and create a PR.\n          timeout-minutes: '30'\n          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}\n```\n\n### Multi-Harness Example (Codex)\n\n```yaml\n- uses: a5c-ai/babysitter@main\n  with:\n    prompt: 'Implement and test the feature'\n    harness: codex\n    model: openai:o4-mini\n    openai-api-key: ${{ secrets.OPENAI_API_KEY }}\n```\n\n### Multi-Harness Example (Gemini CLI)\n\n```yaml\n- uses: a5c-ai/babysitter@main\n  with:\n    prompt: 'Analyze the codebase and generate documentation'\n    harness: gemini-cli\n    gemini-api-key: ${{ secrets.GEMINI_API_KEY }}\n```\n\n## Environment Variables\n\nConfigure babysitter behavior via environment variables on the workflow step:\n\n```yaml\n- uses: a5c-ai/babysitter@main\n  with:\n    prompt: 'Your task'\n    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}\n  env:\n    BABYSITTER_MAX_ITERATIONS: 50\n    BABYSITTER_QUALITY_THRESHOLD: 85\n    BABYSITTER_LOG_LEVEL: debug\n    BABYSITTER_TIMEOUT: 180000\n```\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `BABYSITTER_MAX_ITERATIONS` | `65000` | Max orchestration iterations |\n| `BABYSITTER_QUALITY_THRESHOLD` | `80` | Quality gate threshold (0-100) |\n| `BABYSITTER_LOG_LEVEL` | `info` | Logging: info, debug, warn, error |\n| `BABYSITTER_TIMEOUT` | `120000` | Operation timeout in ms |\n| `BABYSITTER_RUNS_DIR` | `~/.a5c/runs` | Run state directory override |\n| `BABYSITTER_RUNS_SCOPE` | `global` | Set to `repo` to keep runs under `<repo>/.a5c/runs` |\n\n## Artifacts and Outputs\n\n### Run Artifacts\n\nThe action automatically uploads babysitter run artifacts (journals, task results, blobs) as a GitHub Actions artifact named `babysitter-runs`. Configure retention:\n\n```yaml\n# Override in your workflow after the babysitter step\n- uses: actions/upload-artifact@v4\n  if: always()\n  with:\n    name: babysitter-runs\n    path: ~/.a5c/runs/\n    retention-days: 14\n```\n\n### Using Outputs\n\n```yaml\n- uses: a5c-ai/babysitter@main\n  id: babysitter\n  with:\n    prompt: 'Your task'\n    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}\n\n- name: Check results\n  run: |\n    echo \"Run ID: ${{ steps.babysitter.outputs.run-id }}\"\n    echo \"Status: ${{ steps.babysitter.outputs.status }}\"\n    echo \"Iterations: ${{ steps.babysitter.outputs.iterations }}\"\n```\n\n## Prompt Templates\n\nThe prompt input supports GitHub context variables via shell expansion. Common variables:\n\n| Variable | Description |\n|----------|-------------|\n| `${{ github.repository }}` | Owner/repo |\n| `${{ github.event_name }}` | Event type |\n| `${{ github.event.issue.number }}` | Issue number |\n| `${{ github.event.pull_request.number }}` | PR number |\n| `${{ github.event.comment.body }}` | Comment text |\n| `${{ github.sha }}` | Commit SHA |\n| `${{ github.ref }}` | Git ref |\n| `${{ github.actor }}` | Triggering user |\n\n## Troubleshooting\n\n### Babysitter Agent Runtime Build Failed\n\nThe action builds `babysitter-agent` from the action repository. If it fails, check Node.js availability:\n\n```yaml\n- uses: actions/setup-node@v4\n  with:\n    node-version: '22'\n```\n\n### Authentication Errors\n\nEnsure the correct API key secret is set for your harness/model:\n- `internal` or `claude-code` with Anthropic models → `ANTHROPIC_API_KEY`\n- `codex` or OpenAI models → `OPENAI_API_KEY`\n- `gemini-cli` → `GEMINI_API_KEY`\n- Azure models → `AZURE_OPENAI_API_KEY` plus project/deployment/URL\n\n### Runs Timing Out\n\n1. Reduce `max-iterations` (e.g., `50`)\n2. Increase `timeout-minutes`\n3. Use a simpler methodology (GSD vs TDD)\n4. Break the task into smaller pieces\n\n### No Output / Empty Results\n\nEnable verbose mode for debugging:\n\n```yaml\n- uses: a5c-ai/babysitter@main\n  with:\n    prompt: 'Your task'\n    verbose: 'true'\n    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}\n```\n\n## Reference\n\n### Babysitter\n- [Babysitter Repository](https://github.com/a5c-ai/babysitter)\n- [Babysitter Agent Runtime](https://github.com/a5c-ai/babysitter/tree/main/packages/babysitter-agent)\n- [Babysitter SDK](https://www.npmjs.com/package/@a5c-ai/babysitter-sdk)\n\n### Harness-Specific Actions\n- [Claude Code Action](https://github.com/anthropics/claude-code-action) — [Setup Guide](github-actions-setup-claude-code.md)\n- [Codex Action](https://github.com/openai/codex-action) — [Setup Guide](github-actions-setup-codex.md)\n- [Gemini CLI Action](https://github.com/google-github-actions/run-gemini-cli) — [Setup Guide](github-actions-setup-gemini-cli.md)\n\n### Marketplace Plugins\n- [github-actions-cicd-babysitter](https://github.com/a5c-ai/babysitter/blob/main/plugins/a5c/marketplace/plugins/github-actions-cicd-babysitter/configure.md) — Marketplace plugin for this action\n- [github-actions-cicd-claude-code](https://github.com/a5c-ai/babysitter/blob/main/plugins/a5c/marketplace/plugins/github-actions-cicd-claude-code/configure.md) — Claude Code specific\n- [github-actions-cicd-codex](https://github.com/a5c-ai/babysitter/blob/main/plugins/a5c/marketplace/plugins/github-actions-cicd-codex/configure.md) — Codex specific\n- [github-actions-cicd-gemini-cli](https://github.com/a5c-ai/babysitter/blob/main/plugins/a5c/marketplace/plugins/github-actions-cicd-gemini-cli/configure.md) — Gemini CLI specific\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs",
      "to": "page:docs-github-actions-setup-babysitter",
      "kind": "contains_page"
    }
  ]
}