- List project milestones
- Get single milestone
- Create new milestone
- Edit milestone
- Delete project milestone
- Get all issues assigned to a single milestone
- Get all merge requests assigned to a single milestone
- Promote project milestone to a group milestone
- Get all burndown chart events for a single milestone
Project milestones API
Use project milestones with the REST API. There’s a separate group milestones API page.
List project milestones
Returns a list of project milestones.
GET /projects/:id/milestones
GET /projects/:id/milestones?iids[]=42
GET /projects/:id/milestones?iids[]=42&iids[]=43
GET /projects/:id/milestones?state=active
GET /projects/:id/milestones?state=closed
GET /projects/:id/milestones?title=1.0
GET /projects/:id/milestones?search=version
GET /projects/:id/milestones?updated_before=2013-10-02T09%3A24%3A18Z
GET /projects/:id/milestones?updated_after=2013-10-02T09%3A24%3A18Z
Parameters:
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
iids[] | integer array | no | Return only the milestones having the given iid (Note: ignored if include_parent_milestones is set as true) |
state | string | no | Return only active or closed milestones |
title | string | no | Return only the milestones having the given title
|
search | string | no | Return only milestones with a title or description matching the provided string |
include_parent_milestones | boolean | no | Include group milestones from parent group and its ancestors. Introduced in GitLab 13.4 |
updated_before | datetime | no | Return only milestones updated before the given datetime. Expected in ISO 8601 format (2019-03-15T08:00:00Z). Introduced in GitLab 15.10 |
updated_after | datetime | no | Return only milestones updated after the given datetime. Expected in ISO 8601 format (2019-03-15T08:00:00Z). Introduced in GitLab 15.10 |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/milestones"
Example Response:
[
{
"id": 12,
"iid": 3,
"project_id": 16,
"title": "10.0",
"description": "Version",
"due_date": "2013-11-29",
"start_date": "2013-11-10",
"state": "active",
"updated_at": "2013-10-02T09:24:18Z",
"created_at": "2013-10-02T09:24:18Z",
"expired": false
}
]
Get single milestone
Gets a single project milestone.
GET /projects/:id/milestones/:milestone_id
Parameters:
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
milestone_id | integer | yes | The ID of the project’s milestone |
Create new milestone
Creates a new project milestone.
POST /projects/:id/milestones
Parameters:
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
title | string | yes | The title of a milestone |
description | string | no | The description of the milestone |
due_date | string | no | The due date of the milestone (YYYY-MM-DD) |
start_date | string | no | The start date of the milestone (YYYY-MM-DD) |
Edit milestone
Updates an existing project milestone.
PUT /projects/:id/milestones/:milestone_id
Parameters:
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
milestone_id | integer | yes | The ID of the project’s milestone |
title | string | no | The title of a milestone |
description | string | no | The description of the milestone |
due_date | string | no | The due date of the milestone (YYYY-MM-DD) |
start_date | string | no | The start date of the milestone (YYYY-MM-DD) |
state_event | string | no | The state event of the milestone (close or activate) |
Delete project milestone
Changed the minimum user role from Developer to Reporter in GitLab 15.0.
Only for users with at least the Reporter role in the project.
DELETE /projects/:id/milestones/:milestone_id
Parameters:
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
milestone_id | integer | yes | The ID of the project’s milestone |
Get all issues assigned to a single milestone
Gets all issues assigned to a single project milestone.
GET /projects/:id/milestones/:milestone_id/issues
Parameters:
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
milestone_id | integer | yes | The ID of the project’s milestone |
Get all merge requests assigned to a single milestone
Gets all merge requests assigned to a single project milestone.
GET /projects/:id/milestones/:milestone_id/merge_requests
Parameters:
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
milestone_id | integer | yes | The ID of the project’s milestone |
Promote project milestone to a group milestone
Changed the minimum user role from Developer to Reporter in GitLab 15.0.
Only for users with at least the Reporter role in the group.
POST /projects/:id/milestones/:milestone_id/promote
Parameters:
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
milestone_id | integer | yes | The ID of the project’s milestone |
Get all burndown chart events for a single milestone
Version history
- Introduced in GitLab 12.1
- Moved to GitLab Premium in 13.9.
Gets all burndown chart events for a single milestone.
GET /projects/:id/milestones/:milestone_id/burndown_events
Parameters:
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
milestone_id | integer | yes | The ID of the project’s milestone |