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

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]

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