feat(api): add support for token self-rotation

Massimiliano Riva · JohnVillalovos · commit da40e0949827 · 2025-05-15T08:32:35.000-07:00
diff --git a/docs/gl_objects/group_access_tokens.rst b/docs/gl_objects/group_access_tokens.rst
@@ -46,3 +46,9 @@ Rotate a group access token and retrieve its new value::
     # or directly using a token ID
     new_token = group.access_tokens.rotate(42)
     print(new_token.token)
+
+Self-Rotate the group access token you are using to authenticate the request and retrieve its new value::
+
+    token = group.access_tokens.get(42, lazy=True)
+    token.rotate(self_rotate=True)
+    print(token.token)
diff --git a/docs/gl_objects/personal_access_tokens.rst b/docs/gl_objects/personal_access_tokens.rst
@@ -61,6 +61,12 @@ Rotate a personal access token and retrieve its new value::
     new_token_dict = gl.personal_access_tokens.rotate(42)
     print(new_token_dict)
 
+Self-Rotate the personal access token you are using to authenticate the request and retrieve its new value::
+
+    token = gl.personal_access_tokens.get(42, lazy=True)
+    token.rotate(self_rotate=True)
+    print(token.token)
+
 Create a personal access token for a user (admin only)::
 
     user = gl.users.get(25, lazy=True)
diff --git a/docs/gl_objects/project_access_tokens.rst b/docs/gl_objects/project_access_tokens.rst
@@ -46,3 +46,9 @@ Rotate a project access token and retrieve its new value::
     # or directly using a token ID
     new_token = project.access_tokens.rotate(42)
     print(new_token.token)
+
+Self-Rotate the project access token you are using to authenticate the request and retrieve its new value::
+
+    token = project.access_tokens.get(42, lazy=True)
+    token.rotate(self_rotate=True)
+    print(new_token.token)
diff --git a/gitlab/mixins.py b/gitlab/mixins.py
@@ -660,10 +660,11 @@ class ObjectRotateMixin(_RestObjectBase):
         optional=("expires_at",),
     )
     @exc.on_http_error(exc.GitlabRotateError)
