.. _issues_examples: ###### Issues ###### Reported issues =============== Reference --------- * v4 API: + :class:`gitlab.v4.objects.Issue` + :class:`gitlab.v4.objects.IssueManager` + :attr:`gitlab.Gitlab.issues` * GitLab API: https://docs.gitlab.com/ce/api/issues.html Examples -------- List the issues:: issues = gl.issues.list() Use the ``state`` and ``label`` parameters to filter the results. Use the ``order_by`` and ``sort`` attributes to sort the results:: open_issues = gl.issues.list(state='opened') closed_issues = gl.issues.list(state='closed') tagged_issues = gl.issues.list(labels=['foo', 'bar']) .. note:: It is not possible to edit or delete Issue objects. You need to create a ProjectIssue object to perform changes:: issue = gl.issues.list()[0] project = gl.projects.get(issue.project_id, lazy=True) editable_issue = project.issues.get(issue.iid, lazy=True) editable_issue.title = updated_title editable_issue.save() Group issues ============ Reference --------- * v4 API: + :class:`gitlab.v4.objects.GroupIssue` + :class:`gitlab.v4.objects.GroupIssueManager` + :attr:`gitlab.v4.objects.Group.issues` * GitLab API: https://docs.gitlab.com/ce/api/issues.html Examples -------- List the group issues:: issues = group.issues.list() # Filter using the state, labels and milestone parameters issues = group.issues.list(milestone='1.0', state='opened') # Order using the order_by and sort parameters issues = group.issues.list(order_by='created_at', sort='desc') .. note:: It is not possible to edit or delete GroupIssue objects. You need to create a ProjectIssue object to perform changes:: issue = group.issues.list()[0] project = gl.projects.get(issue.project_id, lazy=True) editable_issue = project.issues.get(issue.iid, lazy=True) editable_issue.title = updated_title editable_issue.save() Project issues ============== Reference --------- * v4 API: + :class:`gitlab.v4.objects.ProjectIssue` + :class:`gitlab.v4.objects.ProjectIssueManager` + :attr:`gitlab.v4.objects.Project.issues` * GitLab API: https://docs.gitlab.com/ce/api/issues.html Examples -------- List the project issues:: issues = project.issues.list() # Filter using the state, labels and milestone parameters issues = project.issues.list(milestone='1.0', state='opened') # Order using the order_by and sort parameters issues = project.issues.list(order_by='created_at', sort='desc') Get a project issue:: issue = project.issues.get(issue_iid) Create a new issue:: issue = project.issues.create({'title': 'I have a bug', 'description': 'Something useful here.'}) Update an issue:: issue.labels = ['foo', 'bar'] issue.save() Close / reopen an issue:: # close an issue issue.state_event = 'close' issue.save() # reopen it issue.state_event = 'reopen' issue.save() Delete an issue (admin or project owner only):: project.issues.delete(issue_id) # pr issue.delete() Subscribe / unsubscribe from an issue:: issue.subscribe() issue.unsubscribe() Move an issue to another project:: issue.move(other_project_id) Make an issue as todo:: issue.todo() Get time tracking stats:: issue.time_stats() On recent versions of Gitlab the time stats are also returned as an issue object attribute:: issue = project.issue.get(iid) print(issue.attributes['time_stats']) Set a time estimate for an issue:: issue.time_estimate('3h30m') Reset a time estimate for an issue:: issue.reset_time_estimate() Add spent time for an issue:: issue.add_spent_time('3h30m') Reset spent time for an issue:: issue.reset_spent_time() Get user agent detail for the issue (admin only):: detail = issue.user_agent_detail() Get the list of merge requests that will close an issue when merged:: mrs = issue.closed_by() Get the merge requests related to an issue:: mrs = issue.related_merge_requests() Get the list of participants:: users = issue.participants() Issue links =========== Reference --------- * v4 API: + :class:`gitlab.v4.objects.ProjectIssueLink` + :class:`gitlab.v4.objects.ProjectIssueLinkManager` + :attr:`gitlab.v4.objects.ProjectIssue.links` * GitLab API: https://docs.gitlab.com/ee/api/issue_links.html (EE feature) Examples -------- List the issues linked to ``i1``:: links = i1.links.list() Link issue ``i1`` to issue ``i2``:: data = { 'target_project_id': i2.project_id, 'target_issue_iid': i2.iid } src_issue, dest_issue = i1.links.create(data) .. note:: The ``create()`` method returns the source and destination ``ProjectIssue`` objects, not a ``ProjectIssueLink`` object. Delete a link:: i1.links.delete(issue_link_id) Issues statistics ========================= Reference --------- * v4 API: + :class:`gitlab.v4.objects.IssuesStatistics` + :class:`gitlab.v4.objects.IssuesStatisticsManager` + :attr:`gitlab.issues_statistics` + :class:`gitlab.v4.objects.GroupIssuesStatistics` + :class:`gitlab.v4.objects.GroupIssuesStatisticsManager` + :attr:`gitlab.v4.objects.Group.issues_statistics` + :class:`gitlab.v4.objects.ProjectIssuesStatistics` + :class:`gitlab.v4.objects.ProjectIssuesStatisticsManager` + :attr:`gitlab.v4.objects.Project.issues_statistics` * GitLab API: https://docs.gitlab.com/ce/api/issues_statistics.htm Examples --------- Get statistics of all issues created by the current user:: statistics = gl.issues_statistics.get() Get statistics of all issues the user has access to:: statistics = gl.issues_statistics.get(scope='all') Get statistics of issues for the user with ``foobar`` in the ``title`` or the ``description``:: statistics = gl.issues_statistics.get(search='foobar') Get statistics of all issues in a group:: statistics = group.issues_statistics.get() Get statistics of issues in a group with ``foobar`` in the ``title`` or the ``description``:: statistics = group.issues_statistics.get(search='foobar') Get statistics of all issues in a project:: statistics = project.issues_statistics.get() Get statistics of issues in a project with ``foobar`` in the ``title`` or the ``description``:: statistics = project.issues_statistics.get(search='foobar')