airbyte_ops_mcp.mcp.connector_qa

MCP tools for connector quality assurance: regression tests and connector release blocking.

MCP reference

MCP primitives registered by the connector_qa module of the airbyte-internal-ops server: 4 tool(s), 0 prompt(s), 0 resource(s).

Tools (4)

block_connector_release

Block a connector from being released by creating a block-release.yaml marker.

Triggers the block-release.yml workflow in the airbyte monorepo, which creates a marker file, opens a PR, and force-merges it to master. While the marker exists, the publish pipeline will skip the connector with a warning.

Use this after yanking a connector version to prevent CI from accidentally re-publishing the broken code.

Parameters:

Name Type Required Default Description
connector_name string yes — Connector technical name (e.g., source-faker, destination-postgres)
reason string yes — Human-readable reason for blocking the release
yanked_version string | null no null Version that was yanked (for reference)
blocked_by string | null no null Email or identifier of the person requesting the block

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "connector_name": {
      "description": "Connector technical name (e.g., `source-faker`, `destination-postgres`)",
      "type": "string"
    },
    "reason": {
      "description": "Human-readable reason for blocking the release",
      "type": "string"
    },
    "yanked_version": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Version that was yanked (for reference)"
    },
    "blocked_by": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Email or identifier of the person requesting the block"
    }
  },
  "required": [
    "connector_name",
    "reason"
  ],
  "type": "object"
}

Show output JSON schema

{
  "description": "Result of triggering a release block workflow.",
  "properties": {
    "success": {
      "description": "Whether the workflow dispatch succeeded",
      "type": "boolean"
    },
    "message": {
      "description": "Human-readable result message",
      "type": "string"
    },
    "workflow_url": {
      "description": "URL to the workflow",
      "type": "string"
    },
    "run_id": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Workflow run ID, if discovered"
    },
    "run_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "URL to the workflow run"
    }
  },
  "required": [
    "success",
    "message",
    "workflow_url"
  ],
  "type": "object"
}

list_blocked_connector_releases

List connectors that are currently blocked from release.

Searches the airbyte monorepo for block-release.yaml marker files using the GitHub API. Returns a list of blocked connectors, with marker metadata when include_details is True.

Parameters:

Name Type Required Default Description
connector_name string | null no null Optional connector name to check. If not provided, scans all connectors.
include_details boolean no true Whether to fetch and parse each marker file for reason and metadata.

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "connector_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional connector name to check. If not provided, scans all connectors."
    },
    "include_details": {
      "default": true,
      "description": "Whether to fetch and parse each marker file for reason and metadata.",
      "type": "boolean"
    }
  },
  "type": "object"
}

Show output JSON schema

{
  "description": "Result of listing blocked connectors via the GitHub API.",
  "properties": {
    "blocked_connectors": {
      "description": "List of blocked connectors with optional block metadata",
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "type": "array"
    },
    "count": {
      "default": 0,
      "description": "Number of blocked connectors",
      "type": "integer"
    }
  },
  "type": "object"
}

run_regression_tests

Start a regression test run via GitHub Actions workflow.

This tool triggers the regression test workflow which builds the connector from the specified PR and runs tests against it.

Supports both OSS connectors (from airbytehq/airbyte) and enterprise connectors (from airbytehq/airbyte-enterprise). Use the 'repo' parameter to specify which repository contains the connector PR.

  • skip_compare=False (default): Comparison mode - compares the PR version against the baseline (control) version. A read is reported NOT EXERCISED, never a pass, when a stream only the target was configured to read (typically one the PR adds) returns no records: the comparison could not fail it, and the PR's new code path never ran.
  • skip_compare=True: Single-version mode - runs tests without comparison.

If connection_id is provided, config/catalog are fetched from Airbyte Cloud. Otherwise, the default-config GSM integration-test secret is preferred before other connector secrets are tried. EU connections always run masked; raw output is refused. If residency cannot be confirmed, the run fails closed unless output_mode='masked' is explicitly requested.

Returns immediately with a run_id and workflow URL. Check the workflow URL to monitor progress and view results.

Requires GITHUB_CI_WORKFLOW_TRIGGER_PAT or GITHUB_TOKEN environment variable with 'actions:write' permission.

Parameters:

