31 KiB
stage, group, info, title
stage | group | info | title |
---|---|---|---|
Package | Package Registry | To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments | Maven Virtual Registry API |
{{< details >}}
- Tier: Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
{{< /details >}}
{{< alert type="flag" >}}
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.
{{< /alert >}}
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
{{< history >}}
- Introduced in GitLab 17.4 with a flag named
virtual_registry_maven
. Disabled by default. - Feature flag renamed to
maven_virtual_registry
in GitLab 18.1. - Changed from experiment to beta in GitLab 18.1.
- Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 18.2.
{{< /history >}}
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
{{< history >}}
- Introduced in GitLab 17.4 with a flag named
virtual_registry_maven
. Disabled by default. - Feature flag renamed to
maven_virtual_registry
in GitLab 18.1. - Changed from experiment to beta in GitLab 18.1.
- Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 18.2.
{{< /history >}}
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
{{< history >}}
- Introduced in GitLab 17.4 with a flag named
virtual_registry_maven
. Disabled by default. - Feature flag renamed to
maven_virtual_registry
in GitLab 18.1. - Changed from experiment to beta in GitLab 18.1.
- Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 18.2.
{{< /history >}}
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
{{< history >}}
- Introduced in GitLab 18.0 with a flag named
virtual_registry_maven
. Disabled by default. - Feature flag renamed to
maven_virtual_registry
in GitLab 18.1. - Changed from experiment to beta in GitLab 18.1.
- Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 18.2.
{{< /history >}}
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 --request PATCH \
--header "PRIVATE-TOKEN: <your_access_token>" \
--header "Content-Type: application/json" \
--data '{"name": "my-virtual-registry", "description": "My virtual registry"}' \
--url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registries/1"
If successful, returns a 200 OK
status code.
Delete a virtual registry
{{< history >}}
- Introduced in GitLab 17.4 with a flag named
virtual_registry_maven
. Disabled by default. - Feature flag renamed to
maven_virtual_registry
in GitLab 18.1. - Changed from experiment to beta in GitLab 18.1.
- Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 18.2.
{{< /history >}}
Deletes a specific Maven virtual registry.
DELETE /virtual_registries/packages/maven/registries/:id
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer | yes | The ID of the Maven virtual registry. |
Example request:
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
--header "Accept: application/json" \
--url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registries/1"
If successful, returns a 204 No Content
status code.
Delete cache entries for a virtual registry
{{< history >}}
- Introduced in GitLab 18.2 with a flag named
maven_virtual_registry
. Enabled by default.
{{< /history >}}
Schedule all cache entries for deletion in all exclusive upstream registries for a Maven virtual registry. Cache entries are not scheduled for deletion for upstream registries that are associated with other virtual registries.
DELETE /virtual_registries/packages/maven/registries/:id/cache
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer | yes | The ID of the Maven virtual registry. |
Example request:
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
--header "Accept: application/json" \
--url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registries/1/cache"
If successful, returns a 204 No Content
status code.
Manage upstream registries
Use the following endpoints to configure and manage upstream Maven registries.
List all upstream registries for a top-level group
{{< history >}}
- Introduced in GitLab 18.3 with a flag named
maven_virtual_registry
. Enabled by default.
{{< /history >}}
Lists all upstream registries for a top-level group.
GET /groups/:id/-/virtual_registries/packages/maven/upstreams
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id |
string/integer | yes | The group ID or full group path. Must be a top-level group. |
page |
integer | no | The page number. Defaults to 1. |
per_page |
integer | no | The number of items per page. Defaults to 20. |
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/upstreams"
Example response:
[
{
"id": 1,
"group_id": 5,
"url": "https://repo.maven.apache.org/maven2",
"name": "Maven Central",
"description": "Maven Central repository",
"cache_validity_hours": 24,
"username": "user",
"created_at": "2024-05-30T12:28:27.855Z",
"updated_at": "2024-05-30T12:28:27.855Z"
}
]
List all upstream registries for a virtual registry
{{< history >}}
- Introduced in GitLab 17.4 with a flag named
virtual_registry_maven
. Disabled by default. - Feature flag renamed to
maven_virtual_registry
in GitLab 18.1. - Changed from experiment to beta in GitLab 18.1.
- Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 18.2.
{{< /history >}}
Lists all upstream registries for a Maven virtual registry.
GET /virtual_registries/packages/maven/registries/:id/upstreams
Supported attributes:
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/upstreams"
Example response:
[
{
"id": 1,
"group_id": 5,
"url": "https://repo.maven.apache.org/maven2",
"name": "Maven Central",
"description": "Maven Central repository",
"cache_validity_hours": 24,
"username": "user",
"created_at": "2024-05-30T12:28:27.855Z",
"updated_at": "2024-05-30T12:28:27.855Z",
"registry_upstream": {
"id": 1,
"registry_id": 1,
"position": 1
}
}
]
Create an upstream registry
{{< history >}}
- Introduced in GitLab 17.4 with a flag named
virtual_registry_maven
. Disabled by default. - Feature flag renamed to
maven_virtual_registry
in GitLab 18.1. - Changed from experiment to beta in GitLab 18.1.
- Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 18.2.
{{< /history >}}
Adds an upstream registry to a Maven virtual registry.
POST /virtual_registries/packages/maven/registries/:id/upstreams
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. |
{{< alert type="note" >}}
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.
{{< /alert >}}
Example request:
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--header "Content-Type: application/json" \
--data '{"url": "https://repo.maven.apache.org/maven2", "name": "Maven Central", "description": "Maven Central repository", "username": <your_username>, "password": <your_password>, "cache_validity_hours": 48}' \
--url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registries/1/upstreams"
Example response:
{
"id": 1,
"group_id": 5,
"url": "https://repo.maven.apache.org/maven2",
"name": "Maven Central",
"description": "Maven Central repository",
"cache_validity_hours": 48,
"username": "user",
"created_at": "2024-05-30T12:28:27.855Z",
"updated_at": "2024-05-30T12:28:27.855Z",
"registry_upstream": {
"id": 1,
"registry_id": 1,
"position": 1
}
}
Get an upstream registry
{{< history >}}
- Introduced in GitLab 17.4 with a flag named
virtual_registry_maven
. Disabled by default. - Feature flag renamed to
maven_virtual_registry
in GitLab 18.1. - Changed from experiment to beta in GitLab 18.1.
- Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 18.2.
{{< /history >}}
Gets a specific upstream registry for a Maven virtual registry.
GET /virtual_registries/packages/maven/upstreams/:id
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer | yes | The ID of the upstream 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/upstreams/1"
Example response:
{
"id": 1,
"group_id": 5,
"url": "https://repo.maven.apache.org/maven2",
"name": "Maven Central",
"description": "Maven Central repository",
"cache_validity_hours": 24,
"username": "user",
"created_at": "2024-05-30T12:28:27.855Z",
"updated_at": "2024-05-30T12:28:27.855Z",
"registry_upstreams": [
{
"id": 1,
"registry_id": 1,
"position": 1
}
]
}
Update an upstream registry
{{< history >}}
- Introduced in GitLab 17.4 with a flag named
virtual_registry_maven
. Disabled by default. - Feature flag renamed to
maven_virtual_registry
in GitLab 18.1. - Changed from experiment to beta in GitLab 18.1.
- Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 18.2.
{{< /history >}}
Updates a specific upstream registry for a Maven virtual registry.
PATCH /virtual_registries/packages/maven/upstreams/:id
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. |
{{< alert type="note" >}}
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.
{{< /alert >}}
Example request:
curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" \
--header "Content-Type: application/json" \
--data '{"cache_validity_hours": 72}' \
--url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/upstreams/1"
If successful, returns a 200 OK
status code.
Update an upstream registry position
{{< history >}}
- Introduced in GitLab 18.0 with a flag named
virtual_registry_maven
. Disabled by default. - Feature flag renamed to
maven_virtual_registry
in GitLab 18.1. - Changed from experiment to beta in GitLab 18.1.
- Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 18.2.
{{< /history >}}
Updates the position of an upstream registry in an ordered list for a Maven virtual registry.
PATCH /virtual_registries/packages/maven/registry_upstreams/:id
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:
curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" \
--header "Content-Type: application/json" \
--data '{"position": 5}' \
--url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registry_upstreams/1"
If successful, returns a 200 OK
status code.
Delete an upstream registry
{{< history >}}
- Introduced in GitLab 17.4 with a flag named
virtual_registry_maven
. Disabled by default. - Feature flag renamed to
maven_virtual_registry
in GitLab 18.1. - Changed from experiment to beta in GitLab 18.1.
- Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 18.2.
{{< /history >}}
Deletes a specific upstream registry for a Maven virtual registry.
DELETE /virtual_registries/packages/maven/upstreams/:id
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer | yes | The ID of the upstream registry. |
Example request:
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
--header "Accept: application/json" \
--url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/upstreams/1"
If successful, returns a 204 No Content
status code.
Associate an upstream with a registry
{{< history >}}
- Introduced in GitLab 18.1 with a flag named
maven_virtual_registry
. Disabled by default. - Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 18.2.
{{< /history >}}
Associates an existing upstream registry with a Maven virtual registry.
POST /virtual_registries/packages/maven/registry_upstreams
Attribute | Type | Required | Description |
---|---|---|---|
registry_id |
integer | yes | The ID of the Maven virtual registry. |
upstream_id |
integer | yes | The ID of the Maven upstream registry. |
Example request:
curl --request POST \
--header "PRIVATE-TOKEN: <your_access_token>" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{"registry_id": 1, "upstream_id": 2}' \
--url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registry_upstreams"
Example response:
{
"id": 5,
"registry_id": 1,
"upstream_id": 2,
"position": 2
}
Disassociate an upstream from a registry
{{< history >}}
- Introduced in GitLab 18.1 with a flag named
maven_virtual_registry
. Disabled by default. - Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 18.2.
{{< /history >}}
Removes the association between an upstream registry and a Maven virtual registry.
{{< alert type="warning" >}}
If this is the last association for the upstream, removal of the association deletes the upstream itself and all its cache entries.
{{< /alert >}}
DELETE /virtual_registries/packages/maven/registry_upstreams/:id
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer | yes | The ID of the registry upstream association. |
Example request:
curl --request DELETE \
--header "PRIVATE-TOKEN: <your_access_token>" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registry_upstreams/1"
If successful, returns a 204 No Content
status code.
Delete cache entries for an upstream registry
{{< history >}}
- Introduced in GitLab 18.2 with a flag named
maven_virtual_registry
. Enabled by default.
{{< /history >}}
Schedules all cache entries for deletion for a specific upstream registry in a Maven virtual registry.
DELETE /virtual_registries/packages/maven/upstreams/:id/cache
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer | yes | The ID of the upstream registry. |
Example request:
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
--header "Accept: application/json" \
--url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/upstreams/1/cache"
If successful, returns a 204 No Content
status code.
Manage cache entries
Use the following endpoints to manage cache entries for a Maven virtual registry.
List upstream registry cache entries
{{< history >}}
- Introduced in GitLab 17.4 with a flag named
virtual_registry_maven
. Disabled by default. - Feature flag renamed to
maven_virtual_registry
in GitLab 18.1. - Changed from experiment to beta in GitLab 18.1.
- Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 18.2.
{{< /history >}}
Lists cache entries for a Maven upstream registry.
GET /virtual_registries/packages/maven/upstreams/:id/cache_entries
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:
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--header "Accept: application/json" \
--url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/upstreams/1/cache_entries?search=foo/bar"
Example response:
[
{
"id": "MTUgZm9vL2Jhci9teXBrZy8xLjAtU05BUFNIT1QvbXlwa2ctMS4wLVNOQVBTSE9ULmphcg==",
"group_id": 5,
"upstream_id": 1,
"upstream_checked_at": "2024-05-30T12:28:27.855Z",
"file_md5": "44f21d5190b5a6df8089f54799628d7e",
"file_sha1": "74d101856d26f2db17b39bd22d3204021eb0bf7d",
"size": 2048,
"relative_path": "foo/bar/package-1.0.0.pom",
"content_type": "application/xml",
"upstream_etag": "\"686897696a7c876b7e\"",
"created_at": "2024-05-30T12:28:27.855Z",
"updated_at": "2024-05-30T12:28:27.855Z"
}
]
Delete an upstream registry cache entry
{{< history >}}
- Introduced in GitLab 17.4 with a flag named
virtual_registry_maven
. Disabled by default. - Feature flag renamed to
maven_virtual_registry
in GitLab 18.1. - Changed from experiment to beta in GitLab 18.1.
- Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 18.2.
{{< /history >}}
Deletes a specific cache entry for a Maven upstream registry.
DELETE /virtual_registries/packages/maven/cache_entries/*id
Attribute | Type | Required | Description |
---|---|---|---|
id |
string | yes | The base64-encoded upstream ID and relative path of the cache entry (for example, 'Zm9vL2Jhci9teXBrZy5wb20='). |
Example request:
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
--header "Accept: application/json" \
--url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/cache_entries/Zm9vL2Jhci9teXBrZy5wb20="
If successful, returns a 204 No Content
status code.
Manage package operations
Use the following endpoints to manage package operations for a Maven virtual registry.
{{< alert type="warning" >}}
These endpoints are intended for internal use by GitLab, and generally not meant for manual consumption.
{{< /alert >}}
{{< alert type="note" >}}
These endpoints do not adhere to the REST API authentication methods. For more information on which headers and token types are supported, see Maven virtual registry. Undocumented authentication methods might be removed in the future.
{{< /alert >}}
Download a package
{{< history >}}
- Introduced in GitLab 17.3 with a flag named
virtual_registry_maven
. Disabled by default. - Feature flag renamed to
maven_virtual_registry
in GitLab 18.1. - Changed from experiment to beta in GitLab 18.1.
- Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 18.2.
{{< /history >}}
Downloads a package from a Maven virtual registry. To access this resource, you must authenticate with the registry.
GET /virtual_registries/packages/maven/:id/*path
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:
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/1/foo/bar/mypkg/1.0-SNAPSHOT/mypkg-1.0-SNAPSHOT.jar" \
--output mypkg-1.0-SNAPSHOT.jar
If successful, returns 200 OK
and
the following response headers:
x-checksum-sha1
: SHA1 checksum of the filex-checksum-md5
: MD5 checksum of the fileContent-Type
: The MIME type of the fileContent-Length
: The file size in bytes
Upload a package
{{< history >}}
- Introduced in GitLab 17.4 with a flag named
virtual_registry_maven
. Disabled by default. - Feature flag renamed to
maven_virtual_registry
in GitLab 18.1. - Changed from experiment to beta in GitLab 18.1.
- Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 18.2.
{{< /history >}}
Uploads a package to a Maven virtual registry. This endpoint is accessible only by GitLab Workhorse.
POST /virtual_registries/packages/maven/:id/*path/upload
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 fileGitLab-Workhorse-Send-Dependency-Content-Type
: Content type of the fileUpstream-GID
: Global ID of the target upstream
If successful, returns a 200 OK
status code.