Maven Virtual Registry API

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

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

Use this API to create and manage Maven virtual registries, configure upstream registries, manage cache entries, and handle package downloads and uploads.

Manage virtual registries

Use the following endpoints to create and manage Maven virtual registries.

List all virtual registries

Version history

Introduced in GitLab 17.4 with a flag named virtual_registry_maven. Disabled by default.

Lists all Maven virtual registries for a group.

GET /groups/:id/-/virtual_registries/packages/maven/registries

Supported attributes:

Attribute	Type	Required	Description
`id`	string/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/packages/maven/registries"

Example response:

[
  {
    "id": 1,
    "group_id": 5,
    "name": "my-virtual-registry",
    "description": "My virtual registry",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z"
  }
]

Create a virtual registry

Version history

Introduced in GitLab 17.4 with a flag named virtual_registry_maven. Disabled by default.

Creates a Maven virtual registry for a group.

POST /groups/:id/-/virtual_registries/packages/maven/registries

Attribute	Type	Required	Description
`id`	string/integer	yes	The group ID or full group path. Must be a top-level group.
`name`	string	yes	The name of the virtual registry.
`description`	string	no	The description of the virtual registry.

Example request:

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data '{"name": "my-virtual-registry", "description": "My virtual registry"}' \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/packages/maven/registries"

Example response:

{
  "id": 1,
  "group_id": 5,
  "name": "my-virtual-registry",
  "description": "My virtual registry",
  "created_at": "2024-05-30T12:28:27.855Z",
  "updated_at": "2024-05-30T12:28:27.855Z"
}

Get a virtual registry

Version history

Introduced in GitLab 17.4 with a flag named virtual_registry_maven. Disabled by default.

Gets a specific Maven virtual registry.

GET /virtual_registries/packages/maven/registries/:id

Parameters:

Attribute	Type	Required	Description
`id`	integer	yes	The ID of the Maven virtual registry.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registries/1"

Example response:

{
  "id": 1,
  "group_id": 5,
  "name": "my-virtual-registry",
  "description": "My virtual registry",
  "created_at": "2024-05-30T12:28:27.855Z",
  "updated_at": "2024-05-30T12:28:27.855Z"
}

Update a virtual registry

Version history

Introduced in GitLab 18.0 with a flag named virtual_registry_maven. Disabled by default.

Updates a specific Maven virtual registry.

PATCH /virtual_registries/packages/maven/registries/:id

Attribute	Type	Required	Description
`id`	integer	yes	The ID of the Maven virtual registry.
`name`	string	yes	The name of the virtual registry.
`description`	string	no	The description of the virtual registry.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/packages/maven/registries"
```0

If successful, returns a [`200 OK`](rest/troubleshooting.md#status-codes) status code.

### Delete a virtual registry

#### Version history

- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/161615) in GitLab 17.4 [with a flag](../administration/feature_flags.md) named `virtual_registry_maven`. Disabled by default.

Deletes a specific Maven virtual registry.

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/packages/maven/registries"
```1

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of the Maven virtual registry. |

Example request:

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/packages/maven/registries"
```2

If successful, returns a [`204 No Content`](rest/troubleshooting.md#status-codes) status code.

## Manage upstream registries

Use the following endpoints to configure and manage upstream Maven registries.

### List all upstream registries

#### Version history

- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/162019) in GitLab 17.4 [with a flag](../administration/feature_flags.md) named `virtual_registry_maven`. Disabled by default.

Lists all upstream registries for a Maven virtual registry.

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/packages/maven/registries"
```3

Supported attributes:

| Attribute | Type | Required | Description |
|:----------|:-----|:---------|:------------|
| `id` | integer | yes | The ID of the Maven virtual registry. |

Example request:

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/packages/maven/registries"
```4

Example response:

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/packages/maven/registries"
```5

### Create an upstream registry

#### Version history

- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/162019) in GitLab 17.4 [with a flag](../administration/feature_flags.md) named `virtual_registry_maven`. Disabled by default.

