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:

bash

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:

bash

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:

bash

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:

yaml

jobs:
  validate:
    uses: markhuangai/git-vibe/.github/workflows/[email protected]

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

bash

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:

json

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

Optional Codex SDK auth:

json

{
  "CODEX_AUTH_JSON": "<escaped ~/.codex/auth.json>"
}

For Codex auth JSON, store escaped file contents:

bash

jq -Rs . < ~/.codex/auth.json

When a codex-sdk profile uses auth_json.from_bundle, GitVibe can write refreshed Codex auth back to GITVIBE_AI_ENV_JSON through the hosted GitHub App secrets-write path.

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.