feat: add support for deployment approval endpoint

Add support for the deployment approval endpoint[1]

[1] https://docs.gitlab.com/ee/api/deployments.html#approve-or-reject-a-blocked-deployment
Closes: #2253

2 files changed, 55 insertions, 1 deletions

diff --git a/gitlab/exceptions.py b/gitlab/exceptions.py
index 01439e4..633de5b 100644
--- a/gitlab/exceptions.py
+++ b/gitlab/exceptions.py
@@ -301,6 +301,10 @@ class GitlabUserRejectError(GitlabOperationError):
     pass
 
 
+class GitlabDeploymentApprovalError(GitlabOperationError):
+    pass
+
+
 # For an explanation of how these type-hints work see:
 # https://mypy.readthedocs.io/en/stable/generics.html#declaring-decorators
 #
diff --git a/gitlab/v4/objects/deployments.py b/gitlab/v4/objects/deployments.py
index a431603..145273b 100644
--- a/gitlab/v4/objects/deployments.py
+++ b/gitlab/v4/objects/deployments.py
@@ -1,5 +1,11 @@
-from typing import Any, cast, Union
+"""
+GitLab API:
+https://docs.gitlab.com/ee/api/deployments.html
+"""
+from typing import Any, cast, Dict, Optional, TYPE_CHECKING, Union
 
+from gitlab import cli
+from gitlab import exceptions as exc
 from gitlab.base import RESTManager, RESTObject
 from gitlab.mixins import CreateMixin, RetrieveMixin, SaveMixin, UpdateMixin
 from gitlab.types import RequiredOptional
@@ -15,6 +21,50 @@ __all__ = [
 class ProjectDeployment(SaveMixin, RESTObject):
     mergerequests: ProjectDeploymentMergeRequestManager
 
+    @cli.register_custom_action(
+        "ProjectDeployment",
+        mandatory=("status",),
+        optional=("comment", "represented_as"),
+    )
+    @exc.on_http_error(exc.GitlabDeploymentApprovalError)
+    def approval(
+        self,
+        status: str,
+        comment: Optional[str] = None,
+        represented_as: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        """Approve or reject a blocked deployment.
+
+        Args:
+            status: Either "approved" or "rejected"
+            comment: A comment to go with the approval
+            represented_as: The name of the User/Group/Role to use for the
+                            approval, when the user belongs to multiple
+                            approval rules.
+            **kwargs: Extra options to send to the server (e.g. sudo)
+
+        Raises:
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabMRApprovalError: If the approval failed
+
+        Returns:
+           A dict containing the result.
+
+        https://docs.gitlab.com/ee/api/deployments.html#approve-or-reject-a-blocked-deployment
+        """
+        path = f"{self.manager.path}/{self.encoded_id}/approval"
+        data = {"status": status}
+        if comment is not None:
+            data["comment"] = comment
+        if represented_as is not None:
+            data["represented_as"] = represented_as
+
+        server_data = self.manager.gitlab.http_post(path, post_data=data, **kwargs)
+        if TYPE_CHECKING:
+            assert isinstance(server_data, dict)
+        return server_data
+
 
 class ProjectDeploymentManager(RetrieveMixin, CreateMixin, UpdateMixin, RESTManager):
     _path = "/projects/{project_id}/deployments"