Operations And Troubleshooting

This page is for GitVibe service operators. Repository owners using hosted GitVibe normally troubleshoot repository secrets, wrapper workflows, labels, and AI profiles instead of running the app server.

This page covers running, monitoring, and diagnosing the hosted GitVibe app server and workflows.

Runtime Paths

flowchart TD
  A[Start server] --> B[Load GitHub App credentials]
  B --> C[Listen on PORT]
  C --> D[GET /health]
  C --> E[POST /webhooks]
  E --> F[Installation or repository event]
  F --> G[Bootstrap labels for installed repositories]

Repository-specific setup runs from GitHub App webhooks. The app does not need a deploy-time GITHUB_REPOSITORY value and does not run deploy-time repository checks.

Health Check

curl -fsS http://localhost:3000/health

Expected response:

{ "ok": true }

Docker Compose

GITHUB_WEBHOOK_SECRET=... \
GITHUB_APP_ID=... \
GITVIBE_APP_PRIVATE_KEY=... \
docker compose up -d

Compose reads:

• GITVIBE_IMAGE, default ghcr.io/markhuangai/git-vibe:latest
• GITHUB_API_URL, default https://api.github.com
• GITHUB_APP_ID, required
• GITHUB_WEBHOOK_SECRET, required
• GITVIBE_APP_PRIVATE_KEY, required
• GITVIBE_DISCUSSION_CATEGORY, default Ideas

Runtime env details live in Runtime Environment.

Deployment Workflow

The release workflow detects app-impacting changes when an admin creates a release tag. App-impacting releases build and push the semantic image tag:

ghcr.io/markhuangai/git-vibe:<release-tag>

Prerelease tags from dev deploy only when app-impacting files changed. Runner-only prereleases still publish the GitHub release and pinned reusable workflows, but skip app image build and deployment. Stable tags from main publish stable and latest images only when app-impacting files changed.

When deployment runs, Docker Compose executes on the app runner. If /opt/git-vibe/docker-compose.override.yml exists on the host, the deploy workflow includes it for host-specific reverse proxy, network, or label settings.

Operational Checks

flowchart TD
  A[Webhook not working] --> B[Check /health]
  B --> C[Check GitHub webhook delivery status]
  C --> D[Check signature secret matches]
  D --> E[Check app logs]
  E --> F[Check GitHub App permissions]
  F --> G[Check workflow run and result artifact]

Common Symptoms

Workflow Debugging

Each runner stage writes result JSON under RUNNER_TEMP when available and uploads result artifacts in reusable workflows. Stage prompts reference context files in a unique per-run temp directory such as git-vibe-<stage>-*/git-vibe-<stage>-context-files/manifest.json, plus per-unit text files under the same context directory, so SDK agents can inspect exact context without large inline prompt payloads.

Examples:

git-vibe-investigate-*/git-vibe-investigate-context.json
git-vibe-investigate-*/git-vibe-investigate-context-files/manifest.json
git-vibe-investigate-*/git-vibe-investigate-context-files/units/0002-artifact-body-*.txt
git-vibe-investigate-result.json
git-vibe-review-matrix-result.json

Use these artifacts to compare what the model saw with what the schema-validated result said. Durable GitHub comments are rendered from the validated result.

AI Provider Debugging

flowchart LR
  A[AI failure] --> B{Adapter}
  B -->|codex-sdk| C[Check CODEX_AUTH_JSON and isolated CODEX_HOME setup]
  B -->|claude-code-sdk| D[Check profile env mappings]
  C --> F[Run AI smoke workflow]
  D --> F

The AI smoke workflow is documented in AI Smoke Tests.

Recovery Rules

• Retry investigation after adding missing maintainer answers.
• Retry validation after clarifying acceptance criteria.
• Rerun PR review with git-vibe:review after fixes or new review context.
• Do not manually add gvi: labels to force state. Use public trigger labels and comments so GitVibe can preserve traceability.