1######
2Labels
3######
4
5Project labels
6==============
7
8Reference
9---------
10
11* v4 API:
12
13  + :class:`gitlab.v4.objects.ProjectLabel`
14  + :class:`gitlab.v4.objects.ProjectLabelManager`
15  + :attr:`gitlab.v4.objects.Project.labels`
16
17* GitLab API: https://docs.gitlab.com/ce/api/labels.html
18
19Examples
20--------
21
22List labels for a project::
23
24    labels = project.labels.list()
25
26Create a label for a project::
27
28    label = project.labels.create({'name': 'foo', 'color': '#8899aa'})
29
30Update a label for a project::
31
32    # change the name of the label:
33    label.new_name = 'bar'
34    label.save()
35    # change its color:
36    label.color = '#112233'
37    label.save()
38
39Delete a label for a project::
40
41    project.labels.delete(label_id)
42    # or
43    label.delete()
44
45Manage labels in issues and merge requests::
46
47    # Labels are defined as lists in issues and merge requests. The labels must
48    # exist.
49    issue = p.issues.create({'title': 'issue title',
50                             'description': 'issue description',
51                             'labels': ['foo']})
52    issue.labels.append('bar')
53    issue.save()
54
55Label events
56============
57
58Resource label events keep track about who, when, and which label was added or
59removed to an issuable.
60
61Group epic label events are only available in the EE edition.
62
63Reference
64---------
65
66* v4 API:
67
68  + :class:`gitlab.v4.objects.ProjectIssueResourceLabelEvent`
69  + :class:`gitlab.v4.objects.ProjectIssueResourceLabelEventManager`
70  + :attr:`gitlab.v4.objects.ProjectIssue.resourcelabelevents`
71  + :class:`gitlab.v4.objects.ProjectMergeRequestResourceLabelEvent`
72  + :class:`gitlab.v4.objects.ProjectMergeRequestResourceLabelEventManager`
73  + :attr:`gitlab.v4.objects.ProjectMergeRequest.resourcelabelevents`
74  + :class:`gitlab.v4.objects.GroupEpicResourceLabelEvent`
75  + :class:`gitlab.v4.objects.GroupEpicResourceLabelEventManager`
76  + :attr:`gitlab.v4.objects.GroupEpic.resourcelabelevents`
77
78* GitLab API: https://docs.gitlab.com/ee/api/resource_label_events.html
79
80Examples
81--------
82
83Get the events for a resource (issue, merge request or epic)::
84
85    events = resource.resourcelabelevents.list()
86
87Get a specific event for a resource::
88
89    event = resource.resourcelabelevents.get(event_id)
90