Configuration

This page owns .github/git-vibe.yml, AI profiles, stage routing, validation commands, prompt additions, and AI secret bundle shape.

Configuration Boundaries

GitVibe has two configuration surfaces:

flowchart TD
  Env[Hosted app runtime env] --> App[Hosted app server]
  Vars[GitHub repository variables] --> App
  Vars --> Runner[Reusable workflow runner]
  Yaml[.github/git-vibe.yml] --> Runner
  Secrets[GitHub secrets] --> Runner
  Secrets --> App

  App -->|webhooks, permission checks, workflow dispatch| GitHub[GitHub API]
  Runner -->|AI stages, tests, deterministic writes| GitHub

Current implementation detail:

Repository owners do not configure hosted app runtime env. The example config includes future-facing sections. Today, the app hard-codes the command prefix, managed labels, and trusted permission set. Treat this page as the source for implemented config behavior.

Minimal Active Runner Config

version: 1
​
ai:
  profiles:
    codex_sdk:
      adapter: codex-sdk
      auth_json:
        from_bundle: CODEX_AUTH_JSON
      model: gpt-5.3-codex
      reasoning:
        effort: high
        summary: concise
    claude_code:
      adapter: claude-code-sdk
      env:
        ANTHROPIC_API_KEY:
          from_bundle: GITVIBE_AI_API_KEY
        ANTHROPIC_BASE_URL:
          from_bundle: GITVIBE_AI_BASE_URL
        ANTHROPIC_DEFAULT_OPUS_MODEL: kimi-k2.5
        ANTHROPIC_DEFAULT_SONNET_MODEL: kimi-k2.5
        ANTHROPIC_DEFAULT_HAIKU_MODEL: kimi-k2.5
        ANTHROPIC_MODEL: opus
        CLAUDE_CODE_SUBAGENT_MODEL: opus
      model: opus
      reasoning:
        effort: high
  role_groups:
    review_gate:
      synthesizer: codex_sdk
      parallel: 2
      roles:
        - role: correctness.md
          profile: claude_code
        - role: security.md
          profile: claude_code
        - role: maintainability.md
          profile: claude_code
  stages:
    investigate:
      role_group: review_gate
    validate:
      role_group: review_gate
    materialize:
      profile: codex_sdk
    review-matrix:
      role_group: review_gate
​
tests:
  commands: []

Every active stage must define profile or role_group. GitVibe fails fast if a stage has no explicit profile routing.

Current runtime stage keys are investigate, validate, materialize, and review-matrix. Older starter configs may still contain stage entries such as implement, create-pr, or address-pr-feedback; current workflows do not dispatch those stages, so those entries are inert.

AI Profiles

Profiles live under:

ai:
  profiles:
    <profile-name>:
      adapter: ...

Common fields:

Claude Code SDK Profile

ai:
  profiles:
    claude_code:
      adapter: claude-code-sdk
      env:
        ANTHROPIC_API_KEY:
          from_bundle: GITVIBE_AI_API_KEY
        ANTHROPIC_BASE_URL:
          from_bundle: GITVIBE_AI_BASE_URL
        ANTHROPIC_DEFAULT_OPUS_MODEL: kimi-k2.5
        ANTHROPIC_DEFAULT_SONNET_MODEL: kimi-k2.5
        ANTHROPIC_DEFAULT_HAIKU_MODEL: kimi-k2.5
        ANTHROPIC_MODEL: opus
        CLAUDE_CODE_SUBAGENT_MODEL: opus
      model: opus
      reasoning:
        effort: high

Rules:

• env entries may be literals or { from_bundle: KEY } mappings from GITVIBE_AI_ENV_JSON.
• GitVibe calls the Claude Code SDK with a separate system prompt, user prompt, strict JSON schema output format, permission bypass, no session persistence, and isolated MCP configuration.
• reasoning.effort supports Claude Code SDK effort values such as high, xhigh, and max.

Codex SDK Profile

