diff options
Diffstat (limited to 'docs/gl_objects')
51 files changed, 0 insertions, 5353 deletions
diff --git a/docs/gl_objects/access_requests.rst b/docs/gl_objects/access_requests.rst deleted file mode 100644 index 467c3e5..0000000 --- a/docs/gl_objects/access_requests.rst +++ /dev/null @@ -1,53 +0,0 @@ -############### -Access requests -############### - -Users can request access to groups and projects. - -When access is granted the user should be given a numerical access level. The -following constants are provided to represent the access levels: - -* ``gitlab.GUEST_ACCESS``: ``10`` -* ``gitlab.REPORTER_ACCESS``: ``20`` -* ``gitlab.DEVELOPER_ACCESS``: ``30`` -* ``gitlab.MAINTAINER_ACCESS``: ``40`` -* ``gitlab.OWNER_ACCESS``: ``50`` - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectAccessRequest` - + :class:`gitlab.v4.objects.ProjectAccessRequestManager` - + :attr:`gitlab.v4.objects.Project.accessrequests` - + :class:`gitlab.v4.objects.GroupAccessRequest` - + :class:`gitlab.v4.objects.GroupAccessRequestManager` - + :attr:`gitlab.v4.objects.Group.accessrequests` - -* GitLab API: https://docs.gitlab.com/ce/api/access_requests.html - -Examples --------- - -List access requests from projects and groups:: - - p_ars = project.accessrequests.list() - g_ars = group.accessrequests.list() - -Create an access request:: - - p_ar = project.accessrequests.create() - g_ar = group.accessrequests.create() - -Approve an access request:: - - ar.approve() # defaults to DEVELOPER level - ar.approve(access_level=gitlab.MAINTAINER_ACCESS) # explicitly set access level - -Deny (delete) an access request:: - - project.accessrequests.delete(user_id) - group.accessrequests.delete(user_id) - # or - ar.delete() diff --git a/docs/gl_objects/appearance.rst b/docs/gl_objects/appearance.rst deleted file mode 100644 index 0c05268..0000000 --- a/docs/gl_objects/appearance.rst +++ /dev/null @@ -1,26 +0,0 @@ -########## -Appearance -########## - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ApplicationAppearance` - + :class:`gitlab.v4.objects.ApplicationAppearanceManager` - + :attr:`gitlab.Gitlab.appearance` - -* GitLab API: https://docs.gitlab.com/ce/api/appearance.html - -Examples --------- - -Get the appearance:: - - appearance = gl.appearance.get() - -Update the appearance:: - - appearance.title = "Test" - appearance.save() diff --git a/docs/gl_objects/applications.rst b/docs/gl_objects/applications.rst deleted file mode 100644 index 146b6e8..0000000 --- a/docs/gl_objects/applications.rst +++ /dev/null @@ -1,31 +0,0 @@ -############ -Applications -############ - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Applications` - + :class:`gitlab.v4.objects.ApplicationManager` - + :attr:`gitlab.Gitlab.applications` - -* GitLab API: https://docs.gitlab.com/ce/api/applications.html - -Examples --------- - -List all OAuth applications:: - - applications = gl.applications.list() - -Create an application:: - - gl.applications.create({'name': 'your_app', 'redirect_uri': 'http://application.url', 'scopes': ['api']}) - -Delete an applications:: - - gl.applications.delete(app_id) - # or - application.delete() diff --git a/docs/gl_objects/badges.rst b/docs/gl_objects/badges.rst deleted file mode 100644 index 2a26bb3..0000000 --- a/docs/gl_objects/badges.rst +++ /dev/null @@ -1,52 +0,0 @@ -###### -Badges -###### - -Badges can be associated with groups and projects. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupBadge` - + :class:`gitlab.v4.objects.GroupBadgeManager` - + :attr:`gitlab.v4.objects.Group.badges` - + :class:`gitlab.v4.objects.ProjectBadge` - + :class:`gitlab.v4.objects.ProjectBadgeManager` - + :attr:`gitlab.v4.objects.Project.badges` - -* GitLab API: - - + https://docs.gitlab.com/ce/api/group_badges.html - + https://docs.gitlab.com/ce/api/project_badges.html - -Examples --------- - -List badges:: - - badges = group_or_project.badges.list() - -Get a badge:: - - badge = group_or_project.badges.get(badge_id) - -Create a badge:: - - badge = group_or_project.badges.create({'link_url': link, 'image_url': image_link}) - -Update a badge:: - - badge.image_link = new_link - badge.save() - -Delete a badge:: - - badge.delete() - -Render a badge (preview the generate URLs):: - - output = group_or_project.badges.render(link, image_link) - print(output['rendered_link_url']) - print(output['rendered_image_url']) diff --git a/docs/gl_objects/boards.rst b/docs/gl_objects/boards.rst deleted file mode 100644 index 3bdbb51..0000000 --- a/docs/gl_objects/boards.rst +++ /dev/null @@ -1,104 +0,0 @@ -############ -Issue boards -############ - -Boards -====== - -Boards are a visual representation of existing issues for a project or a group. -Issues can be moved from one list to the other to track progress and help with -priorities. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectBoard` - + :class:`gitlab.v4.objects.ProjectBoardManager` - + :attr:`gitlab.v4.objects.Project.boards` - + :class:`gitlab.v4.objects.GroupBoard` - + :class:`gitlab.v4.objects.GroupBoardManager` - + :attr:`gitlab.v4.objects.Group.boards` - -* GitLab API: - - + https://docs.gitlab.com/ce/api/boards.html - + https://docs.gitlab.com/ce/api/group_boards.html - -Examples --------- - -Get the list of existing boards for a project or a group:: - - # item is a Project or a Group - boards = project_or_group.boards.list() - -Get a single board for a project or a group:: - - board = project_or_group.boards.get(board_id) - -Create a board:: - - board = project_or_group.boards.create({'name': 'new-board'}) - -.. note:: Board creation is not supported in the GitLab CE edition. - -Delete a board:: - - board.delete() - # or - project_or_group.boards.delete(board_id) - -.. note:: Board deletion is not supported in the GitLab CE edition. - -Board lists -=========== - -Boards are made of lists of issues. Each list is associated to a label, and -issues tagged with this label automatically belong to the list. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectBoardList` - + :class:`gitlab.v4.objects.ProjectBoardListManager` - + :attr:`gitlab.v4.objects.ProjectBoard.lists` - + :class:`gitlab.v4.objects.GroupBoardList` - + :class:`gitlab.v4.objects.GroupBoardListManager` - + :attr:`gitlab.v4.objects.GroupBoard.lists` - -* GitLab API: - - + https://docs.gitlab.com/ce/api/boards.html - + https://docs.gitlab.com/ce/api/group_boards.html - -Examples --------- - -List the issue lists for a board:: - - b_lists = board.lists.list() - -Get a single list:: - - b_list = board.lists.get(list_id) - -Create a new list:: - - # First get a ProjectLabel - label = get_or_create_label() - # Then use its ID to create the new board list - b_list = board.lists.create({'label_id': label.id}) - -Change a list position. The first list is at position 0. Moving a list will -set it at the given position and move the following lists up a position:: - - b_list.position = 2 - b_list.save() - -Delete a list:: - - b_list.delete() diff --git a/docs/gl_objects/branches.rst b/docs/gl_objects/branches.rst deleted file mode 100644 index aeba8ea..0000000 --- a/docs/gl_objects/branches.rst +++ /dev/null @@ -1,42 +0,0 @@ -######## -Branches -######## - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectBranch` - + :class:`gitlab.v4.objects.ProjectBranchManager` - + :attr:`gitlab.v4.objects.Project.branches` - -* GitLab API: https://docs.gitlab.com/ce/api/branches.html - -Examples --------- - -Get the list of branches for a repository:: - - branches = project.branches.list() - -Get a single repository branch:: - - branch = project.branches.get('master') - -Create a repository branch:: - - branch = project.branches.create({'branch': 'feature1', - 'ref': 'master'}) - -Delete a repository branch:: - - project.branches.delete('feature1') - # or - branch.delete() - -Delete the merged branches for a project:: - - project.delete_merged_branches() - -To manage protected branches, see :doc:`/gl_objects/protected_branches`. diff --git a/docs/gl_objects/clusters.rst b/docs/gl_objects/clusters.rst deleted file mode 100644 index 96edd82..0000000 --- a/docs/gl_objects/clusters.rst +++ /dev/null @@ -1,82 +0,0 @@ -############ -Clusters -############ - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectCluster` - + :class:`gitlab.v4.objects.ProjectClusterManager` - + :attr:`gitlab.v4.objects.Project.clusters` - + :class:`gitlab.v4.objects.GroupCluster` - + :class:`gitlab.v4.objects.GroupClusterManager` - + :attr:`gitlab.v4.objects.Group.clusters` - -* GitLab API: https://docs.gitlab.com/ee/api/project_clusters.html -* GitLab API: https://docs.gitlab.com/ee/api/group_clusters.html - -Examples --------- - -List clusters for a project:: - - clusters = project.clusters.list() - -Create an cluster for a project:: - - cluster = project.clusters.create( - { - "name": "cluster1", - "platform_kubernetes_attributes": { - "api_url": "http://url", - "token": "tokenval", - }, - }) - -Retrieve a specific cluster for a project:: - - cluster = project.clusters.get(cluster_id) - -Update an cluster for a project:: - - cluster.platform_kubernetes_attributes = {"api_url": "http://newurl"} - cluster.save() - -Delete an cluster for a project:: - - cluster = project.clusters.delete(cluster_id) - # or - cluster.delete() - - -List clusters for a group:: - - clusters = group.clusters.list() - -Create an cluster for a group:: - - cluster = group.clusters.create( - { - "name": "cluster1", - "platform_kubernetes_attributes": { - "api_url": "http://url", - "token": "tokenval", - }, - }) - -Retrieve a specific cluster for a group:: - - cluster = group.clusters.get(cluster_id) - -Update an cluster for a group:: - - cluster.platform_kubernetes_attributes = {"api_url": "http://newurl"} - cluster.save() - -Delete an cluster for a group:: - - cluster = group.clusters.delete(cluster_id) - # or - cluster.delete() diff --git a/docs/gl_objects/commits.rst b/docs/gl_objects/commits.rst deleted file mode 100644 index a1d878c..0000000 --- a/docs/gl_objects/commits.rst +++ /dev/null @@ -1,147 +0,0 @@ -####### -Commits -####### - -Commits -======= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectCommit` - + :class:`gitlab.v4.objects.ProjectCommitManager` - + :attr:`gitlab.v4.objects.Project.commits` - -Examples --------- - -List the commits for a project:: - - commits = project.commits.list() - -You can use the ``ref_name``, ``since`` and ``until`` filters to limit the -results:: - - commits = project.commits.list(ref_name='my_branch') - commits = project.commits.list(since='2016-01-01T00:00:00Z') - -.. note:: - - The available ``all`` listing argument conflicts with the python-gitlab - argument. Use ``query_parameters`` to avoid the conflict:: - - commits = project.commits.list(all=True, - query_parameters={'ref_name': 'my_branch'}) - -Create a commit:: - - # See https://docs.gitlab.com/ce/api/commits.html#create-a-commit-with-multiple-files-and-actions - # for actions detail - data = { - 'branch': 'master', - 'commit_message': 'blah blah blah', - 'actions': [ - { - 'action': 'create', - 'file_path': 'README.rst', - 'content': open('path/to/file.rst').read(), - }, - { - # Binary files need to be base64 encoded - 'action': 'create', - 'file_path': 'logo.png', - 'content': base64.b64encode(open('logo.png').read()), - 'encoding': 'base64', - } - ] - } - - commit = project.commits.create(data) - -Get a commit detail:: - - commit = project.commits.get('e3d5a71b') - -Get the diff for a commit:: - - diff = commit.diff() - -Cherry-pick a commit into another branch:: - - commit.cherry_pick(branch='target_branch') - -Revert a commit on a given branch:: - - commit.revert(branch='target_branch') - -Get the references the commit has been pushed to (branches and tags):: - - commit.refs() # all references - commit.refs('tag') # only tags - commit.refs('branch') # only branches - -Get the signature of the commit (if the commit was signed, e.g. with GPG or x509):: - - commit.signature() - -List the merge requests related to a commit:: - - commit.merge_requests() - -Commit comments -=============== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectCommitComment` - + :class:`gitlab.v4.objects.ProjectCommitCommentManager` - + :attr:`gitlab.v4.objects.ProjectCommit.comments` - -* GitLab API: https://docs.gitlab.com/ce/api/commits.html - -Examples --------- - -Get the comments for a commit:: - - comments = commit.comments.list() - -Add a comment on a commit:: - - # Global comment - commit = commit.comments.create({'note': 'This is a nice comment'}) - # Comment on a line in a file (on the new version of the file) - commit = commit.comments.create({'note': 'This is another comment', - 'line': 12, - 'line_type': 'new', - 'path': 'README.rst'}) - -Commit status -============= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectCommitStatus` - + :class:`gitlab.v4.objects.ProjectCommitStatusManager` - + :attr:`gitlab.v4.objects.ProjectCommit.statuses` - -* GitLab API: https://docs.gitlab.com/ce/api/commits.html - -Examples --------- - -List the statuses for a commit:: - - statuses = commit.statuses.list() - -Change the status of a commit:: - - commit.statuses.create({'state': 'success'}) diff --git a/docs/gl_objects/deploy_keys.rst b/docs/gl_objects/deploy_keys.rst deleted file mode 100644 index 31e31a9..0000000 --- a/docs/gl_objects/deploy_keys.rst +++ /dev/null @@ -1,70 +0,0 @@ -########### -Deploy keys -########### - -Deploy keys -=========== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.DeployKey` - + :class:`gitlab.v4.objects.DeployKeyManager` - + :attr:`gitlab.Gitlab.deploykeys` - -* GitLab API: https://docs.gitlab.com/ce/api/deploy_keys.html - -Examples --------- - -List the deploy keys:: - - keys = gl.deploykeys.list() - -Deploy keys for projects -======================== - -Deploy keys can be managed on a per-project basis. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectKey` - + :class:`gitlab.v4.objects.ProjectKeyManager` - + :attr:`gitlab.v4.objects.Project.keys` - -* GitLab API: https://docs.gitlab.com/ce/api/deploy_keys.html - -Examples --------- - -List keys for a project:: - - keys = project.keys.list() - -Get a single deploy key:: - - key = project.keys.get(key_id) - -Create a deploy key for a project:: - - key = project.keys.create({'title': 'jenkins key', - 'key': open('/home/me/.ssh/id_rsa.pub').read()}) - -Delete a deploy key for a project:: - - key = project.keys.list(key_id) - # or - key.delete() - -Enable a deploy key for a project:: - - project.keys.enable(key_id) - -Disable a deploy key for a project:: - - project_key.delete() diff --git a/docs/gl_objects/deploy_tokens.rst b/docs/gl_objects/deploy_tokens.rst deleted file mode 100644 index 302cb9c..0000000 --- a/docs/gl_objects/deploy_tokens.rst +++ /dev/null @@ -1,137 +0,0 @@ -############# -Deploy tokens -############# - -Deploy tokens allow read-only access to your repository and registry images -without having a user and a password. - -Deploy tokens -============= - -This endpoint requires admin access. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.DeployToken` - + :class:`gitlab.v4.objects.DeployTokenManager` - + :attr:`gitlab.Gitlab.deploytokens` - -* GitLab API: https://docs.gitlab.com/ce/api/deploy_tokens.html - -Examples --------- - -Use the ``list()`` method to list all deploy tokens across the GitLab instance. - -:: - - # List deploy tokens - deploy_tokens = gl.deploytokens.list() - -Project deploy tokens -===================== - -This endpoint requires project maintainer access or higher. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectDeployToken` - + :class:`gitlab.v4.objects.ProjectDeployTokenManager` - + :attr:`gitlab.v4.objects.Project.deploytokens` - -* GitLab API: https://docs.gitlab.com/ce/api/deploy_tokens.html#project-deploy-tokens - -Examples --------- - -List the deploy tokens for a project:: - - deploy_tokens = project.deploytokens.list() - -Create a new deploy token to access registry images of a project: - -In addition to required parameters ``name`` and ``scopes``, this method accepts -the following parameters: - -* ``expires_at`` Expiration date of the deploy token. Does not expire if no value is provided. -* ``username`` Username for deploy token. Default is ``gitlab+deploy-token-{n}`` - - -:: - - deploy_token = project.deploytokens.create({'name': 'token1', 'scopes': ['read_registry'], 'username':'', 'expires_at':''}) - # show its id - print(deploy_token.id) - # show the token value. Make sure you save it, you won't be able to access it again. - print(deploy_token.token) - -.. warning:: - - With GitLab 12.9, even though ``username`` and ``expires_at`` are not required, they always have to be passed to the API. - You can set them to empty strings, see: https://gitlab.com/gitlab-org/gitlab/-/issues/211878. - Also, the ``username``'s value is ignored by the API and will be overridden with ``gitlab+deploy-token-{n}``, - see: https://gitlab.com/gitlab-org/gitlab/-/issues/211963 - These issues were fixed in GitLab 12.10. - -Remove a deploy token from the project:: - - deploy_token.delete() - # or - project.deploytokens.delete(deploy_token.id) - - -Group deploy tokens -=================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupDeployToken` - + :class:`gitlab.v4.objects.GroupDeployTokenManager` - + :attr:`gitlab.v4.objects.Group.deploytokens` - -* GitLab API: https://docs.gitlab.com/ce/api/deploy_tokens.html#group-deploy-tokens - -Examples --------- - -List the deploy tokens for a group:: - - deploy_tokens = group.deploytokens.list() - -Create a new deploy token to access all repositories of all projects in a group: - -In addition to required parameters ``name`` and ``scopes``, this method accepts -the following parameters: - -* ``expires_at`` Expiration date of the deploy token. Does not expire if no value is provided. -* ``username`` Username for deploy token. Default is ``gitlab+deploy-token-{n}`` - -:: - - deploy_token = group.deploytokens.create({'name': 'token1', 'scopes': ['read_repository'], 'username':'', 'expires_at':''}) - # show its id - print(deploy_token.id) - -.. warning:: - - With GitLab 12.9, even though ``username`` and ``expires_at`` are not required, they always have to be passed to the API. - You can set them to empty strings, see: https://gitlab.com/gitlab-org/gitlab/-/issues/211878. - Also, the ``username``'s value is ignored by the API and will be overridden with ``gitlab+deploy-token-{n}``, - see: https://gitlab.com/gitlab-org/gitlab/-/issues/211963 - These issues were fixed in GitLab 12.10. - -Remove a deploy token from the group:: - - deploy_token.delete() - # or - group.deploytokens.delete(deploy_token.id) - diff --git a/docs/gl_objects/deployments.rst b/docs/gl_objects/deployments.rst deleted file mode 100644 index 945ad41..0000000 --- a/docs/gl_objects/deployments.rst +++ /dev/null @@ -1,63 +0,0 @@ -########### -Deployments -########### - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectDeployment` - + :class:`gitlab.v4.objects.ProjectDeploymentManager` - + :attr:`gitlab.v4.objects.Project.deployments` - -* GitLab API: https://docs.gitlab.com/ce/api/deployments.html - -Examples --------- - -List deployments for a project:: - - deployments = project.deployments.list() - -Get a single deployment:: - - deployment = project.deployments.get(deployment_id) - -Create a new deployment:: - - deployment = project.deployments.create({ - "environment": "Test", - "sha": "1agf4gs", - "ref": "master", - "tag": False, - "status": "created", - }) - -Update a deployment:: - - deployment = project.deployments.get(42) - deployment.status = "failed" - deployment.save() - -Merge requests associated with a deployment -=========================================== - -Reference ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectDeploymentMergeRequest` - + :class:`gitlab.v4.objects.ProjectDeploymentMergeRequestManager` - + :attr:`gitlab.v4.objects.ProjectDeployment.mergerequests` - -* GitLab API: https://docs.gitlab.com/ee/api/deployments.html#list-of-merge-requests-associated-with-a-deployment - -Examples --------- - -List the merge requests associated with a deployment:: - - deployment = project.deployments.get(42, lazy=True) - mrs = deployment.mergerequests.list() diff --git a/docs/gl_objects/discussions.rst b/docs/gl_objects/discussions.rst deleted file mode 100644 index 444d883..0000000 --- a/docs/gl_objects/discussions.rst +++ /dev/null @@ -1,107 +0,0 @@ -########### -Discussions -########### - -Discussions organize the notes in threads. See the :ref:`project-notes` chapter -for more information about notes. - -Discussions are available for project issues, merge requests, snippets and -commits. - -Reference -========= - -* v4 API: - - Issues: - - + :class:`gitlab.v4.objects.ProjectIssueDiscussion` - + :class:`gitlab.v4.objects.ProjectIssueDiscussionManager` - + :class:`gitlab.v4.objects.ProjectIssueDiscussionNote` - + :class:`gitlab.v4.objects.ProjectIssueDiscussionNoteManager` - + :attr:`gitlab.v4.objects.ProjectIssue.notes` - - MergeRequests: - - + :class:`gitlab.v4.objects.ProjectMergeRequestDiscussion` - + :class:`gitlab.v4.objects.ProjectMergeRequestDiscussionManager` - + :class:`gitlab.v4.objects.ProjectMergeRequestDiscussionNote` - + :class:`gitlab.v4.objects.ProjectMergeRequestDiscussionNoteManager` - + :attr:`gitlab.v4.objects.ProjectMergeRequest.notes` - - Snippets: - - + :class:`gitlab.v4.objects.ProjectSnippetDiscussion` - + :class:`gitlab.v4.objects.ProjectSnippetDiscussionManager` - + :class:`gitlab.v4.objects.ProjectSnippetDiscussionNote` - + :class:`gitlab.v4.objects.ProjectSnippetDiscussionNoteManager` - + :attr:`gitlab.v4.objects.ProjectSnippet.notes` - -* GitLab API: https://docs.gitlab.com/ce/api/discussions.html - -Examples -======== - -List the discussions for a resource (issue, merge request, snippet or commit):: - - discussions = resource.discussions.list() - -Get a single discussion:: - - discussion = resource.discussions.get(discussion_id) - -You can access the individual notes in the discussion through the ``notes`` -attribute. It holds a list of notes in chronological order:: - - # ``resource.notes`` is a DiscussionNoteManager, so we need to get the - # object notes using ``attributes`` - for note in discussion.attributes['notes']: - print(note['body']) - -.. note:: - - The notes are dicts, not objects. - -You can add notes to existing discussions:: - - new_note = discussion.notes.create({'body': 'Episode IV: A new note'}) - -You can get and update a single note using the ``*DiscussionNote`` resources:: - - discussion = resource.discussions.get(discussion_id) - # Get the latest note's id - note_id = discussion.attributes['note'][-1]['id'] - last_note = discussion.notes.get(note_id) - last_note.body = 'Updated comment' - last_note.save() - -Create a new discussion:: - - discussion = resource.discussions.create({'body': 'First comment of discussion'}) - -You can comment on merge requests and commit diffs. Provide the ``position`` -dict to define where the comment should appear in the diff:: - - mr_diff = mr.diffs.get(diff_id) - mr.discussions.create({'body': 'Note content', - 'position': { - 'base_sha': mr_diff.base_commit_sha, - 'start_sha': mr_diff.start_commit_sha, - 'head_sha': mr_diff.head_commit_sha, - 'position_type': 'text', - 'new_line': 1, - 'old_path': 'README.rst', - 'new_path': 'README.rst'} - }) - -Resolve / unresolve a merge request discussion:: - - mr_d = mr.discussions.get(d_id) - mr_d.resolved = True # True to resolve, False to unresolve - mr_d.save() - -Delete a comment:: - - discussions.notes.delete(note_id) - # or - note.delete() diff --git a/docs/gl_objects/emojis.rst b/docs/gl_objects/emojis.rst deleted file mode 100644 index 179141f..0000000 --- a/docs/gl_objects/emojis.rst +++ /dev/null @@ -1,45 +0,0 @@ -############ -Award Emojis -############ - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectIssueAwardEmoji` - + :class:`gitlab.v4.objects.ProjectIssueNoteAwardEmoji` - + :class:`gitlab.v4.objects.ProjectMergeRequestAwardEmoji` - + :class:`gitlab.v4.objects.ProjectMergeRequestNoteAwardEmoji` - + :class:`gitlab.v4.objects.ProjectSnippetAwardEmoji` - + :class:`gitlab.v4.objects.ProjectSnippetNoteAwardEmoji` - + :class:`gitlab.v4.objects.ProjectIssueAwardEmojiManager` - + :class:`gitlab.v4.objects.ProjectIssueNoteAwardEmojiManager` - + :class:`gitlab.v4.objects.ProjectMergeRequestAwardEmojiManager` - + :class:`gitlab.v4.objects.ProjectMergeRequestNoteAwardEmojiManager` - + :class:`gitlab.v4.objects.ProjectSnippetAwardEmojiManager` - + :class:`gitlab.v4.objects.ProjectSnippetNoteAwardEmojiManager` - - -* GitLab API: https://docs.gitlab.com/ce/api/award_emoji.html - -Examples --------- - -List emojis for a resource:: - - emojis = obj.awardemojis.list() - -Get a single emoji:: - - emoji = obj.awardemojis.get(emoji_id) - -Add (create) an emoji:: - - emoji = obj.awardemojis.create({'name': 'tractor'}) - -Delete an emoji:: - - emoji.delete - # or - obj.awardemojis.delete(emoji_id) diff --git a/docs/gl_objects/environments.rst b/docs/gl_objects/environments.rst deleted file mode 100644 index 6edde12..0000000 --- a/docs/gl_objects/environments.rst +++ /dev/null @@ -1,44 +0,0 @@ -############ -Environments -############ - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectEnvironment` - + :class:`gitlab.v4.objects.ProjectEnvironmentManager` - + :attr:`gitlab.v4.objects.Project.environments` - -* GitLab API: https://docs.gitlab.com/ce/api/environments.html - -Examples --------- - -List environments for a project:: - - environments = project.environments.list() - -Create an environment for a project:: - - environment = project.environments.create({'name': 'production'}) - -Retrieve a specific environment for a project:: - - environment = project.environments.get(112) - -Update an environment for a project:: - - environment.external_url = 'http://foo.bar.com' - environment.save() - -Delete an environment for a project:: - - environment = project.environments.delete(environment_id) - # or - environment.delete() - -Stop an environments:: - - environment.stop() diff --git a/docs/gl_objects/epics.rst b/docs/gl_objects/epics.rst deleted file mode 100644 index 2b1e23e..0000000 --- a/docs/gl_objects/epics.rst +++ /dev/null @@ -1,79 +0,0 @@ -##### -Epics -##### - -Epics -===== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupEpic` - + :class:`gitlab.v4.objects.GroupEpicManager` - + :attr:`gitlab.Gitlab.Group.epics` - -* GitLab API: https://docs.gitlab.com/ee/api/epics.html (EE feature) - -Examples --------- - -List the epics for a group:: - - epics = groups.epics.list() - -Get a single epic for a group:: - - epic = group.epics.get(epic_iid) - -Create an epic for a group:: - - epic = group.epics.create({'title': 'My Epic'}) - -Edit an epic:: - - epic.title = 'New title' - epic.labels = ['label1', 'label2'] - epic.save() - -Delete an epic:: - - epic.delete() - -Epics issues -============ - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupEpicIssue` - + :class:`gitlab.v4.objects.GroupEpicIssueManager` - + :attr:`gitlab.Gitlab.GroupEpic.issues` - -* GitLab API: https://docs.gitlab.com/ee/api/epic_issues.html (EE feature) - -Examples --------- - -List the issues associated with an issue:: - - ei = epic.issues.list() - -Associate an issue with an epic:: - - # use the issue id, not its iid - ei = epic.issues.create({'issue_id': 4}) - -Move an issue in the list:: - - ei.move_before_id = epic_issue_id_1 - # or - ei.move_after_id = epic_issue_id_2 - ei.save() - -Delete an issue association:: - - ei.delete() diff --git a/docs/gl_objects/events.rst b/docs/gl_objects/events.rst deleted file mode 100644 index 5dc03c7..0000000 --- a/docs/gl_objects/events.rst +++ /dev/null @@ -1,83 +0,0 @@ -###### -Events -###### - -Events -====== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Event` - + :class:`gitlab.v4.objects.EventManager` - + :attr:`gitlab.Gitlab.events` - + :class:`gitlab.v4.objects.ProjectEvent` - + :class:`gitlab.v4.objects.ProjectEventManager` - + :attr:`gitlab.v4.objects.Project.events` - + :class:`gitlab.v4.objects.UserEvent` - + :class:`gitlab.v4.objects.UserEventManager` - + :attr:`gitlab.v4.objects.User.events` - -* GitLab API: https://docs.gitlab.com/ce/api/events.html - -Examples --------- - -You can list events for an entire Gitlab instance (admin), users and projects. -You can filter you events you want to retrieve using the ``action`` and -``target_type`` attributes. The possible values for these attributes are -available on `the gitlab documentation -<https://docs.gitlab.com/ce/api/events.html>`_. - -List all the events (paginated):: - - events = gl.events.list() - -List the issue events on a project:: - - events = project.events.list(target_type='issue') - -List the user events:: - - events = project.events.list() - -Resource state events -===================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectIssueResourceStateEvent` - + :class:`gitlab.v4.objects.ProjectIssueResourceStateEventManager` - + :attr:`gitlab.v4.objects.ProjectIssue.resourcestateevents` - + :class:`gitlab.v4.objects.ProjectMergeRequestResourceStateEvent` - + :class:`gitlab.v4.objects.ProjectMergeRequestResourceStateEventManager` - + :attr:`gitlab.v4.objects.ProjectMergeRequest.resourcestateevents` - -* GitLab API: https://docs.gitlab.com/ee/api/resource_state_events.html - -Examples --------- - -You can list and get specific resource state events (via their id) for project issues -and project merge requests. - -List the state events of a project issue (paginated):: - - state_events = issue.resourcestateevents.list() - -Get a specific state event of a project issue by its id:: - - state_event = issue.resourcestateevents.get(1) - -List the state events of a project merge request (paginated):: - - state_events = mr.resourcestateevents.list() - -Get a specific state event of a project merge request by its id:: - - state_event = mr.resourcestateevents.get(1) diff --git a/docs/gl_objects/features.rst b/docs/gl_objects/features.rst deleted file mode 100644 index 2344895..0000000 --- a/docs/gl_objects/features.rst +++ /dev/null @@ -1,32 +0,0 @@ -############## -Features flags -############## - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Feature` - + :class:`gitlab.v4.objects.FeatureManager` - + :attr:`gitlab.Gitlab.features` - -* GitLab API: https://docs.gitlab.com/ce/api/features.html - -Examples --------- - -List features:: - - features = gl.features.list() - -Create or set a feature:: - - feature = gl.features.set(feature_name, True) - feature = gl.features.set(feature_name, 30) - feature = gl.features.set(feature_name, True, user=filipowm) - feature = gl.features.set(feature_name, 40, group=mygroup) - -Delete a feature:: - - feature.delete() diff --git a/docs/gl_objects/geo_nodes.rst b/docs/gl_objects/geo_nodes.rst deleted file mode 100644 index 181ec91..0000000 --- a/docs/gl_objects/geo_nodes.rst +++ /dev/null @@ -1,43 +0,0 @@ -######### -Geo nodes -######### - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GeoNode` - + :class:`gitlab.v4.objects.GeoNodeManager` - + :attr:`gitlab.Gitlab.geonodes` - -* GitLab API: https://docs.gitlab.com/ee/api/geo_nodes.html (EE feature) - -Examples --------- - -List the geo nodes:: - - nodes = gl.geonodes.list() - -Get the status of all the nodes:: - - status = gl.geonodes.status() - -Get a specific node and its status:: - - node = gl.geonodes.get(node_id) - node.status() - -Edit a node configuration:: - - node.url = 'https://secondary.mygitlab.domain' - node.save() - -Delete a node:: - - node.delete() - -List the sync failure on the current node:: - - failures = gl.geonodes.current_failures() diff --git a/docs/gl_objects/groups.rst b/docs/gl_objects/groups.rst deleted file mode 100644 index 549fe53..0000000 --- a/docs/gl_objects/groups.rst +++ /dev/null @@ -1,378 +0,0 @@ -###### -Groups -###### - -Groups -====== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Group` - + :class:`gitlab.v4.objects.GroupManager` - + :attr:`gitlab.Gitlab.groups` - -* GitLab API: https://docs.gitlab.com/ce/api/groups.html - -Examples --------- - -List the groups:: - - groups = gl.groups.list() - -Get a group's detail:: - - group = gl.groups.get(group_id) - -List a group's projects:: - - projects = group.projects.list() - -.. note:: - - ``GroupProject`` objects returned by this API call are very limited, and do - not provide all the features of ``Project`` objects. If you need to - manipulate projects, create a new ``Project`` object:: - - first_group_project = group.projects.list()[0] - manageable_project = gl.projects.get(first_group_project.id, lazy=True) - -You can filter and sort the result using the following parameters: - -* ``archived``: limit by archived status -* ``visibility``: limit by visibility. Allowed values are ``public``, - ``internal`` and ``private`` -* ``search``: limit to groups matching the given value -* ``order_by``: sort by criteria. Allowed values are ``id``, ``name``, ``path``, - ``created_at``, ``updated_at`` and ``last_activity_at`` -* ``sort``: sort order: ``asc`` or ``desc`` -* ``ci_enabled_first``: return CI enabled groups first -* ``include_subgroups``: include projects in subgroups - -Create a group:: - - group = gl.groups.create({'name': 'group1', 'path': 'group1'}) - -Create a subgroup under an existing group:: - - subgroup = gl.groups.create({'name': 'subgroup1', 'path': 'subgroup1', 'parent_id': parent_group_id}) - -Update a group:: - - group.description = 'My awesome group' - group.save() - -Set the avatar image for a group:: - - # the avatar image can be passed as data (content of the file) or as a file - # object opened in binary mode - group.avatar = open('path/to/file.png', 'rb') - group.save() - -Remove a group:: - - gl.groups.delete(group_id) - # or - group.delete() - -Share/unshare the group with a group:: - - group.share(group2.id, gitlab.DEVELOPER_ACCESS) - group.unshare(group2.id) - -Import / Export -=============== - -You can export groups from gitlab, and re-import them to create new groups. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupExport` - + :class:`gitlab.v4.objects.GroupExportManager` - + :attr:`gitlab.v4.objects.Group.exports` - + :class:`gitlab.v4.objects.GroupImport` - + :class:`gitlab.v4.objects.GroupImportManager` - + :attr:`gitlab.v4.objects.Group.imports` - + :attr:`gitlab.v4.objects.GroupManager.import_group` - -* GitLab API: https://docs.gitlab.com/ce/api/group_import_export.html - -Examples --------- - -A group export is an asynchronous operation. To retrieve the archive -generated by GitLab you need to: - -#. Create an export using the API -#. Wait for the export to be done -#. Download the result - -.. warning:: - - Unlike the Project Export API, GitLab does not provide an export_status - for Group Exports. It is up to the user to ensure the export is finished. - - However, Group Exports only contain metadata, so they are much faster - than Project Exports. - -:: - - # Create the export - group = gl.groups.get(my_group) - export = group.exports.create() - - # Wait for the export to finish - time.sleep(3) - - # Download the result - with open('/tmp/export.tgz', 'wb') as f: - export.download(streamed=True, action=f.write) - -Import the group:: - - with open('/tmp/export.tgz', 'rb') as f: - gl.groups.import_group(f, path='imported-group', name="Imported Group") - -Subgroups -========= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupSubgroup` - + :class:`gitlab.v4.objects.GroupSubgroupManager` - + :attr:`gitlab.v4.objects.Group.subgroups` - -Examples --------- - -List the subgroups for a group:: - - subgroups = group.subgroups.list() - -.. note:: - - The ``GroupSubgroup`` objects don't expose the same API as the ``Group`` - objects. If you need to manipulate a subgroup as a group, create a new - ``Group`` object:: - - real_group = gl.groups.get(subgroup_id, lazy=True) - real_group.issues.list() - -Descendant Groups -================= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupDescendantGroup` - + :class:`gitlab.v4.objects.GroupDescendantGroupManager` - + :attr:`gitlab.v4.objects.Group.descendant_groups` - -Examples --------- - -List the descendant groups of a group:: - - descendant_groups = group.descendant_groups.list() - -.. note:: - - Like the ``GroupSubgroup`` objects described above, ``GroupDescendantGroup`` - objects do not expose the same API as the ``Group`` objects. Create a new - ``Group`` object instead if needed, as shown in the subgroup example. - -Group custom attributes -======================= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupCustomAttribute` - + :class:`gitlab.v4.objects.GroupCustomAttributeManager` - + :attr:`gitlab.v4.objects.Group.customattributes` - -* GitLab API: https://docs.gitlab.com/ce/api/custom_attributes.html - -Examples --------- - -List custom attributes for a group:: - - attrs = group.customattributes.list() - -Get a custom attribute for a group:: - - attr = group.customattributes.get(attr_key) - -Set (create or update) a custom attribute for a group:: - - attr = group.customattributes.set(attr_key, attr_value) - -Delete a custom attribute for a group:: - - attr.delete() - # or - group.customattributes.delete(attr_key) - -Search groups by custom attribute:: - - group.customattributes.set('role': 'admin') - gl.groups.list(custom_attributes={'role': 'admin'}) - -Group members -============= - -The following constants define the supported access levels: - -* ``gitlab.GUEST_ACCESS = 10`` -* ``gitlab.REPORTER_ACCESS = 20`` -* ``gitlab.DEVELOPER_ACCESS = 30`` -* ``gitlab.MAINTAINER_ACCESS = 40`` -* ``gitlab.OWNER_ACCESS = 50`` - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupMember` - + :class:`gitlab.v4.objects.GroupMemberManager` - + :class:`gitlab.v4.objects.GroupMemberAllManager` - + :class:`gitlab.v4.objects.GroupBillableMember` - + :class:`gitlab.v4.objects.GroupBillableMemberManager` - + :attr:`gitlab.v4.objects.Group.members` - + :attr:`gitlab.v4.objects.Group.members_all` - + :attr:`gitlab.v4.objects.Group.billable_members` - -* GitLab API: https://docs.gitlab.com/ce/api/members.html - -Billable group members are only available in GitLab EE. - -Examples --------- - -List only direct group members:: - - members = group.members.list() - -List the group members recursively (including inherited members through -ancestor groups):: - - members = group.members_all.list(all=True) - -Get only direct group member:: - - members = group.members.get(member_id) - -Get a member of a group, including members inherited through ancestor groups:: - - members = group.members_all.get(member_id) - -Add a member to the group:: - - member = group.members.create({'user_id': user_id, - 'access_level': gitlab.GUEST_ACCESS}) - -Update a member (change the access level):: - - member.access_level = gitlab.DEVELOPER_ACCESS - member.save() - -Remove a member from the group:: - - group.members.delete(member_id) - # or - member.delete() - -List billable members of a group (top-level groups only):: - - billable_members = group.billable_members.list() - -Remove a billable member from the group:: - - group.billable_members.delete(member_id) - # or - billable_member.delete() - -List memberships of a billable member:: - - billable_member.memberships.list() - -LDAP group links -================ - -Add an LDAP group link to an existing GitLab group:: - - group.add_ldap_group_link(ldap_group_cn, gitlab.DEVELOPER_ACCESS, 'ldapmain') - -Remove a link:: - - group.delete_ldap_group_link(ldap_group_cn, 'ldapmain') - -Sync the LDAP groups:: - - group.ldap_sync() - -You can use the ``ldapgroups`` manager to list available LDAP groups:: - - # listing (supports pagination) - ldap_groups = gl.ldapgroups.list() - - # filter using a group name - ldap_groups = gl.ldapgroups.list(search='foo') - - # list the groups for a specific LDAP provider - ldap_groups = gl.ldapgroups.list(search='foo', provider='ldapmain') - -Groups hooks -============ - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupHook` - + :class:`gitlab.v4.objects.GroupHookManager` - + :attr:`gitlab.v4.objects.Group.hooks` - -* GitLab API: https://docs.gitlab.com/ce/api/groups.html#hooks - -Examples --------- - -List the group hooks:: - - hooks = group.hooks.list() - -Get a group hook:: - - hook = group.hooks.get(hook_id) - -Create a group hook:: - - hook = group.hooks.create({'url': 'http://my/action/url', 'push_events': 1}) - -Update a group hook:: - - hook.push_events = 0 - hook.save() - -Delete a group hook:: - - group.hooks.delete(hook_id) - # or - hook.delete() diff --git a/docs/gl_objects/issues.rst b/docs/gl_objects/issues.rst deleted file mode 100644 index dfb1ff7..0000000 --- a/docs/gl_objects/issues.rst +++ /dev/null @@ -1,279 +0,0 @@ -.. _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') diff --git a/docs/gl_objects/keys.rst b/docs/gl_objects/keys.rst deleted file mode 100644 index 6d35218..0000000 --- a/docs/gl_objects/keys.rst +++ /dev/null @@ -1,28 +0,0 @@ -#### -Keys -#### - -Keys -==== - -Reference ---------- - -* v4 API - - + :class:`gitlab.v4.objects.Key` - + :class:`gitlab.v4.objects.KeyManager` - + :attr:`gitlab.Gitlab.keys` - -* GitLab API: https://docs.gitlab.com/ce/api/keys.html - -Examples --------- - -Get an ssh key by its id (requires admin access):: - - key = gl.keys.get(key_id) - -Get an ssh key (requires admin access) or a deploy key by its fingerprint:: - - key = gl.keys.get(fingerprint="SHA256:ERJJ/OweAM6jA8OjJ/gXs4N5fqUaREEJnz/EyfywfXY") diff --git a/docs/gl_objects/labels.rst b/docs/gl_objects/labels.rst deleted file mode 100644 index a4667aa..0000000 --- a/docs/gl_objects/labels.rst +++ /dev/null @@ -1,89 +0,0 @@ -###### -Labels -###### - -Project labels -============== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectLabel` - + :class:`gitlab.v4.objects.ProjectLabelManager` - + :attr:`gitlab.v4.objects.Project.labels` - -* GitLab API: https://docs.gitlab.com/ce/api/labels.html - -Examples --------- - -List labels for a project:: - - labels = project.labels.list() - -Create a label for a project:: - - label = project.labels.create({'name': 'foo', 'color': '#8899aa'}) - -Update a label for a project:: - - # change the name of the label: - label.new_name = 'bar' - label.save() - # change its color: - label.color = '#112233' - label.save() - -Delete a label for a project:: - - project.labels.delete(label_id) - # or - label.delete() - -Manage labels in issues and merge requests:: - - # Labels are defined as lists in issues and merge requests. The labels must - # exist. - issue = p.issues.create({'title': 'issue title', - 'description': 'issue description', - 'labels': ['foo']}) - issue.labels.append('bar') - issue.save() - -Label events -============ - -Resource label events keep track about who, when, and which label was added or -removed to an issuable. - -Group epic label events are only available in the EE edition. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectIssueResourceLabelEvent` - + :class:`gitlab.v4.objects.ProjectIssueResourceLabelEventManager` - + :attr:`gitlab.v4.objects.ProjectIssue.resourcelabelevents` - + :class:`gitlab.v4.objects.ProjectMergeRequestResourceLabelEvent` - + :class:`gitlab.v4.objects.ProjectMergeRequestResourceLabelEventManager` - + :attr:`gitlab.v4.objects.ProjectMergeRequest.resourcelabelevents` - + :class:`gitlab.v4.objects.GroupEpicResourceLabelEvent` - + :class:`gitlab.v4.objects.GroupEpicResourceLabelEventManager` - + :attr:`gitlab.v4.objects.GroupEpic.resourcelabelevents` - -* GitLab API: https://docs.gitlab.com/ee/api/resource_label_events.html - -Examples --------- - -Get the events for a resource (issue, merge request or epic):: - - events = resource.resourcelabelevents.list() - -Get a specific event for a resource:: - - event = resource.resourcelabelevents.get(event_id) diff --git a/docs/gl_objects/messages.rst b/docs/gl_objects/messages.rst deleted file mode 100644 index 32fbb95..0000000 --- a/docs/gl_objects/messages.rst +++ /dev/null @@ -1,48 +0,0 @@ -################## -Broadcast messages -################## - -You can use broadcast messages to display information on all pages of the -gitlab web UI. You must have administration permissions to manipulate broadcast -messages. - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.BroadcastMessage` - + :class:`gitlab.v4.objects.BroadcastMessageManager` - + :attr:`gitlab.Gitlab.broadcastmessages` - -* GitLab API: https://docs.gitlab.com/ce/api/broadcast_messages.html - -Examples --------- - -List the messages:: - - msgs = gl.broadcastmessages.list() - -Get a single message:: - - msg = gl.broadcastmessages.get(msg_id) - -Create a message:: - - msg = gl.broadcastmessages.create({'message': 'Important information'}) - -The date format for the ``starts_at`` and ``ends_at`` parameters is -``YYYY-MM-ddThh:mm:ssZ``. - -Update a message:: - - msg.font = '#444444' - msg.color = '#999999' - msg.save() - -Delete a message:: - - gl.broadcastmessages.delete(msg_id) - # or - msg.delete() diff --git a/docs/gl_objects/milestones.rst b/docs/gl_objects/milestones.rst deleted file mode 100644 index 3830f81..0000000 --- a/docs/gl_objects/milestones.rst +++ /dev/null @@ -1,105 +0,0 @@ -########## -Milestones -########## - -Project milestones -================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectMilestone` - + :class:`gitlab.v4.objects.ProjectMilestoneManager` - + :attr:`gitlab.v4.objects.Project.milestones` - - + :class:`gitlab.v4.objects.GroupMilestone` - + :class:`gitlab.v4.objects.GroupMilestoneManager` - + :attr:`gitlab.v4.objects.Group.milestones` - -* GitLab API: - - + https://docs.gitlab.com/ce/api/milestones.html - + https://docs.gitlab.com/ce/api/group_milestones.html - -Examples --------- - -List the milestones for a project or a group:: - - p_milestones = project.milestones.list() - g_milestones = group.milestones.list() - -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') - g_milestones = group.milestones.list(state='active') - -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() - -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: - - + :class:`gitlab.v4.objects.ProjectIssueResourceMilestoneEvent` - + :class:`gitlab.v4.objects.ProjectIssueResourceMilestoneEventManager` - + :attr:`gitlab.v4.objects.ProjectIssue.resourcemilestoneevents` - + :class:`gitlab.v4.objects.ProjectMergeRequestResourceMilestoneEvent` - + :class:`gitlab.v4.objects.ProjectMergeRequestResourceMilestoneEventManager` - + :attr:`gitlab.v4.objects.ProjectMergeRequest.resourcemilestoneevents` - -* GitLab API: https://docs.gitlab.com/ee/api/resource_milestone_events.html - -Examples --------- - -Get milestones for a resource (issue, merge request):: - - milestones = resource.resourcemilestoneevents.list() - -Get a specific milestone for a resource:: - - milestone = resource.resourcemilestoneevents.get(milestone_id) diff --git a/docs/gl_objects/mr_approvals.rst b/docs/gl_objects/mr_approvals.rst deleted file mode 100644 index 9e47535..0000000 --- a/docs/gl_objects/mr_approvals.rst +++ /dev/null @@ -1,86 +0,0 @@ -################################ -Merge request approvals settings -################################ - -Merge request approvals can be defined at the project level or at the merge -request level. - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectApproval` - + :class:`gitlab.v4.objects.ProjectApprovalManager` - + :class:`gitlab.v4.objects.ProjectApprovalRule` - + :class:`gitlab.v4.objects.ProjectApprovalRuleManager` - + :attr:`gitlab.v4.objects.Project.approvals` - + :class:`gitlab.v4.objects.ProjectMergeRequestApproval` - + :class:`gitlab.v4.objects.ProjectMergeRequestApprovalManager` - + :attr:`gitlab.v4.objects.ProjectMergeRequest.approvals` - + :class:`gitlab.v4.objects.ProjectMergeRequestApprovalRule` - + :class:`gitlab.v4.objects.ProjectMergeRequestApprovalRuleManager` - + :attr:`gitlab.v4.objects.ProjectMergeRequest.approval_rules` - -* GitLab API: https://docs.gitlab.com/ee/api/merge_request_approvals.html - -Examples --------- - -List project-level MR approval rules:: - - p_mras = project.approvalrules.list() - -Change project-level MR approval rule:: - - p_approvalrule.user_ids = [234] - p_approvalrule.save() - -Delete project-level MR approval rule:: - - p_approvalrule.delete() - -Get project-level or MR-level MR approvals settings:: - - p_mras = project.approvals.get() - - mr_mras = mr.approvals.get() - -Change project-level or MR-level MR approvals settings:: - - p_mras.approvals_before_merge = 2 - p_mras.save() - - mr_mras.set_approvers(approvals_required = 1) - -Change project-level MR allowed approvers:: - - project.approvals.set_approvers(approver_ids=[105], - approver_group_ids=[653, 654]) - -Create a new MR-level approval rule or change an existing MR-level approval rule:: - - mr.approvals.set_approvers(approvals_required = 1, approver_ids=[105], - approver_group_ids=[653, 654], - approval_rule_name="my MR custom approval rule") - -List MR-level MR approval rules:: - - mr.approval_rules.list() - -Change MR-level MR approval rule:: - - mr_approvalrule.user_ids = [105] - mr_approvalrule.approvals_required = 2 - mr_approvalrule.group_ids = [653, 654] - mr_approvalrule.save() - -Create a MR-level MR approval rule:: - - mr.approval_rules.create({ - "name": "my MR custom approval rule", - "approvals_required": 2, - "rule_type": "regular", - "user_ids": [105], - "group_ids": [653, 654], - }) diff --git a/docs/gl_objects/mrs.rst b/docs/gl_objects/mrs.rst deleted file mode 100644 index f17ad26..0000000 --- a/docs/gl_objects/mrs.rst +++ /dev/null @@ -1,217 +0,0 @@ -.. _merge_requests_examples: - -############## -Merge requests -############## - -You can use merge requests to notify a project that a branch is ready for -merging. The owner of the target projet can accept the merge request. - -Merge requests are linked to projects, but they can be listed globally or for -groups. - -Group and global listing -======================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupMergeRequest` - + :class:`gitlab.v4.objects.GroupMergeRequestManager` - + :attr:`gitlab.v4.objects.Group.mergerequests` - + :class:`gitlab.v4.objects.MergeRequest` - + :class:`gitlab.v4.objects.MergeRequestManager` - + :attr:`gitlab.Gitlab.mergerequests` - -* GitLab API: https://docs.gitlab.com/ce/api/merge_requests.html - -Examples --------- - -List the merge requests created by the user of the token on the GitLab server:: - - mrs = gl.mergerequests.list() - -List the merge requests available on the GitLab server:: - - mrs = gl.mergerequests.list(scope="all") - -List the merge requests for a group:: - - group = gl.groups.get('mygroup') - mrs = group.mergerequests.list() - -.. note:: - - It is not possible to edit or delete ``MergeRequest`` and - ``GroupMergeRequest`` objects. You need to create a ``ProjectMergeRequest`` - object to apply changes:: - - mr = group.mergerequests.list()[0] - project = gl.projects.get(mr.project_id, lazy=True) - editable_mr = project.mergerequests.get(mr.iid, lazy=True) - editable_mr.title = updated_title - editable_mr.save() - -Project merge requests -====================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectMergeRequest` - + :class:`gitlab.v4.objects.ProjectMergeRequestManager` - + :attr:`gitlab.v4.objects.Project.mergerequests` - -* GitLab API: https://docs.gitlab.com/ce/api/merge_requests.html - -Examples --------- - -List MRs for a project:: - - mrs = project.mergerequests.list() - -You can filter and sort the returned list with the following parameters: - -* ``state``: state of the MR. It can be one of ``all``, ``merged``, ``opened`` - or ``closed`` -* ``order_by``: sort by ``created_at`` or ``updated_at`` -* ``sort``: sort order (``asc`` or ``desc``) - -For example:: - - mrs = project.mergerequests.list(state='merged', order_by='updated_at') - -Get a single MR:: - - mr = project.mergerequests.get(mr_id) - -Create a MR:: - - mr = project.mergerequests.create({'source_branch': 'cool_feature', - 'target_branch': 'master', - 'title': 'merge cool feature', - 'labels': ['label1', 'label2']}) - -Update a MR:: - - mr.description = 'New description' - mr.labels = ['foo', 'bar'] - mr.save() - -Change the state of a MR (close or reopen):: - - mr.state_event = 'close' # or 'reopen' - mr.save() - -Delete a MR:: - - project.mergerequests.delete(mr_id) - # or - mr.delete() - -Accept a MR:: - - mr.merge() - -Cancel a MR when the build succeeds:: - - mr.cancel_merge_when_pipeline_succeeds() - -List commits of a MR:: - - commits = mr.commits() - -List the changes of a MR:: - - changes = mr.changes() - -List issues that will close on merge:: - - mr.closes_issues() - -Subscribe to / unsubscribe from a MR:: - - mr.subscribe() - mr.unsubscribe() - -Mark a MR as todo:: - - mr.todo() - -List the diffs for a merge request:: - - diffs = mr.diffs.list() - -Get a diff for a merge request:: - - diff = mr.diffs.get(diff_id) - -Get time tracking stats:: - - merge request.time_stats() - -On recent versions of Gitlab the time stats are also returned as a merge -request object attribute:: - - mr = project.mergerequests.get(id) - print(mr.attributes['time_stats']) - -Set a time estimate for a merge request:: - - mr.time_estimate('3h30m') - -Reset a time estimate for a merge request:: - - mr.reset_time_estimate() - -Add spent time for a merge request:: - - mr.add_spent_time('3h30m') - -Reset spent time for a merge request:: - - mr.reset_spent_time() - -Get user agent detail for the issue (admin only):: - - detail = issue.user_agent_detail() - -Attempt to rebase an MR:: - - mr.rebase() - -Attempt to merge changes between source and target branch:: - - response = mr.merge_ref() - print(response['commit_id']) - -Merge Request Pipelines -======================= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectMergeRequestPipeline` - + :class:`gitlab.v4.objects.ProjectMergeRequestPipelineManager` - + :attr:`gitlab.v4.objects.ProjectMergeRequest.pipelines` - -* GitLab API: https://docs.gitlab.com/ee/api/merge_requests.html#list-mr-pipelines - -Examples --------- - -List pipelines for a merge request:: - - pipelines = mr.pipelines.list() - -Create a pipeline for a merge request:: - - pipeline = mr.pipelines.create() diff --git a/docs/gl_objects/namespaces.rst b/docs/gl_objects/namespaces.rst deleted file mode 100644 index 1aebd29..0000000 --- a/docs/gl_objects/namespaces.rst +++ /dev/null @@ -1,25 +0,0 @@ -########## -Namespaces -########## - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Namespace` - + :class:`gitlab.v4.objects.NamespaceManager` - + :attr:`gitlab.Gitlab.namespaces` - -* GitLab API: https://docs.gitlab.com/ce/api/namespaces.html - -Examples --------- - -List namespaces:: - - namespaces = gl.namespaces.list() - -Search namespaces:: - - namespaces = gl.namespaces.list(search='foo') diff --git a/docs/gl_objects/notes.rst b/docs/gl_objects/notes.rst deleted file mode 100644 index 053c0a0..0000000 --- a/docs/gl_objects/notes.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. _project-notes: - -##### -Notes -##### - -You can manipulate notes (comments) on project issues, merge requests and -snippets. - -Reference ---------- - -* v4 API: - - Issues: - - + :class:`gitlab.v4.objects.ProjectIssueNote` - + :class:`gitlab.v4.objects.ProjectIssueNoteManager` - + :attr:`gitlab.v4.objects.ProjectIssue.notes` - - MergeRequests: - - + :class:`gitlab.v4.objects.ProjectMergeRequestNote` - + :class:`gitlab.v4.objects.ProjectMergeRequestNoteManager` - + :attr:`gitlab.v4.objects.ProjectMergeRequest.notes` - - Snippets: - - + :class:`gitlab.v4.objects.ProjectSnippetNote` - + :class:`gitlab.v4.objects.ProjectSnippetNoteManager` - + :attr:`gitlab.v4.objects.ProjectSnippet.notes` - -* GitLab API: https://docs.gitlab.com/ce/api/notes.html - -Examples --------- - -List the notes for a resource:: - - i_notes = issue.notes.list() - mr_notes = mr.notes.list() - s_notes = snippet.notes.list() - -Get a note for a resource:: - - i_note = issue.notes.get(note_id) - mr_note = mr.notes.get(note_id) - s_note = snippet.notes.get(note_id) - -Create a note for a resource:: - - i_note = issue.notes.create({'body': 'note content'}) - mr_note = mr.notes.create({'body': 'note content'}) - s_note = snippet.notes.create({'body': 'note content'}) - -Update a note for a resource:: - - note.body = 'updated note content' - note.save() - -Delete a note for a resource:: - - note.delete() diff --git a/docs/gl_objects/notifications.rst b/docs/gl_objects/notifications.rst deleted file mode 100644 index ab0287f..0000000 --- a/docs/gl_objects/notifications.rst +++ /dev/null @@ -1,59 +0,0 @@ -##################### -Notification settings -##################### - -You can define notification settings globally, for groups and for projects. -Valid levels are defined as constants: - -* ``gitlab.NOTIFICATION_LEVEL_DISABLED`` -* ``gitlab.NOTIFICATION_LEVEL_PARTICIPATING`` -* ``gitlab.NOTIFICATION_LEVEL_WATCH`` -* ``gitlab.NOTIFICATION_LEVEL_GLOBAL`` -* ``gitlab.NOTIFICATION_LEVEL_MENTION`` -* ``gitlab.NOTIFICATION_LEVEL_CUSTOM`` - -You get access to fine-grained settings if you use the -``NOTIFICATION_LEVEL_CUSTOM`` level. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.NotificationSettings` - + :class:`gitlab.v4.objects.NotificationSettingsManager` - + :attr:`gitlab.Gitlab.notificationsettings` - + :class:`gitlab.v4.objects.GroupNotificationSettings` - + :class:`gitlab.v4.objects.GroupNotificationSettingsManager` - + :attr:`gitlab.v4.objects.Group.notificationsettings` - + :class:`gitlab.v4.objects.ProjectNotificationSettings` - + :class:`gitlab.v4.objects.ProjectNotificationSettingsManager` - + :attr:`gitlab.v4.objects.Project.notificationsettings` - -* GitLab API: https://docs.gitlab.com/ce/api/notification_settings.html - -Examples --------- - -Get the notifications settings:: - - # global settings - settings = gl.notificationsettings.get() - # for a group - settings = gl.groups.get(group_id).notificationsettings.get() - # for a project - settings = gl.projects.get(project_id).notificationsettings.get() - -Update the notifications settings:: - - # use a predefined level - settings.level = gitlab.NOTIFICATION_LEVEL_WATCH - - # create a custom setup - settings.level = gitlab.NOTIFICATION_LEVEL_CUSTOM - settings.save() # will create additional attributes, but not mandatory - - settings.new_merge_request = True - settings.new_issue = True - settings.new_note = True - settings.save() diff --git a/docs/gl_objects/packages.rst b/docs/gl_objects/packages.rst deleted file mode 100644 index cc64e07..0000000 --- a/docs/gl_objects/packages.rst +++ /dev/null @@ -1,131 +0,0 @@ -######## -Packages -######## - -Packages allow you to utilize GitLab as a private repository for a variety -of common package managers, as well as GitLab's generic package registry. - -Project Packages -===================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectPackage` - + :class:`gitlab.v4.objects.ProjectPackageManager` - + :attr:`gitlab.v4.objects.Project.packages` - -* GitLab API: https://docs.gitlab.com/ee/api/packages.html#within-a-project - -Examples --------- - -List the packages in a project:: - - packages = project.packages.list() - -Filter the results by ``package_type`` or ``package_name`` :: - - packages = project.packages.list(package_type='pypi') - -Get a specific package of a project by id:: - - package = project.packages.get(1) - -Delete a package from a project:: - - package.delete() - # or - project.packages.delete(package.id) - - -Group Packages -=================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GroupPackage` - + :class:`gitlab.v4.objects.GroupPackageManager` - + :attr:`gitlab.v4.objects.Group.packages` - -* GitLab API: https://docs.gitlab.com/ee/api/packages.html#within-a-group - -Examples --------- - -List the packages in a group:: - - packages = group.packages.list() - -Filter the results by ``package_type`` or ``package_name`` :: - - packages = group.packages.list(package_type='pypi') - - -Project Package Files -===================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectPackageFile` - + :class:`gitlab.v4.objects.ProjectPackageFileManager` - + :attr:`gitlab.v4.objects.ProjectPackage.package_files` - -* GitLab API: https://docs.gitlab.com/ee/api/packages.html#list-package-files - -Examples --------- - -List package files for package in project:: - - package = project.packages.get(1) - package_files = package.package_files.list() - -Generic Packages -================ - -You can use python-gitlab to upload and download generic packages. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.GenericPackage` - + :class:`gitlab.v4.objects.GenericPackageManager` - + :attr:`gitlab.v4.objects.Project.generic_packages` - -* GitLab API: https://docs.gitlab.com/ee/user/packages/generic_packages - -Examples --------- - -Upload a generic package to a project:: - - project = gl.projects.get(1, lazy=True) - package = project.generic_packages.upload( - package_name="hello-world", - package_version="v1.0.0", - file_name="hello.tar.gz", - path="/path/to/local/hello.tar.gz" - ) - -Download a project's generic package:: - - project = gl.projects.get(1, lazy=True) - package = project.generic_packages.download( - package_name="hello-world", - package_version="v1.0.0", - file_name="hello.tar.gz", - ) - -.. hint:: You can use the Packages API described above to find packages and - retrieve the metadata you need download them. diff --git a/docs/gl_objects/pagesdomains.rst b/docs/gl_objects/pagesdomains.rst deleted file mode 100644 index d6b39c7..0000000 --- a/docs/gl_objects/pagesdomains.rst +++ /dev/null @@ -1,65 +0,0 @@ -############# -Pages domains -############# - -Admin -===== - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.PagesDomain` - + :class:`gitlab.v4.objects.PagesDomainManager` - + :attr:`gitlab.Gitlab.pagesdomains` - -* GitLab API: https://docs.gitlab.com/ce/api/pages_domains.html#list-all-pages-domains - -Examples --------- - -List all the existing domains (admin only):: - - domains = gl.pagesdomains.list() - -Project pages domain -==================== - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectPagesDomain` - + :class:`gitlab.v4.objects.ProjectPagesDomainManager` - + :attr:`gitlab.v4.objects.Project.pagesdomains` - -* GitLab API: https://docs.gitlab.com/ce/api/pages_domains.html#list-pages-domains - -Examples --------- - -List domains for a project:: - - domains = project.pagesdomains.list() - -Get a single domain:: - - domain = project.pagesdomains.get('d1.example.com') - -Create a new domain:: - - domain = project.pagesdomains.create({'domain': 'd2.example.com}) - -Update an existing domain:: - - domain.certificate = open('d2.crt').read() - domain.key = open('d2.key').read() - domain.save() - -Delete an existing domain:: - - domain.delete - # or - project.pagesdomains.delete('d2.example.com') diff --git a/docs/gl_objects/personal_access_tokens.rst b/docs/gl_objects/personal_access_tokens.rst deleted file mode 100644 index 0704c75..0000000 --- a/docs/gl_objects/personal_access_tokens.rst +++ /dev/null @@ -1,54 +0,0 @@ -###################### -Personal Access Tokens -###################### - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.PersonalAccessToken` - + :class:`gitlab.v4.objects.PersonalAcessTokenManager` - + :attr:`gitlab.Gitlab.personal_access_tokens` - + :class:`gitlab.v4.objects.UserPersonalAccessToken` - + :class:`gitlab.v4.objects.UserPersonalAcessTokenManager` - + :attr:`gitlab.Gitlab.User.personal_access_tokens` - -* GitLab API: - - + https://docs.gitlab.com/ee/api/personal_access_tokens.html - + https://docs.gitlab.com/ee/api/users.html#create-a-personal-access-token - -Examples --------- - -List personal access tokens:: - - access_tokens = gl.personal_access_tokens.list() - print(access_tokens[0].name) - -List personal access tokens from other user_id (admin only):: - - access_tokens = gl.personal_access_tokens.list(user_id=25) - -Revoke a personal access token fetched via list:: - - access_token = access_tokens[0] - access_token.delete() - -Revoke a personal access token by id:: - - gl.personal_access_tokens.delete(123) - -Create a personal access token for a user (admin only):: - - user = gl.users.get(25, lazy=True) - access_token = user.personal_access_tokens.create({"name": "test", "scopes": "api"}) - -.. note:: As you can see above, you can only create personal access tokens - via the Users API, but you cannot revoke these objects directly. - This is because the create API uses a different endpoint than the list and revoke APIs. - You need to fetch the token via the list API first to revoke it. - - As of 14.2, GitLab does not provide a GET API for single personal access tokens. - You must use the list method to retrieve single tokens. diff --git a/docs/gl_objects/pipelines_and_jobs.rst b/docs/gl_objects/pipelines_and_jobs.rst deleted file mode 100644 index 675ff4e..0000000 --- a/docs/gl_objects/pipelines_and_jobs.rst +++ /dev/null @@ -1,355 +0,0 @@ -################## -Pipelines and Jobs -################## - -Project pipelines -================= - -A pipeline is a group of jobs executed by GitLab CI. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectPipeline` - + :class:`gitlab.v4.objects.ProjectPipelineManager` - + :attr:`gitlab.v4.objects.Project.pipelines` - -* GitLab API: https://docs.gitlab.com/ce/api/pipelines.html - -Examples --------- - -List pipelines for a project:: - - pipelines = project.pipelines.list() - -Get a pipeline for a project:: - - pipeline = project.pipelines.get(pipeline_id) - -Get variables of a pipeline:: - - variables = pipeline.variables.list() - -Create a pipeline for a particular reference with custom variables:: - - pipeline = project.pipelines.create({'ref': 'master', 'variables': [{'key': 'MY_VARIABLE', 'value': 'hello'}]}) - -Retry the failed builds for a pipeline:: - - pipeline.retry() - -Cancel builds in a pipeline:: - - pipeline.cancel() - -Delete a pipeline:: - - pipeline.delete() - -Triggers -======== - -Triggers provide a way to interact with the GitLab CI. Using a trigger a user -or an application can run a new build/job for a specific commit. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectTrigger` - + :class:`gitlab.v4.objects.ProjectTriggerManager` - + :attr:`gitlab.v4.objects.Project.triggers` - -* GitLab API: https://docs.gitlab.com/ce/api/pipeline_triggers.html - -Examples --------- - -List triggers:: - - triggers = project.triggers.list() - -Get a trigger:: - - trigger = project.triggers.get(trigger_token) - -Create a trigger:: - - trigger = project.triggers.create({'description': 'mytrigger'}) - -Remove a trigger:: - - project.triggers.delete(trigger_token) - # or - trigger.delete() - -Full example with wait for finish:: - - def get_or_create_trigger(project): - trigger_decription = 'my_trigger_id' - for t in project.triggers.list(): - if t.description == trigger_decription: - return t - return project.triggers.create({'description': trigger_decription}) - - trigger = get_or_create_trigger(project) - pipeline = project.trigger_pipeline('master', trigger.token, variables={"DEPLOY_ZONE": "us-west1"}) - while pipeline.finished_at is None: - pipeline.refresh() - time.sleep(1) - -You can trigger a pipeline using token authentication instead of user -authentication. To do so create an anonymous Gitlab instance and use lazy -objects to get the associated project:: - - gl = gitlab.Gitlab(URL) # no authentication - project = gl.projects.get(project_id, lazy=True) # no API call - project.trigger_pipeline('master', trigger_token) - -Reference: https://docs.gitlab.com/ee/ci/triggers/#trigger-token - -Pipeline schedule -================= - -You can schedule pipeline runs using a cron-like syntax. Variables can be -associated with the scheduled pipelines. - -Reference ---------- - -* v4 API - - + :class:`gitlab.v4.objects.ProjectPipelineSchedule` - + :class:`gitlab.v4.objects.ProjectPipelineScheduleManager` - + :attr:`gitlab.v4.objects.Project.pipelineschedules` - + :class:`gitlab.v4.objects.ProjectPipelineScheduleVariable` - + :class:`gitlab.v4.objects.ProjectPipelineScheduleVariableManager` - + :attr:`gitlab.v4.objects.Project.pipelineschedules` - -* GitLab API: https://docs.gitlab.com/ce/api/pipeline_schedules.html - -Examples --------- - -List pipeline schedules:: - - scheds = project.pipelineschedules.list() - -Get a single schedule:: - - sched = projects.pipelineschedules.get(schedule_id) - -Create a new schedule:: - - sched = project.pipelineschedules.create({ - 'ref': 'master', - 'description': 'Daily test', - 'cron': '0 1 * * *'}) - -Update a schedule:: - - sched.cron = '1 2 * * *' - sched.save() - -Take ownership of a schedule: - - sched.take_ownership() - -Trigger a pipeline schedule immediately:: - - sched = projects.pipelineschedules.get(schedule_id) - sched.play() - -Delete a schedule:: - - sched.delete() - -List schedule variables:: - - # note: you need to use get() to retrieve the schedule variables. The - # attribute is not present in the response of a list() call - sched = projects.pipelineschedules.get(schedule_id) - vars = sched.attributes['variables'] - -Create a schedule variable:: - - var = sched.variables.create({'key': 'foo', 'value': 'bar'}) - -Edit a schedule variable:: - - var.value = 'new_value' - var.save() - -Delete a schedule variable:: - - var.delete() - - -Jobs -==== - -Jobs are associated to projects, pipelines and commits. They provide -information on the jobs that have been run, and methods to manipulate -them. - -Reference ---------- - -* v4 API - - + :class:`gitlab.v4.objects.ProjectJob` - + :class:`gitlab.v4.objects.ProjectJobManager` - + :attr:`gitlab.v4.objects.Project.jobs` - -* GitLab API: https://docs.gitlab.com/ce/api/jobs.html - -Examples --------- - -Jobs are usually automatically triggered, but you can explicitly trigger a new -job:: - - project.trigger_build('master', trigger_token, - {'extra_var1': 'foo', 'extra_var2': 'bar'}) - -List jobs for the project:: - - jobs = project.jobs.list() - -Get a single job:: - - project.jobs.get(job_id) - -List the jobs of a pipeline:: - - project = gl.projects.get(project_id) - pipeline = project.pipelines.get(pipeline_id) - jobs = pipeline.jobs.list() - -.. note:: - - Job methods (play, cancel, and so on) are not available on - ``ProjectPipelineJob`` objects. To use these methods create a ``ProjectJob`` - object:: - - pipeline_job = pipeline.jobs.list()[0] - job = project.jobs.get(pipeline_job.id, lazy=True) - job.retry() - -Get the artifacts of a job:: - - build_or_job.artifacts() - -Get the artifacts of a job by its name from the latest successful pipeline of -a branch or tag: - - project.artifacts(ref_name='master', job='build') - -.. warning:: - - Artifacts are entirely stored in memory in this example. - -.. _streaming_example: - -You can download artifacts as a stream. Provide a callable to handle the -stream:: - - with open("archive.zip", "wb") as f: - build_or_job.artifacts(streamed=True, action=f.write) - -You can also directly stream the output into a file, and unzip it afterwards:: - - zipfn = "___artifacts.zip" - with open(zipfn, "wb") as f: - build_or_job.artifacts(streamed=True, action=f.write) - subprocess.run(["unzip", "-bo", zipfn]) - os.unlink(zipfn) - -Get a single artifact file:: - - build_or_job.artifact('path/to/file') - -Get a single artifact file by branch and job:: - - project.artifact('branch', 'path/to/file', 'job') - -Mark a job artifact as kept when expiration is set:: - - build_or_job.keep_artifacts() - -Delete the artifacts of a job:: - - build_or_job.delete_artifacts() - -Get a job trace:: - - build_or_job.trace() - -.. warning:: - - Traces are entirely stored in memory unless you use the streaming feature. - See :ref:`the artifacts example <streaming_example>`. - -Cancel/retry a job:: - - build_or_job.cancel() - build_or_job.retry() - -Play (trigger) a job:: - - build_or_job.play() - -Erase a job (artifacts and trace):: - - build_or_job.erase() - - -Pipeline bridges -===================== - -Get a list of bridge jobs (including child pipelines) for a pipeline. - -Reference ---------- - -* v4 API - - + :class:`gitlab.v4.objects.ProjectPipelineBridge` - + :class:`gitlab.v4.objects.ProjectPipelineBridgeManager` - + :attr:`gitlab.v4.objects.ProjectPipeline.bridges` - -* GitLab API: https://docs.gitlab.com/ee/api/jobs.html#list-pipeline-bridges - -Examples --------- - -List bridges for the pipeline:: - - bridges = pipeline.bridges.list() - -Pipeline test report -==================== - -Get a pipeline's complete test report. - -Reference ---------- - -* v4 API - - + :class:`gitlab.v4.objects.ProjectPipelineTestReport` - + :class:`gitlab.v4.objects.ProjectPipelineTestReportManager` - + :attr:`gitlab.v4.objects.ProjectPipeline.test_report` - -* GitLab API: https://docs.gitlab.com/ee/api/pipelines.html#get-a-pipelines-test-report - -Examples --------- - -Get the test report for a pipeline:: - - test_report = pipeline.test_report.get() diff --git a/docs/gl_objects/project_access_tokens.rst b/docs/gl_objects/project_access_tokens.rst deleted file mode 100644 index 850cd25..0000000 --- a/docs/gl_objects/project_access_tokens.rst +++ /dev/null @@ -1,34 +0,0 @@ -##################### -Project Access Tokens -##################### - -Get a list of project access tokens - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectAccessToken` - + :class:`gitlab.v4.objects.ProjectAccessTokenManager` - + :attr:`gitlab.Gitlab.project_access_tokens` - -* GitLab API: https://docs.gitlab.com/ee/api/resource_access_tokens.html - -Examples --------- - -List project access tokens:: - - access_tokens = gl.projects.get(1, lazy=True).access_tokens.list() - print(access_tokens[0].name) - -Create project access token:: - - access_token = gl.projects.get(1).access_tokens.create({"name": "test", "scopes": ["api"]}) - -Revoke a project access tokens:: - - gl.projects.get(1).access_tokens.delete(42) - # or - access_token.delete() diff --git a/docs/gl_objects/projects.rst b/docs/gl_objects/projects.rst deleted file mode 100644 index fdf5ac5..0000000 --- a/docs/gl_objects/projects.rst +++ /dev/null @@ -1,768 +0,0 @@ -######## -Projects -######## - -Projects -======== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Project` - + :class:`gitlab.v4.objects.ProjectManager` - + :attr:`gitlab.Gitlab.projects` - -* GitLab API: https://docs.gitlab.com/ce/api/projects.html - -Examples --------- - -List projects:: - - projects = gl.projects.list() - -The API provides several filtering parameters for the listing methods: - -* ``archived``: if ``True`` only archived projects will be returned -* ``visibility``: returns only projects with the specified visibility (can be - ``public``, ``internal`` or ``private``) -* ``search``: returns project matching the given pattern - -Results can also be sorted using the following parameters: - -* ``order_by``: sort using the given argument. Valid values are ``id``, - ``name``, ``path``, ``created_at``, ``updated_at`` and ``last_activity_at``. - The default is to sort by ``created_at`` -* ``sort``: sort order (``asc`` or ``desc``) - -:: - - # List all projects (default 20) - projects = gl.projects.list(all=True) - # Archived projects - projects = gl.projects.list(archived=1) - # Limit to projects with a defined visibility - projects = gl.projects.list(visibility='public') - - # List owned projects - projects = gl.projects.list(owned=True) - - # List starred projects - projects = gl.projects.list(starred=True) - - # Search projects - projects = gl.projects.list(search='keyword') - -.. note:: - - Fetching a list of projects, doesn't include all attributes of all projects. - To retrieve all attributes, you'll need to fetch a single project - -Get a single project:: - - # Get a project by ID - project_id = 851 - project = gl.projects.get(project_id) - - # Get a project by name with namespace - project_name_with_namespace = "namespace/project_name" - project = gl.projects.get(project_name_with_namespace) - -Create a project:: - - project = gl.projects.create({'name': 'project1'}) - -Create a project for a user (admin only):: - - alice = gl.users.list(username='alice')[0] - user_project = alice.projects.create({'name': 'project'}) - user_projects = alice.projects.list() - -Create a project in a group:: - - # You need to get the id of the group, then use the namespace_id attribute - # to create the group - group_id = gl.groups.list(search='my-group')[0].id - project = gl.projects.create({'name': 'myrepo', 'namespace_id': group_id}) - -Update a project:: - - project.snippets_enabled = 1 - project.save() - -Set the avatar image for a project:: - - # the avatar image can be passed as data (content of the file) or as a file - # object opened in binary mode - project.avatar = open('path/to/file.png', 'rb') - project.save() - -Delete a project:: - - gl.projects.delete(project_id) - # or - project.delete() - -Fork a project:: - - fork = project.forks.create({}) - - # fork to a specific namespace - fork = project.forks.create({'namespace': 'myteam'}) - -Get a list of forks for the project:: - - forks = project.forks.list() - -Create/delete a fork relation between projects (requires admin permissions):: - - project.create_fork_relation(source_project.id) - project.delete_fork_relation() - -Get languages used in the project with percentage value:: - - languages = project.languages() - -Star/unstar a project:: - - project.star() - project.unstar() - -Archive/unarchive a project:: - - project.archive() - project.unarchive() - -Start the housekeeping job:: - - project.housekeeping() - -List the repository tree:: - - # list the content of the root directory for the default branch - items = project.repository_tree() - - # list the content of a subdirectory on a specific branch - items = project.repository_tree(path='docs', ref='branch1') - -Get the content and metadata of a file for a commit, using a blob sha:: - - items = project.repository_tree(path='docs', ref='branch1') - file_info = p.repository_blob(items[0]['id']) - content = base64.b64decode(file_info['content']) - size = file_info['size'] - -Update a project submodule:: - - items = project.update_submodule( - submodule="foo/bar", - branch="master", - commit_sha="4c3674f66071e30b3311dac9b9ccc90502a72664", - commit_message="Message", # optional - ) - -Get the repository archive:: - - tgz = project.repository_archive() - - # get the archive for a branch/tag/commit - tgz = project.repository_archive(sha='4567abc') - -.. warning:: - - Archives are entirely stored in memory unless you use the streaming feature. - See :ref:`the artifacts example <streaming_example>`. - -Get the content of a file using the blob id:: - - # find the id for the blob (simple search) - id = [d['id'] for d in p.repository_tree() if d['name'] == 'README.rst'][0] - - # get the content - file_content = p.repository_raw_blob(id) - -.. warning:: - - Blobs are entirely stored in memory unless you use the streaming feature. - See :ref:`the artifacts example <streaming_example>`. - -Get a snapshot of the repository:: - - tar_file = project.snapshot() - -.. warning:: - - Snapshots are entirely stored in memory unless you use the streaming - feature. See :ref:`the artifacts example <streaming_example>`. - -Compare two branches, tags or commits:: - - result = project.repository_compare('master', 'branch1') - - # get the commits - for commit in result['commits']: - print(commit) - - # get the diffs - for file_diff in result['diffs']: - print(file_diff) - -Get a list of contributors for the repository:: - - contributors = project.repository_contributors() - -Get a list of users for the repository:: - - users = p.users.list() - - # search for users - users = p.users.list(search='pattern') - -Start the pull mirroring process (EE edition):: - - project.mirror_pull() - -Import / Export -=============== - -You can export projects from gitlab, and re-import them to create new projects -or overwrite existing ones. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectExport` - + :class:`gitlab.v4.objects.ProjectExportManager` - + :attr:`gitlab.v4.objects.Project.exports` - + :class:`gitlab.v4.objects.ProjectImport` - + :class:`gitlab.v4.objects.ProjectImportManager` - + :attr:`gitlab.v4.objects.Project.imports` - + :attr:`gitlab.v4.objects.ProjectManager.import_project` - -* GitLab API: https://docs.gitlab.com/ce/api/project_import_export.html - -Examples --------- - -A project export is an asynchronous operation. To retrieve the archive -generated by GitLab you need to: - -#. Create an export using the API -#. Wait for the export to be done -#. Download the result - -:: - - # Create the export - p = gl.projects.get(my_project) - export = p.exports.create() - - # Wait for the 'finished' status - export.refresh() - while export.export_status != 'finished': - time.sleep(1) - export.refresh() - - # Download the result - with open('/tmp/export.tgz', 'wb') as f: - export.download(streamed=True, action=f.write) - -Import the project:: - - output = gl.projects.import_project(open('/tmp/export.tgz', 'rb'), 'my_new_project') - # Get a ProjectImport object to track the import status - project_import = gl.projects.get(output['id'], lazy=True).imports.get() - while project_import.import_status != 'finished': - time.sleep(1) - project_import.refresh() - - -Project custom attributes -========================= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectCustomAttribute` - + :class:`gitlab.v4.objects.ProjectCustomAttributeManager` - + :attr:`gitlab.v4.objects.Project.customattributes` - -* GitLab API: https://docs.gitlab.com/ce/api/custom_attributes.html - -Examples --------- - -List custom attributes for a project:: - - attrs = project.customattributes.list() - -Get a custom attribute for a project:: - - attr = project.customattributes.get(attr_key) - -Set (create or update) a custom attribute for a project:: - - attr = project.customattributes.set(attr_key, attr_value) - -Delete a custom attribute for a project:: - - attr.delete() - # or - project.customattributes.delete(attr_key) - -Search projects by custom attribute:: - - project.customattributes.set('type', 'internal') - gl.projects.list(custom_attributes={'type': 'internal'}) - -Project files -============= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectFile` - + :class:`gitlab.v4.objects.ProjectFileManager` - + :attr:`gitlab.v4.objects.Project.files` - -* GitLab API: https://docs.gitlab.com/ce/api/repository_files.html - -Examples --------- - -Get a file:: - - f = project.files.get(file_path='README.rst', ref='master') - - # get the base64 encoded content - print(f.content) - - # get the decoded content - print(f.decode()) - -Get a raw file:: - - raw_content = project.files.raw(file_path='README.rst', ref='master') - print(raw_content) - with open('/tmp/raw-download.txt', 'wb') as f: - project.files.raw(file_path='README.rst', ref='master', streamed=True, action=f.write) - -Create a new file:: - - f = project.files.create({'file_path': 'testfile.txt', - 'branch': 'master', - 'content': file_content, - 'author_email': 'test@example.com', - 'author_name': 'yourname', - 'encoding': 'text', - 'commit_message': 'Create testfile'}) - -Update a file. The entire content must be uploaded, as plain text or as base64 -encoded text:: - - f.content = 'new content' - f.save(branch='master', commit_message='Update testfile') - - # or for binary data - # Note: decode() is required with python 3 for data serialization. You can omit - # it with python 2 - f.content = base64.b64encode(open('image.png').read()).decode() - f.save(branch='master', commit_message='Update testfile', encoding='base64') - -Delete a file:: - - f.delete(commit_message='Delete testfile', branch='master') - # or - project.files.delete(file_path='testfile.txt', commit_message='Delete testfile', branch='master') - -Get file blame:: - - b = project.files.blame(file_path='README.rst', ref='master') - -Project tags -============ - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectTag` - + :class:`gitlab.v4.objects.ProjectTagManager` - + :attr:`gitlab.v4.objects.Project.tags` - -* GitLab API: https://docs.gitlab.com/ce/api/tags.html - -Examples --------- - -List the project tags:: - - tags = project.tags.list() - -Get a tag:: - - tag = project.tags.get('1.0') - -Create a tag:: - - tag = project.tags.create({'tag_name': '1.0', 'ref': 'master'}) - -Delete a tag:: - - project.tags.delete('1.0') - # or - tag.delete() - -.. _project_snippets: - -Project snippets -================ - -The snippet visibility can be defined using the following constants: - -* ``gitlab.VISIBILITY_PRIVATE`` -* ``gitlab.VISIBILITY_INTERNAL`` -* ``gitlab.VISIBILITY_PUBLIC`` - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectSnippet` - + :class:`gitlab.v4.objects.ProjectSnippetManager` - + :attr:`gitlab.v4.objects.Project.files` - -* GitLab API: https://docs.gitlab.com/ce/api/project_snippets.html - -Examples --------- - -List the project snippets:: - - snippets = project.snippets.list() - -Get a snippet:: - - snippet = project.snippets.get(snippet_id) - -Get the content of a snippet:: - - print(snippet.content()) - -.. warning:: - - The snippet content is entirely stored in memory unless you use the - streaming feature. See :ref:`the artifacts example <streaming_example>`. - -Create a snippet:: - - snippet = project.snippets.create({'title': 'sample 1', - 'file_name': 'foo.py', - 'code': 'import gitlab', - 'visibility_level': - gitlab.VISIBILITY_PRIVATE}) - -Update a snippet:: - - snippet.code = 'import gitlab\nimport whatever' - snippet.save - -Delete a snippet:: - - project.snippets.delete(snippet_id) - # or - snippet.delete() - -Get user agent detail (admin only):: - - detail = snippet.user_agent_detail() - -Notes -===== - -See :ref:`project-notes`. - -Project members -=============== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectMember` - + :class:`gitlab.v4.objects.ProjectMemberManager` - + :class:`gitlab.v4.objects.ProjectMemberAllManager` - + :attr:`gitlab.v4.objects.Project.members` - + :attr:`gitlab.v4.objects.Project.members_all` - -* GitLab API: https://docs.gitlab.com/ce/api/members.html - -Examples --------- - -List only direct project members:: - - members = project.members.list() - -List the project members recursively (including inherited members through -ancestor groups):: - - members = project.members_all.list(all=True) - -Search project members matching a query string:: - - members = project.members.list(query='bar') - -Get only direct project member:: - - member = project.members.get(user_id) - -Get a member of a project, including members inherited through ancestor groups:: - - members = project.members_all.get(member_id) - - -Add a project member:: - - member = project.members.create({'user_id': user.id, 'access_level': - gitlab.DEVELOPER_ACCESS}) - -Modify a project member (change the access level):: - - member.access_level = gitlab.MAINTAINER_ACCESS - member.save() - -Remove a member from the project team:: - - project.members.delete(user.id) - # or - member.delete() - -Share/unshare the project with a group:: - - project.share(group.id, gitlab.DEVELOPER_ACCESS) - project.unshare(group.id) - -Project hooks -============= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectHook` - + :class:`gitlab.v4.objects.ProjectHookManager` - + :attr:`gitlab.v4.objects.Project.hooks` - -* GitLab API: https://docs.gitlab.com/ce/api/projects.html#hooks - -Examples --------- - -List the project hooks:: - - hooks = project.hooks.list() - -Get a project hook:: - - hook = project.hooks.get(hook_id) - -Create a project hook:: - - hook = project.hooks.create({'url': 'http://my/action/url', 'push_events': 1}) - -Update a project hook:: - - hook.push_events = 0 - hook.save() - -Delete a project hook:: - - project.hooks.delete(hook_id) - # or - hook.delete() - -Project Services -================ - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectService` - + :class:`gitlab.v4.objects.ProjectServiceManager` - + :attr:`gitlab.v4.objects.Project.services` - -* GitLab API: https://docs.gitlab.com/ce/api/services.html - -Examples ---------- - -Get a service:: - - service = project.services.get('asana') - # display its status (enabled/disabled) - print(service.active) - -List active project services:: - - service = project.services.list() - -List the code names of available services (doesn't return objects):: - - services = project.services.available() - -Configure and enable a service:: - - service.api_key = 'randomkey' - service.save() - -Disable a service:: - - service.delete() - -File uploads -============ - -Reference ---------- - -* v4 API: - - + :attr:`gitlab.v4.objects.Project.upload` - -* Gitlab API: https://docs.gitlab.com/ce/api/projects.html#upload-a-file - -Examples --------- - -Upload a file into a project using a filesystem path:: - - project.upload("filename.txt", filepath="/some/path/filename.txt") - -Upload a file into a project without a filesystem path:: - - project.upload("filename.txt", filedata="Raw data") - -Upload a file and comment on an issue using the uploaded file's -markdown:: - - uploaded_file = project.upload("filename.txt", filedata="data") - issue = project.issues.get(issue_id) - issue.notes.create({ - "body": "See the attached file: {}".format(uploaded_file["markdown"]) - }) - -Upload a file and comment on an issue while using custom -markdown to reference the uploaded file:: - - uploaded_file = project.upload("filename.txt", filedata="data") - issue = project.issues.get(issue_id) - issue.notes.create({ - "body": "See the [attached file]({})".format(uploaded_file["url"]) - }) - -Project push rules -================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectPushRules` - + :class:`gitlab.v4.objects.ProjectPushRulesManager` - + :attr:`gitlab.v4.objects.Project.pushrules` - -* GitLab API: https://docs.gitlab.com/ee/api/projects.html#push-rules - -Examples ---------- - -Create project push rules (at least one rule is necessary):: - - project.pushrules.create({'deny_delete_tag': True}) - -Get project push rules (returns None is there are no push rules):: - - pr = project.pushrules.get() - -Edit project push rules:: - - pr.branch_name_regex = '^(master|develop|support-\d+|release-\d+\..+|hotfix-.+|feature-.+)$' - pr.save() - -Delete project push rules:: - - pr.delete() - -Project protected tags -====================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectProtectedTag` - + :class:`gitlab.v4.objects.ProjectProtectedTagManager` - + :attr:`gitlab.v4.objects.Project.protectedtags` - -* GitLab API: https://docs.gitlab.com/ce/api/protected_tags.html - -Examples ---------- - -Get a list of protected tags from a project:: - - protected_tags = project.protectedtags.list() - -Get a single protected tag or wildcard protected tag:: - - protected_tag = project.protectedtags.get('v*') - -Protect a single repository tag or several project repository tags using a wildcard protected tag:: - - project.protectedtags.create({'name': 'v*', 'create_access_level': '40'}) - -Unprotect the given protected tag or wildcard protected tag.:: - - protected_tag.delete() - -Additional project statistics -============================= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectAdditionalStatistics` - + :class:`gitlab.v4.objects.ProjectAdditionalStatisticsManager` - + :attr:`gitlab.v4.objects.Project.additionalstatistics` - -* GitLab API: https://docs.gitlab.com/ce/api/project_statistics.html - -Examples ---------- - -Get all additional statistics of a project:: - - statistics = project.additionalstatistics.get() - -Get total fetches in last 30 days of a project:: - - total_fetches = project.additionalstatistics.get().fetches['total'] diff --git a/docs/gl_objects/protected_branches.rst b/docs/gl_objects/protected_branches.rst deleted file mode 100644 index 3498aa5..0000000 --- a/docs/gl_objects/protected_branches.rst +++ /dev/null @@ -1,51 +0,0 @@ -################## -Protected branches -################## - -You can define a list of protected branch names on a repository. Names can use -wildcards (``*``). - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectProtectedBranch` - + :class:`gitlab.v4.objects.ProjectProtectedBranchManager` - + :attr:`gitlab.v4.objects.Project.protectedbranches` - -* GitLab API: https://docs.gitlab.com/ce/api/protected_branches.html#protected-branches-api - -Examples --------- - -Get the list of protected branches for a project:: - - p_branches = project.protectedbranches.list() - -Get a single protected branch:: - - p_branch = project.protectedbranches.get('master') - -Create a protected branch:: - - p_branch = project.protectedbranches.create({ - 'name': '*-stable', - 'merge_access_level': gitlab.DEVELOPER_ACCESS, - 'push_access_level': gitlab.MAINTAINER_ACCESS - }) - -Create a protected branch with more granular access control:: - - p_branch = project.protectedbranches.create({ - 'name': '*-stable', - 'allowed_to_push': [{"user_id": 99}, {"user_id": 98}], - 'allowed_to_merge': [{"group_id": 653}], - 'allowed_to_unprotect': [{"access_level": gitlab.MAINTAINER_ACCESS}] - }) - -Delete a protected branch:: - - project.protectedbranches.delete('*-stable') - # or - p_branch.delete() diff --git a/docs/gl_objects/releases.rst b/docs/gl_objects/releases.rst deleted file mode 100644 index 6077fe9..0000000 --- a/docs/gl_objects/releases.rst +++ /dev/null @@ -1,83 +0,0 @@ -######## -Releases -######## - -Project releases -================ - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectRelease` - + :class:`gitlab.v4.objects.ProjectReleaseManager` - + :attr:`gitlab.v4.objects.Project.releases` - -* Gitlab API: https://docs.gitlab.com/ee/api/releases/index.html - -Examples --------- - -Get a list of releases from a project:: - - release = project.releases.list() - -Get a single release:: - - release = project.releases.get('v1.2.3') - -Edit a release:: - - release.name = "Demo Release" - release.description = "release notes go here" - release.save() - -Create a release for a project tag:: - - release = project.releases.create({'name':'Demo Release', 'tag_name':'v1.2.3', 'description':'release notes go here'}) - -Delete a release:: - - # via its tag name from project attributes - release = project.releases.delete('v1.2.3') - - # delete object directly - release.delete() - -Project release links -===================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectReleaseLink` - + :class:`gitlab.v4.objects.ProjectReleaseLinkManager` - + :attr:`gitlab.v4.objects.ProjectRelease.links` - -* Gitlab API: https://docs.gitlab.com/ee/api/releases/links.html - -Examples --------- - -Get a list of releases from a project:: - - links = release.links.list() - -Get a single release link:: - - link = release.links.get(1) - -Create a release link for a release:: - - link = release.links.create({"url": "https://example.com/asset", "name": "asset"}) - -Delete a release link:: - - # via its ID from release attributes - release.links.delete(1) - - # delete object directly - link.delete() diff --git a/docs/gl_objects/remote_mirrors.rst b/docs/gl_objects/remote_mirrors.rst deleted file mode 100644 index 9024228..0000000 --- a/docs/gl_objects/remote_mirrors.rst +++ /dev/null @@ -1,34 +0,0 @@ -###################### -Project Remote Mirrors -###################### - -Remote Mirrors allow you to set up push mirroring for a project. - -References -========== - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectRemoteMirror` - + :class:`gitlab.v4.objects.ProjectRemoteMirrorManager` - + :attr:`gitlab.v4.objects.Project.remote_mirrors` - -* GitLab API: https://docs.gitlab.com/ce/api/remote_mirrors.html - -Examples --------- - -Get the list of a project's remote mirrors:: - - mirrors = project.remote_mirrors.list() - -Create (and enable) a remote mirror for a project:: - - mirror = project.remote_mirrors.create({'url': 'https://gitlab.com/example.git', - 'enabled': True}) - -Update an existing remote mirror's attributes:: - - mirror.enabled = False - mirror.only_protected_branches = True - mirror.save() diff --git a/docs/gl_objects/repositories.rst b/docs/gl_objects/repositories.rst deleted file mode 100644 index 6622c0c..0000000 --- a/docs/gl_objects/repositories.rst +++ /dev/null @@ -1,28 +0,0 @@ -##################### -Registry Repositories -##################### - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectRegistryRepository` - + :class:`gitlab.v4.objects.ProjectRegistryRepositoryManager` - + :attr:`gitlab.v4.objects.Project.repositories` - -* Gitlab API: https://docs.gitlab.com/ce/api/container_registry.html - -Examples --------- - -Get the list of container registry repositories associated with the project:: - - repositories = project.repositories.list() - -Delete repository:: - - project.repositories.delete(id=x) - # or - repository = repositories.pop() - repository.delete() diff --git a/docs/gl_objects/repository_tags.rst b/docs/gl_objects/repository_tags.rst deleted file mode 100644 index 2fa807c..0000000 --- a/docs/gl_objects/repository_tags.rst +++ /dev/null @@ -1,47 +0,0 @@ -######################## -Registry Repository Tags -######################## - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectRegistryTag` - + :class:`gitlab.v4.objects.ProjectRegistryTagManager` - + :attr:`gitlab.v4.objects.Repository.tags` - -* Gitlab API: https://docs.gitlab.com/ce/api/container_registry.html - -Examples --------- - -Get the list of repository tags in given registry:: - - repositories = project.repositories.list() - repository = repositories.pop() - tags = repository.tags.list() - -Get specific tag:: - - repository.tags.get(id=tag_name) - -Delete tag:: - - repository.tags.delete(id=tag_name) - # or - tag = repository.tags.get(id=tag_name) - tag.delete() - -Delete tag in bulk:: - - repository.tags.delete_in_bulk(keep_n=1) - # or - repository.tags.delete_in_bulk(older_than="1m") - # or - repository.tags.delete_in_bulk(name_regex="v.+", keep_n=2) - -.. note:: - - Delete in bulk is asynchronous operation and may take a while. - Refer to: https://docs.gitlab.com/ce/api/container_registry.html#delete-repository-tags-in-bulk diff --git a/docs/gl_objects/runners.rst b/docs/gl_objects/runners.rst deleted file mode 100644 index 1919975..0000000 --- a/docs/gl_objects/runners.rst +++ /dev/null @@ -1,137 +0,0 @@ -####### -Runners -####### - -Runners are external processes used to run CI jobs. They are deployed by the -administrator and registered to the GitLab instance. - -Shared runners are available for all projects. Specific runners are enabled for -a list of projects. - -Global runners (admin) -====================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Runner` - + :class:`gitlab.v4.objects.RunnerManager` - + :attr:`gitlab.Gitlab.runners` - -* GitLab API: https://docs.gitlab.com/ce/api/runners.html - -Examples --------- - -Use the ``list()`` and ``all()`` methods to list runners. - -Both methods accept a ``scope`` parameter to filter the list. Allowed values -for this parameter are: - -* ``active`` -* ``paused`` -* ``online`` -* ``specific`` (``all()`` only) -* ``shared`` (``all()`` only) - -.. note:: - - The returned objects hold minimal information about the runners. Use the - ``get()`` method to retrieve detail about a runner. - -:: - - # List owned runners - runners = gl.runners.list() - # With a filter - runners = gl.runners.list(scope='active') - # List all runners, using a filter - runners = gl.runners.all(scope='paused') - -Get a runner's detail:: - - runner = gl.runners.get(runner_id) - -Register a new runner:: - - runner = gl.runners.create({'token': secret_token}) - -Update a runner:: - - runner = gl.runners.get(runner_id) - runner.tag_list.append('new_tag') - runner.save() - -Remove a runner:: - - gl.runners.delete(runner_id) - # or - runner.delete() - -Verify a registered runner token:: - - try: - gl.runners.verify(runner_token) - print("Valid token") - except GitlabVerifyError: - print("Invalid token") - -Project/Group runners -===================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectRunner` - + :class:`gitlab.v4.objects.ProjectRunnerManager` - + :attr:`gitlab.v4.objects.Project.runners` - + :class:`gitlab.v4.objects.GroupRunner` - + :class:`gitlab.v4.objects.GroupRunnerManager` - + :attr:`gitlab.v4.objects.Group.runners` - -* GitLab API: https://docs.gitlab.com/ce/api/runners.html - -Examples --------- - -List the runners for a project:: - - runners = project.runners.list() - -Enable a specific runner for a project:: - - p_runner = project.runners.create({'runner_id': runner.id}) - -Disable a specific runner for a project:: - - project.runners.delete(runner.id) - -Runner jobs -=========== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.RunnerJob` - + :class:`gitlab.v4.objects.RunnerJobManager` - + :attr:`gitlab.v4.objects.Runner.jobs` - -* GitLab API: https://docs.gitlab.com/ce/api/runners.html - -Examples --------- - -List for jobs for a runner:: - - jobs = runner.jobs.list() - -Filter the list using the jobs status:: - - # status can be 'running', 'success', 'failed' or 'canceled' - active_jobs = runner.jobs.list(status='running') diff --git a/docs/gl_objects/search.rst b/docs/gl_objects/search.rst deleted file mode 100644 index eb8ba80..0000000 --- a/docs/gl_objects/search.rst +++ /dev/null @@ -1,77 +0,0 @@ -########## -Search API -########## - -You can search for resources at the top level, in a project or in a group. -Searches are based on a scope (issues, merge requests, and so on) and a search -string. The following constants are provided to represent the possible scopes: - - -* Shared scopes (global, group and project): - - + ``gitlab.SEARCH_SCOPE_PROJECTS``: ``projects`` - + ``gitlab.SEARCH_SCOPE_ISSUES``: ``issues`` - + ``gitlab.SEARCH_SCOPE_MERGE_REQUESTS``: ``merge_requests`` - + ``gitlab.SEARCH_SCOPE_MILESTONES``: ``milestones`` - + ``gitlab.SEARCH_SCOPE_WIKI_BLOBS``: ``wiki_blobs`` - + ``gitlab.SEARCH_SCOPE_COMMITS``: ``commits`` - + ``gitlab.SEARCH_SCOPE_BLOBS``: ``blobs`` - + ``gitlab.SEARCH_SCOPE_USERS``: ``users`` - - -* specific global scope: - - + ``gitlab.SEARCH_SCOPE_GLOBAL_SNIPPET_TITLES``: ``snippet_titles`` - - -* specific project scope: - - + ``gitlab.SEARCH_SCOPE_PROJECT_NOTES``: ``notes`` - - -Reference ---------- - -* v4 API: - - + :attr:`gitlab.Gitlab.search` - + :attr:`gitlab.v4.objects.Group.search` - + :attr:`gitlab.v4.objects.Project.search` - -* GitLab API: https://docs.gitlab.com/ce/api/search.html - -Examples --------- - -Search for issues matching a specific string:: - - # global search - gl.search(gitlab.SEARCH_SCOPE_ISSUES, 'regression') - - # group search - group = gl.groups.get('mygroup') - group.search(gitlab.SEARCH_SCOPE_ISSUES, 'regression') - - # project search - project = gl.projects.get('myproject') - project.search(gitlab.SEARCH_SCOPE_ISSUES, 'regression') - -The ``search()`` methods implement the pagination support:: - - # get lists of 10 items, and start at page 2 - gl.search(gitlab.SEARCH_SCOPE_ISSUES, search_str, page=2, per_page=10) - - # get a generator that will automatically make required API calls for - # pagination - for item in gl.search(gitlab.SEARCH_SCOPE_ISSUES, search_str, as_list=False): - do_something(item) - -The search API doesn't return objects, but dicts. If you need to act on -objects, you need to create them explicitly:: - - for item in gl.search(gitlab.SEARCH_SCOPE_ISSUES, search_str, as_list=False): - issue_project = gl.projects.get(item['project_id'], lazy=True) - issue = issue_project.issues.get(item['iid']) - issue.state = 'closed' - issue.save() - diff --git a/docs/gl_objects/settings.rst b/docs/gl_objects/settings.rst deleted file mode 100644 index 4accfe0..0000000 --- a/docs/gl_objects/settings.rst +++ /dev/null @@ -1,26 +0,0 @@ -######## -Settings -######## - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ApplicationSettings` - + :class:`gitlab.v4.objects.ApplicationSettingsManager` - + :attr:`gitlab.Gitlab.settings` - -* GitLab API: https://docs.gitlab.com/ce/api/settings.html - -Examples --------- - -Get the settings:: - - settings = gl.settings.get() - -Update the settings:: - - settings.signin_enabled = False - settings.save() diff --git a/docs/gl_objects/sidekiq.rst b/docs/gl_objects/sidekiq.rst deleted file mode 100644 index 5f44762..0000000 --- a/docs/gl_objects/sidekiq.rst +++ /dev/null @@ -1,23 +0,0 @@ -############### -Sidekiq metrics -############### - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.SidekiqManager` - + :attr:`gitlab.Gitlab.sidekiq` - -* GitLab API: https://docs.gitlab.com/ce/api/sidekiq_metrics.html - -Examples --------- - -.. code-block:: python - - gl.sidekiq.queue_metrics() - gl.sidekiq.process_metrics() - gl.sidekiq.job_stats() - gl.sidekiq.compound_metrics() diff --git a/docs/gl_objects/snippets.rst b/docs/gl_objects/snippets.rst deleted file mode 100644 index 1bedb07..0000000 --- a/docs/gl_objects/snippets.rst +++ /dev/null @@ -1,66 +0,0 @@ -######## -Snippets -######## - -Reference -========= - -* v4 API: - - + :class:`gitlab.v4.objects.Snippet` - + :class:`gitlab.v4.objects.SnipptManager` - + :attr:`gitlab.Gitlab.snippets` - -* GitLab API: https://docs.gitlab.com/ce/api/snippets.html - -Examples -======== - -List snippets owned by the current user:: - - snippets = gl.snippets.list() - -List the public snippets:: - - public_snippets = gl.snippets.public() - -Get a snippet:: - - snippet = gl.snippets.get(snippet_id) - # get the content - content = snippet.content() - -.. warning:: - - Blobs are entirely stored in memory unless you use the streaming feature. - See :ref:`the artifacts example <streaming_example>`. - - -Create a snippet:: - - snippet = gl.snippets.create({'title': 'snippet1', - 'file_name': 'snippet1.py', - 'content': open('snippet1.py').read()}) - -Update the snippet attributes:: - - snippet.visibility_level = gitlab.VISIBILITY_PUBLIC - snippet.save() - -To update a snippet code you need to create a ``ProjectSnippet`` object:: - - snippet = gl.snippets.get(snippet_id) - project = gl.projects.get(snippet.projec_id, lazy=True) - editable_snippet = project.snippets.get(snippet.id) - editable_snippet.code = new_snippet_content - editable_snippet.save() - -Delete a snippet:: - - gl.snippets.delete(snippet_id) - # or - snippet.delete() - -Get user agent detail (admin only):: - - detail = snippet.user_agent_detail() diff --git a/docs/gl_objects/system_hooks.rst b/docs/gl_objects/system_hooks.rst deleted file mode 100644 index 6203168..0000000 --- a/docs/gl_objects/system_hooks.rst +++ /dev/null @@ -1,35 +0,0 @@ -############ -System hooks -############ - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Hook` - + :class:`gitlab.v4.objects.HookManager` - + :attr:`gitlab.Gitlab.hooks` - -* GitLab API: https://docs.gitlab.com/ce/api/system_hooks.html - -Examples --------- - -List the system hooks:: - - hooks = gl.hooks.list() - -Create a system hook:: - - gl.hooks.get(hook_id) - -Test a system hook. The returned object is not usable (it misses the hook ID):: - - hook = gl.hooks.create({'url': 'http://your.target.url'}) - -Delete a system hook:: - - gl.hooks.delete(hook_id) - # or - hook.delete() diff --git a/docs/gl_objects/templates.rst b/docs/gl_objects/templates.rst deleted file mode 100644 index f939e5f..0000000 --- a/docs/gl_objects/templates.rst +++ /dev/null @@ -1,114 +0,0 @@ -######### -Templates -######### - -You can request templates for different type of files: - -* License files -* .gitignore files -* GitLab CI configuration files -* Dockerfiles - -License templates -================= - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.License` - + :class:`gitlab.v4.objects.LicenseManager` - + :attr:`gitlab.Gitlab.licenses` - -* GitLab API: https://docs.gitlab.com/ce/api/templates/licenses.html - -Examples --------- - -List known license templates:: - - licenses = gl.licenses.list() - -Generate a license content for a project:: - - license = gl.licenses.get('apache-2.0', project='foobar', fullname='John Doe') - print(license.content) - -.gitignore templates -==================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Gitignore` - + :class:`gitlab.v4.objects.GitignoreManager` - + :attr:`gitlab.Gitlab.gitignores` - -* GitLab API: https://docs.gitlab.com/ce/api/templates/gitignores.html - -Examples --------- - -List known gitignore templates:: - - gitignores = gl.gitignores.list() - -Get a gitignore template:: - - gitignore = gl.gitignores.get('Python') - print(gitignore.content) - -GitLab CI templates -=================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Gitlabciyml` - + :class:`gitlab.v4.objects.GitlabciymlManager` - + :attr:`gitlab.Gitlab.gitlabciymls` - -* GitLab API: https://docs.gitlab.com/ce/api/templates/gitlab_ci_ymls.html - -Examples --------- - -List known GitLab CI templates:: - - gitlabciymls = gl.gitlabciymls.list() - -Get a GitLab CI template:: - - gitlabciyml = gl.gitlabciymls.get('Pelican') - print(gitlabciyml.content) - -Dockerfile templates -==================== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.Dockerfile` - + :class:`gitlab.v4.objects.DockerfileManager` - + :attr:`gitlab.Gitlab.gitlabciymls` - -* GitLab API: Not documented. - -Examples --------- - -List known Dockerfile templates:: - - dockerfiles = gl.dockerfiles.list() - -Get a Dockerfile template:: - - dockerfile = gl.dockerfiles.get('Python') - print(dockerfile.content) diff --git a/docs/gl_objects/todos.rst b/docs/gl_objects/todos.rst deleted file mode 100644 index 24a14c2..0000000 --- a/docs/gl_objects/todos.rst +++ /dev/null @@ -1,44 +0,0 @@ -##### -Todos -##### - -Reference ---------- - -* v4 API: - - + :class:`~gitlab.objects.Todo` - + :class:`~gitlab.objects.TodoManager` - + :attr:`gitlab.Gitlab.todos` - -* GitLab API: https://docs.gitlab.com/ce/api/todos.html - -Examples --------- - -List active todos:: - - todos = gl.todos.list() - -You can filter the list using the following parameters: - -* ``action``: can be ``assigned``, ``mentioned``, ``build_failed``, ``marked``, - or ``approval_required`` -* ``author_id`` -* ``project_id`` -* ``state``: can be ``pending`` or ``done`` -* ``type``: can be ``Issue`` or ``MergeRequest`` - -For example:: - - todos = gl.todos.list(project_id=1) - todos = gl.todos.list(state='done', type='Issue') - -Mark a todo as done:: - - todos = gl.todos.list(project_id=1) - todos[0].mark_as_done() - -Mark all the todos as done:: - - gl.todos.mark_all_as_done() diff --git a/docs/gl_objects/users.rst b/docs/gl_objects/users.rst deleted file mode 100644 index dd6db6a..0000000 --- a/docs/gl_objects/users.rst +++ /dev/null @@ -1,404 +0,0 @@ -###################### -Users and current user -###################### - -The Gitlab API exposes user-related method that can be manipulated by admins -only. - -The currently logged-in user is also exposed. - -Users -===== - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.User` - + :class:`gitlab.v4.objects.UserManager` - + :attr:`gitlab.Gitlab.users` - -* GitLab API: https://docs.gitlab.com/ce/api/users.html - -Examples --------- - -Get the list of users:: - - users = gl.users.list() - -Search users whose username match a given string:: - - users = gl.users.list(search='foo') - -Get a single user:: - - # by ID - user = gl.users.get(user_id) - # by username - user = gl.users.list(username='root')[0] - -Create a user:: - - user = gl.users.create({'email': 'john@doe.com', - 'password': 's3cur3s3cr3T', - 'username': 'jdoe', - 'name': 'John Doe'}) - -Update a user:: - - user.name = 'Real Name' - user.save() - -Delete a user:: - - gl.users.delete(user_id) - # or - user.delete() - -Block/Unblock a user:: - - user.block() - user.unblock() - -Activate/Deactivate a user:: - - user.activate() - user.deactivate() - -Follow/Unfollow a user:: - - user.follow() - user.unfollow() - -Set the avatar image for a user:: - - # the avatar image can be passed as data (content of the file) or as a file - # object opened in binary mode - user.avatar = open('path/to/file.png', 'rb') - user.save() - -Set an external identity for a user:: - - user.provider = 'oauth2_generic' - user.extern_uid = '3' - user.save() - -Delete an external identity by provider name:: - - user.identityproviders.delete('oauth2_generic') - -Get the followers of a user - - user.followers_users.list() - -Get the followings of a user - - user.following_users.list() - - -User custom attributes -====================== - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.UserCustomAttribute` - + :class:`gitlab.v4.objects.UserCustomAttributeManager` - + :attr:`gitlab.v4.objects.User.customattributes` - -* GitLab API: https://docs.gitlab.com/ce/api/custom_attributes.html - -Examples --------- - -List custom attributes for a user:: - - attrs = user.customattributes.list() - -Get a custom attribute for a user:: - - attr = user.customattributes.get(attr_key) - -Set (create or update) a custom attribute for a user:: - - attr = user.customattributes.set(attr_key, attr_value) - -Delete a custom attribute for a user:: - - attr.delete() - # or - user.customattributes.delete(attr_key) - -Search users by custom attribute:: - - user.customattributes.set('role', 'QA') - gl.users.list(custom_attributes={'role': 'QA'}) - -User impersonation tokens -========================= - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.UserImpersonationToken` - + :class:`gitlab.v4.objects.UserImpersonationTokenManager` - + :attr:`gitlab.v4.objects.User.impersonationtokens` - -* GitLab API: https://docs.gitlab.com/ce/api/users.html#get-all-impersonation-tokens-of-a-user - -List impersonation tokens for a user:: - - i_t = user.impersonationtokens.list(state='active') - i_t = user.impersonationtokens.list(state='inactive') - -Get an impersonation token for a user:: - - i_t = user.impersonationtokens.get(i_t_id) - -Create and use an impersonation token for a user:: - - i_t = user.impersonationtokens.create({'name': 'token1', 'scopes': ['api']}) - # use the token to create a new gitlab connection - user_gl = gitlab.Gitlab(gitlab_url, private_token=i_t.token) - -Revoke (delete) an impersonation token for a user:: - - i_t.delete() - - -User memberships -========================= - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.UserMembership` - + :class:`gitlab.v4.objects.UserMembershipManager` - + :attr:`gitlab.v4.objects.User.memberships` - -* GitLab API: https://docs.gitlab.com/ee/api/users.html#user-memberships-admin-only - -List direct memberships for a user:: - - memberships = user.memberships.list() - -List only direct project memberships:: - - memberships = user.memberships.list(type='Project') - -List only direct group memberships:: - - memberships = user.memberships.list(type='Namespace') - -Current User -============ - -References ----------- - -* v4 API: - - + :class:`gitlab.v4.objects.CurrentUser` - + :class:`gitlab.v4.objects.CurrentUserManager` - + :attr:`gitlab.Gitlab.user` - -* GitLab API: https://docs.gitlab.com/ce/api/users.html - -Examples --------- - -Get the current user:: - - gl.auth() - current_user = gl.user - -GPG keys -======== - -References ----------- - -You can manipulate GPG keys for the current user and for the other users if you -are admin. - -* v4 API: - - + :class:`gitlab.v4.objects.CurrentUserGPGKey` - + :class:`gitlab.v4.objects.CurrentUserGPGKeyManager` - + :attr:`gitlab.v4.objects.CurrentUser.gpgkeys` - + :class:`gitlab.v4.objects.UserGPGKey` - + :class:`gitlab.v4.objects.UserGPGKeyManager` - + :attr:`gitlab.v4.objects.User.gpgkeys` - -* GitLab API: https://docs.gitlab.com/ce/api/users.html#list-all-gpg-keys - -Examples --------- - -List GPG keys for a user:: - - gpgkeys = user.gpgkeys.list() - -Get a GPG gpgkey for a user:: - - gpgkey = user.gpgkeys.get(key_id) - -Create a GPG gpgkey for a user:: - - # get the key with `gpg --export -a GPG_KEY_ID` - k = user.gpgkeys.create({'key': public_key_content}) - -Delete a GPG gpgkey for a user:: - - user.gpgkeys.delete(key_id) - # or - gpgkey.delete() - -SSH keys -======== - -References ----------- - -You can manipulate SSH keys for the current user and for the other users if you -are admin. - -* v4 API: - - + :class:`gitlab.v4.objects.CurrentUserKey` - + :class:`gitlab.v4.objects.CurrentUserKeyManager` - + :attr:`gitlab.v4.objects.CurrentUser.keys` - + :class:`gitlab.v4.objects.UserKey` - + :class:`gitlab.v4.objects.UserKeyManager` - + :attr:`gitlab.v4.objects.User.keys` - -* GitLab API: https://docs.gitlab.com/ce/api/users.html#list-ssh-keys - -Examples --------- - -List SSH keys for a user:: - - keys = user.keys.list() - -Create an SSH key for a user:: - - k = user.keys.create({'title': 'my_key', - 'key': open('/home/me/.ssh/id_rsa.pub').read()}) - -Delete an SSH key for a user:: - - user.keys.delete(key_id) - # or - key.delete() - -Status -====== - -References ----------- - -You can manipulate the status for the current user and you can read the status of other users. - -* v4 API: - - + :class:`gitlab.v4.objects.CurrentUserStatus` - + :class:`gitlab.v4.objects.CurrentUserStatusManager` - + :attr:`gitlab.v4.objects.CurrentUser.status` - + :class:`gitlab.v4.objects.UserStatus` - + :class:`gitlab.v4.objects.UserStatusManager` - + :attr:`gitlab.v4.objects.User.status` - -* GitLab API: https://docs.gitlab.com/ce/api/users.html#user-status - -Examples --------- - -Get current user status:: - - status = user.status.get() - -Update the status for the current user:: - - status = user.status.get() - status.message = "message" - status.emoji = "thumbsup" - status.save() - -Get the status of other users:: - - gl.users.get(1).status.get() - -Emails -====== - -References ----------- - -You can manipulate emails for the current user and for the other users if you -are admin. - -* v4 API: - - + :class:`gitlab.v4.objects.CurrentUserEmail` - + :class:`gitlab.v4.objects.CurrentUserEmailManager` - + :attr:`gitlab.v4.objects.CurrentUser.emails` - + :class:`gitlab.v4.objects.UserEmail` - + :class:`gitlab.v4.objects.UserEmailManager` - + :attr:`gitlab.v4.objects.User.emails` - -* GitLab API: https://docs.gitlab.com/ce/api/users.html#list-emails - -Examples --------- - -List emails for a user:: - - emails = user.emails.list() - -Get an email for a user:: - - email = user.emails.get(email_id) - -Create an email for a user:: - - k = user.emails.create({'email': 'foo@bar.com'}) - -Delete an email for a user:: - - user.emails.delete(email_id) - # or - email.delete() - -Users activities -================ - -References ----------- - -* admin only - -* v4 API: - - + :class:`gitlab.v4.objects.UserActivities` - + :class:`gitlab.v4.objects.UserActivitiesManager` - + :attr:`gitlab.Gitlab.user_activities` - -* GitLab API: https://docs.gitlab.com/ce/api/users.html#get-user-activities-admin-only - -Examples --------- - -Get the users activities:: - - activities = gl.user_activities.list( - query_parameters={'from': '2018-07-01'}, - all=True, as_list=False) diff --git a/docs/gl_objects/variables.rst b/docs/gl_objects/variables.rst deleted file mode 100644 index f679925..0000000 --- a/docs/gl_objects/variables.rst +++ /dev/null @@ -1,104 +0,0 @@ -############### -CI/CD Variables -############### - -You can configure variables at the instance-level (admin only), or associate -variables to projects and groups, to modify pipeline/job scripts behavior. - - -Instance-level variables -======================== - -This endpoint requires admin access. - -Reference ---------- - -* v4 API - - + :class:`gitlab.v4.objects.Variable` - + :class:`gitlab.v4.objects.VariableManager` - + :attr:`gitlab.Gitlab.variables` - -* GitLab API - - + https://docs.gitlab.com/ce/api/instance_level_ci_variables.html - -Examples --------- - -List all instance variables:: - - variables = gl.variables.list() - -Get an instance variable by key:: - - variable = gl.variables.get('key_name') - -Create an instance variable:: - - variable = gl.variables.create({'key': 'key1', 'value': 'value1'}) - -Update a variable value:: - - variable.value = 'new_value' - variable.save() - -Remove a variable:: - - gl.variables.delete('key_name') - # or - variable.delete() - -Projects and groups variables -============================= - -Reference ---------- - -* v4 API - - + :class:`gitlab.v4.objects.ProjectVariable` - + :class:`gitlab.v4.objects.ProjectVariableManager` - + :attr:`gitlab.v4.objects.Project.variables` - + :class:`gitlab.v4.objects.GroupVariable` - + :class:`gitlab.v4.objects.GroupVariableManager` - + :attr:`gitlab.v4.objects.Group.variables` - -* GitLab API - - + https://docs.gitlab.com/ce/api/instance_level_ci_variables.html - + https://docs.gitlab.com/ce/api/project_level_variables.html - + https://docs.gitlab.com/ce/api/group_level_variables.html - -Examples --------- - -List variables:: - - p_variables = project.variables.list() - g_variables = group.variables.list() - -Get a variable:: - - p_var = project.variables.get('key_name') - g_var = group.variables.get('key_name') - -Create a variable:: - - var = project.variables.create({'key': 'key1', 'value': 'value1'}) - var = group.variables.create({'key': 'key1', 'value': 'value1'}) - -Update a variable value:: - - var.value = 'new_value' - var.save() - # or - project.variables.update("key1", {"value": "new_value"}) - -Remove a variable:: - - project.variables.delete('key_name') - group.variables.delete('key_name') - # or - var.delete() diff --git a/docs/gl_objects/wikis.rst b/docs/gl_objects/wikis.rst deleted file mode 100644 index e98b9d4..0000000 --- a/docs/gl_objects/wikis.rst +++ /dev/null @@ -1,56 +0,0 @@ -########## -Wiki pages -########## - - -References -========== - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectWiki` - + :class:`gitlab.v4.objects.ProjectWikiManager` - + :attr:`gitlab.v4.objects.Project.wikis` - + :class:`gitlab.v4.objects.GroupWiki` - + :class:`gitlab.v4.objects.GroupWikiManager` - + :attr:`gitlab.v4.objects.Group.wikis` - -* GitLab API for Projects: https://docs.gitlab.com/ce/api/wikis.html -* GitLab API for Groups: https://docs.gitlab.com/ee/api/group_wikis.html - -Examples --------- - -Get the list of wiki pages for a project. These do not contain the contents of the wiki page. You will need to call get(slug) to retrieve the content by accessing the content attribute:: - - pages = project.wikis.list() - -Get the list of wiki pages for a group. These do not contain the contents of the wiki page. You will need to call get(slug) to retrieve the content by accessing the content attribute:: - - pages = group.wikis.list() - -Get a single wiki page for a project:: - - page = project.wikis.get(page_slug) - -Get a single wiki page for a group:: - - page = group.wikis.get(page_slug) - -Get the contents of a wiki page:: - - print(page.content) - -Create a wiki page on a project level:: - - page = project.wikis.create({'title': 'Wiki Page 1', - 'content': open(a_file).read()}) - -Update a wiki page:: - - page.content = 'My new content' - page.save() - -Delete a wiki page:: - - page.delete() |