Problem
Admins must wait for scheduled sync runs to get fresh data. There is no way to trigger immediate sync when needed (e.g., after fixing a configuration issue or before a demo).
Proposed Solution
Add API endpoints for admins to manually trigger sync operations with appropriate guards.
Scope
In scope:
- Workspace-wide sync trigger (all monitored repositories)
- Single repository sync trigger
- Backfill reset (clear cursor to retry failed backfills)
- Cooldown enforcement (prevent spam)
- Rate limit check before execution
Out of scope:
- Background job queue visualization
- Sync cancellation
- Priority queue manipulation
Technical Notes
Proposed endpoints:
POST /api/workspaces/{slug}/sync/trigger
Body: { "scope": "WORKSPACE" | "REPOSITORY", "repositoryId": 123 }
Response: {
"accepted": true,
"estimatedDuration": "PT5M",
"cooldownRemaining": null
} | {
"accepted": false,
"reason": "COOLDOWN_ACTIVE" | "RATE_LIMIT_LOW",
"cooldownRemaining": "PT3M"
}
POST /api/workspaces/{slug}/sync/reset-backfill
Body: { "repositoryId": 123 }
Response: { "reset": true, "previousCursor": "abc123" }
Cooldown logic:
- Workspace sync: 15-minute cooldown between manual triggers
- Repository sync: 5-minute cooldown per repository
- Store last trigger time in memory (Caffeine cache, workspace-scoped)
Rate limit check:
- If GitHub/GitLab rate limit remaining <100, reject with
RATE_LIMIT_LOW
- Use existing
ScopedRateLimitTracker to check
Sync execution:
- Trigger is async (return 202 Accepted immediately)
- Reuse existing sync service methods
- Log manual trigger for audit trail
Files to create:
workspace/sync/SyncTriggerController.java
workspace/sync/SyncTriggerService.java
workspace/sync/dto/SyncTriggerRequest.java
workspace/sync/dto/SyncTriggerResponse.java
Acceptance Criteria
Problem
Admins must wait for scheduled sync runs to get fresh data. There is no way to trigger immediate sync when needed (e.g., after fixing a configuration issue or before a demo).
Proposed Solution
Add API endpoints for admins to manually trigger sync operations with appropriate guards.
Scope
In scope:
Out of scope:
Technical Notes
Proposed endpoints:
Cooldown logic:
Rate limit check:
RATE_LIMIT_LOWScopedRateLimitTrackerto checkSync execution:
Files to create:
workspace/sync/SyncTriggerController.javaworkspace/sync/SyncTriggerService.javaworkspace/sync/dto/SyncTriggerRequest.javaworkspace/sync/dto/SyncTriggerResponse.javaAcceptance Criteria