Adds an upstream registry to a Maven virtual registry.

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/packages/maven/registries"
```6

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of the Maven virtual registry. |
| `url` | string | yes | The URL of the upstream registry. |
| `username` | string | no | The username of the upstream registry. |
| `password` | string | no | The password of the upstream registry. |
| `cache_validity_hours` | integer | no | The cache validity period. Defaults to 24 hours. |

You must include both the `username` and `password` in the request, or not at all. If not set, a public (anonymous) request is used to access the upstream.

Example request:

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/packages/maven/registries"
```7

Example response:

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/packages/maven/registries"
```8

### Get an upstream registry

#### Version history

- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/162019) in GitLab 17.4 [with a flag](../administration/feature_flags.md) named `virtual_registry_maven`. Disabled by default.

Gets a specific upstream registry for a Maven virtual registry.

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/packages/maven/registries"
```9

Parameters:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of the upstream registry. |

Example request:

```json
[
  {
    "id": 1,
    "group_id": 5,
    "name": "my-virtual-registry",
    "description": "My virtual registry",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z"
  }
]
```0

Example response:

```json
[
  {
    "id": 1,
    "group_id": 5,
    "name": "my-virtual-registry",
    "description": "My virtual registry",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z"
  }
]
```1

### Update an upstream registry

#### Version history

- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/162019) in GitLab 17.4 [with a flag](../administration/feature_flags.md) named `virtual_registry_maven`. Disabled by default.

Updates a specific upstream registry for a Maven virtual registry.

```json
[
  {
    "id": 1,
    "group_id": 5,
    "name": "my-virtual-registry",
    "description": "My virtual registry",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z"
  }
]
```2

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of the upstream registry. |
| `url` | string | no | The URL of the upstream registry. |
| `name` | string | no | The name of the upstream registry. |
| `description` | string | no | The description of the upstream registry. |
| `username` | string | no | The username of the upstream registry. |
| `password` | string | no | The password of the upstream registry. |
| `cache_validity_hours` | integer | no | The cache validity period. Defaults to 24 hours. |

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

The `username` and `password` must be provided together, or not at all. If not set, a public (anonymous) request is used to access the upstream.

Example request:

```json
[
  {
    "id": 1,
    "group_id": 5,
    "name": "my-virtual-registry",
    "description": "My virtual registry",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z"
  }
]
```3

If successful, returns a [`200 OK`](rest/troubleshooting.md#status-codes) status code.

### Update an upstream registry position

#### Version history

- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/186890) in GitLab 18.0 [with a flag](../administration/feature_flags.md) named `virtual_registry_maven`. Disabled by default.

Updates the position of an upstream registry in an ordered list for a Maven virtual registry.

```json
[
  {
    "id": 1,
    "group_id": 5,
    "name": "my-virtual-registry",
    "description": "My virtual registry",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z"
  }
]
```4

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of the upstream registry. |
| `position` | integer | yes | The position of the upstream registry. Between 1 and 20. |

Example request:

```json
[
  {
    "id": 1,
    "group_id": 5,
    "name": "my-virtual-registry",
    "description": "My virtual registry",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z"
  }
]
```5

If successful, returns a [`200 OK`](rest/troubleshooting.md#status-codes) status code.

### Delete an upstream registry

#### Version history

- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/162019) in GitLab 17.4 [with a flag](../administration/feature_flags.md) named `virtual_registry_maven`. Disabled by default.

Deletes a specific upstream registry for a Maven virtual registry.

```json
[
  {
    "id": 1,
    "group_id": 5,
    "name": "my-virtual-registry",
    "description": "My virtual registry",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z"
  }
]
```6

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of the upstream registry. |

Example request:

```json
[
  {
    "id": 1,
    "group_id": 5,
    "name": "my-virtual-registry",
    "description": "My virtual registry",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z"
  }
]
```7

If successful, returns a [`204 No Content`](rest/troubleshooting.md#status-codes) status code.

## Manage cache entries

Use the following endpoints to manage cache entries for a Maven virtual registry.

### List upstream registry cache entries

#### Version history

- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/162614) in GitLab 17.4 [with a flag](../administration/feature_flags.md) named `virtual_registry_maven`. Disabled by default.

