feat(auth): Add SCM authentication support for repository access

Author: akosyakov

Diff for: examples/anthropic_tool_use.py

@@ -1,4 +1,5 @@
-#!/usr/bin/env python
+# EXPORT ANTHROPIC_API_KEY=...
+# python -m examples.anthropic_tool_use
 
 from __future__ import annotations
 
@@ -11,6 +12,8 @@
 from gitpod import AsyncGitpod
 from gitpod.types.environment_initializer_param import Spec
 
+from .scm_auth import verify_context_url  # type: ignore
+
 gpclient = AsyncGitpod()
 llmclient = Anthropic()
 
@@ -43,6 +46,9 @@ async def create_environment(args: dict[str, str], cleanup: util.Disposables) ->
         raise Exception("No environment class found. Please create one first.")
     env_class_id = env_class.id
     assert env_class_id is not None
+    
+    assert env_class.runner_id is not None
+    await verify_context_url(gpclient, args["context_url"], env_class.runner_id)
 
     environment = (await gpclient.environments.create(
         spec={
@@ -63,7 +69,7 @@ async def create_environment(args: dict[str, str], cleanup: util.Disposables) ->
     cleanup.add(lambda: asyncio.run(gpclient.environments.delete(environment_id=environment_id)))    
 
     print(f"\nCreated environment: {environment_id} - waiting for it to be ready...")
-    await util.wait_for_environment_ready(gpclient, environment_id)
+    await util.wait_for_environment_running(gpclient, environment_id)
     print(f"\nEnvironment is ready: {environment_id}")
     return environment_id
 

Diff for: examples/fs_access.py

@@ -1,5 +1,3 @@
-#!/usr/bin/env python
-
 import sys
 import asyncio
 from io import StringIO
@@ -11,10 +9,12 @@
 from gitpod.types.environment_spec_param import EnvironmentSpecParam
 from gitpod.types.environment_initializer_param import Spec
 
+from .scm_auth import verify_context_url  # type: ignore
+
 
 # Examples:
-# - ./examples/fs_access.py
-# - ./examples/fs_access.py https://github.com/gitpod-io/empty
+# - python -m examples.fs_access
+# - python -m examples.fs_access https://github.com/gitpod-io/empty
 async def main(cleanup: util.Disposables) -> None:
     client = AsyncGitpod()
 
@@ -46,6 +46,8 @@ async def main(cleanup: util.Disposables) -> None:
         }]
     }
     if context_url:
