App Server Settings

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

Loading

The app accepts these public routes:

Purpose	Method and path
Health check	GET /health
GitHub App webhook	POST /webhooks
Actions hosted token exchange	POST /actions/token
Legacy Codex auth writeback	POST /actions/codex-auth

POST /actions/codex-auth exists only so older pinned reusable workflows can finish while repositories migrate from Codex auth.json to proxy auth. Current GitVibe actions do not call it. 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.

Environment variable	Required	Default	Purpose
GITHUB_APP_ID	Yes	None	Registered GitHub App ID
GITHUB_WEBHOOK_SECRET	Yes	None	GitHub App webhook secret used to verify signatures
GITVIBE_APP_PRIVATE_KEY	Yes	None	Private key generated for the registered GitHub App; GitHub-downloaded RSA PEM keys are supported
GITHUB_API_URL	No	https://api.github.com	GitHub API base URL
GITVIBE_ACTIONS_OIDC_AUDIENCE	No	https://git-vibe.markhuang.ai/actions/token	Audience used for GitHub Actions OIDC token exchange
GITVIBE_DISCUSSION_CATEGORY	No	Ideas	Preferred Discussion category for feature issue conversion
PORT	No	3000	HTTP listen port inside the app process

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:

Setting	Value
Homepage URL	https://markhuang.ai/manuals/git-vibe
Setup URL	https://markhuang.ai/manuals/git-vibe/repository-settings
Webhook URL	https://git-vibe.markhuang.ai/webhooks
Callback URL	Blank
Request user authorization during installation	Off
Device flow	Off

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:

Permission	Access
Actions	Read and write
Checks	Read-only
Contents	Read and write
Discussions	Read and write
Issues	Read and write
Pull requests	Read and write
Secrets	Read and write
Variables	Read-only

Variables read is used for repository workflow dispatch settings such as GITVIBE_BASE_BRANCH. Secrets write is required only for the legacy /actions/codex-auth compatibility endpoint used by older pinned workflows.

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:

Place	Value
GitHub App webhook Secret field	Shared webhook secret
Running app env GITHUB_WEBHOOK_SECRET	Same shared secret

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.

Purpose	URL
Health check	https://your-public-gitvibe-url/health
GitHub App webhook	https://your-public-gitvibe-url/webhooks

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.