ai:
  profiles:
    codex_sdk:
      adapter: codex-sdk
      auth_json:
        from_bundle: CODEX_AUTH_JSON
      model: gpt-5.3-codex
      reasoning:
        effort: high
        summary: concise

GitVibe creates an isolated CODEX_HOME for each codex-sdk run and calls the Codex SDK with schema output validation. The adapter combines GitVibe's rendered system and user prompts into the prompt passed to the Codex thread. The selected SDK adapter resolves its native executable after profile selection, so reusable stage actions do not prepare Codex or Claude Code executables before knowing which profile will run.

When auth_json.from_bundle is used, GitVibe can write refreshed Codex auth back to GITVIBE_AI_ENV_JSON. That path requires the GitHub App Secrets permission listed in GitHub App Permissions.

Legacy Adapter Migration

git-vibe-setup update migrates removed adapter names in existing .github/git-vibe.yml files:

• ai-sdk-agentool -> claude-code-sdk
• cli-claude-code -> claude-code-sdk
• cli-codex -> codex-sdk

For ai-sdk-agentool profiles, the migration preserves the profile name, moves provider.api_key and provider.base_url into Claude environment mappings, copies provider.model into the Claude default model env values, sets model: opus, and removes Agentool-only provider fields. Runtime fallback for removed adapters is not supported.

Stage Routing

Stages live under:

ai:
  stages:
    investigate:
      profile: codex_sdk

Routing rules:

A stage cannot define both profile and role_group. role_group is allowed only for read-only stages: investigate, validate, and review-matrix.

Default stage targets, schemas, tools, and next states are in Stage Reference.

MCP Context And Tools

MCP server definitions live under ai.mcp.servers. Stage entries under ai.stages.<stage>.mcp choose which servers are active and which MCP tools may be used by that stage.

ai:
  mcp:
    servers:
      dense_mem:
        transport: stdio
        command: node
        args: ["./scripts/dense-mem-mcp.js"]
        env:
          DENSE_MEM_API_KEY:
            from_bundle: DENSE_MEM_API_KEY
​
  stages:
    review-matrix:
      mcp:
        dense_mem:
          required: false
          tools: ["search_memory"]

MCP rules:

tools is an allowlist, not a required capability list. If an allowlisted model tool is missing from the MCP server's actual listTools result, GitVibe logs a warning and continues without exposing that tool. Required MCP servers still block the stage when GitVibe cannot connect, list tools, or complete required deterministic context_calls.

Tests Commands

tests.commands is repository-owned validation guidance for investigation handoffs and future implementation work. Current GitVibe workflows do not run these commands automatically because code-writing stages are removed.

tests:
  commands:
    - pnpm install --frozen-lockfile
    - pnpm check

Keep the commands accurate so investigation and validation results can point a human implementer at the right repository gate.

AI Budgets

Runtime-supported workflow budget keys:

The starter config may contain older or forward-compatible budget names such as implementation, feedback, repair, retry, and iteration controls. Current runtime code ignores those keys unless they are added to the workflow budget mapping.

Repository Prompt Additions

Consumer repositories can append prompt text without replacing GitVibe stage contracts:

.git-vibe/prompts/<stage>/system.md
.git-vibe/prompts/<stage>/user.md

Example:

.git-vibe/prompts/review-matrix/user.md
.git-vibe/prompts/validate/system.md

The stage folder name matches the prompt directory in Stage Reference. Additions are wrapped in a repository-provided XML section after GitVibe-controlled prompt content.

Secret Bundle Shape

GITVIBE_AI_ENV_JSON is a GitHub secret, not a config file. Every value must be a string:

{
  "GITVIBE_AI_API_KEY": "...",
  "GITVIBE_AI_BASE_URL": "https://api.provider.example/v1",
  "CODEX_AUTH_JSON": "<escaped ~/.codex/auth.json>"
}

Profiles read bundle values through:

from_bundle: GITVIBE_AI_API_KEY

GitVibe passes only explicitly mapped profile environment values plus the adapter-required isolated runtime environment.

Config Failure Modes