Quick Start

Quick Start

This page is the setup path for a repository owner who wants to start using GitVibe. It avoids architecture details and points to deeper pages only when needed.

Use this page when you need to:

• install the starter files with git-vibe-setup,
• configure .github/git-vibe.yml,
• add required AI secrets and repository variables,
• install the hosted GitVibe GitHub App,
• run the first GitVibe command or label.

For system design and internals, use the developer guides: Architecture, AI and Stage Contracts, and Development and Testing.

1. Confirm Requirements

In the consumer repository:

• Issues are enabled.
• GitHub Actions are enabled.
• Discussions are enabled only if you want feature refinement or materialization from Discussions.
• You have admin access to install GitHub Apps and create Actions secrets.
• Your organization allows the hosted GitVibe GitHub App installation.

For the full preflight checklist, see Setup Requirements.

2. Install Starter Files

Run this from the consumer repository root:

npx git-vibe-setup setup

The installer adds the files GitVibe needs:

.github/git-vibe.yml
.github/workflows/investigate.yml
.github/workflows/materialize.yml
.github/workflows/review.yml
.github/workflows/validate.yml
.git-vibe/role-group/correctness.md
.git-vibe/role-group/maintainability.md
.git-vibe/role-group/security.md

The installer fetches examples/consumer from the latest stable GitVibe release, pins reusable workflow refs to that release, and refuses to overwrite existing files.

Read more: Repository Settings.

To refresh existing GitVibe wrapper workflows after upgrading git-vibe-setup, run:

npx git-vibe-setup update

update migrates supported .github/git-vibe.yml settings in place, rewrites .github/workflows/*.yml GitVibe wrapper files, and pins them to the latest stable GitVibe release. It does not change .git-vibe, secrets, or variables, and it refuses to overwrite same-named workflow files that do not look like GitVibe wrappers.

For prerelease testing, use a git-vibe-setup version that supports release selection and pin an exact GitVibe release tag:

npx git-vibe-setup@<setup-version> update --release <git-vibe-release-tag>

Use --include-prereleases only when automatic latest-release lookup should be allowed to choose prereleases:

npx git-vibe-setup@<setup-version> update --include-prereleases

3. Configure .github/git-vibe.yml

Open:

.github/git-vibe.yml

At minimum:

• configure one ai.profiles entry,
• route each ai.stages entry to a profile or role_group,
• set tests.commands to the repository's validation commands,
• optionally add bot logins to safety.ignored_authors if their comments should be omitted from GitVibe safety scans and model context,
• adjust .git-vibe/role-group/*.md if you use role groups.

Read more: Configuration.

4. Add Repository Secrets And Variables

Create repository or organization secrets:

Repository Settings
-> Secrets and variables
-> Actions
-> Secrets

Required for AI stages:

Secret	Value
GITVIBE_AI_ENV_JSON	JSON object with AI provider keys, endpoint values, and optional SDK auth

Minimal GITVIBE_AI_ENV_JSON:

{
  "GITVIBE_AI_API_KEY": "your-provider-key",
  "GITVIBE_AI_BASE_URL": "https://api.provider.example/v1",
  "CODEX_BASE_URL": "https://codex-proxy.example/v1"
}

Codex SDK profiles require base_url.from_bundle and api_key.from_bundle in .github/git-vibe.yml. GitVibe passes those values directly to the Codex SDK for current workflows and does not prepare ~/.codex/auth.json.

Optional repository variables:

Repository Settings
-> Secrets and variables
-> Actions
-> Variables

Variable	Value
GITVIBE_BASE_BRANCH	Branch ref used for workflow dispatch; empty means repository default branch
GITVIBE_DISCUSSION_CATEGORY	Discussion category, default Ideas
GITVIBE_AI_MODEL	Optional AI smoke-test model override

Read more: Repository Settings.

5. Install The Hosted GitHub App

Install GitVibe for GitHub on the repositories you want GitVibe to manage.

Repository owners do not run the app server, register webhooks, create a GITVIBE_GITHUB_TOKEN PAT secret, or manage GitHub App private keys. Hosted GitVibe owns the app server, webhook registration, and short-lived GitHub App token exchange.

After installation, GitVibe bootstraps managed labels from GitHub App installation and repository events.

Read more: Repository Settings and Security and Permissions.

6. Run The First GitVibe Action

Start with a read-only or planning-oriented action:

Task	Human action	Result
Investigate a bug issue	Add git-vibe:investigate or comment /git-vibe investigate	Posts findings
Validate issue or discussion	Add git-vibe:validate	Posts validation result
Materialize feature discussion	After gvi:validated, add git-vibe:approved or comment /git-vibe materialize	Creates implementation issue(s)
Review an existing PR	Add git-vibe:review to the pull request	Runs review matrix

Command and label details live in Commands and Labels.