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__)