Operations and Troubleshooting

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]

Loading

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]

Loading

Common Symptoms

Symptom	Likely cause	Check
GITHUB_WEBHOOK_SECRET is required	Runtime env missing	Runtime Environment
invalid GitHub signature	Webhook secret mismatch	GitHub webhook secret and app env
Command returns 403	Actor is not write, maintain, or admin	Trusted Actor Model
Protected label removed	Untrusted actor or invalid internal label	Protected Label Policy
Approval label on issue has no effect	Code-writing workflows are removed; issue approval is a trusted no-op	Public Trigger Labels
Workflow dispatch fails	GitHub App lacks Actions or workflow access	GitHub App Permissions
/actions/token returns 422	GitHub App installation has not granted a requested permission, often Checks read	GitHub App Permissions
Feature issue conversion fails	Discussions disabled, category missing, or token lacks Discussions access	Repository Features
AI profile error	Missing stage profile or bundle key	Config Failure Modes
SDK adapter setup fails	Runner lacks Node, pnpm/Corepack, npm path, or network	Hosted App Operator Checklist
Review label removed from an issue	Standalone review automation only runs on pull requests	Public Trigger Labels
Review repeats the full PR	No valid completed checkpoint, base change, rewritten history, or oversized compare	Review result marker and review_checkpoint log field
Review result rejected as superseded	A newer commit arrived after the run froze its target	review_target log field and current PR head
Review snapshot mismatch	A downstream job reconstructed different files or checkpoint state	Security job outputs, changed PR timeline, and GitHub compare response

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. Review context JSON includes reviewScope.baseSha, optional reviewScope.checkpointSha, reviewScope.targetSha, and reviewScope.snapshotSha. The runner also logs review_checkpoint and review_target. 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_BASE_URL and GITVIBE_AI_API_KEY bundle values]
  B -->|claude-code-sdk| D[Check profile env mappings]
  C --> F[Run AI smoke workflow]
  D --> F

Loading

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 restart from a canceled run's target SHA. GitVibe resumes from the latest completed review result that was actually published.
• Do not manually add gvi: labels to force state. Use public trigger labels and comments so GitVibe can preserve traceability.