Architecture

GitVibe is a pnpm workspace. The root @git-vibe/app package is split by runtime ownership, while packages/git-vibe-setup ships the standalone consumer setup CLI. The app server orchestrates GitHub events. Reusable workflows and composite actions execute AI stages on GitHub runners.

Runtime Boundaries

src/
  app/       webhook server and repository orchestration
  runner/    action runtime, context, prompts, schemas, AI, stage writes
  shared/    GitHub helpers, labels, stages, traceability, shared types

flowchart LR
  App[src/app] --> Shared[src/shared]
  Runner[src/runner] --> Shared
  Docker[Docker image] --> App
  Docker --> Shared
  Actions[Composite actions] --> Runner
  Actions --> Shared

The Docker image builds app and shared output. Composite actions build runner code on the GitHub runner before executing a stage.

System Shape

flowchart LR
  User[Guest or contributor] --> GH[GitHub issues, discussions, PRs]
  Maintainer[Admin, maintain, or write actor] --> GH
  GH -->|webhook| App[Hosted GitVibe app]
  App -->|verify signature| App
  App -->|check collaborator permission| API[GitHub API]
  App -->|labels, comments, workflow dispatch| API
  API --> WF[GitHub Actions workflow]
  WF --> Runner[GitVibe runner action]
  Runner --> AI[Codex SDK or Claude Code SDK]
  Runner --> Checkout[repository checkout]
  Runner -->|comments, labels, issues, PR reviews| API

Webhook Request Path

sequenceDiagram
  participant GH as GitHub
  participant App as GitVibe app
  participant API as GitHub API
  participant WF as Workflow

  GH->>App: POST /webhooks with x-hub-signature-256
  App->>App: Verify HMAC SHA-256 signature
  App->>API: Bootstrap managed labels if needed
  App->>API: Check actor permission for protected action
  App->>API: Add or remove labels and comments
  App->>API: Dispatch reusable workflow
  API->>WF: Start Actions run

The hosted app accepts:

GET /health
POST /webhooks
POST /actions/token
POST /actions/codex-auth

Other routes return 404.

App Responsibilities

Area	Behavior
Webhook verification	Verifies GitHub `x-hub-signature-256`
Label bootstrap	Creates managed `git-vibe:` and `gvi:` labels
Actor authorization	Accepts trusted actors with `write`, `maintain`, or `admin` repository permission
Feature issue intake	Converts feature issue forms into linked Discussions when possible
Command dispatch	Handles `/git-vibe investigate` on issues and `/git-vibe materialize` on validated Discussions
Label dispatch	Handles protected labels, including `git-vibe:accept-risk`
PR review events	Marks trusted approvals and logs ignored non-approval review submissions
PR state tracking	Marks trusted approvals and merged GitVibe-traced PRs

App runtime values are listed in Runtime Environment.

Runner Responsibilities

Area	Behavior
Config loading	Reads `.github/git-vibe.yml` from the consumer workspace
Context assembly	Builds issue, discussion, or PR context packets
Prompt rendering	Combines GitVibe prompts, repository prompt additions, schema, and context
AI execution	Routes to `codex-sdk` or `claude-code-sdk` profiles
Validation	Validates stage output against JSON Schema
Deterministic writes	Applies label transitions, comments, materialized issues, PR reviews, and handoffs
Artifacts	Writes result JSON under `RUNNER_TEMP` and file-backed prompt context under a unique per-run temp directory

Stage details live in AI and Stage Contracts.

Event Delivery

flowchart TD
  GH[GitHub events] --> Webhook[webhook mode]
  GH --> Relay[relay mode]
  GH --> Actions[actions receiver mode]
  GH --> Polling[polling mode]

  Webhook --> Implemented[Implemented]
  Relay --> Planned[Planned]
  Actions --> Planned
  Polling --> Planned

Mode	Status	Notes
`webhook`	Implemented	Production default; GitHub sends GitHub App webhooks to the hosted app server
`relay`	Planned	Intended for tunnel or relay providers
`actions`	Planned	Intended for no-server receiver workflows
`polling`	Planned	Intended for scheduled GitHub API scans

Workflow Dispatch Ref

When dispatching workflows, GitVibe chooses the workflow ref from:

flowchart TD
  A[Read repository variable GITVIBE_BASE_BRANCH] --> B{Value present?}
  B -->|yes| C[Use configured branch]
  B -->|no| D[Read repository default branch]
  D --> E[Use default branch]

Workflow dispatch also reads GITVIBE_BASE_BRANCH. When the variable is empty or missing, GitVibe dispatches reusable workflows on the repository default branch.