Virtual registries cleanup policies API

Tier: Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
Status: Experiment

The availability of these endpoints is controlled by a feature flag. For more information, see the history. Review the documentation carefully before you use them.

Use this API to:

Create and manage virtual registries cleanup policies.
Configure cleanup schedules and retention settings.
Automatically clean up unused cache entries.

Manage cleanup policies

Use the following endpoints to create and manage virtual registries cleanup policies. Each group can have only one cleanup policy.

Get the cleanup policy for a group

Gets the cleanup policy for a group. Each group can have only one cleanup policy.

GET /groups/:id/-/virtual_registries/cleanup/policy

Supported attributes:

Attribute	Type	Required	Description
`id`	string or integer	Yes	The group ID or full-group path. Must be a top-level group.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/cleanup/policy"

Example response:

{
  "group_id": 5,
  "next_run_at": "2024-06-06T12:28:27.855Z",
  "last_run_at": "2024-05-30T12:28:27.855Z",
  "last_run_deleted_size": 1048576,
  "last_run_deleted_entries_count": 25,
  "keep_n_days_after_download": 30,
  "status": "scheduled",
  "cadence": 7,
  "enabled": true,
  "failure_message": null,
  "last_run_detailed_metrics": {
    "maven": {
      "deleted_entries_count": 25,
      "deleted_size": 1048576
    }
  },
  "created_at": "2024-05-30T12:28:27.855Z",
  "updated_at": "2024-05-30T12:28:27.855Z"
}

Create a cleanup policy

Creates a cleanup policy for a group. Each group can have only one cleanup policy.

POST /groups/:id/-/virtual_registries/cleanup/policy

Attribute	Type	Required	Description
`id`	string or integer	Yes	The group ID or full-group path. Must be a top-level group.
`cadence`	integer	No	How often the cleanup policy should run. Must be one of: `1` (daily), `7` (weekly), `14` (bi-weekly), `30` (monthly), `90` (quarterly).
`enabled`	boolean	No	Enable or disable the cleanup policy.
`keep_n_days_after_download`	integer	No	Number of days after which unused cache entries should be cleaned up. Must be between 1 and 365.

Example request:

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data '{"enabled": true, "keep_n_days_after_download": 30, "cadence": 7}' \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/cleanup/policy"

Example response:

{
  "group_id": 5,
  "next_run_at": "2024-06-06T12:28:27.855Z",
  "last_run_at": null,
  "last_run_deleted_size": 0,
  "last_run_deleted_entries_count": 0,
  "keep_n_days_after_download": 30,
  "status": "scheduled",
  "cadence": 7,
  "enabled": true,
  "failure_message": null,
  "last_run_detailed_metrics": {},
  "created_at": "2024-05-30T12:28:27.855Z",
  "updated_at": "2024-05-30T12:28:27.855Z"
}

Update a cleanup policy

Updates the cleanup policy for a group.

PATCH /groups/:id/-/virtual_registries/cleanup/policy

Attribute	Type	Required	Description
`id`	string or integer	Yes	The group ID or full-group path. Must be a top-level group.
`cadence`	integer	No	How often the cleanup policy should run. Must be one of: `1` (daily), `7` (weekly), `14` (bi-weekly), `30` (monthly), `90` (quarterly).
`enabled`	boolean	No	Boolean to enable/disable the policy.
`keep_n_days_after_download`	integer	No	Number of days after which unused cache entries should be cleaned up. Must be between 1 and 365.

You must provide at least one of the optional parameters in your request.

Example request:

curl --request PATCH \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"keep_n_days_after_download": 60}' \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/cleanup/policy"

Example response:

{
  "group_id": 5,
  "next_run_at": "2024-06-06T12:28:27.855Z",
  "last_run_at": "2024-05-30T12:28:27.855Z",
  "last_run_deleted_size": 1048576,
  "last_run_deleted_entries_count": 25,
  "keep_n_days_after_download": 60,
  "status": "scheduled",
  "cadence": 7,
  "enabled": true,
  "failure_message": null,
  "last_run_detailed_metrics": {
    "maven": {
      "deleted_entries_count": 25,
      "deleted_size": 1048576
    }
  },
  "created_at": "2024-05-30T12:28:27.855Z",
  "updated_at": "2024-05-30T12:28:27.855Z"
}

Delete a cleanup policy

Deletes the cleanup policy for a group.

DELETE /groups/:id/-/virtual_registries/cleanup/policy

Attribute	Type	Required	Description
`id`	string or integer	Yes	The group ID or full-group path. Must be a top-level group.

Example request:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/cleanup/policy"

If successful, returns a 204 No Content status code.