feat(api): add support for job token scope settings

Author: nejch

docs/api-objects.rst

@@ -29,6 +29,7 @@ API examples
    gl_objects/invitations
    gl_objects/issues
    gl_objects/iterations
+   gl_objects/job_token_scope
    gl_objects/keys
    gl_objects/boards
    gl_objects/labels

docs/gl_objects/job_token_scope.rst

@@ -0,0 +1,51 @@
+#####################
+CI/CD job token scope
+#####################
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectJobTokenScope`
+  + :class:`gitlab.v4.objects.ProjectJobTokenScopeManager`
+  + :attr:`gitlab.v4.objects.Project.job_token_scope`
+
+* GitLab API: https://docs.gitlab.com/ee/api/project_job_token_scopes.html
+
+Examples
+--------
+
+.. warning::
+
+   The GitLab API does **not** return any data when saving or updating
+   the job token scope settings. You need to call ``refresh()`` (or ``get()``
+   a new object) as shown below to get the latest state.
+
+Get a project's CI/CD job token access settings::
+
+    scope = project.job_token_scope.get()
+    print(scope.inbound_enabled)
+    # True
+
+Update the job token scope settings::
+
+    scope.enabled = False
+    scope.save()
+
+.. warning::
+
+   As you can see above, the attributes you receive from and send to the GitLab API
+   are not consistent. GitLab returns `inbound_enabled` and `outbound_enabled`,
+   but expects `enabled`, which only refers to the inbound scope. This is important
+   when accessing and updating these attributes.
+
+Or update the job token scope settings directly::
+
+    project.job_token_scope.update(new_data={"enabled": True})
+
+Refresh the current state of job token scope::
+
+    scope.refresh()
+    print(scope.inbound_enabled)
+    # False

gitlab/mixins.py

@@ -309,6 +309,7 @@ def create(
 class UpdateMethod(enum.IntEnum):
     PUT = 1
     POST = 2
+    PATCH = 3
 
 
 class UpdateMixin(_RestManagerBase):
@@ -331,6 +332,9 @@ def _get_update_method(
         """
         if self._update_method is UpdateMethod.POST:
             http_method = self.gitlab.http_post
+        elif self._update_method is UpdateMethod.PATCH:
+            # only patch uses required kwargs, so our types are a bit misaligned
+            http_method = self.gitlab.http_patch  # type: ignore[assignment]
         else:
             http_method = self.gitlab.http_put
         return http_method

gitlab/v4/objects/__init__.py

@@ -32,6 +32,7 @@
 from .invitations import *
 from .issues import *
 from .iterations import *
+from .job_token_scope import *
 from .jobs import *
 from .keys import *
 from .labels import *

gitlab/v4/objects/job_token_scope.py

@@ -0,0 +1,29 @@
+from typing import Any, cast
+
+from gitlab.base import RESTManager, RESTObject
+from gitlab.mixins import (
+    GetWithoutIdMixin,
+    RefreshMixin,
+    SaveMixin,
+    UpdateMethod,
+    UpdateMixin,
+)
+
+__all__ = [
+    "ProjectJobTokenScope",
+    "ProjectJobTokenScopeManager",
+]
+
+
+class ProjectJobTokenScope(RefreshMixin, SaveMixin, RESTObject):
+    _id_attr = None
+
+
+class ProjectJobTokenScopeManager(GetWithoutIdMixin, UpdateMixin, RESTManager):
+    _path = "/projects/{project_id}/job_token_scope"
+    _obj_cls = ProjectJobTokenScope
+    _from_parent_attrs = {"project_id": "id"}
+    _update_method = UpdateMethod.PATCH
+
+    def get(self, **kwargs: Any) -> ProjectJobTokenScope:
+        return cast(ProjectJobTokenScope, super().get(**kwargs))

gitlab/v4/objects/projects.py

@@ -59,6 +59,7 @@
 from .invitations import ProjectInvitationManager  # noqa: F401
 from .issues import ProjectIssueManager  # noqa: F401
 from .iterations import ProjectIterationManager  # noqa: F401
+from .job_token_scope import ProjectJobTokenScopeManager  # noqa: F401
 from .jobs import ProjectJobManager  # noqa: F401
 from .labels import ProjectLabelManager  # noqa: F401
 from .members import ProjectMemberAllManager, ProjectMemberManager  # noqa: F401
@@ -191,6 +192,7 @@ class Project(RefreshMixin, SaveMixin, ObjectDeleteMixin, RepositoryMixin, RESTO
     issues_statistics: ProjectIssuesStatisticsManager
     iterations: ProjectIterationManager
     jobs: ProjectJobManager
+    job_token_scope: ProjectJobTokenScopeManager
     keys: ProjectKeyManager
     labels: ProjectLabelManager
     members: ProjectMemberManager

tests/unit/objects/test_job_token_scope.py

@@ -0,0 +1,63 @@
+"""
+GitLab API: https://docs.gitlab.com/ee/api/project_job_token_scopes.html
+"""
+
+import pytest
+import responses
+
+from gitlab.v4.objects import ProjectJobTokenScope
+
+job_token_scope_content = {
+    "inbound_enabled": True,
+    "outbound_enabled": False,
+}
+
+
+@pytest.fixture
+def resp_get_job_token_scope():
+    with responses.RequestsMock(assert_all_requests_are_fired=False) as rsps:
+        rsps.add(
+            method=responses.GET,
+            url="http://localhost/api/v4/projects/1/job_token_scope",
+            json=job_token_scope_content,
+            content_type="application/json",
+            status=200,
+        )
+        yield rsps
+
+
+@pytest.fixture
+def resp_patch_job_token_scope():
+    with responses.RequestsMock(assert_all_requests_are_fired=False) as rsps:
+        rsps.add(
+            method=responses.PATCH,
+            url="http://localhost/api/v4/projects/1/job_token_scope",
+            status=204,
+            match=[responses.matchers.json_params_matcher({"enabled": False})],
+        )
+        yield rsps
+
+
+@pytest.fixture
+def job_token_scope(project, resp_get_job_token_scope):
+    return project.job_token_scope.get()
+
+
+def test_get_job_token_scope(project, resp_get_job_token_scope):
+    scope = project.job_token_scope.get()
+    assert isinstance(scope, ProjectJobTokenScope)
+    assert scope.inbound_enabled is True
+
+
+def test_refresh_job_token_scope(job_token_scope, resp_get_job_token_scope):
+    job_token_scope.refresh()
+    assert job_token_scope.inbound_enabled is True
+
+
+def test_save_job_token_scope(job_token_scope, resp_patch_job_token_scope):
+    job_token_scope.enabled = False
+    job_token_scope.save()
+
+
+def test_update_job_token_scope(project, resp_patch_job_token_scope):
+    project.job_token_scope.update(new_data={"enabled": False})