# Milestones

## Project milestones

### Reference

- v4 API:

  - `gitlab.v4.objects.ProjectMilestone`

  - `gitlab.v4.objects.ProjectMilestoneManager`

  - `gitlab.v4.objects.Project.milestones`

  - `gitlab.v4.objects.GroupMilestone`

  - `gitlab.v4.objects.GroupMilestoneManager`

  - `gitlab.v4.objects.Group.milestones`

- GitLab API:

  - https://docs.gitlab.com/api/milestones

  - https://docs.gitlab.com/api/group_milestones

### Examples

List the milestones for a project or a group:

    p_milestones = project.milestones.list(get_all=True)
    g_milestones = group.milestones.list(get_all=True)

You can filter the list using the following parameters:

- `iids`: unique IDs of milestones for the project

- `state`: either `active` or `closed`

- `search`: to search using a string

    p_milestones = project.milestones.list(state='closed', get_all=True)
    g_milestones = group.milestones.list(state='active', get_all=True)

Get a single milestone:

    p_milestone = project.milestones.get(milestone_id)
    g_milestone = group.milestones.get(milestone_id)

Create a milestone:

    milestone = project.milestones.create({'title': '1.0'})

Edit a milestone:

    milestone.description = 'v 1.0 release'
    milestone.save()

Change the state of a milestone (activate / close):

    # close a milestone
    milestone.state_event = 'close'
    milestone.save()

    # activate a milestone
    milestone.state_event = 'activate'
    milestone.save()

Promote a project milestone:

    milestone.promote()

List the issues related to a milestone:

    issues = milestone.issues()

List the merge requests related to a milestone:

    merge_requests = milestone.merge_requests()

## Milestone events

Resource milestone events keep track of what happens to GitLab issues and merge requests.

### Reference

- v4 API:

  - `gitlab.v4.objects.ProjectIssueResourceMilestoneEvent`

  - `gitlab.v4.objects.ProjectIssueResourceMilestoneEventManager`

  - `gitlab.v4.objects.ProjectIssue.resourcemilestoneevents`

  - `gitlab.v4.objects.ProjectMergeRequestResourceMilestoneEvent`

  - `gitlab.v4.objects.ProjectMergeRequestResourceMilestoneEventManager`

  - `gitlab.v4.objects.ProjectMergeRequest.resourcemilestoneevents`

- GitLab API: https://docs.gitlab.com/api/resource_milestone_events

### Examples

Get milestones for a resource (issue, merge request):

    milestones = resource.resourcemilestoneevents.list(get_all=True)

Get a specific milestone for a resource:

    milestone = resource.resourcemilestoneevents.get(milestone_id)