Skip to content

Add API endpoint to reset hard-failed pull mirrors

Proposal

Add API support for resetting hard-failed pull mirrors without requiring Rails console access.

Currently, when a pull mirror fails 14 consecutive times, it enters a "hard failure" state and stops attempting to sync. The existing pull mirroring API endpoint (POST /projects/:id/mirror/pull) returns a 403 error with "Mirroring for the project is on pause" when attempting to trigger updates on hard-failed mirrors. This is documented under Fix hard failures when mirroring.

As noted in the documentation the UI provides a "Update now" button that can reset hard failures and resume mirroring for individual mirrors however there is no equivalent API functionality when multiple projects are affected. This creates a significant limitation for:

  • GitLab.com users who don't have Rails console access
  • Organizations managing multiple mirror projects programmatically
  • Organizations that do not want to log into the rails console
  • Automation workflows that need to recover from mirror failures

Proposed Solution:

Add one of the following API enhancements:

  1. Option A: Add a force or reset_hard_failure parameter to the existing POST /projects/:id/mirror/pull endpoint

    POST /projects/:id/mirror/pull?force=true

  2. Option B: Create a dedicated endpoint for resetting mirror failures

    POST /projects/:id/mirror/pull/reset

The implementation should mirror the UI behavior found in ee/app/controllers/ee/projects/mirrors_controller.rb where StartPullMirroringService is called with pause_on_hard_failure: false, allowing the service to reset the retry count for hard-failed mirrors.

Benefits:

  • Provides API parity with UI functionality
  • Enables programmatic recovery from mirror failures
  • Reduces dependency on Rails console access for mirror management
  • Improves automation capabilities for organizations with multiple mirrors

Related Code:

  • Current API implementation: ee/lib/api/project_mirror.rb
  • UI implementation: ee/app/controllers/ee/projects/mirrors_controller.rb
  • Service logic: ee/app/services/start_pull_mirroring_service.rb
Edited by 🤖 GitLab Bot 🤖