Lists cache entries for a Maven upstream registry.

```json
[
  {
    "id": 1,
    "group_id": 5,
    "name": "my-virtual-registry",
    "description": "My virtual registry",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z"
  }
]
```8

Supported attributes:

| Attribute | Type | Required | Description |
|:----------|:-----|:---------|:------------|
| `id` | integer | yes | The ID of the upstream registry. |
| `search` | string | no | The search query for the relative path of the package (for example, `foo/bar/mypkg`). |
| `page` | integer | no | The page number. Defaults to 1. |
| `per_page` | integer | no | The number of items per page. Defaults to 20. |

Example request:

```json
[
  {
    "id": 1,
    "group_id": 5,
    "name": "my-virtual-registry",
    "description": "My virtual registry",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z"
  }
]
```9

Example response:

```plaintext
POST /groups/:id/-/virtual_registries/packages/maven/registries
```0

### Delete an upstream registry cache entry

#### Version history

- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/162614) in GitLab 17.4 [with a flag](../administration/feature_flags.md) named `virtual_registry_maven`. Disabled by default.

Deletes a specific cache entry for a Maven upstream registry.

```plaintext
POST /groups/:id/-/virtual_registries/packages/maven/registries
```1

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | string | yes | The base64-encoded upstream ID and relative path of the cache entry (for example, 'Zm9vL2Jhci9teXBrZy5wb20='). |

Example request:

```plaintext
POST /groups/:id/-/virtual_registries/packages/maven/registries
```2

If successful, returns a [`204 No Content`](rest/troubleshooting.md#status-codes) status code.

## Manage package operations

Use the following endpoints to manage package operations for a Maven virtual registry.

These endpoints are intended for internal use by GitLab, and generally not meant for manual consumption.

These endpoints do not adhere to the [REST API authentication methods](rest/authentication.md).
For more information on which headers and token types are supported, 
see [Maven package registry](../user/packages/maven_repository/_index.md). Undocumented authentication methods might be removed in the future.

### Download a package

#### Version history

- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/160891) in GitLab 17.3 [with a flag](../administration/feature_flags.md) named `virtual_registry_maven`. Disabled by default.

Downloads a package from a Maven virtual registry. To access this resource, you must [authenticate with the registry](../user/packages/package_registry/supported_functionality.md#authenticate-with-the-registry).

```plaintext
POST /groups/:id/-/virtual_registries/packages/maven/registries
```3

Supported attributes:

| Attribute | Type | Required | Description |
|:----------|:-----|:---------|:------------|
| `id` | integer | yes | The ID of the Maven virtual registry. |
| `path` | string | yes | The full package path (for example, `foo/bar/mypkg/1.0-SNAPSHOT/mypkg-1.0-SNAPSHOT.jar`). |

Example request:

```plaintext
POST /groups/:id/-/virtual_registries/packages/maven/registries
```4

If successful, returns [`200 OK`](rest/troubleshooting.md#status-codes) and
the following response headers:

- `x-checksum-sha1`: SHA1 checksum of the file
- `x-checksum-md5`: MD5 checksum of the file
- `Content-Type`: The MIME type of the file
- `Content-Length`: The file size in bytes

### Upload a package

#### Version history

- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163641) in GitLab 17.4 [with a flag](../administration/feature_flags.md) named `virtual_registry_maven`. Disabled by default.

Uploads a package to a Maven virtual registry. This endpoint is accessible only by [GitLab Workhorse](../development/workhorse/_index.md).

```plaintext
POST /groups/:id/-/virtual_registries/packages/maven/registries
```5

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of the Maven virtual registry. |
| `path` | string | yes | The full package path (for example, `foo/bar/mypkg/1.0-SNAPSHOT/mypkg-1.0-SNAPSHOT.jar`). |
| `file` | file | yes | The file being uploaded. |

Request headers:

- `Etag`: Entity tag for the file
- `GitLab-Workhorse-Send-Dependency-Content-Type`: Content type of the file
- `Upstream-GID`: Global ID of the target upstream

If successful, returns a [`200 OK`](rest/troubleshooting.md#status-codes) status code.