Name Type Required Default Description
connector_name string yes — Connector name to build from source (e.g., 'source-pokeapi'). Required.
pr integer yes — PR number to checkout and build from (e.g., 70847). Required. The PR must be from the repository specified by the 'repo' parameter.
repo enum("airbyte", "airbyte-enterprise") yes — Repository where the connector PR is located. Use 'airbyte' for OSS connectors (default) or 'airbyte-enterprise' for enterprise connectors.
connection_id string | null no null Airbyte Cloud connection ID to fetch config/catalog from. If not provided, prefers the default-config GSM integration-test secret before trying other connector secrets.
skip_compare boolean no false If True, skip comparison and run single-version tests only. If False (default), run comparison tests (target vs control versions).
skip_read_action boolean no false If True, skip the read action (run only spec, check, discover). If False (default), run all verbs including read.
override_test_image string | null no null Override test connector image with tag (e.g., 'airbyte/source-github:1.0.0'). Ignored if skip_compare=False.
override_control_image string | null no null Override control connector image (baseline version) with tag. Ignored if skip_compare=True.
workspace_id string | enum("266ebdfe-0d7b-4540-9817-de7e4505ba61") | null no null Optional Airbyte Cloud workspace ID (UUID) or alias. If provided with connection_id, validates that the connection belongs to this workspace before triggering tests. Accepts '@devin-ai-sandbox' as an alias for the Devin AI sandbox workspace.
selected_streams array<string> | null no null List of stream names to include in the read. Only these streams will be included in the configured catalog. This is useful to limit data volume by testing only specific streams. If not provided, all streams are tested.
discover_missing_streams boolean no false Read selected streams the connection does not sync yet, such as a stream the PR adds. READ discovers them on the PR version and adds them to the catalog. A stream the control version does not discover has no control side and is read by the target only; when every selected stream is new, also select one stream the connection already syncs, so the control reads something. Needs selected_streams.
injected_sync_mode enum("full_refresh", "incremental") | null no null Sync mode for streams added by discover_missing_streams. Default prefers full refresh; incremental uses the stream's default cursor.
enable_debug_logs boolean no false Enable debug-level logging for regression test output. Also passed as LOG_LEVEL=DEBUG to the connector Docker container. Debug logs are off on masked runs for now: with output_mode='masked', or on a connection_id run that leaves output_mode unset, the run goes ahead with them switched off.
disable_http_replay boolean no false Run both connector versions against the live API instead of replaying the control run's recorded HTTP responses. Replay is on by default and is what makes a record difference attributable to the version under test rather than to upstream drift, so only disable it for a connector whose traffic cannot be replayed faithfully. Comparison mode only.
with_state boolean | null no null Fetch and pass the connection's current state to the read command, producing a warm read instead of a cold read. Defaults to True when connection_id is provided, False otherwise. Has no effect unless the command is read.
max_records integer | null no null Stop each side of the read when a RECORD message arrives past this many in total, across its streams; a side that emits no more than this many reads in full. Bounds a read of a large connection; a read the cap stops is a smoke test of the records read before the cap, not a full regression, and the report says so on each side that stopped early. The two sides can stop at different records. At least 1. Leave unset for no cap. Has no effect unless the command is read.
state_json string | null no null Airbyte state to seed the read with, as a JSON string holding a non-empty list of STREAM state messages (the shape get_connection_state returns; a GLOBAL or LEGACY state is refused). Both versions then start from these cursors instead of the connection's stored state, so with_state is ignored. Use it to replay a sync from a chosen point, for example the state a customer's failing sync started from. Needs connection_id: the connection's catalog says which streams sync incrementally, and without one every stream is read full_refresh and the seed would be ignored. A connector may clamp a seed to what its API still serves. The workflow keeps the seed out of the job log, and the report names the seeded streams but none of its values. Has no effect unless the command is read.
output_mode enum("masked", "raw") | null no null How the connector output is written to the run artifacts. masked masks every record value as a type-and-length token as it is written, masks primary keys, keeps a cursor readable only when its declared type is an integer or a date, and keeps only the length of DEBUG, TRACE, ERROR and FATAL log messages, stack traces, error internals and every line of the connector's stderr; INFO and WARN log messages, a TRACE error's message and the CONNECTION_STATUS message stay readable. raw keeps the output as emitted. Leave unset for the default: masked on a connection_id run, which reads a customer's data, and raw otherwise. raw is an explicit opt-in for US connections and is refused for EU connections. A raw request also fails closed when residency cannot be confirmed. Pass masked to mask a GSM run. Debug logs are off on masked runs for now, so a masked run switches enable_debug_logs off.
read_timeout_minutes integer | null no null Minutes the read may take, from its start to its report; in comparison mode both versions share them. A read still running at the end is stopped, compared and reported as incomplete. Raise it for a connection too large to read in the default 170 minutes. From 1 to 300, so the run stays inside GitHub's six-hour job limit with fifty minutes for the other steps. Leave unset for the default. Has no effect unless the command is read.

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "connector_name": {
      "description": "Connector name to build from source (e.g., 'source-pokeapi'). Required.",
      "type": "string"
    },
    "pr": {
      "description": "PR number to checkout and build from (e.g., 70847). Required. The PR must be from the repository specified by the 'repo' parameter.",
      "type": "integer"
    },
    "repo": {
      "description": "Repository where the connector PR is located. Use 'airbyte' for OSS connectors (default) or 'airbyte-enterprise' for enterprise connectors.",
      "enum": [
        "airbyte",
        "airbyte-enterprise"
      ],
      "type": "string"
    },
    "connection_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Airbyte Cloud connection ID to fetch config/catalog from. If not provided, prefers the default-config GSM integration-test secret before trying other connector secrets."
    },
    "skip_compare": {
      "default": false,
      "description": "If True, skip comparison and run single-version tests only. If False (default), run comparison tests (target vs control versions).",
      "type": "boolean"
    },
    "skip_read_action": {
      "default": false,
      "description": "If True, skip the read action (run only spec, check, discover). If False (default), run all verbs including read.",
      "type": "boolean"
    },
    "override_test_image": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Override test connector image with tag (e.g., 'airbyte/source-github:1.0.0'). Ignored if skip_compare=False."
    },
    "override_control_image": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Override control connector image (baseline version) with tag. Ignored if skip_compare=True."
    },
    "workspace_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "description": "Workspace ID aliases that can be used in place of UUIDs.\n\nEach member's name is the alias (e.g., \"@devin-ai-sandbox\") and its value\nis the actual workspace UUID. Use `WorkspaceAliasEnum.resolve()` to\nresolve aliases to actual IDs.",
          "enum": [
            "266ebdfe-0d7b-4540-9817-de7e4505ba61"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional Airbyte Cloud workspace ID (UUID) or alias. If provided with connection_id, validates that the connection belongs to this workspace before triggering tests. Accepts '@devin-ai-sandbox' as an alias for the Devin AI sandbox workspace."
    },
    "selected_streams": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "List of stream names to include in the read. Only these streams will be included in the configured catalog. This is useful to limit data volume by testing only specific streams. If not provided, all streams are tested."
    },
    "discover_missing_streams": {
      "default": false,
      "description": "Read selected streams the connection does not sync yet, such as a stream the PR adds. READ discovers them on the PR version and adds them to the catalog. A stream the control version does not discover has no control side and is read by the target only; when every selected stream is new, also select one stream the connection already syncs, so the control reads something. Needs selected_streams.",
      "type": "boolean"
    },
    "injected_sync_mode": {
      "anyOf": [
        {
          "enum": [
            "full_refresh",
            "incremental"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Sync mode for streams added by discover_missing_streams. Default prefers full refresh; incremental uses the stream's default cursor."
    },
    "enable_debug_logs": {
      "default": false,
      "description": "Enable debug-level logging for regression test output. Also passed as `LOG_LEVEL=DEBUG` to the connector Docker container. Debug logs are off on masked runs for now: with `output_mode='masked'`, or on a `connection_id` run that leaves `output_mode` unset, the run goes ahead with them switched off.",
      "type": "boolean"
    },
    "disable_http_replay": {
      "default": false,
      "description": "Run both connector versions against the live API instead of replaying the control run's recorded HTTP responses. Replay is on by default and is what makes a record difference attributable to the version under test rather than to upstream drift, so only disable it for a connector whose traffic cannot be replayed faithfully. Comparison mode only.",
      "type": "boolean"
    },
    "with_state": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Fetch and pass the connection's current state to the read command, producing a warm read instead of a cold read. Defaults to `True` when `connection_id` is provided, `False` otherwise. Has no effect unless the command is `read`."
    },
    "max_records": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Stop each side of the read when a RECORD message arrives past this many in total, across its streams; a side that emits no more than this many reads in full. Bounds a read of a large connection; a read the cap stops is a smoke test of the records read before the cap, not a full regression, and the report says so on each side that stopped early. The two sides can stop at different records. At least 1. Leave unset for no cap. Has no effect unless the command is `read`."
    },
    "state_json": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Airbyte state to seed the read with, as a JSON string holding a non-empty list of STREAM state messages (the shape `get_connection_state` returns; a GLOBAL or LEGACY state is refused). Both versions then start from these cursors instead of the connection's stored state, so `with_state` is ignored. Use it to replay a sync from a chosen point, for example the state a customer's failing sync started from. Needs `connection_id`: the connection's catalog says which streams sync incrementally, and without one every stream is read full_refresh and the seed would be ignored. A connector may clamp a seed to what its API still serves. The workflow keeps the seed out of the job log, and the report names the seeded streams but none of its values. Has no effect unless the command is `read`."
    },
    "output_mode": {
      "anyOf": [
        {
          "enum": [
            "masked",
            "raw"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "How the connector output is written to the run artifacts. `masked` masks every record value as a type-and-length token as it is written, masks primary keys, keeps a cursor readable only when its declared type is an integer or a date, and keeps only the length of DEBUG, TRACE, ERROR and FATAL log messages, stack traces, error internals and every line of the connector's stderr; INFO and WARN log messages, a TRACE error's message and the CONNECTION_STATUS message stay readable. `raw` keeps the output as emitted. Leave unset for the default: `masked` on a `connection_id` run, which reads a customer's data, and `raw` otherwise. `raw` is an explicit opt-in for US connections and is refused for EU connections. A raw request also fails closed when residency cannot be confirmed. Pass `masked` to mask a GSM run. Debug logs are off on masked runs for now, so a masked run switches `enable_debug_logs` off."
    },
    "read_timeout_minutes": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Minutes the read may take, from its start to its report; in comparison mode both versions share them. A read still running at the end is stopped, compared and reported as incomplete. Raise it for a connection too large to read in the default 170 minutes. From 1 to 300, so the run stays inside GitHub's six-hour job limit with fifty minutes for the other steps. Leave unset for the default. Has no effect unless the command is `read`."
    }
  },
  "required": [
    "connector_name",
    "pr",
    "repo"
  ],
  "type": "object"
}

