Webhooks and sync¶
Arnold keeps its own copy of change requests so lists and the merge queue load without per-row forge API calls. Three mechanisms keep that copy fresh.
| Mechanism | What it imports | When | Configure |
|---|---|---|---|
| Repository sync | Every open PR/MR in repositories Arnold can access | Every ARNOLD_REPOSITORY_SYNC_INTERVAL_SECONDS (300), first run ~30 s after boot |
ARNOLD_REPOSITORY_SYNC_*, ARNOLD_GITLAB_SYNC_GROUPS |
| User sync | Each connected user's authored, reviewing and assigned MRs | Every 15 minutes per user, and on demand (Sync now) | userSyncConfiguration |
| Webhooks | Changes as they happen | On each event | Forge webhook settings |
Running several backend instances is safe: scheduled sync uses a leader lease in Aerospike, so only one instance syncs at a time.
Repository sync¶
Imports from:
- GitHub: every repository where the GitHub App is installed;
- GitLab: every project
GITLAB_SERVICE_TOKENis a member of, or only projects inARNOLD_GITLAB_SYNC_GROUPS(comma-separated group ids or full paths; subgroups included).
ARNOLD_REPOSITORY_SYNC_ENABLED=true
ARNOLD_REPOSITORY_SYNC_INTERVAL_SECONDS=300
ARNOLD_GITLAB_SYNC_GROUPS=platform,payments/backend
Results appear in Merge Requests โ All open. Admins can see the last run and trigger one under Admin โ Sync controls.
User sync¶
Per-user sync uses each user's own forge connection, so it sees exactly what they can see. Settings:
serviceCoreConfiguration:
userSyncConfiguration:
intervalMs: 900000 # per-user sync interval
leaseMs: 300000 # lease held while syncing one user
workerBatchSize: 25
maxConcurrentUsers: 4
leaderLeaseMs: 120000 # scheduler leader lease
gitlabSyncConfiguration:
webhookSecret: ${GITLAB_WEBHOOK_SECRET}
historyWindowMs: 7776000000 # 90 days of merged/closed history
watermarkOverlapMs: 300000
Users can trigger their own sync from the notification menu (Sync GitLab now). The footer status bar shows the sync state for each forge.
Webhooks¶
| Forge | Endpoint (on the backend) | Events | Secret |
|---|---|---|---|
| GitHub | /github-callbacks/v1/events |
Pull request, Pull request review | GITHUB_APP_WEBHOOK_SECRET (HMAC X-Hub-Signature-256) |
| GitLab | /gitlab-callbacks/v1/events |
Merge request, Comments (note), Pipeline | GITLAB_WEBHOOK_SECRET (X-Gitlab-Token) |
Both endpoints deduplicate deliveries. They must be reachable from the forge; they are not served through the UI's
/api proxy once sign-in is enabled. See GitHub App and
GitLab for the forge-side steps.
For local testing, relay webhooks with smee.io:
Sync mode (admin)¶
Admin โ Sync controls sets how periodic user sync and webhooks interact. The setting is stored in Aerospike and applies to the whole cluster.
| Mode | Behaviour |
|---|---|
Event driven (AUTO, recommended) |
Periodic sync runs, and Arnold records whether webhooks are arriving |
Always scheduled (POLLING) |
Periodic sync always runs |
Callback only (CALLBACK_ONLY) |
No periodic user sync; rely entirely on webhooks |
Reset callback observation clears the "webhooks seen" flag, for example after changing webhook configuration.