+        assert env_class.runner_id is not None
+        await verify_context_url(client, context_url, env_class.runner_id)
         spec["content"] = {
             "initializer": {"specs": [Spec(
                 context_url={

Diff for: examples/run_command.py

@@ -1,5 +1,3 @@
-#!/usr/bin/env python
-
 import sys
 import asyncio
 
@@ -8,10 +6,12 @@
 from gitpod.types.environment_spec_param import EnvironmentSpecParam
 from gitpod.types.environment_initializer_param import Spec
 
+from .scm_auth import verify_context_url  # type: ignore
+
 
 # Examples:
-# - ./examples/run_command.py 'echo "Hello World!"'
-# - ./examples/run_command.py 'echo "Hello World!"' https://github.com/gitpod-io/empty
+# - python -m examples.run_command 'echo "Hello World!"'
+# - python -m examples.run_command 'echo "Hello World!"' https://github.com/gitpod-io/empty
 async def main(cleanup: util.Disposables) -> None:
     client = AsyncGitpod()
 
@@ -35,6 +35,8 @@ async def main(cleanup: util.Disposables) -> None:
         "machine": {"class": env_class_id},
     }
     if context_url:
+        assert env_class.runner_id is not None
+        await verify_context_url(client, context_url, env_class.runner_id)
         spec["content"] = {
             "initializer": {"specs": [Spec(
                 context_url={
@@ -51,7 +53,7 @@ async def main(cleanup: util.Disposables) -> None:
     cleanup.add(lambda: asyncio.run(client.environments.delete(environment_id=environment_id)))
 
     print("Waiting for environment to be ready")
-    await util.wait_for_environment_ready(client, environment_id)
+    await util.wait_for_environment_running(client, environment_id)
 
     print("Running command")
     lines = await util.run_command(client, environment_id, command)

Diff for: examples/run_service.py

@@ -1,5 +1,4 @@
-#!/usr/bin/env python
-
+import os
 import sys
 import asyncio
 
@@ -8,16 +7,23 @@
 from gitpod.types.environment_spec_param import EnvironmentSpecParam
 from gitpod.types.environment_initializer_param import Spec
 
+from .scm_auth import verify_context_url  # type: ignore
+
 
 # Examples:
-# - ./examples/run_service.py
-# - ./examples/run_service.py https://github.com/gitpod-io/empty
+# - python -m examples.run_service
+# - python -m examples.run_service https://github.com/gitpod-io/empty
 async def main(cleanup: util.Disposables) -> None:
     client = AsyncGitpod()
 
     context_url = sys.argv[1] if len(sys.argv) > 1 else None
+    env_class_id = os.getenv("GITPOD_ENV_CLASS_ID")
 
-    env_class = await util.find_most_used_environment_class(client)
+    if not env_class_id:
+        env_class = await util.find_most_used_environment_class(client)
+    else:
+        env_class = await util.find_environment_class_by_id(client, env_class_id)
+    
     if not env_class:
         print("Error: No environment class found. Please create one first.")
         sys.exit(1)
@@ -36,15 +42,16 @@ async def main(cleanup: util.Disposables) -> None:
         }]
     }
     if context_url:
+        assert env_class.runner_id is not None
+        await verify_context_url(client, context_url, env_class.runner_id)
         spec["content"] = {
             "initializer": {"specs": [Spec(
-             context_url={
-                 "url": context_url
-             }
-        )]}
-    }
+                 context_url={
+                     "url": context_url
+                }
+            )]}
+        }
 
-    print("Creating environment")
     environment = (await client.environments.create(spec=spec)).environment
     assert environment is not None
     environment_id = environment.id
@@ -77,4 +84,4 @@ async def main(cleanup: util.Disposables) -> None:
 if __name__ == "__main__":
     disposables = util.Disposables()
     with disposables:
-        asyncio.run(main(disposables))
+        asyncio.run(main(disposables))

Diff for: examples/scm_auth.py

@@ -0,0 +1,131 @@
+import sys
+from urllib.parse import urlparse
+
+import gitpod
+import gitpod.lib as util
+from gitpod import AsyncGitpod
+
+
+async def handle_pat_auth(client: AsyncGitpod, user_id: str, runner_id: str, host: str) -> None:
+    scm_info = {
+        "github.com": {
+            "create_url": f"https://{host}/settings/tokens/new?scopes=repo,workflow,read:user,user:email&description=gitpod",
+            "docs_url": "https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens",
+            "scopes": "repo, workflow, read:user, user:email"
+        },
+        "gitlab.com": {
+            "create_url": f"https://{host}/-/user_settings/personal_access_tokens?scopes=api,read_user,read_repository&name=gitpod",
+            "docs_url": "https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html",
+            "scopes": "api, read_user, read_repository"
+        },
+        "dev.azure.com": {
+            "create_url": None,
+            "docs_url": "https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate",
+            "scopes": "Code (Read & Write)"
+        }
+    }.get(host, {
+        "create_url": None,
+        "docs_url": "https://www.gitpod.io/docs/flex/source-control",
+        "scopes": "repository access"
+    })
+
+    print("\nTo create a Personal Access Token:")
+    create_url = scm_info["create_url"] # type: ignore
+    if create_url: 
+        print(f"1. Visit: {create_url}")
+    else:
+        print(f"1. Go to {host} > Settings > Developer Settings")
+    print(f"2. Create a new token with the following scopes: {scm_info['scopes']}") # type: ignore
+    print(f"3. Copy the generated token")
+    print(f"\nFor detailed instructions, visit: {scm_info['docs_url']}") # type: ignore
+
+    pat = input("\nEnter your Personal Access Token: ").strip()
+    if not pat:
+        return
+
+    await util.set_scm_pat(client, user_id, runner_id, host, pat)
+
+async def verify_context_url(client: AsyncGitpod, context_url: str, runner_id: str) -> None:
+    """Verify and handle authentication for a repository context URL."""
+    host = urlparse(context_url).hostname
+    if host is None:
+        print("Error: Invalid context URL")
+        sys.exit(1)
+
+    resp = await client.users.get_authenticated_user()
+    assert resp is not None
+    user = resp.user
+    assert user is not None
+    user_id = user.id
+    assert user_id is not None
+
+    # Main authentication loop
+    first_attempt = True
+    while True:
+        try:
+            # Try to access the context URL
+            await client.runners.parse_context_url(context_url=context_url, runner_id=runner_id)
+            print("\n✓ Authentication verified successfully")
+            return
+
+        except gitpod.APIError as e:
+            if e.code != "failed_precondition":
+                raise e
+            
+        # Show authentication required message only on first attempt
+        if first_attempt:
+            print(f"\nAuthentication required for {host}")
+            first_attempt = False
+
+        # Get authentication options for the host
+        auth_resp = await client.runners.check_authentication_for_host(
+            host=host,
+            runner_id=runner_id
+        )
+
+        # Handle re-authentication case
+        if auth_resp.authenticated and not first_attempt:
+            print("\nIt looks like you are already authenticated.")
+            if input("Would you like to re-authenticate? (y/n): ").lower().strip() != 'y':
+                print("\nAuthentication cancelled")
+                sys.exit(1)
+            else:
+                print("\nRetrying authentication...")
+                continue
+                
+        auth_methods: list[tuple[str, str]] = []
+        if auth_resp.authentication_url:
+            auth_methods.append(("OAuth", "Recommended"))
+        if auth_resp.pat_supported:
+            auth_methods.append(("Personal Access Token (PAT)", ""))
+
+        if not auth_methods:
+            print(f"\nError: No authentication method available for {host}")
+            sys.exit(1)
+
+        # Present authentication options
+        if len(auth_methods) > 1:
+            print("\nAvailable authentication methods:")
+            for i, (method, note) in enumerate(auth_methods, 1):
+                note_text = f" ({note})" if note else ""
+                print(f"{i}. {method}{note_text}")
+            
+            choice = input(f"\nChoose authentication method (1-{len(auth_methods)}): ").strip()
+            try:
+                method_index = int(choice) - 1
+                if not 0 <= method_index < len(auth_methods):
+                    raise ValueError()
+            except ValueError:
+                method_index = 0  # Default to OAuth if invalid input
+        else:
+            method_index = 0
+
+        # Handle chosen authentication method
+        chosen_method = auth_methods[method_index][0]
+        if chosen_method == "Personal Access Token (PAT)":
+            await handle_pat_auth(client, user_id, runner_id, host)
+        else:
+            print(f"\nPlease visit the following URL to authenticate:")
+            print(f"{auth_resp.authentication_url}")
+            print("\nWaiting for authentication to complete...")
+            input("Press Enter after completing authentication in your browser...") 

Diff for: requirements-dev.lock

@@ -73,7 +73,6 @@ packaging==23.2
     # via nox
     # via pytest
 paramiko==3.5.1
-    # via gitpod-sdk
 platformdirs==3.11.0
     # via virtualenv
 pluggy==1.5.0

Diff for: requirements.lock

@@ -14,16 +14,9 @@ annotated-types==0.6.0
 anyio==4.4.0
     # via gitpod-sdk
     # via httpx
-bcrypt==4.2.1
-    # via paramiko
 certifi==2023.7.22
     # via httpcore
     # via httpx
-cffi==1.17.1
-    # via cryptography
-    # via pynacl
-cryptography==44.0.1
-    # via paramiko
 distro==1.8.0
     # via gitpod-sdk
 exceptiongroup==1.2.2
@@ -37,16 +30,10 @@ httpx==0.28.1
 idna==3.4
     # via anyio
     # via httpx
-paramiko==3.5.1
-    # via gitpod-sdk
-pycparser==2.22
-    # via cffi
 pydantic==2.10.3
     # via gitpod-sdk
 pydantic-core==2.27.1
     # via pydantic
-pynacl==1.5.0
-    # via paramiko
 sniffio==1.3.0
     # via anyio
     # via gitpod-sdk

Diff for: src/gitpod/lib/__init__.py

@@ -1,12 +1,20 @@
+from .runner import set_scm_pat
 from .automation import run_command, run_service
 from .disposables import Disposables
-from .environment import EnvironmentState, wait_for_environment_ready, find_most_used_environment_class
+from .environment import (
+    EnvironmentState,
+    find_environment_class_by_id,
+    wait_for_environment_running,
+    find_most_used_environment_class,
+)
 
 __all__ = [
     'find_most_used_environment_class',
     'run_command',
     'run_service',
     'EnvironmentState',
     'Disposables',
-    'wait_for_environment_ready',
+    'wait_for_environment_running',
+    'find_environment_class_by_id',
+    'set_scm_pat',
 ]