App Server Settings

This page is for GitVibe service operators. Repository owners using hosted GitVibe do not run this app server, configure Docker Compose, manage the GitHub App private key, or register webhooks.

This page covers settings that live on the hosted GitVibe app server: Docker Compose, runtime environment variables, public routes, and GitHub App webhook setup.

For repository secrets, variables, and AI bundle shape, see Repository Settings.

Runtime Model

flowchart LR
  GitHub[GitHub App webhook] -->|POST /webhooks| Proxy[Public HTTPS URL]
  Proxy --> App[GitVibe app server]
  App -->|GitHub App installation token| Repo[Installed repository]
  Repo -->|reusable workflows| Runner[GitHub Actions runner]
  Runner -->|OIDC| App

The app accepts these public routes:

All other routes return 404.

Runtime Environment

The app reads environment variables from the process or container. It does not read .github/git-vibe.yml.

Do not configure GITVIBE_GITHUB_TOKEN or GITHUB_REPOSITORY for the hosted GitHub App path. GitVibe mints short-lived installation tokens from the App private key and repository identity in webhook or OIDC claims.

Docker Compose

Example:

services:
  git-vibe-app:
    image: ghcr.io/markhuangai/git-vibe:latest
    container_name: git-vibe-app
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      GITHUB_API_URL: ${GITHUB_API_URL:-https://api.github.com}
      GITHUB_APP_ID: ${GITHUB_APP_ID:?GITHUB_APP_ID is required}
      GITHUB_WEBHOOK_SECRET: ${GITHUB_WEBHOOK_SECRET:?GITHUB_WEBHOOK_SECRET is required}
      GITVIBE_ACTIONS_OIDC_AUDIENCE: ${GITVIBE_ACTIONS_OIDC_AUDIENCE:-https://git-vibe.markhuang.ai/actions/token}
      GITVIBE_APP_PRIVATE_KEY: ${GITVIBE_APP_PRIVATE_KEY:?GITVIBE_APP_PRIVATE_KEY is required}
      GITVIBE_DISCUSSION_CATEGORY: ${GITVIBE_DISCUSSION_CATEGORY:-Ideas}

Prefer a local uncommitted .env file for secrets. GitHub App private keys downloaded from GitHub commonly start with -----BEGIN RSA PRIVATE KEY-----; that format is supported.

GITHUB_APP_ID=123456
GITHUB_WEBHOOK_SECRET=replace-with-webhook-secret
GITVIBE_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----..."

After changing Compose or .env, recreate the container:

docker compose up -d --force-recreate

GitHub App Settings

Register or update the GitVibe GitHub App with:

GitHub Apps receive installation and installation_repositories events by default. Subscribe the App to these repository events:

Installation
Installation repositories
Issues
Issue comments
Sub-issues
Discussions
Discussion comments
Pull requests
Pull request reviews

Do not select "Send me everything".

The App needs these repository permissions:

Secrets write is used only for hosted Codex auth bundle write-back when a codex-sdk profile uses auth_json.from_bundle. Variables read is used for repository workflow dispatch settings such as GITVIBE_BASE_BRANCH.

Repository Installation

Install the GitVibe GitHub App on repositories you want GitVibe to manage. The App registration owns webhook delivery, so customer repositories do not create repo-level webhooks.

When the App is installed or repositories are added, GitVibe lazily bootstraps managed labels. Discussions are optional at installation time; GitVibe checks Discussion availability only when a Discussion-backed feature is used.

Webhook Secret

The same exact string must exist in both places:

Use a hex secret to avoid YAML and shell interpolation surprises:

openssl rand -hex 32

The secret does not need to be 32 characters. The command above returns 64 hex characters, which is a safe practical default.

Public URL

Expose the app through HTTPS before configuring the GitHub App webhook.

Check routing:

curl -fsS https://your-public-gitvibe-url/health

Expected response:

{ "ok": true }

If multiple GitVibe containers are running, verify the hostname routes to the right container by watching that container's logs while sending a request.

Signature Troubleshooting

Unsigned request:

curl -i -X POST https://your-public-gitvibe-url/webhooks \
  -H 'content-type: application/json' \
  --data '{}'

Expected response:

{ "error": "missing GitHub signature" }

Expected app log:

[git-vibe] app error: missing GitHub signature

If the response appears but the expected container does not log it, the public hostname is routed to the wrong backend.

Wrong secret test:

BODY='{"zen":"debug","repository":{"name":"repo","owner":{"login":"owner"}}}'
SIG="$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac 'wrong-secret' | sed 's/^.* //')"
​
curl -i -X POST https://your-public-gitvibe-url/webhooks \
  -H 'content-type: application/json' \
  -H 'x-github-event: ping' \
  -H "x-hub-signature-256: sha256=$SIG" \
  --data-binary "$BODY"

Expected response:

{ "error": "invalid GitHub signature" }

If GitHub still reports 401 after routing is correct, the GitHub App webhook secret and the running container's GITHUB_WEBHOOK_SECRET do not match.

Startup Logs

Healthy startup:

[git-vibe] app server listening on :3000

Repository setup runs from GitHub App installation webhooks and repository events delivered through the App, not from deploy-time repository environment variables.