Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration

sheltie-server reads its settings from environment variables, and from a .env file in the working directory if there is one.

VariableDefaultMeaning
DATABASE_URL(required)postgres://user:password@host:port/database. Migrations run on startup.
SHELTIE_BIND127.0.0.1:8080Address to listen on. The container image sets 0.0.0.0:8080.
SHELTIE_GITHUB_APP_IDThe App’s numeric id.
SHELTIE_GITHUB_PRIVATE_KEY_PATHPath to the App’s private key (PEM).
SHELTIE_GITHUB_WEBHOOK_SECRETThe App’s webhook secret.
SHELTIE_GITHUB_API_URLhttps://api.github.comFor GitHub Enterprise Server.
SHELTIE_OIDC_AUDIENCEsheltieAudience CI tokens must be issued for (the workflows’ audience input).
SHELTIE_OIDC_ISSUERGitHub Actions on github.comOIDC issuer of CI tokens.
SHELTIE_EPOCH_SECONDS10Time between scheduler epochs (1–3600).
SHELTIE_LEASE_TTL_HOURS4How long an agent’s claim on an issue lasts unless renewed (1–168).
SHELTIE_PUBLIC_HOSTSComma-separated public host names; the MCP endpoint rejects other Host headers.
SHELTIE_PUBLIC_URLThe server’s public URL, e.g. https://sheltie.example.com. With the two below it turns on the dashboard.
SHELTIE_GITHUB_CLIENT_IDThe App’s OAuth client id (dashboard sign-in).
SHELTIE_GITHUB_CLIENT_SECRETThe App’s OAuth client secret.
SHELTIE_GITHUB_WEB_URLhttps://github.comGitHub’s web URL, for GitHub Enterprise Server.
RUST_LOGinfoLog filter, e.g. info,sheltie_server=debug.

Set all three SHELTIE_GITHUB_APP_ID, …_PRIVATE_KEY_PATH and …_WEBHOOK_SECRET, or none of them; without them the server serves only /healthz. Likewise set all three of SHELTIE_PUBLIC_URL and the client id and secret, or none (no dashboard).

compose.yaml also reads SHELTIE_POSTGRES_PASSWORD, SHELTIE_UID, SHELTIE_PORT, SHELTIE_IMAGE and SHELTIE_GITHUB_KEY_FILE from .env.

Per repository

Each repository starts in shadow mode. Change it with the CLI, which uses the same DATABASE_URL:

sheltie-server repo set-mode --repo owner/name --mode merge         # or shadow
sheltie-server repo set-merge-engine --repo owner/name --state on   # or off
sheltie-server token create --repo owner/name --name agent-a        # agent token, printed once
sheltie-server token revoke --repo owner/name --name agent-a
sheltie-server shadow-report --repo owner/name --days 7
sheltie-server stats --days 30

Merge rules and replay are configured in the repository itself, in .sheltie/merge.toml on the default branch: see Merge rules.

GitHub App permissions

From deploy/github-app-manifest.json:

  • Permissions:
    • Checks: write
    • Contents: write
    • Issues: write
    • Metadata: read
    • Pull requests: write
    • Commit statuses: read
  • Events: check_run, check_suite, issues, pull_request, pull_request_review, push, status.