1.. _issues_examples: 2 3###### 4Issues 5###### 6 7Reported issues 8=============== 9 10Reference 11--------- 12 13* v4 API: 14 15 + :class:`gitlab.v4.objects.Issue` 16 + :class:`gitlab.v4.objects.IssueManager` 17 + :attr:`gitlab.Gitlab.issues` 18 19* GitLab API: https://docs.gitlab.com/ce/api/issues.html 20 21Examples 22-------- 23 24List the issues:: 25 26 issues = gl.issues.list() 27 28Use the ``state`` and ``label`` parameters to filter the results. Use the 29``order_by`` and ``sort`` attributes to sort the results:: 30 31 open_issues = gl.issues.list(state='opened') 32 closed_issues = gl.issues.list(state='closed') 33 tagged_issues = gl.issues.list(labels=['foo', 'bar']) 34 35.. note:: 36 37 It is not possible to edit or delete Issue objects. You need to create a 38 ProjectIssue object to perform changes:: 39 40 issue = gl.issues.list()[0] 41 project = gl.projects.get(issue.project_id, lazy=True) 42 editable_issue = project.issues.get(issue.iid, lazy=True) 43 editable_issue.title = updated_title 44 editable_issue.save() 45 46Group issues 47============ 48 49Reference 50--------- 51 52* v4 API: 53 54 + :class:`gitlab.v4.objects.GroupIssue` 55 + :class:`gitlab.v4.objects.GroupIssueManager` 56 + :attr:`gitlab.v4.objects.Group.issues` 57 58* GitLab API: https://docs.gitlab.com/ce/api/issues.html 59 60Examples 61-------- 62 63List the group issues:: 64 65 issues = group.issues.list() 66 # Filter using the state, labels and milestone parameters 67 issues = group.issues.list(milestone='1.0', state='opened') 68 # Order using the order_by and sort parameters 69 issues = group.issues.list(order_by='created_at', sort='desc') 70 71.. note:: 72 73 It is not possible to edit or delete GroupIssue objects. You need to create 74 a ProjectIssue object to perform changes:: 75 76 issue = group.issues.list()[0] 77 project = gl.projects.get(issue.project_id, lazy=True) 78 editable_issue = project.issues.get(issue.iid, lazy=True) 79 editable_issue.title = updated_title 80 editable_issue.save() 81 82Project issues 83============== 84 85Reference 86--------- 87 88* v4 API: 89 90 + :class:`gitlab.v4.objects.ProjectIssue` 91 + :class:`gitlab.v4.objects.ProjectIssueManager` 92 + :attr:`gitlab.v4.objects.Project.issues` 93 94* GitLab API: https://docs.gitlab.com/ce/api/issues.html 95 96Examples 97-------- 98 99List the project issues:: 100 101 issues = project.issues.list() 102 # Filter using the state, labels and milestone parameters 103 issues = project.issues.list(milestone='1.0', state='opened') 104 # Order using the order_by and sort parameters 105 issues = project.issues.list(order_by='created_at', sort='desc') 106 107Get a project issue:: 108 109 issue = project.issues.get(issue_iid) 110 111Create a new issue:: 112 113 issue = project.issues.create({'title': 'I have a bug', 114 'description': 'Something useful here.'}) 115 116Update an issue:: 117 118 issue.labels = ['foo', 'bar'] 119 issue.save() 120 121Close / reopen an issue:: 122 123 # close an issue 124 issue.state_event = 'close' 125 issue.save() 126 # reopen it 127 issue.state_event = 'reopen' 128 issue.save() 129 130Delete an issue (admin or project owner only):: 131 132 project.issues.delete(issue_id) 133 # pr 134 issue.delete() 135 136Subscribe / unsubscribe from an issue:: 137 138 issue.subscribe() 139 issue.unsubscribe() 140 141Move an issue to another project:: 142 143 issue.move(other_project_id) 144 145Make an issue as todo:: 146 147 issue.todo() 148 149Get time tracking stats:: 150 151 issue.time_stats() 152 153On recent versions of Gitlab the time stats are also returned as an issue 154object attribute:: 155 156 issue = project.issue.get(iid) 157 print(issue.attributes['time_stats']) 158 159Set a time estimate for an issue:: 160 161 issue.time_estimate('3h30m') 162 163Reset a time estimate for an issue:: 164 165 issue.reset_time_estimate() 166 167Add spent time for an issue:: 168 169 issue.add_spent_time('3h30m') 170 171Reset spent time for an issue:: 172 173 issue.reset_spent_time() 174 175Get user agent detail for the issue (admin only):: 176 177 detail = issue.user_agent_detail() 178 179Get the list of merge requests that will close an issue when merged:: 180 181 mrs = issue.closed_by() 182 183Get the merge requests related to an issue:: 184 185 mrs = issue.related_merge_requests() 186 187Get the list of participants:: 188 189 users = issue.participants() 190 191Issue links 192=========== 193 194Reference 195--------- 196 197* v4 API: 198 199 + :class:`gitlab.v4.objects.ProjectIssueLink` 200 + :class:`gitlab.v4.objects.ProjectIssueLinkManager` 201 + :attr:`gitlab.v4.objects.ProjectIssue.links` 202 203* GitLab API: https://docs.gitlab.com/ee/api/issue_links.html (EE feature) 204 205Examples 206-------- 207 208List the issues linked to ``i1``:: 209 210 links = i1.links.list() 211 212Link issue ``i1`` to issue ``i2``:: 213 214 data = { 215 'target_project_id': i2.project_id, 216 'target_issue_iid': i2.iid 217 } 218 src_issue, dest_issue = i1.links.create(data) 219 220.. note:: 221 222 The ``create()`` method returns the source and destination ``ProjectIssue`` 223 objects, not a ``ProjectIssueLink`` object. 224 225Delete a link:: 226 227 i1.links.delete(issue_link_id) 228 229Issues statistics 230========================= 231 232Reference 233--------- 234 235* v4 API: 236 237 + :class:`gitlab.v4.objects.IssuesStatistics` 238 + :class:`gitlab.v4.objects.IssuesStatisticsManager` 239 + :attr:`gitlab.issues_statistics` 240 + :class:`gitlab.v4.objects.GroupIssuesStatistics` 241 + :class:`gitlab.v4.objects.GroupIssuesStatisticsManager` 242 + :attr:`gitlab.v4.objects.Group.issues_statistics` 243 + :class:`gitlab.v4.objects.ProjectIssuesStatistics` 244 + :class:`gitlab.v4.objects.ProjectIssuesStatisticsManager` 245 + :attr:`gitlab.v4.objects.Project.issues_statistics` 246 247 248* GitLab API: https://docs.gitlab.com/ce/api/issues_statistics.htm 249 250Examples 251--------- 252 253Get statistics of all issues created by the current user:: 254 255 statistics = gl.issues_statistics.get() 256 257Get statistics of all issues the user has access to:: 258 259 statistics = gl.issues_statistics.get(scope='all') 260 261Get statistics of issues for the user with ``foobar`` in the ``title`` or the ``description``:: 262 263 statistics = gl.issues_statistics.get(search='foobar') 264 265Get statistics of all issues in a group:: 266 267 statistics = group.issues_statistics.get() 268 269Get statistics of issues in a group with ``foobar`` in the ``title`` or the ``description``:: 270 271 statistics = group.issues_statistics.get(search='foobar') 272 273Get statistics of all issues in a project:: 274 275 statistics = project.issues_statistics.get() 276 277Get statistics of issues in a project with ``foobar`` in the ``title`` or the ``description``:: 278 279 statistics = project.issues_statistics.get(search='foobar') 280