Skip to content

Implement repository deletion endpoint to clean up orphaned registry records

Problem

When Rails deletes container repositories, it calls the Registry API to delete all tags, then deletes the repository record from its own database. However, the Container Registry's database retains orphaned repository records along with their associated manifests, layers, and link references. This creates a state mismatch that prevents operations like project moves when the repository count exceeds limits.

Related issue: https://gitlab.com/gitlab-com/request-for-help/-/issues/3682

Current Behavior

  1. Rails calls the Registry API to list all tags in a repository
  2. Rails calls the Registry API to delete all tags
  3. Rails deletes the repository record from its database
  4. Registry database is left with orphaned repository records and their associated data (manifests, layers, link references)
  5. This causes operations that count repositories (like project moves) to fail when counts exceed limits

Proposed Solution

Implement a repository deletion endpoint in the Container Registry that:

  1. Safely deletes repository records and all associated data (manifests, layers, link references)
  2. Handles cascading deletions properly, including untagged manifests and their layers
  3. Uses distributed locking to prevent concurrent writes to the same repositories during deletion
  4. Provides observability through metrics tracking deletion duration, repository counts, and lock contention

Implementation Considerations

  • Schema analysis: Identify all dependent records in the registry database that need cascading deletion
  • Performance: Deletion of large numbers of repositories may be computationally expensive; batch operations and efficient queries may be required
  • Concurrency: Implement distributed locking (Redis-based or database-level) to prevent race conditions during long-running deletions
  • Coordination: Rails should call this endpoint before deleting its own repository record
  • Metrics: Track operation duration and repository counts to inform future limit increases

Related Issues