Skill repos (git-backed)

Customer-owned git repositories are first-class skill sources. Git remains the source of truth; Cavalry indexes, syncs, and serves — it never writes content to your repo on the content path.

Setup (GitHub)

  1. Register a per-deployment GitHub App (see GitHub Apps docs). Permissions: Contents: Read, Metadata: Read, Pull requests: Read & write. Subscribe to push, create, delete, installation, installation_repositories.
  2. Set CAVALRY_GITHUB_APP_ID, CAVALRY_GITHUB_APP_PRIVATE_KEY, CAVALRY_GITHUB_APP_WEBHOOK_SECRET, CAVALRY_GITHUB_APP_SLUG.
  3. Point the App's webhook URL at <CAVALRY_WEB_URL>/api/webhooks/github.
  4. In the UI at /[org]/skill-repos/connect, click "Install on GitHub", install on your org, pick a repo, confirm.

cavalry.yaml

The repo must have a cavalry.yaml on its default branch. Minimal:

version: 1
skills:
  - path: "skills/*"
releases:
  tag_pattern: "{skill}/v{version}"
defaults:
  namespace: acme-platform
  targets: ["claude-code", "cursor"]

Tagging kafka-wrapper/v1.0.0 publishes version 1.0.0 of acme-platform/kafka-wrapper.

Guarantees

  • Published skill_versions are immutable once inserted.
  • Force-pushed tags raise skill_repo.force_push_detected, flip the repo to degraded, and never overwrite existing versions.
  • Missed webhooks are caught by the scheduled reconciler (every CAVALRY_SYNC_RECONCILE_INTERVAL_SECONDS).
  • Disconnecting a repo archives its skills; existing versions remain installable for audit continuity.