-    def rotate(self, **kwargs: Any) -> dict[str, Any]:
+    def rotate(self, *, self_rotate: bool = False, **kwargs: Any) -> dict[str, Any]:
         """Rotate the current access token object.
 
         Args:
+            self_rotate: If True, the current access token object will be rotated.
             **kwargs: Extra options to send to the server (e.g. sudo)
 
         Raises:
@@ -673,7 +674,8 @@ def rotate(self, **kwargs: Any) -> dict[str, Any]:
         if TYPE_CHECKING:
             assert isinstance(self.manager, RotateMixin)
             assert self.encoded_id is not None
-        server_data = self.manager.rotate(self.encoded_id, **kwargs)
+        token_id = "self" if self_rotate else self.encoded_id
+        server_data = self.manager.rotate(token_id, **kwargs)
         self._update_attrs(server_data)
         return server_data
 
diff --git a/tests/unit/objects/test_group_access_tokens.py b/tests/unit/objects/test_group_access_tokens.py
@@ -91,6 +91,19 @@ def resp_rotate_group_access_token(token_content):
         yield rsps
 
 
+@pytest.fixture
+def resp_self_rotate_group_access_token(token_content):
+    with responses.RequestsMock() as rsps:
+        rsps.add(
+            method=responses.POST,
+            url="http://localhost/api/v4/groups/1/access_tokens/self/rotate",
+            json=token_content,
+            content_type="application/json",
+            status=200,
+        )
+        yield rsps
+
+
 def test_list_group_access_tokens(gl, resp_list_group_access_token):
     access_tokens = gl.groups.get(1, lazy=True).access_tokens.list()
     assert len(access_tokens) == 1
@@ -127,3 +140,15 @@ def test_rotate_group_access_token(group, resp_rotate_group_access_token):
     access_token.rotate()
     assert isinstance(access_token, GroupAccessToken)
     assert access_token.token == "s3cr3t"
+
+
+def test_self_rotate_group_access_token(group, resp_self_rotate_group_access_token):
+    access_token = group.access_tokens.get(1, lazy=True)
+    access_token.rotate(self_rotate=True)
+    assert isinstance(access_token, GroupAccessToken)
+    assert access_token.token == "s3cr3t"
+
+    # Verify that the url contains "self"
+    rotation_calls = resp_self_rotate_group_access_token.calls
+    assert len(rotation_calls) == 1
+    assert "self/rotate" in rotation_calls[0].request.url
diff --git a/tests/unit/objects/test_personal_access_tokens.py b/tests/unit/objects/test_personal_access_tokens.py
@@ -102,6 +102,19 @@ def resp_rotate_personal_access_token(token_content):
         yield rsps
 
 
+@pytest.fixture
+def resp_self_rotate_personal_access_token(token_content):
+    with responses.RequestsMock() as rsps:
+        rsps.add(
+            method=responses.POST,
+            url="http://localhost/api/v4/personal_access_tokens/self/rotate",
+            json=token_content,
+            content_type="application/json",
+            status=200,
+        )
+        yield rsps
+
+
 def test_create_personal_access_token(gl, resp_create_user_personal_access_token):
     user = gl.users.get(1, lazy=True)
     access_token = user.personal_access_tokens.create(
@@ -148,8 +161,20 @@ def test_revoke_personal_access_token_by_id(gl, resp_delete_personal_access_toke
     gl.personal_access_tokens.delete(token_id)
 
 
-def test_rotate_project_access_token(gl, resp_rotate_personal_access_token):
+def test_rotate_personal_access_token(gl, resp_rotate_personal_access_token):
     access_token = gl.personal_access_tokens.get(1, lazy=True)
     access_token.rotate()
     assert isinstance(access_token, PersonalAccessToken)
     assert access_token.token == "s3cr3t"
+
+
+def test_self_rotate_personal_access_token(gl, resp_self_rotate_personal_access_token):
+    access_token = gl.personal_access_tokens.get(1, lazy=True)
+    access_token.rotate(self_rotate=True)
+    assert isinstance(access_token, PersonalAccessToken)
+    assert access_token.token == "s3cr3t"
+
+    # Verify that the url contains "self"
+    rotation_calls = resp_self_rotate_personal_access_token.calls
+    assert len(rotation_calls) == 1
+    assert "self/rotate" in rotation_calls[0].request.url
diff --git a/tests/unit/objects/test_project_access_tokens.py b/tests/unit/objects/test_project_access_tokens.py
@@ -91,6 +91,19 @@ def resp_rotate_project_access_token(token_content):
         yield rsps
 
 
+@pytest.fixture
+def resp_self_rotate_project_access_token(token_content):
+    with responses.RequestsMock() as rsps:
+        rsps.add(
+            method=responses.POST,
+            url="http://localhost/api/v4/projects/1/access_tokens/self/rotate",
+            json=token_content,
+            content_type="application/json",
+            status=200,
+        )
+        yield rsps
+
+
 def test_list_project_access_tokens(gl, resp_list_project_access_token):
     access_tokens = gl.projects.get(1, lazy=True).access_tokens.list()
     assert len(access_tokens) == 1
@@ -127,3 +140,17 @@ def test_rotate_project_access_token(project, resp_rotate_project_access_token):
     access_token.rotate()
     assert isinstance(access_token, ProjectAccessToken)
     assert access_token.token == "s3cr3t"
+
+
+def test_self_rotate_project_access_token(
+    project, resp_self_rotate_project_access_token
+):
+    access_token = project.access_tokens.get(1, lazy=True)
+    access_token.rotate(self_rotate=True)
+    assert isinstance(access_token, ProjectAccessToken)
+    assert access_token.token == "s3cr3t"
+
+    # Verify that the url contains "self"
+    rotation_calls = resp_self_rotate_project_access_token.calls
+    assert len(rotation_calls) == 1
+    assert "self/rotate" in rotation_calls[0].request.url
