Webhooks and CI statuses

Commit statuses

CI systems can report commit statuses to POST /api/repositories/{owner}/{repo}/statuses/{40-character-sha} using a Finluth Git access token as HTTP Basic credentials (use the account email as username and the token as password). Send JSON with context, state (pending, success, failure, or error), and optional description and HTTPS targetUrl.

Report pending when a job starts and its final state when it finishes. Use the pull request head commit SHA; for GitHub Actions pull_request workflows, use github.event.pull_request.head.sha instead of GITHUB_SHA. For example:

curl -fsS -u "$FINLUTH_GIT_USER:$FINLUTH_GIT_TOKEN" \
  -H 'content-type: application/json' \
  --data '{"context":"ci/build","state":"success","description":"Build passed"}' \
  "$FINLUTH_GIT_URL/api/repositories/finluth/finspot/statuses/$GIT_COMMIT_SHA"

In Access & rulesets, create a branch ruleset, enable Require status checks, and enter the exact context names, one per line. Finluth shows statuses for the pull request head commit and blocks merges until each required context reports success for that exact commit. Protected branch pushes are also rejected unless the new commit has successful reports for all required contexts. Statuses and rulesets are stored in .finluth/metadata.json.

Repository webhooks

Repository admins can open Webhooks from a repository and configure up to 10 HTTPS endpoints for push and pull_request events. Push payloads include each changed ref's old and new object IDs. Pull request events include opened, synchronize, and closed actions; merged pull requests have merged: true.

Requests include X-Finluth-Event, X-Finluth-Action, X-Finluth-Delivery, X-Finluth-Timestamp, and X-Finluth-Signature-256 headers. Verify the signature as sha256= plus the HMAC-SHA256 of <timestamp>.<raw request body> using the webhook signing secret.

Secrets are shown once when generated; rotate by entering a replacement in Webhooks. Recent delivery results and attempt history are available there, with automatic retries for network errors, HTTP 429, and server errors, followed by manual retry controls for final failures. Endpoint URLs must resolve only to public IPs; redirects are not followed. Webhook secrets are stored in .finluth/metadata.json, so include that file in protected backups.