airbyte-internal-ops 0.3.1__py3-none-any.whl → 0.4.1__py3-none-any.whl

{airbyte_internal_ops-0.3.1.dist-info → airbyte_internal_ops-0.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: airbyte-internal-ops
-Version: 0.3.1
+Version: 0.4.1
 Summary: MCP and API interfaces that let the agents do the admin work
 Author-email: Aaron Steers <aj@airbyte.io>
 Keywords: admin,airbyte,api,mcp

{airbyte_internal_ops-0.3.1.dist-info → airbyte_internal_ops-0.4.1.dist-info}/RECORD

@@ -2,8 +2,8 @@ airbyte_ops_mcp/__init__.py,sha256=tuzdlMkfnWBnsri5KGHM2M_xuNnzFk2u_aR79mmN7Yg,7
 airbyte_ops_mcp/_annotations.py,sha256=MO-SBDnbykxxHDESG7d8rviZZ4WlZgJKv0a8eBqcEzQ,1757
 airbyte_ops_mcp/constants.py,sha256=khcv9W3WkApIyPygEGgE2noBIqLomjoOMLxFBU1ArjA,5308
 airbyte_ops_mcp/gcp_auth.py,sha256=i0cm1_xX4fj_31iKlfARpNvTaSr85iGTSw9KMf4f4MU,7206
-airbyte_ops_mcp/github_actions.py,sha256=wKnuIVmF4u1gMYNdSoryD_PUmvMz5SaHgOvbU0dsolA,9957
-airbyte_ops_mcp/github_api.py,sha256=uupbYKAkm7yLHK_1cDXYKl1bOYhUygZhG5IHspS7duE,8104
+airbyte_ops_mcp/github_actions.py,sha256=FSi_tjS9TbwRVp8dwlDZhFOi7lJXEZQLhPm2KpcjNlY,7022
+airbyte_ops_mcp/github_api.py,sha256=ezpMR1vjqQ-1f5yOLBVbxW70OPtUferl1uA0u_gUVo8,12733
 airbyte_ops_mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 airbyte_ops_mcp/_legacy/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 airbyte_ops_mcp/_legacy/airbyte_ci/README.md,sha256=qEYx4geDR8AEDjrcA303h7Nol-CMDLojxUyiGzQprM8,236
@@ -354,8 +354,8 @@ airbyte_ops_mcp/cli/_base.py,sha256=I8tWnyQf0ks4r3J8N8h-5GZxyn37T-55KsbuHnxYlcg,
 airbyte_ops_mcp/cli/_shared.py,sha256=jg-xMyGzTCGPqKd8VTfE_3kGPIyO_3Kx5sQbG4rPc0Y,1311
 airbyte_ops_mcp/cli/app.py,sha256=SEdBpqFUG2O8zGV5ifwptxrLGFph_dLr66-MX9d69gQ,789
 airbyte_ops_mcp/cli/cloud.py,sha256=OmeJPW8ME82PLJSqzoU_tz_3iqsTA-MY4QBO-ad8gfo,44141
-airbyte_ops_mcp/cli/gh.py,sha256=91b1AxFXvHQCFyXhrrym-756ZjnMCqvxFdmwCtma1zI,2046
-airbyte_ops_mcp/cli/registry.py,sha256=tcf_CDiUVJpSdBRNqlEL3zFKMqK53AhFpJjAETM4gLs,9781
+airbyte_ops_mcp/cli/gh.py,sha256=koJPu0MDB6AW7mJq2z4dZV65ofvsZTkqoeitGF8KJR8,5364
+airbyte_ops_mcp/cli/registry.py,sha256=L4nDKhlegr31gSE-GUvDFSq10KgDz5kJuZXgLIxYIyg,9785
 airbyte_ops_mcp/cli/repo.py,sha256=G1hoQpH0XYhUH3FFOsia9xabGB0LP9o3XcwBuqvFVo0,16331
 airbyte_ops_mcp/cloud_admin/__init__.py,sha256=cqE96Q10Kp6elhH9DAi6TVsIwSUy3sooDLLrxTaktGk,816
 airbyte_ops_mcp/cloud_admin/api_client.py,sha256=ysTztSbLX0SZSK3qneHTSKVODRzVmLbHBC3ND0j_LTc,38020
@@ -376,21 +376,21 @@ airbyte_ops_mcp/mcp/cloud_connector_versions.py,sha256=5qUYRZapYBprmmc5J3lKQzeQ3
 airbyte_ops_mcp/mcp/connector_analysis.py,sha256=OC4KrOSkMkKPkOisWnSv96BDDE5TQYHq-Jxa2vtjJpo,298
 airbyte_ops_mcp/mcp/connector_qa.py,sha256=aImpqdnqBPDrz10BS0owsV4kuIU2XdalzgbaGZsbOL0,258
 airbyte_ops_mcp/mcp/gcp_logs.py,sha256=IPtq4098_LN1Cgeba4jATO1iYFFFpL2-aRO0pGcOdzs,2689
-airbyte_ops_mcp/mcp/github.py,sha256=h3M3VJrq09y_F9ueQVCq3bUbVBNFuTNKprHtGU_ttio,8045
+airbyte_ops_mcp/mcp/github_actions.py,sha256=_mAVTl6UX3F7S_HeV1-M5R4jMNzNQGI3ADs3sBzden8,11760
 airbyte_ops_mcp/mcp/github_repo_ops.py,sha256=PiERpt8abo20Gz4CfXhrDNlVM4o4FOt5sweZJND2a0s,5314
 airbyte_ops_mcp/mcp/metadata.py,sha256=fwGW97WknR5lfKcQnFtK6dU87aA6TmLj1NkKyqDAV9g,270
-airbyte_ops_mcp/mcp/prerelease.py,sha256=nc6VU03ADVHWM3OjGKxbS5XqY4VoyRyrZNU_fyAtaOI,10465
-airbyte_ops_mcp/mcp/prod_db_queries.py,sha256=DPzyHCT3yxj2kjkucefoVpsR71vscuJQ8tGgLs_lhv0,32068
+airbyte_ops_mcp/mcp/prerelease.py,sha256=fEZwqtyFQC9nKBF6MJf0WcHoiEoCiouFbBG2bqBtuRY,10701
+airbyte_ops_mcp/mcp/prod_db_queries.py,sha256=VsiBBnVbOjc8lBb2Xr1lmcH3wu7QHQfjd4lORarEE1s,42700
 airbyte_ops_mcp/mcp/prompts.py,sha256=mJld9mdPECXYZffWXGSvNs4Xevx3rxqUGNlzGKVC2_s,1599
 airbyte_ops_mcp/mcp/registry.py,sha256=PW-VYUj42qx2pQ_apUkVaoUFq7VgB9zEU7-aGrkSCCw,290
-airbyte_ops_mcp/mcp/regression_tests.py,sha256=S1h-5S5gcZA4WEtIZyAQ836hd04tjSRRqMiYMx0S93g,16079
-airbyte_ops_mcp/mcp/server.py,sha256=lKAXxt4u4bz7dsKvAYFFHziMbun2pOnxYmrMtRxsZvM,5317
+airbyte_ops_mcp/mcp/regression_tests.py,sha256=dmM22ODwUTbVisKiRcJunzEgMKrZOkpsbkUm0_hFWYk,16752
+airbyte_ops_mcp/mcp/server.py,sha256=dMOFXPFeHBIqicOWs8UsPfzgsWnzsWDsZJ79E_OYjT0,5341
 airbyte_ops_mcp/mcp/server_info.py,sha256=Yi4B1auW64QZGBDas5mro_vwTjvrP785TFNSBP7GhRg,2361
 airbyte_ops_mcp/prod_db_access/__init__.py,sha256=5pxouMPY1beyWlB0UwPnbaLTKTHqU6X82rbbgKY2vYU,1069
 airbyte_ops_mcp/prod_db_access/db_engine.py,sha256=VUqEWZtharJUR-Cri_pMwtGh1C4Neu4s195mbEXlm-w,9190
 airbyte_ops_mcp/prod_db_access/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-airbyte_ops_mcp/prod_db_access/queries.py,sha256=TNxTY5Hf3ImHBX0_e_20-VbF3yzYm2mX3ykWzQXgpno,17754
-airbyte_ops_mcp/prod_db_access/sql.py,sha256=xB7SJGnBSlY-ZB7ku_9QfvNIEldGEmCn-jJcAdes_LY,30407
+airbyte_ops_mcp/prod_db_access/queries.py,sha256=pyW5GxDZ5ibwXawxyI_IR7VFcmoX7pZyZ2jdADqhJRY,20276
+airbyte_ops_mcp/prod_db_access/sql.py,sha256=lzFOYfkb-rFTaZ6vrAK9G8Ym4KTUdhPMBzK44NSRzcg,35362
 airbyte_ops_mcp/registry/__init__.py,sha256=iEaPlt9GrnlaLbc__98TguNeZG8wuQu7S-_2QkhHcbA,858
 airbyte_ops_mcp/registry/models.py,sha256=B4L4TKr52wo0xs0CqvCBrpowqjShzVnZ5eTr2-EyhNs,2346
 airbyte_ops_mcp/registry/publish.py,sha256=VoPxsM2_0zJ829orzCRN-kjgcJtuBNyXgW4I9J680ro,12717
@@ -400,7 +400,7 @@ airbyte_ops_mcp/regression_tests/ci_output.py,sha256=rrvCVKKShc1iVPMuQJDBqSbsiAH
 airbyte_ops_mcp/regression_tests/config.py,sha256=dwWeY0tatdbwl9BqbhZ7EljoZDCtKmGO5fvOAIxeXmA,5873
 airbyte_ops_mcp/regression_tests/connection_fetcher.py,sha256=5wIiA0VvCFNEc-fr6Po18gZMX3E5fyPOGf2SuVOqv5U,12799
 airbyte_ops_mcp/regression_tests/connection_secret_retriever.py,sha256=FhWNVWq7sON4nwUmVJv8BgXBOqg1YV4b5WuWyCzZ0LU,4695
-airbyte_ops_mcp/regression_tests/connector_runner.py,sha256=bappfBSq8dn3IyVAMS_XuzYEwWus23hkDCHLa2RFysI,9920
+airbyte_ops_mcp/regression_tests/connector_runner.py,sha256=OZzUa2aLh0sHaEARsDePOA-e3qEX4cvh3Jhnvi8S1rY,10130
 airbyte_ops_mcp/regression_tests/evaluation_modes.py,sha256=lAL6pEDmy_XCC7_m4_NXjt_f6Z8CXeAhMkc0FU8bm_M,1364
 airbyte_ops_mcp/regression_tests/http_metrics.py,sha256=oTD7f2MnQOvx4plOxHop2bInQ0-whvuToSsrC7TIM-M,12469
 airbyte_ops_mcp/regression_tests/models.py,sha256=brtAT9oO1TwjFcP91dFcu0XcUNqQb-jf7di1zkoVEuo,8782
@@ -414,7 +414,7 @@ airbyte_ops_mcp/regression_tests/regression/comparators.py,sha256=MJkLZEKHivgrG0
 airbyte_ops_mcp/regression_tests/validation/__init__.py,sha256=MBEwGOoNuqT4_oCahtoK62OKWIjUCfWa7vZTxNj_0Ek,1532
 airbyte_ops_mcp/regression_tests/validation/catalog_validators.py,sha256=jqqVAMOk0mtdPgwu4d0hA0ZEjtsNh5gapvGydRv3_qk,12553
 airbyte_ops_mcp/regression_tests/validation/record_validators.py,sha256=RjauAhKWNwxMBTu0eNS2hMFNQVs5CLbQU51kp6FOVDk,7432
-airbyte_internal_ops-0.3.1.dist-info/METADATA,sha256=kx1iQ0YE42LjpsFpjJD7SECaYMHEjo36VjvSVf3BwHk,5679
-airbyte_internal_ops-0.3.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-airbyte_internal_ops-0.3.1.dist-info/entry_points.txt,sha256=WxP0l7bRFss4Cr5uQqVj9mTEKwnRKouNuphXQF0lotA,171
-airbyte_internal_ops-0.3.1.dist-info/RECORD,,
+airbyte_internal_ops-0.4.1.dist-info/METADATA,sha256=mjk54F-EL71ItP6D4BxFg8_eZVZlbfe8bW1wTgno10g,5679
+airbyte_internal_ops-0.4.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+airbyte_internal_ops-0.4.1.dist-info/entry_points.txt,sha256=WxP0l7bRFss4Cr5uQqVj9mTEKwnRKouNuphXQF0lotA,171
+airbyte_internal_ops-0.4.1.dist-info/RECORD,,

airbyte_ops_mcp/cli/gh.py

@@ -3,17 +3,23 @@
 
 Commands:
     airbyte-ops gh workflow status - Check GitHub Actions workflow status
+    airbyte-ops gh workflow trigger - Trigger a GitHub Actions CI workflow
 """
 
 from __future__ import annotations
 
+import json
+import time
 from typing import Annotated
 
 from cyclopts import App, Parameter
 
 from airbyte_ops_mcp.cli._base import app
 from airbyte_ops_mcp.cli._shared import exit_with_error, print_json
-from airbyte_ops_mcp.mcp.github import check_workflow_status
+from airbyte_ops_mcp.mcp.github_actions import (
+    check_ci_workflow_status,
+    trigger_ci_workflow,
+)
 
 # Create the gh sub-app
 gh_app = App(name="gh", help="GitHub operations.")
@@ -62,10 +68,107 @@ def workflow_status(
             "Must provide either --url OR all of (--owner, --repo, --run-id)."
         )
 
-    result = check_workflow_status(
+    result = check_ci_workflow_status(
         workflow_url=url,
         owner=owner,
         repo=repo,
         run_id=run_id,
     )
     print_json(result.model_dump())
+
+
+@workflow_app.command(name="trigger")
+def workflow_trigger(
+    owner: Annotated[
+        str,
+        Parameter(help="Repository owner (e.g., 'airbytehq')."),
+    ],
+    repo: Annotated[
+        str,
+        Parameter(help="Repository name (e.g., 'airbyte')."),
+    ],
+    workflow_file: Annotated[
+        str,
+        Parameter(help="Workflow file name (e.g., 'connector-regression-test.yml')."),
+    ],
+    workflow_definition_ref: Annotated[
+        str | None,
+        Parameter(
+            help="Branch name or PR number for the workflow definition to use. "
+            "If a PR number is provided, it resolves to the PR's head branch name. "
+            "Defaults to 'main' if not specified."
+        ),
+    ] = None,
+    inputs: Annotated[
+        str | None,
+        Parameter(
+            help='Workflow inputs as a JSON string (e.g., \'{"key": "value"}\').'
+        ),
+    ] = None,
+    wait: Annotated[
+        bool,
+        Parameter(help="Wait for the workflow to complete before returning."),
+    ] = False,
+    wait_seconds: Annotated[
+        int,
+        Parameter(
+            help="Maximum seconds to wait for workflow completion (default: 600)."
+        ),
+    ] = 600,
+) -> None:
+    """Trigger a GitHub Actions CI workflow via workflow_dispatch.
+
+    This command triggers a workflow in any GitHub repository that has workflow_dispatch
+    enabled. It resolves PR numbers to branch names automatically.
+    """
+    # Parse inputs JSON if provided
+    parsed_inputs: dict[str, str] | None = None
+    if inputs:
+        try:
+            parsed_inputs = json.loads(inputs)
+        except json.JSONDecodeError as e:
+            exit_with_error(f"Invalid JSON for --inputs: {e}")
+
+    # Trigger the workflow
+    result = trigger_ci_workflow(
+        owner=owner,
+        repo=repo,
+        workflow_file=workflow_file,
+        workflow_definition_ref=workflow_definition_ref,
+        inputs=parsed_inputs,
+    )
+
+    print_json(result.model_dump())
+
+    # If wait is enabled and we have a run_id, poll for completion
+    if wait and result.run_id:
+        print(f"\nWaiting for workflow to complete (timeout: {wait_seconds}s)...")
+        start_time = time.time()
+        poll_interval = 10  # seconds
+
+        while time.time() - start_time < wait_seconds:
+            status_result = check_ci_workflow_status(
+                owner=owner,
+                repo=repo,
+                run_id=result.run_id,
+            )
+
+            if status_result.status == "completed":
+                print(
+                    f"\nWorkflow completed with conclusion: {status_result.conclusion}"
+                )
+                print_json(status_result.model_dump())
+                return
+
+            elapsed = int(time.time() - start_time)
+            print(f"  Status: {status_result.status} (elapsed: {elapsed}s)")
+            time.sleep(poll_interval)
+
+        print(f"\nTimeout reached after {wait_seconds}s. Workflow still running.")
+        # Print final status
+        final_status = check_ci_workflow_status(
+            owner=owner,
+            repo=repo,
+            run_id=result.run_id,
+        )
+        print_json(final_status.model_dump())

airbyte_ops_mcp/cli/registry.py

@@ -28,11 +28,11 @@ from airbyte_ops_mcp.cli._shared import (
     print_json,
     print_success,
 )
-from airbyte_ops_mcp.github_actions import (
+from airbyte_ops_mcp.github_api import (
     get_file_contents_at_ref,
     resolve_github_token,
 )
-from airbyte_ops_mcp.mcp.github import get_docker_image_info
+from airbyte_ops_mcp.mcp.github_actions import get_docker_image_info
 from airbyte_ops_mcp.mcp.prerelease import (
     compute_prerelease_docker_image_tag,
     publish_connector_to_airbyte_registry,

airbyte_ops_mcp/github_actions.py

@@ -1,72 +1,23 @@
 # Copyright (c) 2025 Airbyte, Inc., all rights reserved.
 """GitHub Actions API utilities.
 
-This module provides core utilities for interacting with GitHub Actions workflows,
-including workflow dispatch, run discovery, and authentication. These utilities
+This module provides utilities for interacting with GitHub Actions workflows,
+including workflow dispatch, run discovery, and job status. These utilities
 are used by MCP tools but are not MCP-specific.
+
+For general GitHub API utilities (authentication, PR info, file contents),
+see the github_api module.
 """
 
 from __future__ import annotations
 
-import os
-import shutil
-import subprocess
 import time
 from dataclasses import dataclass
 from datetime import datetime, timedelta
 
 import requests
 
-GITHUB_API_BASE = "https://api.github.com"
-
-
-def resolve_github_token(preferred_env_vars: list[str] | None = None) -> str:
-    """Resolve GitHub token from environment variables or gh CLI.
-
-    Checks environment variables in order of preference, returning the first
-    non-empty value found. If no environment variables are set, attempts to
-    get a token from the gh CLI tool using 'gh auth token'.
-
-    Args:
-        preferred_env_vars: List of environment variable names to check in order.
-            Defaults to ["GITHUB_CI_WORKFLOW_TRIGGER_PAT", "GITHUB_TOKEN"].
-
-    Returns:
-        GitHub token string.
-
-    Raises:
-        ValueError: If no GitHub token is found in env vars or gh CLI.
-    """
-    if preferred_env_vars is None:
-        preferred_env_vars = ["GITHUB_CI_WORKFLOW_TRIGGER_PAT", "GITHUB_TOKEN"]
-
-    # Check environment variables first
-    for env_var in preferred_env_vars:
-        token = os.getenv(env_var)
-        if token:
-            return token
-
-    # Fall back to gh CLI if available
-    gh_path = shutil.which("gh")
-    if gh_path:
-        try:
-            result = subprocess.run(
-                [gh_path, "auth", "token"],
-                capture_output=True,
-                text=True,
-                timeout=5,
-                check=False,
-            )
-            if result.returncode == 0 and result.stdout.strip():
-                return result.stdout.strip()
-        except (subprocess.TimeoutExpired, subprocess.SubprocessError):
-            pass
-
-    env_var_list = ", ".join(preferred_env_vars)
-    raise ValueError(
-        f"No GitHub token found. Set one of: {env_var_list} environment variable, "
-        "or authenticate with 'gh auth login'."
-    )
+from airbyte_ops_mcp.github_api import GITHUB_API_BASE, resolve_github_token
 
 
 @dataclass
@@ -106,51 +57,6 @@ class WorkflowJobInfo:
     """ISO 8601 timestamp when the job completed"""
 
 
-def get_file_contents_at_ref(
-    owner: str,
-    repo: str,
-    path: str,
-    ref: str,
-    token: str | None = None,
-) -> str | None:
-    """Fetch file contents from GitHub at a specific ref.
-
-    Uses the GitHub Contents API to retrieve file contents at a specific
-    commit SHA, branch, or tag. This allows reading files without having
-    the repository checked out locally.
-
-    Args:
-        owner: Repository owner (e.g., "airbytehq")
-        repo: Repository name (e.g., "airbyte")
-        path: Path to the file within the repository
-        ref: Git ref (commit SHA, branch name, or tag)
-        token: GitHub API token (optional for public repos, but recommended
-            to avoid rate limiting)
-
-    Returns:
-        File contents as a string, or None if the file doesn't exist.
-
-    Raises:
-        requests.HTTPError: If API request fails (except 404).
-    """
-    url = f"{GITHUB_API_BASE}/repos/{owner}/{repo}/contents/{path}"
-    headers = {
-        "Accept": "application/vnd.github.raw+json",
-        "X-GitHub-Api-Version": "2022-11-28",
-    }
-    if token:
-        headers["Authorization"] = f"Bearer {token}"
-
-    params = {"ref": ref}
-
-    response = requests.get(url, headers=headers, params=params, timeout=30)
-    if response.status_code == 404:
-        return None
-    response.raise_for_status()
-
-    return response.text
-
-
 def get_workflow_jobs(
     owner: str,
     repo: str,

airbyte_ops_mcp/github_api.py

@@ -1,20 +1,178 @@
 # Copyright (c) 2025 Airbyte, Inc., all rights reserved.
-"""GitHub API utilities for user and comment operations.
+"""GitHub API utilities.
 
-This module provides utilities for interacting with GitHub's REST API
-to retrieve user information and comment details. These utilities are
-used by MCP tools for authorization and audit purposes.
+This module provides core utilities for interacting with GitHub's REST API,
+including authentication, user/comment operations, PR information retrieval,
+and file content fetching. These utilities are used by MCP tools and other
+modules but are not MCP-specific.
 """
 
 from __future__ import annotations
 
+import os
 import re
+import shutil
+import subprocess
 from dataclasses import dataclass
 from urllib.parse import urlparse
 
 import requests
 
-from airbyte_ops_mcp.github_actions import GITHUB_API_BASE, resolve_github_token
+GITHUB_API_BASE = "https://api.github.com"
+
+
+def resolve_github_token(preferred_env_vars: list[str] | None = None) -> str:
+    """Resolve GitHub token from environment variables or gh CLI.
+
+    Checks environment variables in order of preference, returning the first
+    non-empty value found. If no environment variables are set, attempts to
+    get a token from the gh CLI tool using 'gh auth token'.
+
+    Args:
+        preferred_env_vars: List of environment variable names to check in order.
+            Defaults to ["GITHUB_CI_WORKFLOW_TRIGGER_PAT", "GITHUB_TOKEN"].
+
+    Returns:
+        GitHub token string.
+
+    Raises:
+        ValueError: If no GitHub token is found in env vars or gh CLI.
+    """
+    if preferred_env_vars is None:
+        preferred_env_vars = ["GITHUB_CI_WORKFLOW_TRIGGER_PAT", "GITHUB_TOKEN"]
+
+    # Check environment variables first
+    for env_var in preferred_env_vars:
+        token = os.getenv(env_var)
+        if token:
+            return token
+
+    # Fall back to gh CLI if available
+    gh_path = shutil.which("gh")
+    if gh_path:
+        try:
+            result = subprocess.run(
+                [gh_path, "auth", "token"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+                check=False,
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                return result.stdout.strip()
+        except (subprocess.TimeoutExpired, subprocess.SubprocessError):
+            pass
+
+    env_var_list = ", ".join(preferred_env_vars)
+    raise ValueError(
+        f"No GitHub token found. Set one of: {env_var_list} environment variable, "
+        "or authenticate with 'gh auth login'."
+    )
+
+
+@dataclass
+class PRHeadInfo:
+    """Information about a PR's head commit."""
+
+    ref: str
+    """Branch name of the PR's head"""
+
+    sha: str
+    """Full commit SHA of the PR's head"""
+
+    short_sha: str
+    """First 7 characters of the commit SHA"""
+
+
+def get_pr_head_ref(
+    owner: str,
+    repo: str,
+    pr_number: int,
+    token: str,
+) -> PRHeadInfo:
+    """Get the head ref (branch name) and SHA for a PR.
+
+    This is useful for resolving a PR number to the actual branch name,
+    which is required for workflow_dispatch API calls (which don't accept
+    refs/pull/{pr}/head format).
+
+    Args:
+        owner: Repository owner (e.g., "airbytehq")
+        repo: Repository name (e.g., "airbyte")
+        pr_number: Pull request number
+        token: GitHub API token
+
+    Returns:
+        PRHeadInfo with ref (branch name), sha, and short_sha.
+
+    Raises:
+        ValueError: If PR not found.
+        requests.HTTPError: If API request fails.
+    """
+    url = f"{GITHUB_API_BASE}/repos/{owner}/{repo}/pulls/{pr_number}"
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+
+    response = requests.get(url, headers=headers, timeout=30)
+    if response.status_code == 404:
+        raise ValueError(f"PR {owner}/{repo}#{pr_number} not found")
+    response.raise_for_status()
+
+    pr_data = response.json()
+    sha = pr_data["head"]["sha"]
+    return PRHeadInfo(
+        ref=pr_data["head"]["ref"],
+        sha=sha,
+        short_sha=sha[:7],
+    )
+
+
+def get_file_contents_at_ref(
+    owner: str,
+    repo: str,
+    path: str,
+    ref: str,
+    token: str | None = None,
+) -> str | None:
+    """Fetch file contents from GitHub at a specific ref.
+
+    Uses the GitHub Contents API to retrieve file contents at a specific
+    commit SHA, branch, or tag. This allows reading files without having
+    the repository checked out locally.
+
+    Args:
+        owner: Repository owner (e.g., "airbytehq")
+        repo: Repository name (e.g., "airbyte")
+        path: Path to the file within the repository
+        ref: Git ref (commit SHA, branch name, or tag)
+        token: GitHub API token (optional for public repos, but recommended
+            to avoid rate limiting)
+
+    Returns:
+        File contents as a string, or None if the file doesn't exist.
+
+    Raises:
+        requests.HTTPError: If API request fails (except 404).
+    """
+    url = f"{GITHUB_API_BASE}/repos/{owner}/{repo}/contents/{path}"
+    headers = {
+        "Accept": "application/vnd.github.raw+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    params = {"ref": ref}
+
+    response = requests.get(url, headers=headers, params=params, timeout=30)
+    if response.status_code == 404:
+        return None
+    response.raise_for_status()
+
+    return response.text
 
 
 class GitHubCommentParseError(Exception):