Release links API - Gitlabhq

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

Added authentication with a GitLab CI/CD job token in GitLab 15.1.

Use this API to interact with links to releases.

GitLab supports asset links with the following protocols:

http
https
ftp

[!note] To interact with project releases directly, see the project release API.

List all release links

Lists all assets as links from a release.

plaintext

GET /projects/:id/releases/:tag_name/assets/links

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the project.
`tag_name`	string	yes	The tag associated with the Release.

Example request:

shell

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/24/releases/v0.1/assets/links"

Example response:

json

[
   {
      "id":2,
      "name":"awesome-v0.2.msi",
      "url":"http://192.168.10.15:3000/msi",
      "link_type":"other"
   },
   {
      "id":1,
      "name":"awesome-v0.2.dmg",
      "url":"http://192.168.10.15:3000",
      "link_type":"other"
   }
]

Retrieve a release link

Retrieves a specified asset as a link from a release.

plaintext

GET /projects/:id/releases/:tag_name/assets/links/:link_id

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the project.
`tag_name`	string	yes	The tag associated with the Release.
`link_id`	integer	yes	The ID of the link.

Example request:

shell

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/24/releases/v0.1/assets/links/1"

Example response:

json

{
   "id":1,
   "name":"awesome-v0.2.dmg",
   "url":"http://192.168.10.15:3000",
   "link_type":"other"
}

Create a release link

Creates an asset link for a specified release.

plaintext

POST /projects/:id/releases/:tag_name/assets/links

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the project.
`tag_name`	string	yes	The tag associated with the Release.
`name`	string	yes	The name of the link. Link names must be unique in the release.
`url`	string	yes	The URL of the link. Link URLs must be unique in the release.
`direct_asset_path`	string	no	Optional path for a direct asset link.
`link_type`	string	no	The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`.

Example request:

shell

curl --request POST \
    --header "PRIVATE-TOKEN: <your_access_token>" \
    --data name="hellodarwin-amd64" \
    --data url="https://gitlab.example.com/mynamespace/hello/-/jobs/688/artifacts/raw/bin/hello-darwin-amd64" \
    --data direct_asset_path="/bin/hellodarwin-amd64" \
    "https://gitlab.example.com/api/v4/projects/20/releases/v1.7.0/assets/links"

Example response:

json

{
   "id":2,
   "name":"hellodarwin-amd64",
   "url":"https://gitlab.example.com/mynamespace/hello/-/jobs/688/artifacts/raw/bin/hello-darwin-amd64",
   "direct_asset_url":"https://gitlab.example.com/mynamespace/hello/-/releases/v1.7.0/downloads/bin/hellodarwin-amd64",
   "link_type":"other"
}

Update a release link

Updates a specified asset link for a release.

plaintext

PUT /projects/:id/releases/:tag_name/assets/links/:link_id

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the project.
`tag_name`	string	yes	The tag associated with the Release.
`link_id`	integer	yes	The ID of the link.
`name`	string	no	The name of the link.
`url`	string	no	The URL of the link.
`direct_asset_path`	string	no	Optional path for a direct asset link.
`link_type`	string	no	The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`.

[!note] You have to specify at least one of name or url

Example request:

shell

curl --request PUT --data name="new name" --data link_type="runbook" \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/24/releases/v0.1/assets/links/1"

Example response:

json

{
   "id":1,
   "name":"new name",
   "url":"http://192.168.10.15:3000",
   "link_type":"runbook"
}

Delete a release link

Deletes a specified asset link from a release.

plaintext

DELETE /projects/:id/releases/:tag_name/assets/links/:link_id

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the project.
`tag_name`	string	yes	The tag associated with the Release.
`link_id`	integer	yes	The ID of the link.

Example request:

shell

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/24/releases/v0.1/assets/links/1"

Example response:

json

{
   "id":1,
   "name":"new name",
   "url":"http://192.168.10.15:3000",
   "link_type":"other"
}