Add: Add GitHub API for creating a workflow dispatch event

Allow to start workflows via API by creating a workflow dispatch event.

pontos/github/api.py

@@ -713,3 +713,43 @@ def get_workflow(self, repo: str, workflow: str) -> JSON:
         response = self._request(api, request=httpx.get)
         response.raise_for_status()
         return response.json()
+
+    def create_workflow_dispatch(
+        self,
+        repo: str,
+        workflow: str,
+        *,
+        ref: str,
+        inputs: Dict[str, str] = None,
+    ):
+        """
+        Create a workflow dispatch event to manually trigger a GitHub Actions
+        workflow run.
+
+        Args:
+            repo: GitHub repository (owner/name) to use
+            workflow: ID of the workflow or workflow file name. For example
+                `main.yml`.
+            ref: The git reference for the workflow. The reference can be a
+                branch or tag name.
+            inputs: Input keys and values configured in the workflow file. Any
+                default properties configured in the workflow file will be used
+                when inputs are omitted.
+        Raises:
+            HTTPStatusError: A httpx.HTTPStatusError is raised if the request
+                failed.
+
+        Example:
+            .. code-block:: python
+
+            api = GitHubRESTApi("...")
+            api.create_workflow_dispatch("foo/bar", "ci.yml", ref="main")
+        """
+        api = f"/repos/{repo}/actions/workflows/{workflow}/dispatches"
+        data = {"ref": ref}
+
+        if inputs:
+            data["inputs"] = inputs
+
+        response = self._request(api, data=data, request=httpx.post)
+        response.raise_for_status()

tests/github/test_api.py

@@ -1234,3 +1234,46 @@ def test_get_workflow_invalid(self, requests_mock: MagicMock):
             params=None,
             follow_redirects=True,
         )
+
+    @patch("pontos.github.api.httpx.post")
+    def test_create_workflow_dispatch(self, requests_mock: MagicMock):
+        api = GitHubRESTApi("12345")
+        api.create_workflow_dispatch("foo/bar", "123", ref="main")
+
+        requests_mock.assert_called_once_with(
+            "https://api.github.com/repos/foo/bar/actions/workflows/123"
+            "/dispatches",
+            headers={
+                "Accept": "application/vnd.github.v3+json",
+                "Authorization": "token 12345",
+            },
+            params=None,
+            follow_redirects=True,
+            json={"ref": "main"},
+        )
+
+    @patch("pontos.github.api.httpx.post")
+    def test_create_workflow_dispatch_failure(self, requests_mock: MagicMock):
+        response = MagicMock(autospec=httpx.Response)
+        response.is_success = False
+        response.raise_for_status.side_effect = httpx.HTTPStatusError(
+            "Dispatch Failed", request=None, response=response
+        )
+
+        requests_mock.return_value = response
+        api = GitHubRESTApi("12345")
+
+        with self.assertRaises(httpx.HTTPStatusError):
+            api.create_workflow_dispatch("foo/bar", "123", ref="main")
+
+        requests_mock.assert_called_once_with(
+            "https://api.github.com/repos/foo/bar/actions/workflows/123"
+            "/dispatches",
+            headers={
+                "Accept": "application/vnd.github.v3+json",
+                "Authorization": "token 12345",
+            },
+            params=None,
+            follow_redirects=True,
+            json={"ref": "main"},
+        )