Setup Requirements

Setup Requirements

This page is the preflight checklist. Detailed settings are split by where they live:

Setting area	Page
GitHub repository features, starter files, secrets, variables, AI bundle, App installation	Repository Settings
Hosted app operator runtime env, Docker Compose, public URL, and GitHub App webhooks	App Server Settings
.github/git-vibe.yml, AI profiles, stages, tests	Configuration
App permissions and trust boundaries	Security and Permissions

Components

flowchart LR
  subgraph ConsumerRepo[Consumer repository]
    Config[.github/git-vibe.yml]
    Wrappers[wrapper workflows]
    Secrets[repo or org secrets]
  end

  subgraph Hosted[Hosted GitVibe service]
    Server[GitVibe app server]
    RuntimeEnv[operator runtime environment]
  end

  subgraph GitHub[GitHub]
    Webhook[GitHub App webhook]
    Actions[Actions runner]
    API[GitHub API]
  end

  Webhook --> Server
  Server --> API
  Server --> Actions
  Actions --> Config
  Actions --> Secrets

Loading

Repository Checklist

Requirement	Where to configure
Issues enabled	Repository Settings -> General -> Features
Discussions enabled, optional	Repository Settings -> General -> Features
Discussion category exists, default Ideas	Required only when using Discussion-backed feature workflows
Actions enabled	Repository Settings -> Actions
Starter files installed	npx git-vibe-setup setup
Existing workflow wrappers updated	npx git-vibe-setup update
Optional prerelease wrapper test	npx git-vibe-setup@<setup-version> update --release <git-vibe-release-tag>
Linux or macOS Actions runner	GitVibe workflows and composite actions do not support Windows runners
Current GitHub Actions runner image	Workflows use Node 24-backed action majors while running project code on Node 22
Hosted GitVibe GitHub App installed	GitVibe for GitHub
Repository secrets created	Repository Settings -> Secrets and variables -> Actions -> Secrets
Optional repository variables created	Repository Settings -> Secrets and variables -> Actions -> Variables

Exact token and secret settings live in Repository Settings.

Hosted App Operator Checklist

Repository owners using hosted GitVibe do not complete this checklist. It is for the GitVibe service operator.

Requirement	Notes
Public HTTPS endpoint	GitHub must reach POST /webhooks
Docker and Docker Compose	Required for the packaged container path
Node 22 plus Corepack	Required only for local source builds
Trusted Linux or macOS runner for SDK adapters	codex-sdk and claude-code-sdk run with GitVibe-managed permission bypass
Network egress controls	Required when prompt-guided web policy is not strict enough

Runtime variables, Compose examples, webhook fields, and routing checks live in App Server Settings.

Endpoint Checklist

For hosted GitVibe, repository owners use the hosted App and do not configure these endpoints themselves.

Purpose	Method and path
Health check	GET /health
GitHub webhook	POST /webhooks

The hosted GitHub webhook Payload URL is:

https://git-vibe.markhuang.ai/webhooks

Setup Checklist

flowchart TD
  A[Install starter files] --> B[Configure .github/git-vibe.yml]
  B --> C[Create repository secrets and variables]
  C --> D[Install hosted GitHub App]
  D --> E[GitHub App webhooks bootstrap labels]
  E --> F[Run AI smoke test if needed]
  F --> G[Trigger investigation, validation, or materialization]

Loading

Official Setup Links

Task	Link
Git setup	Set up Git - GitHub Docs
Docker install	Docker Engine install docs
Docker Desktop	Docker Desktop docs
Node.js	Download Node.js
Corepack	Corepack README
pnpm	pnpm installation
GitHub Discussions	Enable GitHub Discussions
GitHub secrets	Using secrets in GitHub Actions
GitHub variables	Store information in variables
GitHub Apps	About creating GitHub Apps
GitHub webhooks	About webhooks