feat(api): add CheckRepositoryAccess API for repository access validation

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 169
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/gitpod%2Fgitpod-6b80aebab53bff73bb7b87c5f91f98c6dd5db2d623b6c613aaa5e61252b74d75.yml
-openapi_spec_hash: 9636e315ac739c1ab9cba65a7ead6559
-config_hash: 73893621fd64bbd87b86671decf334e6
+configured_endpoints: 170
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/gitpod%2Fgitpod-024993504dfc744ff138b0d1b1a151e28129f9f5a8b55adff4c7b559b0556c62.yml
+openapi_spec_hash: 4773277eb2a6ac6be0b2e8f89a2201d8
+config_hash: 942ffc968ca0131e192c1a7ac5dd8990

api.md

@@ -597,6 +597,7 @@ from gitpod.types import (
     RunnerCreateResponse,
     RunnerRetrieveResponse,
     RunnerCheckAuthenticationForHostResponse,
+    RunnerCheckRepositoryAccessResponse,
     RunnerCreateLogsTokenResponse,
     RunnerCreateRunnerTokenResponse,
     RunnerListScmOrganizationsResponse,
@@ -613,6 +614,7 @@ Methods:
 - <code title="post /gitpod.v1.RunnerService/ListRunners">client.runners.<a href="./src/gitpod/resources/runners/runners.py">list</a>(\*\*<a href="src/gitpod/types/runner_list_params.py">params</a>) -> <a href="./src/gitpod/types/runner.py">SyncRunnersPage[Runner]</a></code>
 - <code title="post /gitpod.v1.RunnerService/DeleteRunner">client.runners.<a href="./src/gitpod/resources/runners/runners.py">delete</a>(\*\*<a href="src/gitpod/types/runner_delete_params.py">params</a>) -> object</code>
 - <code title="post /gitpod.v1.RunnerService/CheckAuthenticationForHost">client.runners.<a href="./src/gitpod/resources/runners/runners.py">check_authentication_for_host</a>(\*\*<a href="src/gitpod/types/runner_check_authentication_for_host_params.py">params</a>) -> <a href="./src/gitpod/types/runner_check_authentication_for_host_response.py">RunnerCheckAuthenticationForHostResponse</a></code>
+- <code title="post /gitpod.v1.RunnerService/CheckRepositoryAccess">client.runners.<a href="./src/gitpod/resources/runners/runners.py">check_repository_access</a>(\*\*<a href="src/gitpod/types/runner_check_repository_access_params.py">params</a>) -> <a href="./src/gitpod/types/runner_check_repository_access_response.py">RunnerCheckRepositoryAccessResponse</a></code>
 - <code title="post /gitpod.v1.RunnerService/CreateRunnerLogsToken">client.runners.<a href="./src/gitpod/resources/runners/runners.py">create_logs_token</a>(\*\*<a href="src/gitpod/types/runner_create_logs_token_params.py">params</a>) -> <a href="./src/gitpod/types/runner_create_logs_token_response.py">RunnerCreateLogsTokenResponse</a></code>
 - <code title="post /gitpod.v1.RunnerService/CreateRunnerToken">client.runners.<a href="./src/gitpod/resources/runners/runners.py">create_runner_token</a>(\*\*<a href="src/gitpod/types/runner_create_runner_token_params.py">params</a>) -> <a href="./src/gitpod/types/runner_create_runner_token_response.py">RunnerCreateRunnerTokenResponse</a></code>
 - <code title="post /gitpod.v1.RunnerService/ListSCMOrganizations">client.runners.<a href="./src/gitpod/resources/runners/runners.py">list_scm_organizations</a>(\*\*<a href="src/gitpod/types/runner_list_scm_organizations_params.py">params</a>) -> <a href="./src/gitpod/types/runner_list_scm_organizations_response.py">RunnerListScmOrganizationsResponse</a></code>

src/gitpod/resources/runners/runners.py

@@ -20,6 +20,7 @@
     runner_create_runner_token_params,
     runner_search_repositories_params,
     runner_list_scm_organizations_params,
+    runner_check_repository_access_params,
     runner_check_authentication_for_host_params,
 )
 from ..._types import Body, Omit, Query, Headers, NotGiven, omit, not_given