Show output JSON schema

{
  "description": "Response from starting a regression test via GitHub Actions workflow.",
  "properties": {
    "run_id": {
      "description": "Unique identifier for the test run (internal tracking ID)",
      "type": "string"
    },
    "status": {
      "description": "Initial status of the test run",
      "enum": [
        "queued",
        "running",
        "succeeded",
        "failed"
      ],
      "type": "string"
    },
    "message": {
      "description": "Human-readable status message",
      "type": "string"
    },
    "workflow_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "URL to view the GitHub Actions workflow file"
    },
    "github_run_id": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "GitHub Actions workflow run ID (use with check_ci_workflow_status)"
    },
    "github_run_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Direct URL to the GitHub Actions workflow run"
    }
  },
  "required": [
    "run_id",
    "status",
    "message"
  ],
  "type": "object"
}

unblock_connector_release

Remove a release block for a connector by deleting its block-release.yaml marker.

Triggers the block-release.yml workflow with action=unblock, which removes the marker file, opens a PR, and force-merges it to master. After this, the connector can be published normally again.

Parameters:

Name Type Required Default Description
connector_name string yes — Connector technical name (e.g., source-faker, destination-postgres)

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "connector_name": {
      "description": "Connector technical name (e.g., `source-faker`, `destination-postgres`)",
      "type": "string"
    }
  },
  "required": [
    "connector_name"
  ],
  "type": "object"
}

Show output JSON schema

