feat(api): add support for Gitlab Deploy Token API

ayoub mrini · ayoub mrini · commit 7703743fa80c · 2020-03-21T20:39:22.000+01:00
diff --git a/docs/gl_objects/deploy_tokens.rst b/docs/gl_objects/deploy_tokens.rst
@@ -0,0 +1,120 @@
+#######
+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']})
+    # 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)
+
+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']})
+    # show its id
+    print(deploy_token.id)
+
+Remove a deploy token from the group::
+
+    deploy_token.delete()
+    # or
+    group.deploytokens.delete(deploy_token.id)
+
diff --git a/gitlab/__init__.py b/gitlab/__init__.py
@@ -119,6 +119,7 @@ def __init__(
 
         self.broadcastmessages = objects.BroadcastMessageManager(self)
         self.deploykeys = objects.DeployKeyManager(self)
+        self.deploytokens = objects.DeployTokenManager(self)
         self.geonodes = objects.GeoNodeManager(self)
         self.gitlabciymls = objects.GitlabciymlManager(self)
         self.gitignores = objects.GitignoreManager(self)
diff --git a/gitlab/tests/test_gitlab.py b/gitlab/tests/test_gitlab.py
@@ -964,6 +964,40 @@ def resp_application_create(url, request):
             self.assertEqual(application.redirect_uri, "http://localhost:8080")
             self.assertEqual(application.scopes, ["api", "email"])
 
+    def test_deploy_tokens(self):
+        @urlmatch(
+            scheme="http",
+            netloc="localhost",
+            path="/api/v4/projects/1/deploy_tokens",
+            method="post",
+        )
+        def resp_deploy_token_create(url, request):
+            headers = {"content-type": "application/json"}
+            content = """{
+            "id": 1,
+            "name": "test_deploy_token",
+            "username": "custom-user",
+            "expires_at": "2022-01-01T00:00:00.000Z",
+            "token": "jMRvtPNxrn3crTAGukpZ",
+            "scopes": [ "read_repository" ]}"""
+            content = content.encode("utf-8")
+            return response(200, content, headers, None, 5, request)
+
+        with HTTMock(resp_deploy_token_create):
+            deploy_token = self.gl.projects.get(1, lazy=True).deploytokens.create(
+                {
+                    "name": "test_deploy_token",
+                    "expires_at": "2022-01-01T00:00:00.000Z",
+                    "username": "custom-user",
+                    "scopes": ["read_repository"],
+                }
+            )
+            self.assertIsInstance(deploy_token, ProjectDeployToken)
+            self.assertEqual(deploy_token.id, 1),
+            self.assertEqual(deploy_token.expires_at, "2022-01-01T00:00:00.000Z"),
+            self.assertEqual(deploy_token.username, "custom-user")
+            self.assertEqual(deploy_token.scopes, ["read_repository"])
+
     def _default_config(self):
         fd, temp_path = tempfile.mkstemp()
         os.write(fd, valid_config)
diff --git a/gitlab/v4/objects.py b/gitlab/v4/objects.py
@@ -695,6 +695,43 @@ class DeployKeyManager(ListMixin, RESTManager):
     _obj_cls = DeployKey
 
 
+class DeployToken(ObjectDeleteMixin, RESTObject):
+    pass
+
+
+class DeployTokenManager(ListMixin, RESTManager):
+    _path = "/deploy_tokens"
+    _obj_cls = DeployToken
+
+
+class ProjectDeployToken(ObjectDeleteMixin, RESTObject):
+    pass
+
+
+class ProjectDeployTokenManager(ListMixin, CreateMixin, DeleteMixin, RESTManager):
+    _path = "/projects/%(project_id)s/deploy_tokens"
+    _from_parent_attrs = {"project_id": "id"}
+    _obj_cls = ProjectDeployToken
+    _create_attrs = (
+        ("name", "scopes",),
+        ("expires_at", "username",),
+    )
+
+
+class GroupDeployToken(ObjectDeleteMixin, RESTObject):
+    pass
+
+
+class GroupDeployTokenManager(ListMixin, CreateMixin, DeleteMixin, RESTManager):
+    _path = "/groups/%(group_id)s/deploy_tokens"
+    _from_parent_attrs = {"group_id": "id"}
+    _obj_cls = GroupDeployToken
+    _create_attrs = (
+        ("name", "scopes",),
+        ("expires_at", "username",),
+    )
+
+
 class NotificationSettings(SaveMixin, RESTObject):
     _id_attr = None
 
@@ -1301,6 +1338,7 @@ class Group(SaveMixin, ObjectDeleteMixin, RESTObject):
         ("subgroups", "GroupSubgroupManager"),
         ("variables", "GroupVariableManager"),
         ("clusters", "GroupClusterManager"),
+        ("deploytokens", "GroupDeployTokenManager"),
     )
 
     @cli.register_custom_action("Group", ("to_project_id",))
@@ -4194,6 +4232,7 @@ class Project(SaveMixin, ObjectDeleteMixin, RESTObject):
         ("clusters", "ProjectClusterManager"),
         ("additionalstatistics", "ProjectAdditionalStatisticsManager"),
         ("issuesstatistics", "ProjectIssuesStatisticsManager"),
+        ("deploytokens", "ProjectDeployTokenManager"),
     )
 
     @cli.register_custom_action("Project", ("submodule", "branch", "commit_sha"))
diff --git a/tools/python_test_v4.py b/tools/python_test_v4.py
@@ -617,6 +617,21 @@
 sudo_project.keys.delete(deploy_key.id)
 assert len(sudo_project.keys.list()) == 0
 
+# deploy tokens
+deploy_token = admin_project.deploytokens.create(
+    {
+        "name": "foo",
+        "username": "bar",
+        "expires_at": "2021-09-09",
+        "scopes": ["read_registry"],
+    }
+)
+assert len(admin_project.deploytokens.list()) == 1
+assert gl.deploytokens.list() == admin_project.deploytokens.list()
+
+deploy_token.delete()
+assert len(admin_project.deploytokens.list()) == 0
+
 # labels
 # label1 = admin_project.labels.create({"name": "label1", "color": "#778899"})
 # label1 = admin_project.labels.list()[0]
