Repository Settings

Repository Settings

This page covers settings that live in the consumer GitHub repository or organization: repository features, starter files, secrets, variables, and the AI environment bundle.

For hosted-service operator runtime variables, GitHub App registration, and webhook routing, see App Server Settings.

Repository Features

Enable these features in the consumer repository:

Feature	Where	Why
Issues	Settings -> General -> Features	Bugs, implementation tasks, labels, and PR conversation comments use issue APIs
Actions	Settings -> Actions	Wrapper workflows call reusable GitVibe workflows
Discussions	Settings -> General -> Features	Optional; feature refinement and materialization start from Discussions

Create the Discussion category named by GITVIBE_DISCUSSION_CATEGORY only when you use Discussion-backed feature workflows. The default category is Ideas.

Install GitVibe for GitHub on repositories you want GitVibe to manage. Customer repositories do not create repo-level webhooks or a GITVIBE_GITHUB_TOKEN secret for hosted auth.

Starter Files

Install the consumer starter from the consumer repository root:

npx git-vibe-setup setup

The starter adds:

.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

git-vibe-setup fetches examples/consumer from the selected GitVibe release. The wrapper workflows are small repository-local entrypoints. They call reusable workflows from the pinned GitVibe release.

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

npx git-vibe-setup update

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

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

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

The exact tag may be a prerelease tag. Consumer wrapper workflows can call prerelease reusable workflows as long as that Git tag exists and contains the reusable workflow files:

jobs:
  validate:
    uses: markhuangai/git-vibe/.github/workflows/validate.yml@v3.0.4-rc.1

Use automatic prerelease lookup only when you explicitly want the latest non-draft prerelease to be eligible:

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

Repository Secrets

Create secrets in:

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

Secret	Required	Value
GITVIBE_AI_ENV_JSON	Yes for AI stages	JSON object containing AI provider keys, endpoints, and optional SDK auth

Do not commit these values into .github/git-vibe.yml or repository files.

The hosted GitVibe App handles GitHub writes. Do not add a repository PAT secret for GitVibe.

Repository Variables

Create variables in:

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

Variable	Required	Value
GITVIBE_BASE_BRANCH	No	Branch ref used for workflow dispatch; empty means repository default branch
GITVIBE_DISCUSSION_CATEGORY	No	Discussion category for feature issue conversion; default Ideas
GITVIBE_AI_MODEL	No	Optional model override for the AI smoke workflow

Variables are not secret. Do not store tokens, API keys, or OAuth values in repository variables.

AI Environment Bundle

GITVIBE_AI_ENV_JSON must be valid JSON. Every value must be a string.

Minimal Claude Code SDK bundle:

{
  "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 read CODEX_BASE_URL through base_url.from_bundle and the proxy API key through api_key.from_bundle. Current GitVibe workflows do not store or refresh Codex auth.json.

Map bundle keys from .github/git-vibe.yml profiles. Profile examples live in Configuration.

Consumer Config

Repository settings and secrets only provide access. The runner still needs .github/git-vibe.yml to know which AI profile and validation commands to use. Use Linux or macOS GitHub Actions runners for GitVibe workflows; Windows runners are unsupported.

Minimum config checklist:

• At least one ai.profiles entry.
• Every ai.stages entry points to a profile or role_group.
• tests.commands matches the repository's validation gate.
• Role-group markdown files are filled when a stage uses role_group.

Use Configuration for the full active config reference.