Skip to content

feat(workspace): manual sync trigger endpoints #728

@FelixTJDietrich

Description

@FelixTJDietrich

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:

  1. Workspace-wide sync trigger (all monitored repositories)
  2. Single repository sync trigger
  3. Backfill reset (clear cursor to retry failed backfills)
  4. Cooldown enforcement (prevent spam)
  5. 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

  • Admin can trigger workspace-wide sync via API
  • Admin can trigger single-repository sync
  • Admin can reset backfill cursor to retry failed backfills
  • Cooldown enforced: workspace=15min, repository=5min
  • Requests during cooldown return 429 with remaining time
  • Rate limit checked before accepting (reject if <100 remaining)
  • Trigger is async (immediate 202 response)
  • Manual triggers logged with user ID and timestamp
  • Admin-only authorization
  • Integration test for cooldown enforcement

Metadata

Metadata

Assignees

No one assigned

    Labels

    application-serverSpring Boot server: APIs, business logic, databasefeatureNew feature or enhancementpriority:mediumPlan for soon - Moderate impact

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions