Documentation
Documentation
https://docs.gitlab.com/api/
APIReference
https://docs.gitlab.com/api/api_resources/
Authentication
https://docs.gitlab.com/api/rest/authentication/
OpenAPI Specification
swagger: '2.0'
info:
title: GitLab access_requests releases API
version: v4
description: Operations related to access requests
host: gitlab.com
produces:
- application/json
tags:
- name: releases
description: Operations related to releases
paths:
/api/v4/groups/{id}/releases:
get:
summary: List group releases
description: Returns a list of group releases.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the group owned by the authenticated user
type: string
required: true
- in: query
name: sort
description: The direction of the order. Either `desc` (default) for descending order or `asc` for ascending order
type: string
default: desc
enum:
- asc
- desc
required: false
- in: query
name: simple
description: Return only limited fields for each release
type: boolean
default: false
required: false
- in: query
name: page
description: Current page number
type: integer
format: int32
default: 1
required: false
example: 1
- in: query
name: per_page
description: Number of items per page
type: integer
format: int32
default: 20
required: false
example: 20
responses:
'200':
description: List group releases
schema:
type: array
items:
$ref: '#/definitions/API_Entities_Release'
'400':
description: Bad request
'403':
description: Forbidden
'404':
description: Not found
tags:
- releases
operationId: getApiV4GroupsIdReleases
/api/v4/projects/{id}/releases:
get:
summary: List Releases
description: Returns a paginated list of releases. This feature was introduced in GitLab 11.7.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- in: query
name: page
description: Current page number
type: integer
format: int32
default: 1
required: false
example: 1
- in: query
name: per_page
description: Number of items per page
type: integer
format: int32
default: 20
required: false
example: 20
- in: query
name: order_by
description: The field to use as order. Either `released_at` (default) or `created_at`
type: string
default: released_at
enum:
- released_at
- created_at
required: false
- in: query
name: sort
description: The direction of the order. Either `desc` (default) for descending order or `asc` for ascending order
type: string
default: desc
enum:
- asc
- desc
required: false
- in: query
name: include_html_description
description: If `true`, a response includes HTML rendered markdown of the release description
type: boolean
required: false
- in: query
name: updated_before
description: 'Return releases updated before the specified datetime. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ'
type: string
format: date-time
required: false
- in: query
name: updated_after
description: 'Return releases updated after the specified datetime. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ'
type: string
format: date-time
required: false
responses:
'200':
description: List Releases
schema:
type: array
items:
$ref: '#/definitions/API_Entities_Release'
tags:
- releases
operationId: getApiV4ProjectsIdReleases
post:
summary: Create a release
description: Creates a release. Developer level access to the project is required to create a release. This feature was introduced in GitLab 11.7.
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- name: postApiV4ProjectsIdReleases
in: body
required: true
schema:
$ref: '#/definitions/postApiV4ProjectsIdReleases'
responses:
'201':
description: Create a release
schema:
$ref: '#/definitions/API_Entities_Release'
'400':
description: Bad request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not found
'409':
description: Conflict
'422':
description: Unprocessable entity
tags:
- releases
operationId: postApiV4ProjectsIdReleases
/api/v4/projects/{id}/releases/{tag_name}:
get:
summary: Get a release by a tag name
description: Gets a release for the given tag. This feature was introduced in GitLab 11.7.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- in: path
name: tag_name
description: The Git tag the release is associated with
type: string
required: true
- in: query
name: include_html_description
description: If `true`, a response includes HTML rendered markdown of the release description
type: boolean
required: false
responses:
'200':
description: Get a release by a tag name
schema:
$ref: '#/definitions/API_Entities_Release'
'401':
description: Unauthorized
'404':
description: Not found
tags:
- releases
operationId: getApiV4ProjectsIdReleasesTagName
put:
summary: Update a release
description: Updates a release. Developer level access to the project is required to update a release. This feature was introduced in GitLab 11.7.
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- in: path
name: tag_name
description: The Git tag the release is associated with
type: string
required: true
- name: putApiV4ProjectsIdReleasesTagName
in: body
required: true
schema:
$ref: '#/definitions/putApiV4ProjectsIdReleasesTagName'
responses:
'200':
description: Update a release
schema:
$ref: '#/definitions/API_Entities_Release'
'400':
description: Bad request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not found
tags:
- releases
operationId: putApiV4ProjectsIdReleasesTagName
delete:
summary: Delete a release
description: Delete a release. Deleting a release doesn't delete the associated tag. Maintainer level access to the project is required to delete a release. This feature was introduced in GitLab 11.7.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- in: path
name: tag_name
description: The Git tag the release is associated with
type: string
required: true
responses:
'400':
description: Bad request
'204':
description: Delete a release
schema:
$ref: '#/definitions/API_Entities_Release'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not found
tags:
- releases
operationId: deleteApiV4ProjectsIdReleasesTagName
/api/v4/projects/{id}/releases/{tag_name}/downloads/*direct_asset_path:
get:
summary: Download a project release asset file
description: This feature was introduced in GitLab 15.4.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- in: path
name: tag_name
description: The Git tag the release is associated with
type: string
required: true
- in: query
name: direct_asset_path
description: The path to the file to download, as specified when creating the release asset
type: string
required: true
responses:
'200':
description: Download a project release asset file
'401':
description: Unauthorized
'404':
description: Not found
tags:
- releases
operationId: getApiV4ProjectsIdReleasesTagNameDownloads*directAssetPath
/api/v4/projects/{id}/releases/permalink/latest(/)(*suffix_path):
get:
summary: Get the latest project release
description: This feature was introduced in GitLab 15.4.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- in: query
name: suffix_path
description: The path to be suffixed to the latest release
type: string
required: true
responses:
'200':
description: Get the latest project release
'401':
description: Unauthorized
'404':
description: Not found
tags:
- releases
operationId: getApiV4ProjectsIdReleasesPermalinkLatest()(*suffixPath)
/api/v4/projects/{id}/releases/{tag_name}/evidence:
post:
summary: Collect release evidence
description: Creates an evidence for an existing Release. This feature was introduced in GitLab 12.10.
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: tag_name
description: The Git tag the release is associated with
type: string
required: true
- in: path
name: id
type: integer
format: int32
required: true
responses:
'201':
description: Collect release evidence
schema:
$ref: '#/definitions/API_Entities_Release'
'401':
description: Unauthorized
'404':
description: Not found
tags:
- releases
operationId: postApiV4ProjectsIdReleasesTagNameEvidence
/api/v4/projects/{id}/releases/{tag_name}/assets/links:
get:
summary: List links of a release
description: Get assets as links from a release. This feature was introduced in GitLab 11.7.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- in: path
name: tag_name
description: The tag associated with the release
type: string
required: true
- in: query
name: page
description: Current page number
type: integer
format: int32
default: 1
required: false
example: 1
- in: query
name: per_page
description: Number of items per page
type: integer
format: int32
default: 20
required: false
example: 20
responses:
'200':
description: List links of a release
schema:
type: array
items:
$ref: '#/definitions/API_Entities_Releases_Link'
'401':
description: Unauthorized
'404':
description: Not found
tags:
- releases
operationId: getApiV4ProjectsIdReleasesTagNameAssetsLinks
post:
summary: Create a release link
description: Create an asset as a link from a release. This feature was introduced in GitLab 11.7.
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- in: path
name: tag_name
description: The tag associated with the release
type: string
required: true
- name: postApiV4ProjectsIdReleasesTagNameAssetsLinks
in: body
required: true
schema:
$ref: '#/definitions/postApiV4ProjectsIdReleasesTagNameAssetsLinks'
responses:
'201':
description: Create a release link
schema:
$ref: '#/definitions/API_Entities_Releases_Link'
'400':
description: Bad request
'401':
description: Unauthorized
tags:
- releases
operationId: postApiV4ProjectsIdReleasesTagNameAssetsLinks
/api/v4/projects/{id}/releases/{tag_name}/assets/links/{link_id}:
get:
summary: Get a release link
description: Get an asset as a link from a release. This feature was introduced in GitLab 11.7.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- in: path
name: tag_name
description: The tag associated with the release
type: string
required: true
- in: path
name: link_id
description: The ID of the link
type: integer
format: int32
required: true
responses:
'200':
description: Get a release link
schema:
$ref: '#/definitions/API_Entities_Releases_Link'
'401':
description: Unauthorized
'404':
description: Not found
tags:
- releases
operationId: getApiV4ProjectsIdReleasesTagNameAssetsLinksLinkId
put:
summary: Update a release link
description: Update an asset as a link from a release. This feature was introduced in GitLab 11.7.
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- in: path
name: tag_name
description: The tag associated with the release
type: string
required: true
- in: path
name: link_id
description: The ID of the link
type: integer
format: int32
required: true
- name: putApiV4ProjectsIdReleasesTagNameAssetsLinksLinkId
in: body
required: true
schema:
$ref: '#/definitions/putApiV4ProjectsIdReleasesTagNameAssetsLinksLinkId'
responses:
'200':
description: Update a release link
schema:
$ref: '#/definitions/API_Entities_Releases_Link'
'400':
description: Bad request
'401':
description: Unauthorized
tags:
- releases
operationId: putApiV4ProjectsIdReleasesTagNameAssetsLinksLinkId
delete:
summary: Delete a release link
description: Deletes an asset as a link from a release. This feature was introduced in GitLab 11.7.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- in: path
name: tag_name
description: The tag associated with the release
type: string
required: true
- in: path
name: link_id
description: The ID of the link
type: integer
format: int32
required: true
responses:
'204':
description: Bad request
'401':
description: Unauthorized
tags:
- releases
operationId: deleteApiV4ProjectsIdReleasesTagNameAssetsLinksLinkId
definitions:
API_Entities_CustomAttribute:
type: object
properties:
key:
type: string
example: foo
value:
type: string
example: bar
required:
- key
- value
description: API_Entities_CustomAttribute model
API_Entities_Releases_Link:
type: object
properties:
id:
type: integer
format: int32
example: 1
name:
type: string
example: app-v1.0.dmg
url:
type: string
example: https://gitlab.example.com/root/app/-/jobs/688/artifacts/raw/bin/app-v1.0.dmg
direct_asset_url:
type: string
example: https://gitlab.example.com/root/app/-/releases/v1.0/downloads/app-v1.0.dmg
link_type:
type: string
example: other
required:
- id
- name
- url
- direct_asset_url
- link_type
description: API_Entities_Releases_Link model
postApiV4ProjectsIdReleases:
type: object
properties:
tag_name:
type: string
description: The tag where the release is created from
tag_message:
type: string
description: Message to use if creating a new annotated tag
name:
type: string
description: The release name
description:
type: string
description: The description of the release. You can use Markdown
ref:
type: string
description: If a tag specified in `tag_name` doesn't exist, the release is created from `ref` and tagged with `tag_name`. It can be a commit SHA, another tag name, or a branch name.
assets:
type: object
description: Object that contains assets for the release
properties:
links:
type: array
description: Link information about the release
items:
type: object
properties:
name:
type: string
description: The name of the link. Link names must be unique within the release
url:
type: string
description: The URL of the link. Link URLs must be unique within the release
direct_asset_path:
type: string
description: Optional path for a direct asset link
filepath:
type: string
description: 'Deprecated: optional path for a direct asset link'
link_type:
type: string
description: 'The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`'
required:
- name
- url
milestones:
type: array
description: The title of each milestone the release is associated with. GitLab Premium customers can specify group milestones. Cannot be combined with `milestone_ids` parameter.
items:
type: string
milestone_ids:
type: string
description: The ID of each milestone the release is associated with. GitLab Premium customers can specify group milestones. Cannot be combined with `milestones` parameter.
released_at:
type: string
format: date-time
description: Date and time for the release. Defaults to the current time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). Only provide this field if creating an upcoming or historical release.
legacy_catalog_publish:
type: boolean
description: If true, the release will be published to the CI catalog. This parameter is for internal use only and will be removed in a future release. If the feature flag ci_release_cli_catalog_publish_option is disabled, this parameter will be ignored and the release will published to the CI catalog as it was before this parameter was introduced.
required:
- tag_name
description: Create a release
putApiV4ProjectsIdReleasesTagName:
type: object
properties:
name:
type: string
description: The release name
description:
type: string
description: The description of the release. You can use Markdown
released_at:
type: string
format: date-time
description: The date when the release is/was ready. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`)
milestones:
type: array
description: The title of each milestone to associate with the release. GitLab Premium customers can specify group milestones. Cannot be combined with `milestone_ids` parameter. To remove all milestones from the release, specify `[]`
items:
type: string
milestone_ids:
type: string
description: The ID of each milestone the release is associated with. GitLab Premium customers can specify group milestones. Cannot be combined with `milestones` parameter. To remove all milestones from the release, specify `[]`
description: Update a release
API_Entities_MilestoneWithStats:
type: object
properties:
id:
type: integer
format: int32
iid:
type: integer
format: int32
project_id:
type: integer
format: int32
group_id:
type: string
title:
type: string
description:
type: string
state:
type: string
created_at:
type: string
updated_at:
type: string
due_date:
type: string
start_date:
type: string
expired:
type: boolean
web_url:
type: string
issue_stats:
type: object
properties:
total:
type: integer
format: int32
example: 10
closed:
type: integer
format: int32
example: 5
required:
- total
- closed
required:
- id
- iid
- title
- description
- state
- created_at
- updated_at
- due_date
- start_date
- expired
- web_url
- issue_stats
API_Entities_UserBasic:
type: object
properties:
id:
type: integer
format: int32
example: 1
username:
type: string
example: admin
public_email:
type: string
example: john@example.com
name:
type: string
example: Administrator
state:
type: string
example: active
locked:
type: boolean
avatar_url:
type: string
example: https://gravatar.com/avatar/1
avatar_path:
type: string
example: /user/avatar/28/The-Big-Lebowski-400-400.png
custom_attributes:
type: array
items:
$ref: '#/definitions/API_Entities_CustomAttribute'
web_url:
type: string
example: https://gitlab.example.com/root
required:
- id
- username
- public_email
- name
- state
- locked
- avatar_url
- web_url
description: API_Entities_UserBasic model
API_Entities_Commit:
type: object
properties:
id:
type: string
example: 2695effb5807a22ff3d138d593fd856244e155e7
short_id:
type: string
example: 2695effb
created_at:
type: string
format: date-time
example: '2017-07-26T11:08:53.000+02:00'
parent_ids:
type: array
items:
type: string
example:
- 2a4b78934375d7f53875269ffd4f45fd83a84ebe
title:
type: string
example: Initial commit
message:
type: string
example: Initial commit
author_name:
type: string
example: John Smith
author_email:
type: string
example: john@example.com
authored_date:
type: string
format: date-time
example: '2012-05-28T04:42:42-07:00'
committer_name:
type: string
example: Jack Smith
committer_email:
type: string
example: jack@example.com
committed_date:
type: string
format: date-time
example: '2012-05-28T04:42:42-07:00'
trailers:
type: object
example:
Merged-By: Jane Doe janedoe@gitlab.com
extended_trailers:
type: object
example:
Signed-off-by:
- John Doe <johndoe@gitlab.com>
- Jane Doe <janedoe@gitlab.com>
web_url:
type: string
example: https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746
required:
- id
- short_id
- created_at
- parent_ids
- title
- message
- author_name
- author_email
- authored_date
- committer_name
- committer_email
- committed_date
- trailers
- extended_trailers
- web_url
description: API_Entities_Commit model
putApiV4ProjectsIdReleasesTagNameAssetsLinksLinkId:
type: object
properties:
name:
type: string
description: The name of the link
url:
type: string
description: The URL of the link
direct_asset_path:
type: string
description: Optional path for a direct asset link
filepath:
type: string
description: 'Deprecated: optional path for a direct asset link'
link_type:
type: string
description: 'The type of the link: `other`, `runbook`, `image`, or `package`. Defaults to `other`'
enum:
- other
- runbook
- image
- package
default: other
description: Update a release link
API_Entities_Release:
type: object
properties:
name:
type: string
example: Release v1.0
tag_name:
type: string
example: v1.0
description:
type: string
example: Finally released v1.0
created_at:
type: string
format: date-time
example: '2019-01-03T01:56:19.539Z'
released_at:
type: string
format: date-time
example: '2019-01-03T01:56:19.539Z'
upcoming_release:
type: boolean
description_html:
type: string
author:
$ref: '#/definitions/API_Entities_UserBasic'
commit:
$ref: '#/definitions/API_Entities_Commit'
milestones:
$ref: '#/definitions/API_Entities_MilestoneWithStats'
commit_path:
type: string
example: /root/app/commit/588440f66559714280628a4f9799f0c4eb880a4a
tag_path:
type: string
example: /root/app/-/tags/v1.0
assets:
type: object
properties:
count:
type: integer
format: int32
example: 2
sources:
$ref: '#/definitions/API_Entities_Releases_Source'
links:
$ref: '#/definitions/API_Entities_Releases_Link'
required:
- count
- links
evidences:
$ref: '#/definitions/API_Entities_Releases_Evidence'
_links:
type: object
properties:
closed_issues_url:
type: string
closed_merge_requests_url:
type: string
edit_url:
type: string
merged_merge_requests_url:
type: string
opened_issues_url:
type: string
opened_merge_requests_url:
type: string
self:
type: string
required:
- name
- tag_name
- description
- created_at
- released_at
- upcoming_release
- assets
- _links
description: API_Entities_Release model
postApiV4ProjectsIdReleasesTagNameAssetsLinks:
type: object
properties:
name:
type: string
description: The name of the link. Link names must be unique in the release
url:
type: string
description: The URL of the link. Link URLs must be unique in the release.
direct_asset_path:
type: string
description: Optional path for a direct asset link
filepath:
type: string
description: 'Deprecated: optional path for a direct asset link'
link_type:
type: string
description: 'The type of the link: `other`, `runbook`, `image`, or `package`. Defaults to `other`'
enum:
- other
- runbook
- image
- package
default: other
required:
- name
- url
description: Create a release link
API_Entities_Releases_Evidence:
type: object
properties:
sha:
type: string
example: 760d6cdfb0879c3ffedec13af470e0f71cf52c6cde4d
filepath:
type: string
example: https://gitlab.example.com/root/app/-/releases/v1.0/evidence.json
collected_at:
type: string
format: date-time
example: '2019-01-03T01:56:19.539Z'
required:
- sha
- filepath
- collected_at
API_Entities_Releases_Source:
type: object
properties:
format:
type: string
example: zip
url:
type: string
example: https://gitlab.example.com/root/app/-/archive/v1.0/app-v1.0.zip
required:
- format
- url
securityDefinitions:
access_token_header:
type: apiKey
name: PRIVATE-TOKEN
in: header
access_token_query:
type: apiKey
name: private_token
in: query