---
title: "Create a release"
method: POST
path: "/api/v4/projects/{id}/releases"
tags: ["releases"]
---

# Create a release

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

## Request

- Base URL: `https://gitlab.com`
- URL: `https://gitlab.com/api/v4/projects/{id}/releases`
- Auth: none declared

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

## Path parameters

- `id` string, required

## Request body

- PostApiV4ProjectsIdReleases: Create a release
  - `tag_name` string, required: The tag where the release is created from
  - `tag_message` string: Message to use if creating a new annotated tag
  - `name` string: The release name
  - `description` string: The description of the release. You can use Markdown
  - `ref` string: 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` object: Object that contains assets for the release
    - `links` object[]: Link information about the release
      - `name` string, required: The name of the link. Link names must be unique within the release
      - `url` string, required: The URL of the link. Link URLs must be unique within the release
      - `direct_asset_path` string: Optional path for a direct asset link
      - `filepath` string: Deprecated: optional path for a direct asset link
      - `link_type` string: The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`
  - `milestones` string[]: The title of each milestone the release is associated with. GitLab Premium customers can specify group milestones. Cannot be combined with `milestone_ids` parameter.
  - `milestone_ids` string: 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` string, date-time: 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` boolean: 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.

## Response `201`

Create a release

- APIEntitiesRelease: API_Entities_Release model
  - `name` string, required
  - `tag_name` string, required
  - `description` string, required
  - `created_at` string, date-time, required
  - `released_at` string, date-time, required
  - `upcoming_release` boolean, required
  - `description_html` string
  - `author` APIEntitiesUserBasic: API_Entities_UserBasic model
    - `id` integer, required
    - `username` string, required
    - `public_email` string, required
    - `name` string, required
    - `state` string, required
    - `locked` boolean, required
    - `avatar_url` string, required
    - `avatar_path` string
    - `custom_attributes` APIEntitiesCustomAttribute[]
      - `key` string, required
      - `value` string, required
    - `web_url` string, required
  - `commit` APIEntitiesCommit: API_Entities_Commit model
    - `id` string, required
    - `short_id` string, required
    - `created_at` string, date-time, required
    - `parent_ids` string[], required
    - `title` string, required
    - `message` string, required
    - `author_name` string, required
    - `author_email` string, required
    - `authored_date` string, date-time, required
    - `committer_name` string, required
    - `committer_email` string, required
    - `committed_date` string, date-time, required
    - `trailers` object, required
    - `extended_trailers` object, required
    - `web_url` string, required
  - `milestones` APIEntitiesMilestoneWithStats
    - `id` integer, required
    - `iid` integer, required
    - `project_id` integer
    - `group_id` string
    - `title` string, required
    - `description` string, required
    - `state` string, required
    - `created_at` string, required
    - `updated_at` string, required
    - `due_date` string, required
    - `start_date` string, required
    - `expired` boolean, required
    - `web_url` string, required
    - `issue_stats` object, required
      - `total` integer, required
      - `closed` integer, required
  - `commit_path` string
  - `tag_path` string
  - `assets` object, required
    - `count` integer, required
    - `sources` APIEntitiesReleasesSource
      - `format` string, required
      - `url` string, required
    - `links` APIEntitiesReleasesLink, required: API_Entities_Releases_Link model
      - `id` integer, required
      - `name` string, required
      - `url` string, required
      - `direct_asset_url` string, required
      - `link_type` string, required
  - `evidences` APIEntitiesReleasesEvidence
    - `sha` string, required
    - `filepath` string, required
    - `collected_at` string, date-time, required
  - `_links` object, required
    - `closed_issues_url` string
    - `closed_merge_requests_url` string
    - `edit_url` string
    - `merged_merge_requests_url` string
    - `opened_issues_url` string
    - `opened_merge_requests_url` string
    - `self` string

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict
- `422`: Unprocessable entity

---

[API](https://skmtc.dev/gitlab/apis/gitlab-api.md) - [All operations](https://skmtc.dev/gitlab/apis/gitlab-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gitlab/apis/gitlab-api/revisions/b234947ef3f2?raw)