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,
• 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:

Minimal GITVIBE_AI_ENV_JSON:

{
  "GITVIBE_AI_API_KEY": "your-provider-key",
  "GITVIBE_AI_BASE_URL": "https://api.provider.example/v1",
  "CODEX_AUTH_JSON": "<escaped ~/.codex/auth.json>"
}

If you remove Codex SDK profiles from .github/git-vibe.yml, CODEX_AUTH_JSON is not required. When it is used, store escaped auth.json contents, for example jq -Rs . < ~/.codex/auth.json.

Optional repository variables:

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

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:

Command and label details live in Commands and Labels.