{
  "description": "Result of triggering a release unblock workflow.",
  "properties": {
    "success": {
      "description": "Whether the workflow dispatch succeeded",
      "type": "boolean"
    },
    "message": {
      "description": "Human-readable result message",
      "type": "string"
    },
    "workflow_url": {
      "description": "URL to the workflow",
      "type": "string"
    },
    "run_id": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Workflow run ID, if discovered"
    },
    "run_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "URL to the workflow run"
    }
  },
  "required": [
    "success",
    "message",
    "workflow_url"
  ],
  "type": "object"
}

   1# Copyright (c) 2025 Airbyte, Inc., all rights reserved.
   2"""MCP tools for connector quality assurance: regression tests and connector release blocking.
   3
   4## MCP reference
   5
   6.. include:: ../../../docs/mcp-generated/connector_qa.md
   7    :start-line: 2
   8"""
   9
  10from __future__ import annotations
  11
  12__all__: list[str] = []
  13
  14import logging
  15import uuid
  16from datetime import datetime
  17from enum import Enum
  18from typing import Annotated, Any, Literal, NamedTuple
  19from urllib.parse import quote
  20
  21import requests
  22import yaml
  23from airbyte.cloud import CloudWorkspace
  24from airbyte.exceptions import (
  25    AirbyteMissingResourceError,
  26    AirbyteNoCloudCredentialsError,
  27    AirbyteWorkspaceMismatchError,
  28    PyAirbyteSecretNotFoundError,
  29)
  30from fastmcp import Context, FastMCP
  31from fastmcp_extensions import mcp_tool, register_mcp_tools
  32from pydantic import BaseModel, Field
  33
  34from airbyte_ops_mcp.cloud_admin.auth import CloudAuthError
  35from airbyte_ops_mcp.cloud_admin.version_overrides import ResolvedCloudAuth
  36from airbyte_ops_mcp.constants import WorkspaceAliasEnum
  37from airbyte_ops_mcp.github_actions import (
  38    resolve_default_workflow_branch,
  39    trigger_workflow_dispatch,
  40)
  41from airbyte_ops_mcp.github_api import (
  42    GITHUB_API_BASE,
  43    get_file_contents_at_ref,
  44    resolve_ci_trigger_github_token,
  45)
  46from airbyte_ops_mcp.mcp.cloud_auth import resolve_cloud_auth
  47from airbyte_ops_mcp.mcp.connector_versions import ConnectorRepo
  48from airbyte_ops_mcp.prod_db_access.queries import query_connection_workspace_details
  49from airbyte_ops_mcp.regression_tests.models import OUTPUT_MODES
  50from airbyte_ops_mcp.regression_tests.read_inputs import READ_TIMEOUT_MINUTES_MAX
  51from airbyte_ops_mcp.regression_tests.seed_state import (
  52    SEED_STATE_NEEDS_CONNECTION,
  53    seed_state_error,
  54)
  55
  56logger = logging.getLogger(__name__)
  57
  58REGRESSION_TEST_REPO_OWNER = "airbytehq"
  59
  60REGRESSION_TEST_REPO_NAME = "airbyte-ops-mcp"
  61
  62REGRESSION_TEST_DEFAULT_BRANCH = "main"
  63
  64REGRESSION_TEST_WORKFLOW_FILE = "connector-regression-test.yml"
  65
  66_MISSING_CLOUD_AUTH_MESSAGE = (
  67    "Airbyte Cloud credentials are required for workspace validation. "
  68    "Provide an Authorization bearer token, both "
  69    "X-Airbyte-Cloud-Client-Id and X-Airbyte-Cloud-Client-Secret headers, or "
  70    "AIRBYTE_CLOUD_CLIENT_ID and AIRBYTE_CLOUD_CLIENT_SECRET environment variables."
  71)
  72
  73
  74def validate_connection_workspace(
  75    connection_id: str,
  76    workspace_id: str,
  77    auth: ResolvedCloudAuth,
  78) -> None:
  79    """Validate that a connection belongs to the expected workspace.
  80
  81    Uses PyAirbyte's CloudConnection.check_is_valid() method to verify that
  82    the connection exists and belongs to the specified workspace.
  83
  84    Raises:
  85        `AirbyteWorkspaceMismatchError`: If connection belongs to a different workspace.
  86        `AirbyteMissingResourceError`: If connection is not found.
  87    """
  88    workspace = CloudWorkspace(
  89        workspace_id=workspace_id,
  90        client_id=auth.client_id,
  91        client_secret=auth.client_secret,
  92        bearer_token=auth.bearer_token,
  93    )
  94    connection = workspace.get_connection(connection_id)
  95    connection.check_is_valid()
  96
  97
  98class _EuDataPlaneCheck(NamedTuple):
  99    """Outcome of the trigger-time EU data-plane lookup.
 100
 101    `skipped` is the reason the check could not decide, or `None` when it did.
 102    """
 103
 104    is_eu: bool
 105    skipped: str | None = None
 106
 107
 108def _check_eu_data_plane(connection_id: str) -> _EuDataPlaneCheck:
 109    """Look up the connection's data plane in the Prod DB replica.
 110
 111    `is_eu` is True only when the replica returns a row whose dataplane group
 112    is named exactly `EU`. When the check cannot decide, `is_eu` is False and
 113    `skipped` says why, so the caller can report the unresolved residency and
 114    fail closed unless masking was explicitly requested. The lookup exception
 115    text is kept out of the response because it can contain SQL or connection
 116    details; the exception class is safe to report.
 117
 118    A missing row (an unknown ID, or a tombstoned source or workspace), or a
 119    workspace without a named dataplane group, cannot be treated as US. A NULL
 120    or empty name counts as unknown, not as US: this is a residency gate,
 121    unlike `tier_cache`, which defaults a missing group to US for tier lookups.
 122
 123    This lookup and the secret retriever differ in three cases:
 124
 125    - a tombstoned source or workspace: no row here, while the retriever
 126      ignores tombstones and still refuses a deleted EU connection;
 127    - a workspace with no dataplane group, or a group with an empty name: a
 128      NULL or empty name here; the retriever refuses the missing group;
 129    - a custom EU group with a name other than exactly `EU` is not recognized.
 130    """
 131    try:
 132        rows = query_connection_workspace_details([connection_id])
 133    except Exception as exc:
 134        return _skip_eu_check(
 135            connection_id,
 136            f"the Prod DB replica lookup failed ({type(exc).__name__})",
 137            detail=f": {exc}",
 138        )
 139    if not rows:
 140        return _skip_eu_check(
 141            connection_id,
 142            "the connection is not in the Prod DB replica "
 143            "(unknown ID, or a tombstoned source or workspace)",
 144        )
 145    dataplane_name = rows[0].get("dataplane_name")
 146    if not dataplane_name or not dataplane_name.strip():
 147        return _skip_eu_check(
 148            connection_id,
 149            "the workspace has no named dataplane group in the Prod DB replica",
 150        )
 151    return _EuDataPlaneCheck(is_eu=dataplane_name == "EU")
 152
 153
 154def _skip_eu_check(
 155    connection_id: str, reason: str, detail: str = ""
 156) -> _EuDataPlaneCheck:
 157    """Fail open with `reason` in the response; `detail` goes to the log only."""
 158    logger.warning(
 159        f"EU data-plane check skipped for connection {connection_id}: {reason}{detail}"
 160    )
 161    return _EuDataPlaneCheck(is_eu=False, skipped=reason)
 162
 163
 164def _get_workflow_run_status(
 165    owner: str,
 166    repo: str,
 167    run_id: int,
 168    token: str,
 169) -> dict[str, Any]:
 170    """Get workflow run details from GitHub API.
 171
 172    Args:
 173        owner: Repository owner (e.g., "airbytehq")
 174        repo: Repository name (e.g., "airbyte-ops-mcp")
 175        run_id: Workflow run ID
 176        token: GitHub API token
 177
 178    Returns:
 179        Workflow run data dictionary.
 180
 181    Raises:
 182        ValueError: If workflow run not found.
 183        requests.HTTPError: If API request fails.
 184    """
 185    url = f"{GITHUB_API_BASE}/repos/{owner}/{repo}/actions/runs/{run_id}"
 186    headers = {
 187        "Authorization": f"Bearer {token}",
 188        "Accept": "application/vnd.github+json",
 189        "X-GitHub-Api-Version": "2022-11-28",
 190    }
 191
 192    response = requests.get(url, headers=headers, timeout=30)
 193    if response.status_code == 404:
 194        raise ValueError(f"Workflow run {owner}/{repo}/actions/runs/{run_id} not found")
 195    response.raise_for_status()
 196
 197    return response.json()
 198
 199
 200class TestRunStatus(str, Enum):
 201    """Status of a test run."""
 202
 203    QUEUED = "queued"
 204    RUNNING = "running"
 205    SUCCEEDED = "succeeded"
 206    FAILED = "failed"
 207
 208
 209class TestOutcome(str, Enum):
 210    """Outcome of a test (execution or comparison)."""
 211
 212    PENDING = "pending"
 213    RUNNING = "running"
 214    PASSED = "passed"
 215    FAILED = "failed"
 216    SKIPPED = "skipped"
 217
 218
 219class ValidationResultModel(BaseModel):
 220    """Result of a single validation check."""
 221
 222    name: str = Field(description="Name of the validation check")
 223    passed: bool = Field(description="Whether the validation passed")
 224    message: str = Field(description="Human-readable result message")
 225    errors: list[str] = Field(
 226        default_factory=list,
 227        description="List of error messages if validation failed",
 228    )
 229
 230
 231class StreamComparisonResultModel(BaseModel):
 232    """Result of comparing a single stream between control and target."""
 233
 234    stream_name: str = Field(description="Name of the stream")
 235    passed: bool = Field(description="Whether all comparisons passed")
 236    control_record_count: int = Field(description="Number of records in control")
 237    target_record_count: int = Field(description="Number of records in target")
 238    missing_pks: list[str] = Field(
 239        default_factory=list,
 240        description="Primary keys present in control but missing in target",
 241    )
 242    differing_records: int = Field(
 243        default=0,
 244        description="Number of records that differ between control and target",
 245    )
 246    message: str = Field(description="Human-readable comparison summary")
 247
 248
 249class RegressionTestExecutionResult(BaseModel):
 250    """Results from executing the connector (validations and record counts)."""
 251
 252    outcome: TestOutcome = Field(description="Outcome of the execution")
 253    catalog_validations: list[ValidationResultModel] = Field(
 254        default_factory=list,
 255        description="Results of catalog validation checks",
 256    )
 257    record_validations: list[ValidationResultModel] = Field(
 258        default_factory=list,
 259        description="Results of record validation checks",
 260    )
 261    record_count: int = Field(
 262        default=0,
 263        description="Total number of records read",
 264    )
 265    error_message: str | None = Field(
 266        default=None,
 267        description="Error message if the execution failed",
 268    )
 269
 270
 271class RegressionTestComparisonResult(BaseModel):
 272    """Results from comparing target vs control connector versions."""
 273
 274    outcome: TestOutcome = Field(description="Outcome of the comparison")
 275    baseline_version: str | None = Field(
 276        default=None,
 277        description="Version of the baseline (control) connector",
 278    )
 279    stream_comparisons: list[StreamComparisonResultModel] = Field(
 280        default_factory=list,
 281        description="Per-stream comparison results",
 282    )
 283    error_message: str | None = Field(
 284        default=None,
 285        description="Error message if the comparison failed",
 286    )
 287
 288
 289class RegressionTestResult(BaseModel):
 290    """Complete result of a regression test run."""
 291
 292    run_id: str = Field(description="Unique identifier for this test run")
 293    connection_id: str = Field(description="The connection being tested")
 294    workspace_id: str = Field(description="The workspace containing the connection")
 295    status: TestRunStatus = Field(description="Overall status of the test run")
 296    target_version: str | None = Field(
 297        default=None,
 298        description="Version of the target connector being tested",
 299    )
 300    baseline_version: str | None = Field(
 301        default=None,
 302        description="Version of the baseline connector (if comparison mode)",
 303    )
 304    evaluation_mode: str = Field(
 305        default="diagnostic",
 306        description="Evaluation mode used (diagnostic or strict)",
 307    )
 308    compare_versions: bool = Field(
 309        default=False,
 310        description="Whether comparison mode was used (target vs control)",
 311    )
 312    execution_result: RegressionTestExecutionResult | None = Field(
 313        default=None,
 314        description="Results from executing the connector (validations and record counts)",
 315    )
 316    comparison_result: RegressionTestComparisonResult | None = Field(
 317        default=None,
 318        description="Results from comparing target vs control connector versions",
 319    )
 320    artifacts: dict[str, str] = Field(
 321        default_factory=dict,
 322        description="Paths to generated artifacts (JSONL, DuckDB, HAR files)",
 323    )
 324    human_summary: str = Field(
 325        default="",
 326        description="Human-readable summary of the test results",
 327    )
 328    started_at: datetime | None = Field(
 329        default=None,
 330        description="When the test run started",
 331    )
 332    completed_at: datetime | None = Field(
 333        default=None,
 334        description="When the test run completed",
 335    )
 336    test_description: str | None = Field(
 337        default=None,
 338        description="Optional description/context for this test run",
 339    )
 340
 341
 342class RunRegressionTestsResponse(BaseModel):
 343    """Response from starting a regression test via GitHub Actions workflow."""
 344
 345    run_id: str = Field(
 346        description="Unique identifier for the test run (internal tracking ID)"
 347    )
 348    status: TestRunStatus = Field(description="Initial status of the test run")
 349    message: str = Field(description="Human-readable status message")
 350    workflow_url: str | None = Field(
 351        default=None,
 352        description="URL to view the GitHub Actions workflow file",
 353    )
 354    github_run_id: int | None = Field(
 355        default=None,
 356        description="GitHub Actions workflow run ID (use with check_ci_workflow_status)",
 357    )
 358    github_run_url: str | None = Field(
 359        default=None,
 360        description="Direct URL to the GitHub Actions workflow run",
 361    )
 362
 363
 364def _api_error_message(exc: requests.RequestException) -> str:
 365    """GitHub's own words for a failed request, or the exception's.
 366
 367    A dispatch whose inputs pass GitHub's 65,535-character limit, which a
 368    large `state_json` can, comes back as a 422 whose body says so.
 369    """
 370    response = exc.response
 371    if response is not None:
 372        try:
 373            body = response.json()
 374        except ValueError:
 375            body = None
 376        message = body.get("message") if isinstance(body, dict) else None
 377        if message:
 378            return f"{response.status_code} {message}"
 379    return str(exc)
 380
 381
 382@mcp_tool(
 383    read_only=False,
 384    idempotent=False,
 385    open_world=True,
 386)
 387def run_regression_tests(
 388    connector_name: Annotated[
 389        str,
 390        "Connector name to build from source (e.g., 'source-pokeapi'). Required.",
 391    ],
 392    pr: Annotated[
 393        int,
 394        "PR number to checkout and build from (e.g., 70847). Required. "
 395        "The PR must be from the repository specified by the 'repo' parameter.",
 396    ],
 397    repo: Annotated[
 398        ConnectorRepo,
 399        "Repository where the connector PR is located. "
 400        "Use 'airbyte' for OSS connectors (default) or 'airbyte-enterprise' for enterprise connectors.",
 401    ],
 402    connection_id: Annotated[
 403        str | None,
 404        "Airbyte Cloud connection ID to fetch config/catalog from. "
 405        "If not provided, prefers the default-config GSM integration-test secret "
 406        "before trying other connector secrets.",
 407    ] = None,
 408    skip_compare: Annotated[
 409        bool,
 410        "If True, skip comparison and run single-version tests only. "
 411        "If False (default), run comparison tests (target vs control versions).",
 412    ] = False,
 413    skip_read_action: Annotated[
 414        bool,
 415        "If True, skip the read action (run only spec, check, discover). "
 416        "If False (default), run all verbs including read.",
 417    ] = False,
 418    override_test_image: Annotated[
 419        str | None,
 420        "Override test connector image with tag (e.g., 'airbyte/source-github:1.0.0'). "
 421        "Ignored if skip_compare=False.",
 422    ] = None,
 423    override_control_image: Annotated[
 424        str | None,
 425        "Override control connector image (baseline version) with tag. "
 426        "Ignored if skip_compare=True.",
 427    ] = None,
 428    workspace_id: Annotated[
 429        str | WorkspaceAliasEnum | None,
 430        "Optional Airbyte Cloud workspace ID (UUID) or alias. If provided with connection_id, "
 431        "validates that the connection belongs to this workspace before triggering tests. "
 432        "Accepts '@devin-ai-sandbox' as an alias for the Devin AI sandbox workspace.",
 433    ] = None,
 434    selected_streams: Annotated[
 435        list[str] | None,
 436        "List of stream names to include in the read. Only these streams will be included "
 437        "in the configured catalog. This is useful to limit data volume by testing only "
 438        "specific streams. If not provided, all streams are tested.",
 439    ] = None,
 440    discover_missing_streams: Annotated[
 441        bool,
 442        "Read selected streams the connection does not sync yet, such as a stream "
 443        "the PR adds. READ discovers them on the PR version and adds them to the "
 444        "catalog. A stream the control version does not discover has no control "
 445        "side and is read by the target only; when every selected stream is new, "
 446        "also select one stream the connection already syncs, so the control reads "
 447        "something. Needs selected_streams.",
 448    ] = False,
 449    injected_sync_mode: Annotated[
 450        Literal["full_refresh", "incremental"] | None,
 451        "Sync mode for streams added by discover_missing_streams. Default prefers "
 452        "full refresh; incremental uses the stream's default cursor.",
 453    ] = None,
 454    enable_debug_logs: Annotated[
 455        bool,
 456        "Enable debug-level logging for regression test output. "
 457        "Also passed as `LOG_LEVEL=DEBUG` to the connector Docker container. "
 458        "Debug logs are off on masked runs for now: with `output_mode='masked'`, "
 459        "or on a `connection_id` run that leaves `output_mode` unset, the run "
 460        "goes ahead with them switched off.",
 461    ] = False,
 462    disable_http_replay: Annotated[
 463        bool,
 464        "Run both connector versions against the live API instead of replaying the "
 465        "control run's recorded HTTP responses. Replay is on by default and is what "
 466        "makes a record difference attributable to the version under test rather "
 467        "than to upstream drift, so only disable it for a connector whose traffic "
 468        "cannot be replayed faithfully. Comparison mode only.",
 469    ] = False,
 470    with_state: Annotated[
 471        bool | None,
 472        "Fetch and pass the connection's current state to the read command, "
 473        "producing a warm read instead of a cold read. Defaults to `True` when "
 474        "`connection_id` is provided, `False` otherwise. Has no effect unless "
 475        "the command is `read`.",
 476    ] = None,
 477    max_records: Annotated[
 478        int | None,
 479        "Stop each side of the read when a RECORD message arrives past this "
 480        "many in total, across its streams; a side that emits no more than "
 481        "this many reads in full. Bounds a read of a large connection; a read "
 482        "the cap stops is a smoke test of the records read before the cap, not "
 483        "a full regression, and the report says so on each side that stopped "
 484        "early. The two sides can stop at different records. At least 1. Leave "
 485        "unset for no cap. Has no effect unless the command is `read`.",
 486    ] = None,
 487    state_json: Annotated[
 488        str | None,
 489        "Airbyte state to seed the read with, as a JSON string holding a "
 490        "non-empty list of STREAM state messages (the shape "
 491        "`get_connection_state` returns; a GLOBAL or LEGACY state is refused). "
 492        "Both versions then start from these cursors instead of the "
 493        "connection's stored state, so `with_state` is ignored. Use it to replay "
 494        "a sync from a chosen point, for example the state a customer's failing "
 495        "sync started from. Needs `connection_id`: the connection's catalog says "
 496        "which streams sync incrementally, and without one every stream is read "
 497        "full_refresh and the seed would be ignored. A connector may clamp a "
 498        "seed to what its API still serves. The workflow keeps the seed out of "
 499        "the job log, and the report names the seeded streams but none of its "
 500        "values. Has no effect unless the command is `read`.",
 501    ] = None,
 502    output_mode: Annotated[
 503        Literal["masked", "raw"] | None,
 504        "How the connector output is written to the run artifacts. `masked` "
 505        "masks every record value as a type-and-length token as it is written, "
 506        "masks primary keys, keeps a cursor readable only when its declared type "
 507        "is an integer or a date, and keeps only the length of DEBUG, TRACE, "
 508        "ERROR and FATAL log messages, stack traces, error internals and every "
 509        "line of the connector's stderr; INFO and WARN log messages, a TRACE "
 510        "error's message and the CONNECTION_STATUS message stay readable. "
 511        "`raw` keeps the output as emitted. "
 512        "Leave unset for the default: `masked` on a `connection_id` run, which "
 513        "reads a customer's data, and `raw` otherwise. `raw` is an explicit "
 514        "opt-in for US connections and is refused for EU connections. A raw "
 515        "request also fails closed when residency cannot be confirmed. Pass "
 516        "`masked` to mask a GSM run. Debug logs are off on masked runs for now, "
 517        "so a masked run switches `enable_debug_logs` off.",
 518    ] = None,
 519    read_timeout_minutes: Annotated[
 520        int | None,
 521        "Minutes the read may take, from its start to its report; in comparison "
 522        "mode both versions share them. A read still running at the end is "
 523        "stopped, compared and reported as incomplete. Raise it for a connection "
 524        "too large to read in the default 170 minutes. From 1 to 300, so the run "
 525        "stays inside GitHub's six-hour job limit with fifty minutes for the "
 526        "other steps. Leave unset for the default. Has no effect unless the "
 527        "command is `read`.",
 528    ] = None,
 529    *,
 530    ctx: Context,
 531) -> RunRegressionTestsResponse:
 532    """Start a regression test run via GitHub Actions workflow.
 533
 534    This tool triggers the regression test workflow which builds the connector
 535    from the specified PR and runs tests against it.
 536
 537    Supports both OSS connectors (from airbytehq/airbyte) and enterprise connectors
 538    (from airbytehq/airbyte-enterprise). Use the 'repo' parameter to specify which
 539    repository contains the connector PR.
 540
 541    - skip_compare=False (default): Comparison mode - compares the PR version
 542      against the baseline (control) version. A read is reported NOT EXERCISED,
 543      never a pass, when a stream only the target was configured to read
 544      (typically one the PR adds) returns no records: the comparison could not
 545      fail it, and the PR's new code path never ran.
 546    - skip_compare=True: Single-version mode - runs tests without comparison.
 547
 548    If connection_id is provided, config/catalog are fetched from Airbyte Cloud.
 549    Otherwise, the default-config GSM integration-test secret is preferred before
 550    other connector secrets are tried. EU connections always run masked; raw
 551    output is refused. If residency cannot be confirmed, the run fails closed
 552    unless output_mode='masked' is explicitly requested.
 553
 554    Returns immediately with a run_id and workflow URL. Check the workflow URL
 555    to monitor progress and view results.
 556
 557    Requires GITHUB_CI_WORKFLOW_TRIGGER_PAT or GITHUB_TOKEN environment variable
 558    with 'actions:write' permission.
 559    """
 560    # Resolve workspace ID alias
 561    resolved_workspace_id = WorkspaceAliasEnum.resolve(workspace_id)
 562
 563    # Generate a unique run ID for tracking
 564    run_id = str(uuid.uuid4())
 565
 566    if max_records is not None and max_records < 1:
 567        return RunRegressionTestsResponse(
 568            run_id=run_id,
 569            status=TestRunStatus.FAILED,
 570            message=f"max_records must be at least 1, got {max_records}",
 571            workflow_url=None,
 572        )
 573
 574    if output_mode is not None and output_mode not in OUTPUT_MODES:
 575        return RunRegressionTestsResponse(
 576            run_id=run_id,
 577            status=TestRunStatus.FAILED,
 578            message=(
 579                f"output_mode must be one of {', '.join(OUTPUT_MODES)}, "
 580                f"got {output_mode!r}"
 581            ),
 582            workflow_url=None,
 583        )
 584
 585    if read_timeout_minutes is not None and not (
 586        1 <= read_timeout_minutes <= READ_TIMEOUT_MINUTES_MAX
 587    ):
 588        return RunRegressionTestsResponse(
 589            run_id=run_id,
 590            status=TestRunStatus.FAILED,
 591            message=(
 592                "read_timeout_minutes must be from 1 to "
 593                f"{READ_TIMEOUT_MINUTES_MAX}, got {read_timeout_minutes}"
 594            ),
 595            workflow_url=None,
 596        )
 597
 598    # A seed is judged here, where a mistake costs a message rather than a
 599    # build; the workflow judges it again before SPEC, by the same rules, for
 600    # a direct dispatch.
 601    if state_json is not None:
 602        seed_error = (
 603            SEED_STATE_NEEDS_CONNECTION
 604            if not connection_id
 605            else seed_state_error(state_json)
 606        )
 607        if seed_error:
 608            return RunRegressionTestsResponse(
 609                run_id=run_id,
 610                status=TestRunStatus.FAILED,
 611                message=seed_error,
 612                workflow_url=None,
 613            )
 614
 615    # Get GitHub token
 616    try:
 617        token = resolve_ci_trigger_github_token()
 618    except ValueError as e:
 619        return RunRegressionTestsResponse(
 620            run_id=run_id,
 621            status=TestRunStatus.FAILED,
 622            message=str(e),
 623            workflow_url=None,
 624        )
 625
 626    effective_output_mode = output_mode or ("masked" if connection_id else "raw")
 627
 628    # Resolve residency before dispatch or workspace validation.
 629    eu_check: _EuDataPlaneCheck | None = None
 630    if connection_id:
 631        eu_check = _check_eu_data_plane(connection_id)
 632        if eu_check.skipped and effective_output_mode != "masked":
 633            return RunRegressionTestsResponse(
 634                run_id=run_id,
 635                status=TestRunStatus.FAILED,
 636                message=(
 637                    f"Could not confirm connection {connection_id}'s residency "
 638                    f"({eu_check.skipped}); pass output_mode='masked' to run it."
 639                ),
 640                workflow_url=None,
 641            )
 642        if eu_check.is_eu and output_mode == "raw":
 643            return RunRegressionTestsResponse(
 644                run_id=run_id,
 645                status=TestRunStatus.FAILED,
 646                message="EU-resident connections always run masked; "
 647                "raw output is refused.",
 648                workflow_url=None,
 649            )
 650        if eu_check.is_eu and output_mode is None:
 651            output_mode = "masked"
 652
 653    # Validate workspace membership if workspace_id and connection_id are provided
 654    if resolved_workspace_id and connection_id:
 655        try:
 656            auth = resolve_cloud_auth(ctx)
 657            if not (auth.bearer_token or (auth.client_id and auth.client_secret)):
 658                raise CloudAuthError(_MISSING_CLOUD_AUTH_MESSAGE)
 659            validate_connection_workspace(connection_id, resolved_workspace_id, auth)
 660        except PyAirbyteSecretNotFoundError:
 661            return RunRegressionTestsResponse(
 662                run_id=run_id,
 663                status=TestRunStatus.FAILED,
 664                message=_MISSING_CLOUD_AUTH_MESSAGE,
 665                workflow_url=None,
 666            )
 667        except (
 668            ValueError,
 669            CloudAuthError,
 670            AirbyteNoCloudCredentialsError,
 671            AirbyteWorkspaceMismatchError,
 672            AirbyteMissingResourceError,
 673        ) as e:
 674            return RunRegressionTestsResponse(
 675                run_id=run_id,
 676                status=TestRunStatus.FAILED,
 677                message=str(e),
 678                workflow_url=None,
 679            )
 680
 681    if discover_missing_streams and not selected_streams:
 682        return RunRegressionTestsResponse(
 683            run_id=run_id,
 684            status=TestRunStatus.FAILED,
 685            message="discover_missing_streams needs selected_streams naming the "
 686            "streams to add to the catalog.",
 687            workflow_url=None,
 688        )
 689
 690    if injected_sync_mode and not discover_missing_streams:
 691        return RunRegressionTestsResponse(
 692            run_id=run_id,
 693            status=TestRunStatus.FAILED,
 694            message="injected_sync_mode only applies with discover_missing_streams.",
 695            workflow_url=None,
 696        )
 697
 698    # Build workflow inputs - connector_name, pr, and repo are required
 699    workflow_inputs: dict[str, str] = {
 700        "connector_name": connector_name,
 701        "pr": str(pr),
 702        "repo": repo,
 703    }
 704
 705    # Add optional inputs
 706    if connection_id:
 707        workflow_inputs["connection_id"] = connection_id
 708    if skip_compare:
 709        workflow_inputs["skip_compare"] = "true"
 710    if skip_read_action:
 711        workflow_inputs["skip_read_action"] = "true"
 712    if override_test_image:
 713        workflow_inputs["override_test_image"] = override_test_image
 714    if override_control_image:
 715        workflow_inputs["override_control_image"] = override_control_image
 716    if selected_streams:
 717        workflow_inputs["selected_streams"] = ",".join(selected_streams)
 718    if discover_missing_streams:
 719        workflow_inputs["discover_missing_streams"] = "true"
 720    if injected_sync_mode:
 721        workflow_inputs["injected_sync_mode"] = injected_sync_mode
 722    if enable_debug_logs:
 723        workflow_inputs["enable_debug_logs"] = "true"
 724    if disable_http_replay:
 725        workflow_inputs["disable_http_replay"] = "true"
 726    if with_state is True:
 727        workflow_inputs["with_state"] = "true"
 728    elif with_state is False:
 729        workflow_inputs["with_state"] = "false"
 730    if max_records is not None:
 731        workflow_inputs["max_records"] = str(max_records)
 732    if state_json is not None:
 733        workflow_inputs["state_json"] = state_json
 734    if output_mode is not None:
 735        workflow_inputs["output_mode"] = output_mode
 736    if read_timeout_minutes is not None:
 737        workflow_inputs["read_timeout_minutes"] = str(read_timeout_minutes)
 738
 739    mode_description = "single-version" if skip_compare else "comparison"
 740
 741    # A refusal from GitHub (a seed past the 65,535-character input limit
 742    # comes back as a 422) or a network error on the dispatch is an answer,
 743    # not a traceback, which would carry the seed in its frames. A run lookup
 744    # that fails after GitHub took the dispatch does not raise: the run is
 745    # queued, only its ID is unknown.
 746    try:
 747        dispatch_result = trigger_workflow_dispatch(
 748            owner=REGRESSION_TEST_REPO_OWNER,
 749            repo=REGRESSION_TEST_REPO_NAME,
 750            workflow_file=REGRESSION_TEST_WORKFLOW_FILE,
 751            ref=resolve_default_workflow_branch(REGRESSION_TEST_DEFAULT_BRANCH),
 752            inputs=workflow_inputs,
 753            token=token,
 754        )
 755    except requests.RequestException as exc:
 756        return RunRegressionTestsResponse(
 757            run_id=run_id,
 758            status=TestRunStatus.FAILED,
 759            message=f"Workflow dispatch failed: {_api_error_message(exc)}",
 760            workflow_url=None,
 761        )
 762
 763    view_url = dispatch_result.run_url or dispatch_result.workflow_url
 764    connection_info = f" for connection {connection_id}" if connection_id else ""
 765    repo_info = f" from {repo}" if repo != ConnectorRepo.AIRBYTE else ""
 766    debug_logs_note = (
 767        " Debug logs will be off: the run is masked."
 768        if effective_output_mode == "masked" and enable_debug_logs
 769        else ""
 770    )
 771    skipped_check = (
 772        f"\nEU data-plane check skipped: {eu_check.skipped}."
 773        if eu_check and eu_check.skipped
 774        else ""
 775    )
 776    return RunRegressionTestsResponse(
 777        run_id=run_id,
 778        status=TestRunStatus.QUEUED,
 779        message=(
 780            f"{mode_description.capitalize()} regression test workflow triggered "
 781            f"for {connector_name} (PR #{pr}{repo_info}){connection_info}. "
 782            f"View progress at: {view_url}{skipped_check}{debug_logs_note}"
 783        ),
 784        workflow_url=dispatch_result.workflow_url,
 785        github_run_id=dispatch_result.run_id,
 786        github_run_url=dispatch_result.run_url,
 787    )
 788
 789
 790AIRBYTE_REPO_OWNER = "airbytehq"
 791
 792AIRBYTE_REPO_NAME = "airbyte"
 793
 794BLOCK_RELEASE_WORKFLOW_FILE = "block-release.yml"
 795
 796DEFAULT_REF = "master"
 797
 798
 799class BlockConnectorReleaseResult(BaseModel):
 800    """Result of triggering a release block workflow."""
 801
 802    success: bool = Field(description="Whether the workflow dispatch succeeded")
 803    message: str = Field(description="Human-readable result message")
 804    workflow_url: str = Field(description="URL to the workflow")
 805    run_id: int | None = Field(
 806        default=None, description="Workflow run ID, if discovered"
 807    )
 808    run_url: str | None = Field(default=None, description="URL to the workflow run")
 809
 810
 811class UnblockConnectorReleaseResult(BaseModel):
 812    """Result of triggering a release unblock workflow."""
 813
 814    success: bool = Field(description="Whether the workflow dispatch succeeded")
 815    message: str = Field(description="Human-readable result message")
 816    workflow_url: str = Field(description="URL to the workflow")
 817    run_id: int | None = Field(
 818        default=None, description="Workflow run ID, if discovered"
 819    )
 820    run_url: str | None = Field(default=None, description="URL to the workflow run")
 821
 822
 823class ListBlockedConnectorsResult(BaseModel):
 824    """Result of listing blocked connectors via the GitHub API."""
 825
 826    blocked_connectors: list[dict] = Field(
 827        default_factory=list,
 828        description="List of blocked connectors with optional block metadata",
 829    )
 830    count: int = Field(default=0, description="Number of blocked connectors")
 831
 832
 833@mcp_tool(
 834    read_only=False,
 835    idempotent=False,
 836    open_world=True,
 837)
 838def block_connector_release(
 839    connector_name: Annotated[
 840        str,
 841        Field(
 842            description="Connector technical name (e.g., `source-faker`, `destination-postgres`)"
 843        ),
 844    ],
 845    reason: Annotated[
 846        str,
 847        Field(description="Human-readable reason for blocking the release"),
 848    ],
 849    yanked_version: Annotated[
 850        str | None,
 851        Field(description="Version that was yanked (for reference)"),
 852    ] = None,
 853    blocked_by: Annotated[
 854        str | None,
 855        Field(description="Email or identifier of the person requesting the block"),
 856    ] = None,
 857) -> BlockConnectorReleaseResult:
 858    """Block a connector from being released by creating a `block-release.yaml` marker.
 859
 860    Triggers the `block-release.yml` workflow in the airbyte monorepo, which
 861    creates a marker file, opens a PR, and force-merges it to master. While the
 862    marker exists, the publish pipeline will skip the connector with a warning.
 863
 864    Use this after yanking a connector version to prevent CI from accidentally
 865    re-publishing the broken code.
 866    """
 867    token = resolve_ci_trigger_github_token()
 868
 869    inputs: dict[str, str] = {
 870        "connector-name": connector_name,
 871        "action": "block",
 872        "reason": reason,
 873    }
 874    if yanked_version:
 875        inputs["yanked-version"] = yanked_version
 876    if blocked_by:
 877        inputs["blocked-by"] = blocked_by
 878
 879    result = trigger_workflow_dispatch(
 880        owner=AIRBYTE_REPO_OWNER,
 881        repo=AIRBYTE_REPO_NAME,
 882        workflow_file=BLOCK_RELEASE_WORKFLOW_FILE,
 883        ref=resolve_default_workflow_branch(DEFAULT_REF),
 884        inputs=inputs,
 885        token=token,
 886        find_run=True,
 887    )
 888
 889    if result.run_id:
 890        message = (
 891            f"Successfully triggered release block for {connector_name}. "
 892            f"Run ID: {result.run_id}"
 893        )
 894    else:
 895        message = (
 896            f"Successfully triggered release block for {connector_name}. "
 897            "Run ID not yet available."
 898        )
 899
 900    return BlockConnectorReleaseResult(
 901        success=True,
 902        message=message,
 903        workflow_url=result.workflow_url,
 904        run_id=result.run_id,
 905        run_url=result.run_url,
 906    )
 907
 908
 909@mcp_tool(
 910    read_only=False,
 911    idempotent=False,
 912    open_world=True,
 913)
 914def unblock_connector_release(
 915    connector_name: Annotated[
 916        str,
 917        Field(
 918            description="Connector technical name (e.g., `source-faker`, `destination-postgres`)"
 919        ),
 920    ],
 921) -> UnblockConnectorReleaseResult:
 922    """Remove a release block for a connector by deleting its `block-release.yaml` marker.
 923
 924    Triggers the `block-release.yml` workflow with action=unblock, which removes
 925    the marker file, opens a PR, and force-merges it to master. After this, the
 926    connector can be published normally again.
 927    """
 928    token = resolve_ci_trigger_github_token()
 929
 930    result = trigger_workflow_dispatch(
 931        owner=AIRBYTE_REPO_OWNER,
 932        repo=AIRBYTE_REPO_NAME,
 933        workflow_file=BLOCK_RELEASE_WORKFLOW_FILE,
 934        ref=resolve_default_workflow_branch(DEFAULT_REF),
 935        inputs={
 936            "connector-name": connector_name,
 937            "action": "unblock",
 938        },
 939        token=token,
 940        find_run=True,
 941    )
 942
 943    if result.run_id:
 944        message = (
 945            f"Successfully triggered release unblock for {connector_name}. "
 946            f"Run ID: {result.run_id}"
 947        )
 948    else:
 949        message = (
 950            f"Successfully triggered release unblock for {connector_name}. "
 951            "Run ID not yet available."
 952        )
 953
 954    return UnblockConnectorReleaseResult(
 955        success=True,
 956        message=message,
 957        workflow_url=result.workflow_url,
 958        run_id=result.run_id,
 959        run_url=result.run_url,
 960    )
 961
 962
 963@mcp_tool(
 964    read_only=True,
 965    idempotent=True,
 966    open_world=True,
 967)
 968def list_blocked_connector_releases(
 969    connector_name: Annotated[
 970        str | None,
 971        Field(
 972            description="Optional connector name to check. If not provided, scans all connectors."
 973        ),
 974    ] = None,
 975    include_details: Annotated[
 976        bool,
 977        Field(
 978            description="Whether to fetch and parse each marker file for reason and metadata."
 979        ),
 980    ] = True,
 981) -> ListBlockedConnectorsResult:
 982    """List connectors that are currently blocked from release.
 983
 984    Searches the airbyte monorepo for `block-release.yaml` marker files using
 985    the GitHub API. Returns a list of blocked connectors, with marker metadata
 986    when `include_details` is `True`.
 987    """
 988
 989    token = resolve_ci_trigger_github_token()
 990    ref = resolve_default_workflow_branch(DEFAULT_REF)
 991    blocked: list[dict] = []
 992
 993    if connector_name:
 994        blocked = _check_single_connector_block(connector_name, token, ref)
 995    else:
 996        blocked = _search_all_blocked_connectors(token, ref, include_details)
 997
 998    return ListBlockedConnectorsResult(
 999        blocked_connectors=blocked,
1000        count=len(blocked),
1001    )
1002
1003
1004def _check_single_connector_block(
1005    connector_name: str,
1006    token: str,
1007    ref: str,
1008) -> list[dict]:
1009    """Check if a single connector has a release block."""
1010    path = f"airbyte-integrations/connectors/{connector_name}/block-release.yaml"
1011    content = get_file_contents_at_ref(
1012        owner=AIRBYTE_REPO_OWNER,
1013        repo=AIRBYTE_REPO_NAME,
1014        path=path,
1015        ref=ref,
1016        token=token,
1017    )
1018    if content is None:
1019        return []
1020
1021    return _parse_block_marker_content(connector_name, content)
1022
1023
1024def _parse_block_marker_content(connector_name: str, content: str) -> list[dict]:
1025    """Parse a `block-release.yaml` marker into the MCP response shape."""
1026    try:
1027        block_file_data = yaml.safe_load(content)
1028        if isinstance(block_file_data, dict):
1029            return [
1030                {
1031                    "connector_name": connector_name,
1032                    "reason": block_file_data.get("reason", "(no reason provided)"),
1033                    "yanked_version": block_file_data.get("yanked_version"),
1034                    "blocked_at": block_file_data.get("blocked_at"),
1035                    "blocked_by": block_file_data.get("blocked_by"),
1036                }
1037            ]
1038    except yaml.YAMLError:
1039        return [
1040            {"connector_name": connector_name, "reason": "(unable to parse marker)"}
1041        ]
1042
1043    return [
1044        {
1045            "connector_name": connector_name,
1046            "reason": "(invalid block-release.yaml format)",
1047        }
1048    ]
1049
1050
1051def _search_all_blocked_connectors(
1052    token: str,
1053    ref: str,
1054    include_details: bool,
1055) -> list[dict]:
1056    """Search the repo for all `block-release.yaml` files at the requested ref."""
1057    tree_ref = quote(ref, safe="")
1058    url = (
1059        f"{GITHUB_API_BASE}/repos/{AIRBYTE_REPO_OWNER}/{AIRBYTE_REPO_NAME}"
1060        f"/git/trees/{tree_ref}"
1061    )
1062    headers = {
1063        "Authorization": f"Bearer {token}",
1064        "Accept": "application/vnd.github+json",
1065        "X-GitHub-Api-Version": "2022-11-28",
1066    }
1067    response = requests.get(
1068        url,
1069        headers=headers,
1070        params={"recursive": "1"},
1071        timeout=30,
1072    )
1073    response.raise_for_status()
1074
1075    tree = response.json().get("tree", [])
1076    blocked: list[dict] = []
1077
1078    for item in tree:
1079        file_path = item.get("path", "")
1080        if not file_path.endswith("/block-release.yaml"):
1081            continue
1082
1083        parts = file_path.split("/")
1084        if (
1085            len(parts) == 4
1086            and parts[0] == "airbyte-integrations"
1087            and parts[1] == "connectors"
1088        ):
1089            connector_name = parts[2]
1090            if not include_details:
1091                blocked.append({"connector_name": connector_name})
1092                continue
1093
1094            content = get_file_contents_at_ref(
1095                owner=AIRBYTE_REPO_OWNER,
1096                repo=AIRBYTE_REPO_NAME,
1097                path=file_path,
1098                ref=ref,
1099                token=token,
1100            )
1101            if content is not None:
1102                blocked.extend(_parse_block_marker_content(connector_name, content))
1103
1104    return blocked
1105
1106
1107def register_connector_qa_tools(app: FastMCP) -> None:
1108    """Register connector_qa tools with the FastMCP app."""
1109    register_mcp_tools(app, mcp_module=__name__)