@@ -62,6 +63,7 @@
 from ...types.runner_create_runner_token_response import RunnerCreateRunnerTokenResponse
 from ...types.runner_search_repositories_response import RunnerSearchRepositoriesResponse
 from ...types.runner_list_scm_organizations_response import RunnerListScmOrganizationsResponse
+from ...types.runner_check_repository_access_response import RunnerCheckRepositoryAccessResponse
 from ...types.runner_check_authentication_for_host_response import RunnerCheckAuthenticationForHostResponse
 
 __all__ = ["RunnersResource", "AsyncRunnersResource"]
@@ -510,6 +512,70 @@ def check_authentication_for_host(
             cast_to=RunnerCheckAuthenticationForHostResponse,
         )
 
+    def check_repository_access(
+        self,
+        *,
+        repository_url: str | Omit = omit,
+        runner_id: str | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> RunnerCheckRepositoryAccessResponse:
+        """
+        Checks if a principal has read access to a repository.
+
+        Use this method to:
+
+        - Validate repository access before workflow execution
+        - Verify executor credentials for automation bindings
+
+        Returns:
+
+        - has_access: true if the principal can read the repository
+        - FAILED_PRECONDITION if authentication is required
+        - INVALID_ARGUMENT if the repository URL is invalid
+
+        ### Examples
+
+        - Check access:
+
+          Verifies read access to a repository.
+
+          ```yaml
+          runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+          repositoryUrl: "https://github.com/org/repo"
+          ```
+
+        Args:
+          repository_url: repository_url is the URL of the repository to check access for. Can be a clone
+              URL (https://github.com/org/repo.git) or web URL (https://github.com/org/repo).
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return self._post(
+            "/gitpod.v1.RunnerService/CheckRepositoryAccess",
+            body=maybe_transform(
+                {
+                    "repository_url": repository_url,
+                    "runner_id": runner_id,
+                },
+                runner_check_repository_access_params.RunnerCheckRepositoryAccessParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=RunnerCheckRepositoryAccessResponse,
+        )
+
     def create_logs_token(
         self,
         *,
@@ -1273,6 +1339,70 @@ async def check_authentication_for_host(
             cast_to=RunnerCheckAuthenticationForHostResponse,
         )
 
+    async def check_repository_access(
+        self,
+        *,
+        repository_url: str | Omit = omit,
+        runner_id: str | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> RunnerCheckRepositoryAccessResponse:
+        """
+        Checks if a principal has read access to a repository.
+
+        Use this method to:
+
+        - Validate repository access before workflow execution
+        - Verify executor credentials for automation bindings
+
+        Returns:
+
+        - has_access: true if the principal can read the repository
+        - FAILED_PRECONDITION if authentication is required
+        - INVALID_ARGUMENT if the repository URL is invalid
+
+        ### Examples
+
+        - Check access:
+
+          Verifies read access to a repository.
+
+          ```yaml
+          runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+          repositoryUrl: "https://github.com/org/repo"
+          ```
+
+        Args:
+          repository_url: repository_url is the URL of the repository to check access for. Can be a clone
+              URL (https://github.com/org/repo.git) or web URL (https://github.com/org/repo).
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return await self._post(
+            "/gitpod.v1.RunnerService/CheckRepositoryAccess",
+            body=await async_maybe_transform(
+                {
+                    "repository_url": repository_url,
+                    "runner_id": runner_id,
+                },
+                runner_check_repository_access_params.RunnerCheckRepositoryAccessParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=RunnerCheckRepositoryAccessResponse,
+        )
+
     async def create_logs_token(
         self,
         *,
@@ -1617,6 +1747,9 @@ def __init__(self, runners: RunnersResource) -> None:
         self.check_authentication_for_host = to_raw_response_wrapper(
             runners.check_authentication_for_host,
         )
+        self.check_repository_access = to_raw_response_wrapper(
+            runners.check_repository_access,
+        )
         self.create_logs_token = to_raw_response_wrapper(
             runners.create_logs_token,
         )
@@ -1664,6 +1797,9 @@ def __init__(self, runners: AsyncRunnersResource) -> None:
         self.check_authentication_for_host = async_to_raw_response_wrapper(
             runners.check_authentication_for_host,
         )
+        self.check_repository_access = async_to_raw_response_wrapper(
+            runners.check_repository_access,
+        )
         self.create_logs_token = async_to_raw_response_wrapper(
             runners.create_logs_token,
         )
@@ -1711,6 +1847,9 @@ def __init__(self, runners: RunnersResource) -> None:
         self.check_authentication_for_host = to_streamed_response_wrapper(
             runners.check_authentication_for_host,
         )
+        self.check_repository_access = to_streamed_response_wrapper(
+            runners.check_repository_access,
+        )
         self.create_logs_token = to_streamed_response_wrapper(
             runners.create_logs_token,
         )
@@ -1758,6 +1897,9 @@ def __init__(self, runners: AsyncRunnersResource) -> None:
         self.check_authentication_for_host = async_to_streamed_response_wrapper(
             runners.check_authentication_for_host,
         )
+        self.check_repository_access = async_to_streamed_response_wrapper(
+            runners.check_repository_access,
+        )
         self.create_logs_token = async_to_streamed_response_wrapper(
             runners.create_logs_token,
         )

src/gitpod/types/__init__.py

@@ -224,6 +224,9 @@
 from .project_prebuild_configuration_param import ProjectPrebuildConfigurationParam as ProjectPrebuildConfigurationParam
 from .runner_list_scm_organizations_params import RunnerListScmOrganizationsParams as RunnerListScmOrganizationsParams
 from .user_get_authenticated_user_response import UserGetAuthenticatedUserResponse as UserGetAuthenticatedUserResponse
+from .runner_check_repository_access_params import (
+    RunnerCheckRepositoryAccessParams as RunnerCheckRepositoryAccessParams,
+)
 from .environment_create_from_project_params import (
     EnvironmentCreateFromProjectParams as EnvironmentCreateFromProjectParams,
 )
@@ -236,6 +239,9 @@
 from .runner_list_scm_organizations_response import (
     RunnerListScmOrganizationsResponse as RunnerListScmOrganizationsResponse,
 )
+from .runner_check_repository_access_response import (
+    RunnerCheckRepositoryAccessResponse as RunnerCheckRepositoryAccessResponse,
+)
 from .environment_create_from_project_response import (
     EnvironmentCreateFromProjectResponse as EnvironmentCreateFromProjectResponse,
 )

src/gitpod/types/runner_check_repository_access_params.py

@@ -0,0 +1,19 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import Annotated, TypedDict
+
+from .._utils import PropertyInfo
+
+__all__ = ["RunnerCheckRepositoryAccessParams"]
+
+
+class RunnerCheckRepositoryAccessParams(TypedDict, total=False):
+    repository_url: Annotated[str, PropertyInfo(alias="repositoryUrl")]
+    """
+    repository_url is the URL of the repository to check access for. Can be a clone
+    URL (https://github.com/org/repo.git) or web URL (https://github.com/org/repo).
+    """
+
+    runner_id: Annotated[str, PropertyInfo(alias="runnerId")]

src/gitpod/types/runner_check_repository_access_response.py

@@ -0,0 +1,20 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Optional
+
+from pydantic import Field as FieldInfo
+
+from .._models import BaseModel
+
+__all__ = ["RunnerCheckRepositoryAccessResponse"]
+
+
+class RunnerCheckRepositoryAccessResponse(BaseModel):
+    error_message: Optional[str] = FieldInfo(alias="errorMessage", default=None)
+    """
+    error_message provides details when access check fails. Empty when has_access is
+    true.
+    """
+
+    has_access: Optional[bool] = FieldInfo(alias="hasAccess", default=None)
+    """has_access indicates whether the principal has read access to the repository."""

tests/api_resources/test_runners.py

@@ -18,6 +18,7 @@
     RunnerCreateRunnerTokenResponse,
     RunnerSearchRepositoriesResponse,
     RunnerListScmOrganizationsResponse,
+    RunnerCheckRepositoryAccessResponse,
     RunnerCheckAuthenticationForHostResponse,
 )
 from gitpod.pagination import SyncRunnersPage, AsyncRunnersPage
@@ -292,6 +293,43 @@ def test_streaming_response_check_authentication_for_host(self, client: Gitpod)
 
         assert cast(Any, response.is_closed) is True
 
+    @pytest.mark.skip(reason="Prism tests are disabled")
+    @parametrize
+    def test_method_check_repository_access(self, client: Gitpod) -> None:
+        runner = client.runners.check_repository_access()
+        assert_matches_type(RunnerCheckRepositoryAccessResponse, runner, path=["response"])
+
+    @pytest.mark.skip(reason="Prism tests are disabled")
+    @parametrize
+    def test_method_check_repository_access_with_all_params(self, client: Gitpod) -> None:
+        runner = client.runners.check_repository_access(
+            repository_url="https://github.com/org/repo",
+            runner_id="d2c94c27-3b76-4a42-b88c-95a85e392c68",
+        )
+        assert_matches_type(RunnerCheckRepositoryAccessResponse, runner, path=["response"])
+
+    @pytest.mark.skip(reason="Prism tests are disabled")
+    @parametrize
+    def test_raw_response_check_repository_access(self, client: Gitpod) -> None:
+        response = client.runners.with_raw_response.check_repository_access()
+
+        assert response.is_closed is True
+        assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+        runner = response.parse()
+        assert_matches_type(RunnerCheckRepositoryAccessResponse, runner, path=["response"])
+
+    @pytest.mark.skip(reason="Prism tests are disabled")
+    @parametrize
+    def test_streaming_response_check_repository_access(self, client: Gitpod) -> None:
+        with client.runners.with_streaming_response.check_repository_access() as response:
+            assert not response.is_closed
+            assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+
+            runner = response.parse()
+            assert_matches_type(RunnerCheckRepositoryAccessResponse, runner, path=["response"])
+
+        assert cast(Any, response.is_closed) is True
+
     @pytest.mark.skip(reason="Prism tests are disabled")
     @parametrize
     def test_method_create_logs_token(self, client: Gitpod) -> None:
@@ -754,6 +792,43 @@ async def test_streaming_response_check_authentication_for_host(self, async_clie
 
         assert cast(Any, response.is_closed) is True
 
+    @pytest.mark.skip(reason="Prism tests are disabled")
+    @parametrize
+    async def test_method_check_repository_access(self, async_client: AsyncGitpod) -> None:
+        runner = await async_client.runners.check_repository_access()
+        assert_matches_type(RunnerCheckRepositoryAccessResponse, runner, path=["response"])
+
+    @pytest.mark.skip(reason="Prism tests are disabled")
+    @parametrize
+    async def test_method_check_repository_access_with_all_params(self, async_client: AsyncGitpod) -> None:
+        runner = await async_client.runners.check_repository_access(
+            repository_url="https://github.com/org/repo",
+            runner_id="d2c94c27-3b76-4a42-b88c-95a85e392c68",
+        )
+        assert_matches_type(RunnerCheckRepositoryAccessResponse, runner, path=["response"])
+
+    @pytest.mark.skip(reason="Prism tests are disabled")
+    @parametrize
+    async def test_raw_response_check_repository_access(self, async_client: AsyncGitpod) -> None:
+        response = await async_client.runners.with_raw_response.check_repository_access()
+
+        assert response.is_closed is True
+        assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+        runner = await response.parse()
+        assert_matches_type(RunnerCheckRepositoryAccessResponse, runner, path=["response"])
+
+    @pytest.mark.skip(reason="Prism tests are disabled")
+    @parametrize
+    async def test_streaming_response_check_repository_access(self, async_client: AsyncGitpod) -> None:
+        async with async_client.runners.with_streaming_response.check_repository_access() as response:
+            assert not response.is_closed
+            assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+
+            runner = await response.parse()
+            assert_matches_type(RunnerCheckRepositoryAccessResponse, runner, path=["response"])
+
+        assert cast(Any, response.is_closed) is True
+
     @pytest.mark.skip(reason="Prism tests are disabled")
     @parametrize
     async def test_method_create_logs_token(self, async_client: AsyncGitpod) -> None: