Create a release

POST

/api/v4/projects/{id}/releases

• GitLab REST API

Creates a release. Developer level access to the project is required to create a release.

Authorizations

• http
• oauth2

Parameters

Path Parameters

id

required

One of:

string

string

integer

integer

The ID or URL-encoded path of the project

Request Body ^required

Media type application/json

object

tag_name

required

The tag where the release is created from

string

nullable

tag_message

Message to use if creating a new annotated tag

string

nullable

name

The release name

string

nullable

description

The description of the release. You can use Markdown

string

nullable

ref

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.

string

nullable

assets

Object that contains assets for the release

object

links

Link information about the release

Array<object>

nullable

object

name

required

The name of the link. Link names must be unique within the release

string

nullable

url

required

The URL of the link. Link URLs must be unique within the release

string

nullable

direct_asset_path

Optional path for a direct asset link

string

nullable

filepath

Deprecated: optional path for a direct asset link

string

nullable

link_type

The type of the link: other, runbook, image, package. Defaults to other

string

nullable

milestones

The title of each milestone the release is associated with. GitLab Premium customers can specify group milestones. Cannot be combined with milestone_ids parameter.

Array<string>

nullable

milestone_ids

One of:

string

string

nullable

integer

integer

nullable

released_at

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.

string format: date-time

nullable

legacy_catalog_publish

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.

boolean

nullable

Example ^generated

{
  "tag_name": "example",
  "tag_message": "example",
  "name": "example",
  "description": "example",
  "ref": "example",
  "assets": {
    "links": [
      {
        "name": "example",
        "url": "example",
        "direct_asset_path": "example",
        "filepath": "example",
        "link_type": "example"
      }
    ]
  },
  "milestones": [
    "example"
  ],
  "milestone_ids": "example",
  "released_at": "2026-04-15T12:00:00Z",
  "legacy_catalog_publish": true
}

Responses

201

Created

Media type application/json

object

name

string

tag_name

string

description

string

created_at

string format: date-time

released_at

string format: date-time

upcoming_release

boolean

description_html

string

author

object

id

integer format: int64

username

string

public_email

string

name

string

state

string

locked

boolean

avatar_url

string

avatar_path

string

custom_attributes

Array<object>

object

key

string

value

string

web_url

string

commit

object

id

string

short_id

string

created_at

string format: date-time

parent_ids

Array<string>

title

string

message

string

author_name

string

author_email

string

authored_date

string format: date-time

committer_name

string

committer_email

string

committed_date

string format: date-time

trailers

object

extended_trailers

object

web_url

string

milestones

object

id

integer format: int64

iid

integer format: int64

project_id

integer format: int64

group_id

string

title

string

description

string

state

string

created_at

string

updated_at

string

due_date

string

start_date

string

expired

boolean

web_url

string

issue_stats

object

commit_path

string

tag_path

string

assets

string

evidences

object

sha

string

filepath

string

collected_at

string format: date-time

_links

string

Example

{
  "name": "Release v1.0",
  "tag_name": "v1.0",
  "description": "Finally released v1.0",
  "created_at": "2019-01-03T01:56:19.539Z",
  "released_at": "2019-01-03T01:56:19.539Z",
  "author": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "commit": {
    "id": "2695effb5807a22ff3d138d593fd856244e155e7",
    "short_id": "2695effb",
    "created_at": "2017-07-26T11:08:53.000+02:00",
    "parent_ids": [
      "2a4b78934375d7f53875269ffd4f45fd83a84ebe"
    ],
    "title": "Initial commit",
    "message": "Initial commit",
    "author_name": "John Smith",
    "author_email": "john@example.com",
    "authored_date": "2012-05-28T04:42:42-07:00",
    "committer_name": "Jack Smith",
    "committer_email": "jack@example.com",
    "committed_date": "2012-05-28T04:42:42-07:00",
    "trailers": {
      "Merged-By": "Jane Doe janedoe@gitlab.com"
    },
    "extended_trailers": {
      "Signed-off-by": [
        "John Doe <johndoe@gitlab.com>",
        "Jane Doe <janedoe@gitlab.com>"
      ]
    },
    "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746"
  },
  "commit_path": "/root/app/commit/588440f66559714280628a4f9799f0c4eb880a4a",
  "tag_path": "/root/app/-/tags/v1.0",
  "evidences": {
    "sha": "760d6cdfb0879c3ffedec13af470e0f71cf52c6cde4d",
    "filepath": "https://gitlab.example.com/root/app/-/releases/v1.0/evidence.json",
    "collected_at": "2019-01-03T01:56:19.539Z"
  }
}

400

Bad request

401

Unauthorized

403

Forbidden

404

Not found

409

Conflict

422

Unprocessable entity