Add repository linking to Bamboo API

 atlassian-api#1240

Author: gonchik

atlassian/bamboo.py

@@ -249,6 +249,40 @@ def get_plan_specs(self, plan_key, package=None, format="YAML"):
             params["package"] = package
         return self.get(self.resource_url(f"plan/{plan_key}/specs"), params=params)
 
+    def search_linked_repositories(self, search_term=None):
+        """Search globally configured Bamboo linked repositories.
+
+        The public Bamboo REST API can search existing linked repositories but
+        does not create or update their connection configuration. Create those
+        connections in Bamboo administration, then use the returned repository
+        ID with :meth:`link_repository_to_project`.
+
+        :param search_term: Optional repository-name fragment.
+        :return: Bamboo's paged linked-repository response.
+        """
+        params = {}
+        if search_term is not None:
+            params["searchTerm"] = search_term
+        return self.get(self.resource_url("repository"), params=params)
+
+    def get_project_linked_repositories(self, project_key):
+        """Return linked repositories authorized for Bamboo Specs in a project."""
+        return self.get(self.resource_url(f"project/{project_key}/repository"))
+
+    def link_repository_to_project(self, project_key, repository_id):
+        """Authorize an existing linked repository for Bamboo Specs in a project.
+
+        This grants a repository-stored Bamboo Specs repository permission to
+        create or edit plans in ``project_key``. It does not change the
+        repositories checked out by an existing plan; update and apply that
+        plan's Bamboo Specs for plan-level repository changes.
+        """
+        return self.post(self.resource_url(f"project/{project_key}/repository"), data={"id": repository_id})
+
+    def unlink_repository_from_project(self, project_key, repository_id):
+        """Remove a project-level Bamboo Specs repository authorization."""
+        return self.delete(self.resource_url(f"project/{project_key}/repository/{repository_id}"))
+
     def search_plans(self, search_term, fuzzy=True, start_index=0, max_results=25):
         """
         Search plans by name

docs/bamboo.rst

@@ -60,6 +60,26 @@ Projects & Plans
     # Delete project
     delete_project(project_key)
 
+Linked repositories and Bamboo Specs
+------------------------------------
+
+Bamboo's public REST API can search existing global linked repositories and
+authorize one for a project’s Repository-Stored Bamboo Specs. It does not
+create a connection on the **Linked repositories** administration page, nor
+does it directly change the repositories checked out by an existing plan.
+Create the global connection in Bamboo administration; change plan repositories
+through that plan's Bamboo Specs and apply the Specs.
+
+.. code-block:: python
+
+    candidates = bamboo.search_linked_repositories("build-specs")
+    repository_id = candidates["searchResults"][0]["id"]
+
+    bamboo.link_repository_to_project("PROJECT", repository_id)
+    allowed = bamboo.get_project_linked_repositories("PROJECT")
+    # Revoke the project-level Repository-Stored Specs authorization:
+    bamboo.unlink_repository_from_project("PROJECT", repository_id)
+
 Branches
 -------------
 

tests/bamboo/test_bamboo.py

@@ -107,3 +107,22 @@ def test_plan_results_supports_multiple_labels(mock_get):
     assert list(bamboo.plan_results("PROJ", "PLAN", label=["release", "production"])) == []
 
     assert mock_get.call_args.args[3]["label"] == ["release", "production"]
+
+
+@patch.object(Bamboo, "delete")
+@patch.object(Bamboo, "post")
+@patch.object(Bamboo, "get")
+def test_project_linked_repository_methods(mock_get, mock_post, mock_delete):
+    bamboo = Bamboo("https://bamboo.example.test", token="token")
+    mock_get.side_effect = [{"searchResults": []}, [{"id": 42, "name": "Specs repository"}]]
+
+    bamboo.search_linked_repositories("specs")
+    bamboo.get_project_linked_repositories("PROJ")
+    bamboo.link_repository_to_project("PROJ", 42)
+    bamboo.unlink_repository_from_project("PROJ", 42)
+
+    assert mock_get.call_args_list[0].args[0] == "rest/api/latest/repository"
+    assert mock_get.call_args_list[0].kwargs["params"] == {"searchTerm": "specs"}
+    assert mock_get.call_args_list[1].args[0] == "rest/api/latest/project/PROJ/repository"
+    mock_post.assert_called_once_with("rest/api/latest/project/PROJ/repository", data={"id": 42})
+    mock_delete.assert_called_once_with("rest/api/latest/project/PROJ/repository/42")