airbyte_ops_mcp.mcp.connector_versions
MCP tools for connector version lifecycle: cloud version overrides, progressive rollouts, and pre-release publishing.
MCP reference
MCP primitives registered by the connector_versions module of the airbyte-internal-ops server: 10 tool(s), 0 prompt(s), 0 resource(s).
Tools (10)
finalize_connector_rollout
Finalize a connector rollout by promoting, rolling back, or canceling.
This tool allows admins to finalize connector rollouts that are in progress. Use this after monitoring a rollout and determining it is ready for finalization.
IMPORTANT: Finalization is asynchronous. This tool sends a finalization
request to the platform API, which transitions the rollout to finalizing
state and triggers a Temporal workflow. The actual promotion (PR creation,
connector publish, registry update) or rollback (GCS cleanup, registry
recompile) happens asynchronously via the finalize_rollout.yml GitHub
Actions workflow. A successful response from this tool means the request
was accepted — NOT that the promotion/rollback is complete.
After calling this tool, you MUST verify:
- The
finalize_rollout.ymlworkflow ran successfully in GitHub Actions - For promotions: a merged PR exists (e.g.,
chore: finalize promote for <connector>) - The rollout state transitioned to its terminal state (
succeeded,failed_rolled_back, orcanceled) viaquery_prod_connector_rollouts
Admin-only operation - Requires:
- AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io environment variable
approval_comment_url(Slack approval record URL fromescalate_to_human), ORadmin_user_email_overridewhen running inside the Ops Webapp.
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
docker_repository |
string |
yes | — | The docker repository (e.g., 'airbyte/source-youtube-analytics') |
docker_image_tag |
string |
yes | — | The docker image tag (e.g., '1.2.0-rc.2') |
actor_definition_id |
string |
yes | — | The actor definition ID (UUID) |
rollout_id |
string |
yes | — | The rollout ID (UUID). Can be found in the 'pin_origin' field of rollout data from query_prod_actors_by_pinned_connector_version. |
state |
enum("succeeded", "failed_rolled_back", "canceled") |
yes | — | The final state for the rollout: 'succeeded' promotes the RC to GA (default version for all users), 'failed_rolled_back' rolls back the RC, 'canceled' cancels the rollout without promotion or rollback. |
approval_comment_url |
string | null |
no | null |
URL to the Slack approval record. Obtain this by calling the escalate_to_human tool with approval_requested=True; the backend delivers the approval record URL when a human clicks Approve. Format: https:// |
admin_user_email_override |
string | null |
no | null |
Direct admin email override for webapp-initiated actions. When the Ops Webapp env var is set, this bypasses the approval URL requirement. Ignored in agent/cron environments. |
error_msg |
string | null |
no | null |
Optional error message for failed/canceled states. |
failed_reason |
string | null |
no | null |
Optional failure reason for failed/canceled states. |
retain_pins_on_cancellation |
boolean | null |
no | null |
If True, retain version pins when canceling. Only applicable when state is 'canceled'. |
Show input JSON schema
{
"additionalProperties": false,
"properties": {
"docker_repository": {
"description": "The docker repository (e.g., 'airbyte/source-youtube-analytics')",
"type": "string"
},
"docker_image_tag": {
"description": "The docker image tag (e.g., '1.2.0-rc.2')",
"type": "string"
},
"actor_definition_id": {
"description": "The actor definition ID (UUID)",
"type": "string"
},
"rollout_id": {
"description": "The rollout ID (UUID). Can be found in the 'pin_origin' field of rollout data from query_prod_actors_by_pinned_connector_version.",
"type": "string"
},
"state": {
"description": "The final state for the rollout: 'succeeded' promotes the RC to GA (default version for all users), 'failed_rolled_back' rolls back the RC, 'canceled' cancels the rollout without promotion or rollback.",
"enum": [
"succeeded",
"failed_rolled_back",
"canceled"
],
"type": "string"
},
"approval_comment_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "URL to the Slack approval record. Obtain this by calling the `escalate_to_human` tool with `approval_requested=True`; the backend delivers the approval record URL when a human clicks Approve. Format: https://<workspace>.slack.com/archives/... The admin email is automatically resolved from the approver's identity via the team roster."
},
"admin_user_email_override": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Direct admin email override for webapp-initiated actions. When the Ops Webapp env var is set, this bypasses the approval URL requirement. Ignored in agent/cron environments."
},
"error_msg": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional error message for failed/canceled states."
},
"failed_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional failure reason for failed/canceled states."
},
"retain_pins_on_cancellation": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "If True, retain version pins when canceling. Only applicable when state is 'canceled'."
}
},
"required": [
"docker_repository",
"docker_image_tag",
"actor_definition_id",
"rollout_id",
"state"
],
"type": "object"
}
Show output JSON schema
{
"description": "Result of a connector rollout finalization operation.\n\nThis model provides detailed information about the outcome of finalizing\na connector rollout (promote, rollback, or cancel).",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"type": "boolean"
},
"message": {
"description": "Human-readable message describing the result",
"type": "string"
},
"rollout_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The rollout ID that was finalized"
},
"docker_repository": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The docker repository (e.g., 'airbyte/source-github')"
},
"docker_image_tag": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The docker image tag (e.g., '1.2.0-rc.2')"
},
"state": {
"anyOf": [
{
"enum": [
"succeeded",
"failed_rolled_back",
"canceled"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The final state of the rollout"
}
},
"required": [
"success",
"message"
],
"type": "object"
}
get_cloud_connector_version
Get the current version information for a deployed connector.
Returns version details including the current version string and whether an override (pin) is applied.
Authentication credentials are resolved in priority order:
- Bearer token (Authorization header or AIRBYTE_CLOUD_BEARER_TOKEN env var)
- HTTP headers: X-Airbyte-Cloud-Client-Id, X-Airbyte-Cloud-Client-Secret
- Environment variables: AIRBYTE_CLOUD_CLIENT_ID, AIRBYTE_CLOUD_CLIENT_SECRET
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
workspace_id |
string | enum("266ebdfe-0d7b-4540-9817-de7e4505ba61") |
yes | — | The Airbyte Cloud workspace ID (UUID) or alias. Accepts '@devin-ai-sandbox' as an alias for the Devin AI sandbox workspace. |
actor_id |
string |
yes | — | The ID of the deployed connector (source or destination) |
actor_type |
enum("source", "destination") |
yes | — | The type of connector (source or destination) |
config_api_root |
string | null |
no | null |
Optional API root URL override for the Config API. Defaults to Airbyte Cloud (https://cloud.airbyte.com/api/v1). Use this to target local or self-hosted deployments. |
Show input JSON schema
{
"additionalProperties": false,
"properties": {
"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"
}
],
"description": "The Airbyte Cloud workspace ID (UUID) or alias. Accepts '@devin-ai-sandbox' as an alias for the Devin AI sandbox workspace."
},
"actor_id": {
"description": "The ID of the deployed connector (source or destination)",
"type": "string"
},
"actor_type": {
"description": "The type of connector (source or destination)",
"enum": [
"source",
"destination"
],
"type": "string"
},
"config_api_root": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional API root URL override for the Config API. Defaults to Airbyte Cloud (https://cloud.airbyte.com/api/v1). Use this to target local or self-hosted deployments."
}
},
"required": [
"workspace_id",
"actor_id",
"actor_type"
],
"type": "object"
}
Show output JSON schema
{
"description": "Information about a cloud connector's version.\n\nThis model represents the current version state of a deployed connector,\nincluding whether a version override (pin) is active.",
"properties": {
"connector_id": {
"description": "The ID of the deployed connector",
"type": "string"
},
"connector_type": {
"description": "The type of connector (source or destination)",
"enum": [
"source",
"destination"
],
"type": "string"
},
"version": {
"description": "The current version string (e.g., '0.1.0')",
"type": "string"
},
"is_version_pinned": {
"description": "Whether a version override is active for this connector",
"type": "boolean"
}
},
"required": [
"connector_id",
"connector_type",
"version",
"is_version_pinned"
],
"type": "object"
}
pause_connector_rollout
Pause a connector rollout, or resume a paused one with unpause=True.
A paused rollout is held in place: Autopilot will not advance or promote it, and already-pinned actors stay on the release candidate. To withdraw the version entirely, yank it instead.
Resuming hands the rollout back to Autopilot from exactly where it stopped, pinning no additional customers. A rollout with nothing pinned yet resumes at 1%, pinning one customer, because the platform rejects a zero-sized step. If Autopilot paused the rollout over failing syncs, it will pause it again while those failures persist.
Prefer pausing over finalize_connector_rollout(state="canceled") when reacting to
a problem: the platform re-creates a rollout for every still-advertised release
candidate, so cancelling loops.
Unlike progress/finalize, neither direction needs Slack approval — both are
reversible and hold or restore the current state rather than moving customers ahead
of the normal cadence. Both require AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io.
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
docker_repository |
string |
yes | — | The docker repository (e.g., 'airbyte/source-pokeapi') |
docker_image_tag |
string |
yes | — | The docker image tag (e.g., '0.3.48-rc.1') |
actor_definition_id |
string |
yes | — | The actor definition ID (UUID) |
rollout_id |
string |
yes | — | The rollout ID (UUID). Can be found from query_prod_connector_rollouts. |
admin_user_email |
string |
yes | — | Email of the admin the change is attributed to, resolved to the rollout's updated_by user ID. |
paused_reason |
string |
no | "" |
Why the rollout is being held, recorded on the rollout (e.g., 'Sync failures reported on TIER_2'). Required unless unpause=True. |
unpause |
boolean |
no | false |
Resume a paused rollout instead of pausing it, handing it back to Autopilot without pinning new customers. |
Show input JSON schema
{
"additionalProperties": false,
"properties": {
"docker_repository": {
"description": "The docker repository (e.g., 'airbyte/source-pokeapi')",
"type": "string"
},
"docker_image_tag": {
"description": "The docker image tag (e.g., '0.3.48-rc.1')",
"type": "string"
},
"actor_definition_id": {
"description": "The actor definition ID (UUID)",
"type": "string"
},
"rollout_id": {
"description": "The rollout ID (UUID). Can be found from query_prod_connector_rollouts.",
"type": "string"
},
"admin_user_email": {
"description": "Email of the admin the change is attributed to, resolved to the rollout's `updated_by` user ID.",
"type": "string"
},
"paused_reason": {
"default": "",
"description": "Why the rollout is being held, recorded on the rollout (e.g., 'Sync failures reported on TIER_2'). Required unless `unpause=True`.",
"type": "string"
},
"unpause": {
"default": false,
"description": "Resume a paused rollout instead of pausing it, handing it back to Autopilot without pinning new customers.",
"type": "boolean"
}
},
"required": [
"docker_repository",
"docker_image_tag",
"actor_definition_id",
"rollout_id",
"admin_user_email"
],
"type": "object"
}
Show output JSON schema
{
"description": "Result of a connector rollout pause operation.\n\nA paused rollout keeps its existing pins; it is the reversible alternative to\nfinalizing a rollout as `canceled`.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"type": "boolean"
},
"message": {
"description": "Human-readable message describing the result",
"type": "string"
},
"rollout_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The rollout ID that was paused"
},
"docker_repository": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The docker repository (e.g., 'airbyte/source-github')"
},
"docker_image_tag": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The docker image tag (e.g., '1.2.0-rc.2')"
},
"paused_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The reason recorded on the paused rollout"
}
},
"required": [
"success",
"message"
],
"type": "object"
}
progress_connector_rollout
Progress a connector rollout by pinning actors to the RC version.
This tool progresses a connector rollout by either:
- Setting a target percentage of actors to pin to the RC version
- Specifying specific actor IDs to pin
Admin-only operation - Requires:
- AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io environment variable
approval_comment_url(Slack approval record URL fromescalate_to_human), ORadmin_user_email_overridewhen running inside the Ops Webapp.
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
docker_repository |
string |
yes | — | The docker repository (e.g., 'airbyte/source-pokeapi') |
docker_image_tag |
string |
yes | — | The docker image tag (e.g., '0.3.48-rc.1') |
actor_definition_id |
string |
yes | — | The actor definition ID (UUID) |
rollout_id |
string |
yes | — | The rollout ID (UUID). Can be found from query_prod_connector_rollouts. |
approval_comment_url |
string | null |
no | null |
URL to the Slack approval record. Obtain this by calling the escalate_to_human tool with approval_requested=True; the backend delivers the approval record URL when a human clicks Approve. Format: https:// |
admin_user_email_override |
string | null |
no | null |
Direct admin email override for webapp-initiated actions. When the Ops Webapp env var is set, this bypasses the approval URL requirement. Ignored in agent/cron environments. |
target_percentage |
integer | null |
no | null |
Target percentage of actors to pin to the RC (1-100). Either target_percentage or actor_ids must be provided. |
actor_ids |
array<string> | null |
no | null |
Specific actor IDs to pin to the RC. Either target_percentage or actor_ids must be provided. |
Show input JSON schema
{
"additionalProperties": false,
"properties": {
"docker_repository": {
"description": "The docker repository (e.g., 'airbyte/source-pokeapi')",
"type": "string"
},
"docker_image_tag": {
"description": "The docker image tag (e.g., '0.3.48-rc.1')",
"type": "string"
},
"actor_definition_id": {
"description": "The actor definition ID (UUID)",
"type": "string"
},
"rollout_id": {
"description": "The rollout ID (UUID). Can be found from query_prod_connector_rollouts.",
"type": "string"
},
"approval_comment_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "URL to the Slack approval record. Obtain this by calling the `escalate_to_human` tool with `approval_requested=True`; the backend delivers the approval record URL when a human clicks Approve. Format: https://<workspace>.slack.com/archives/... The admin email is automatically resolved from the approver's identity via the team roster."
},
"admin_user_email_override": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Direct admin email override for webapp-initiated actions. When the Ops Webapp env var is set, this bypasses the approval URL requirement. Ignored in agent/cron environments."
},
"target_percentage": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Target percentage of actors to pin to the RC (1-100). Either target_percentage or actor_ids must be provided."
},
"actor_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Specific actor IDs to pin to the RC. Either target_percentage or actor_ids must be provided."
}
},
"required": [
"docker_repository",
"docker_image_tag",
"actor_definition_id",
"rollout_id"
],
"type": "object"
}
Show output JSON schema
{
"description": "Result of a connector rollout progress operation.\n\nThis model provides detailed information about the outcome of progressing\na connector rollout (pinning actors to the RC version).",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"type": "boolean"
},
"message": {
"description": "Human-readable message describing the result",
"type": "string"
},
"rollout_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The rollout ID that was progressed"
},
"docker_repository": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The docker repository (e.g., 'airbyte/source-github')"
},
"docker_image_tag": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The docker image tag (e.g., '1.2.0-rc.2')"
},
"target_percentage": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "The target percentage of actors to pin"
}
},
"required": [
"success",
"message"
],
"type": "object"
}
publish_connector_to_airbyte_registry
Publish a connector to the Airbyte registry.
Currently only supports pre-release publishing. This tool triggers the publish-connectors-prerelease workflow in the airbytehq/airbyte repository (for OSS connectors) or the publish_enterprise_connectors workflow in airbytehq/airbyte-enterprise (for enterprise connectors), which publishes a pre-release version of the specified connector from the PR branch.
Pre-release versions are tagged with the format: {version}-preview.{7-char-git-sha} These versions are available for version pinning via the scoped_configuration API.
Requires GITHUB_CONNECTOR_PUBLISHING_PAT or GITHUB_TOKEN environment variable with 'actions:write' permission.
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
connector_name |
string |
yes | — | The connector name to publish (e.g., 'source-github', 'destination-postgres') |
pr_number |
integer |
yes | — | The pull request number containing the connector changes |
repo |
enum("airbyte", "airbyte-enterprise") |
no | "airbyte" |
Repository where the connector PR is located. Use 'airbyte' for OSS connectors (default) or 'airbyte-enterprise' for enterprise connectors. |
prerelease |
boolean |
no | true |
Must be True. Only prerelease publishing is supported at this time. |
Show input JSON schema
{
"additionalProperties": false,
"properties": {
"connector_name": {
"description": "The connector name to publish (e.g., 'source-github', 'destination-postgres')",
"type": "string"
},
"pr_number": {
"description": "The pull request number containing the connector changes",
"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",
"default": "airbyte"
},
"prerelease": {
"const": true,
"default": true,
"description": "Must be True. Only prerelease publishing is supported at this time.",
"type": "boolean"
}
},
"required": [
"connector_name",
"pr_number"
],
"type": "object"
}
Show output JSON schema
{
"description": "Response model for publish_connector_to_airbyte_registry MCP tool.",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"workflow_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"connector_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"pr_number": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"docker_image": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"docker_image_tag": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"success",
"message"
],
"type": "object"
}
query_prod_rollout_monitoring_stats
Get monitoring stats for a connector rollout.
Returns actor selection info and per-actor sync stats for actors participating in the rollout. This uses the platform API's /get_actor_sync_info endpoint which filters sync stats to only include syncs that actually used the RC version associated with the rollout.
This is more accurate than SQL-based approaches which count all syncs regardless of which connector version was used.
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
rollout_id |
string |
yes | — | Rollout UUID to get monitoring stats for |
Show input JSON schema
{
"additionalProperties": false,
"properties": {
"rollout_id": {
"description": "Rollout UUID to get monitoring stats for",
"type": "string"
}
},
"required": [
"rollout_id"
],
"type": "object"
}
Show output JSON schema
{
"description": "Complete monitoring result for a rollout from the platform API.\n\nThis uses the platform API's /get_actor_sync_info endpoint which filters\nsync stats to only include syncs that actually used the RC version\nassociated with the rollout.",
"properties": {
"rollout_id": {
"description": "Rollout UUID",
"type": "string"
},
"actor_selection_info": {
"description": "Actor selection info for the rollout",
"properties": {
"num_actors": {
"description": "Total actors using this connector",
"type": "integer"
},
"num_pinned_to_connector_rollout": {
"description": "Actors specifically pinned to this rollout",
"type": "integer"
},
"num_actors_eligible_or_already_pinned": {
"description": "Actors eligible for pinning or already pinned",
"type": "integer"
}
},
"required": [
"num_actors",
"num_pinned_to_connector_rollout",
"num_actors_eligible_or_already_pinned"
],
"type": "object"
},
"actor_sync_stats": {
"description": "Per-actor sync stats for actors pinned to the rollout",
"items": {
"description": "Per-actor sync stats for a rollout (only syncs using the RC version).",
"properties": {
"actor_id": {
"description": "Actor UUID",
"type": "string"
},
"num_connections": {
"description": "Number of connections using this actor",
"type": "integer"
},
"num_succeeded": {
"description": "Number of successful syncs using the RC version",
"type": "integer"
},
"num_failed": {
"description": "Number of failed syncs using the RC version",
"type": "integer"
}
},
"required": [
"actor_id",
"num_connections",
"num_succeeded",
"num_failed"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"rollout_id",
"actor_selection_info",
"actor_sync_stats"
],
"type": "object"
}
set_cloud_connector_version_override
Set or clear a version override for a deployed connector.
This creates a regular version override, not a progressive-rollout pin. The
rollout does not track it, count it toward its progress, or remove it at
finalization, and an actor with this override is never picked by a rollout.
To include a specific actor in a running rollout, use
progress_connector_rollout with actor_ids instead.
Admin-only operation - Requires:
- AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io environment variable
- issue_url parameter (GitHub issue URL for context)
- approval_comment_url (Slack approval record URL from
escalate_to_human)
The admin user email is automatically derived from the Slack approval record, resolving the approver's @airbyte.io email via the team roster.
You must specify EXACTLY ONE of version OR unset=True, but not both.
When setting a version, override_reason is required.
The customer_tier_filter parameter gates the operation: the call fails if
the actual tier of the workspace's organization does not match. Use ALL
to bypass the check (a warning is still emitted for sensitive tiers).
Business rules enforced:
- Dev versions (-dev): Only creator can unpin their own dev version override
- Production versions: Require strong justification mentioning customer/support/investigation
- Release candidates (-rc): Any admin can pin/unpin RC versions
Authentication credentials are resolved in priority order:
- Bearer token (Authorization header or AIRBYTE_CLOUD_BEARER_TOKEN env var)
- HTTP headers: X-Airbyte-Cloud-Client-Id, X-Airbyte-Cloud-Client-Secret
- Environment variables: AIRBYTE_CLOUD_CLIENT_ID, AIRBYTE_CLOUD_CLIENT_SECRET
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
workspace_id |
string | enum("266ebdfe-0d7b-4540-9817-de7e4505ba61") |
yes | — | The Airbyte Cloud workspace ID (UUID) or alias. Accepts '@devin-ai-sandbox' as an alias for the Devin AI sandbox workspace. |
actor_id |
string |
yes | — | The ID of the deployed connector (source or destination) |
actor_type |
enum("source", "destination") |
yes | — | The type of connector (source or destination) |
approval_comment_url |
string | null |
no | null |
URL to the Slack approval record. Obtain this by calling the escalate_to_human tool with approval_requested=True; the backend delivers the approval record URL when a human clicks Approve. Format: https:// |
version |
string | null |
no | null |
The semver version string to pin to (e.g., '0.1.0'). Must be None if unset is True. |
unset |
boolean |
no | false |
If True, removes any existing version override. Cannot be True if version is provided. |
override_reason |
string | null |
no | null |
Required when setting a version. Explanation for the override (min 10 characters). |
override_reason_reference_url |
string | null |
no | null |
Optional URL with more context (e.g., issue link). |
issue_url |
string | null |
no | null |
URL to the GitHub issue providing context for this operation. Must be a valid GitHub URL (https://github.com/...). Required for authorization. |
ai_agent_session_url |
string | null |
no | null |
URL to the AI agent session driving this operation, if applicable. Provides additional auditability for AI-driven operations. |
force |
boolean |
no | false |
If True, allow overwriting an existing version pin. Existing pins may have been set by rollouts, breaking-change migrations, or other operators. Defaults to False. NOTE: force=True only bypasses the existing-pin check — major-version crossings are always blocked and cannot be overridden. |
config_api_root |
string | null |
no | null |
Optional API root URL override for the Config API. Defaults to Airbyte Cloud (https://cloud.airbyte.com/api/v1). Use this to target local or self-hosted deployments. |
customer_tier_filter |
enum("TIER_0", "TIER_1", "TIER_2", "UNKNOWN", "ALL") |
no | "TIER_2" |
Required tier filter: 'TIER_0', 'TIER_1', 'TIER_2', 'UNKNOWN', or 'ALL'. The operation will be rejected if the actual customer tier does not match. Use 'ALL' to proceed regardless of tier (a warning is shown for sensitive tiers). |
Show input JSON schema
{
"additionalProperties": false,
"properties": {
"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"
}
],
"description": "The Airbyte Cloud workspace ID (UUID) or alias. Accepts '@devin-ai-sandbox' as an alias for the Devin AI sandbox workspace."
},
"actor_id": {
"description": "The ID of the deployed connector (source or destination)",
"type": "string"
},
"actor_type": {
"description": "The type of connector (source or destination)",
"enum": [
"source",
"destination"
],
"type": "string"
},
"approval_comment_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "URL to the Slack approval record. Obtain this by calling the `escalate_to_human` tool with `approval_requested=True`; the backend delivers the approval record URL when a human clicks Approve. Format: https://<workspace>.slack.com/archives/... The admin email is automatically resolved from the approver's identity via the team roster."
},
"version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The semver version string to pin to (e.g., '0.1.0'). Must be None if unset is True."
},
"unset": {
"default": false,
"description": "If True, removes any existing version override. Cannot be True if version is provided.",
"type": "boolean"
},
"override_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Required when setting a version. Explanation for the override (min 10 characters)."
},
"override_reason_reference_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional URL with more context (e.g., issue link)."
},
"issue_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "URL to the GitHub issue providing context for this operation. Must be a valid GitHub URL (https://github.com/...). Required for authorization."
},
"ai_agent_session_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "URL to the AI agent session driving this operation, if applicable. Provides additional auditability for AI-driven operations."
},
"force": {
"default": false,
"description": "If `True`, allow overwriting an existing version pin. Existing pins may have been set by rollouts, breaking-change migrations, or other operators. Defaults to `False`. NOTE: `force=True` only bypasses the existing-pin check \u2014 major-version crossings are always blocked and cannot be overridden.",
"type": "boolean"
},
"config_api_root": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional API root URL override for the Config API. Defaults to Airbyte Cloud (https://cloud.airbyte.com/api/v1). Use this to target local or self-hosted deployments."
},
"customer_tier_filter": {
"default": "TIER_2",
"description": "Required tier filter: 'TIER_0', 'TIER_1', 'TIER_2', 'UNKNOWN', or 'ALL'. The operation will be rejected if the actual customer tier does not match. Use 'ALL' to proceed regardless of tier (a warning is shown for sensitive tiers).",
"enum": [
"TIER_0",
"TIER_1",
"TIER_2",
"UNKNOWN",
"ALL"
],
"type": "string"
}
},
"required": [
"workspace_id",
"actor_id",
"actor_type"
],
"type": "object"
}
Show output JSON schema
{
"description": "Result of a version override operation (set or clear).\n\nThis model provides detailed information about the outcome of a version\npinning or unpinning operation.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"type": "boolean"
},
"message": {
"description": "Human-readable message describing the result",
"type": "string"
},
"connector_id": {
"description": "The ID of the connector that was modified",
"type": "string"
},
"connector_type": {
"description": "The type of connector (source or destination)",
"enum": [
"source",
"destination"
],
"type": "string"
},
"previous_version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The version before the operation (None if not available)"
},
"new_version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The version after the operation (None if cleared or failed)"
},
"was_pinned_before": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether a pin was active before the operation"
},
"is_pinned_after": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether a pin is active after the operation"
},
"customer_tier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Customer tier of the affected entity (TIER_0, TIER_1, TIER_2, UNKNOWN). Included as a guardrail annotation."
},
"is_eu": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether the affected entity is in the EU region."
},
"tier_warning": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Warning message if the operation targets a sensitive customer tier."
},
"warnings": {
"description": "Warnings raised by this operation.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"success",
"message",
"connector_id",
"connector_type"
],
"type": "object"
}
set_organization_connector_version_override
Set or clear an organization-level version override for a connector type.
This pins ALL instances of a connector type across an entire organization to a specific version. For example, pinning 'source-github' at organization level means all GitHub sources in all workspaces within that organization will use the pinned version.
Admin-only operation - Requires:
- AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io environment variable
- issue_url parameter (GitHub issue URL for context)
- approval_comment_url (Slack approval record URL from
escalate_to_human)
You must specify EXACTLY ONE of version OR unset=True, but not both.
When setting a version, override_reason is required.
The customer_tier_filter parameter gates the operation: the call fails if
the actual tier of the organization does not match. Use ALL to bypass
the check (a warning is still emitted for sensitive tiers).
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
organization_id |
string |
yes | — | The Airbyte Cloud organization ID. |
connector_name |
string |
yes | — | The connector name (e.g., 'source-github', 'destination-bigquery'). |
connector_type |
enum("source", "destination") |
yes | — | The type of connector (source or destination) |
approval_comment_url |
string | null |
no | null |
URL to the Slack approval record. Obtain this by calling the escalate_to_human tool with approval_requested=True; the backend delivers the approval record URL when a human clicks Approve. Format: https:// |
version |
string | null |
no | null |
The semver version string to pin to (e.g., '0.1.0'). Must be None if unset is True. |
unset |
boolean |
no | false |
If True, removes any existing version override. Cannot be True if version is provided. |
override_reason |
string | null |
no | null |
Required when setting a version. Explanation for the override (min 10 characters). |
override_reason_reference_url |
string | null |
no | null |
Optional URL with more context (e.g., issue link). |
issue_url |
string | null |
no | null |
URL to the GitHub issue providing context for this operation. Must be a valid GitHub URL (https://github.com/...). Required for authorization. |
ai_agent_session_url |
string | null |
no | null |
URL to the AI agent session driving this operation, if applicable. Provides additional auditability for AI-driven operations. |
force |
boolean |
no | false |
If True, allow overwriting an existing version pin. Existing pins may have been set by rollouts, breaking-change migrations, or other operators. Defaults to False. NOTE: force=True only bypasses the existing-pin check — major-version crossings are always blocked and cannot be overridden. |
config_api_root |
string | null |
no | null |
Optional API root URL override for the Config API. Defaults to Airbyte Cloud (https://cloud.airbyte.com/api/v1). Use this to target local or self-hosted deployments. |
customer_tier_filter |
enum("TIER_0", "TIER_1", "TIER_2", "UNKNOWN", "ALL") |
no | "TIER_2" |
Required tier filter: 'TIER_0', 'TIER_1', 'TIER_2', 'UNKNOWN', or 'ALL'. The operation will be rejected if the actual customer tier does not match. Use 'ALL' to proceed regardless of tier (a warning is shown for sensitive tiers). |
Show input JSON schema
{
"additionalProperties": false,
"properties": {
"organization_id": {
"description": "The Airbyte Cloud organization ID.",
"type": "string"
},
"connector_name": {
"description": "The connector name (e.g., 'source-github', 'destination-bigquery').",
"type": "string"
},
"connector_type": {
"description": "The type of connector (source or destination)",
"enum": [
"source",
"destination"
],
"type": "string"
},
"approval_comment_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "URL to the Slack approval record. Obtain this by calling the `escalate_to_human` tool with `approval_requested=True`; the backend delivers the approval record URL when a human clicks Approve. Format: https://<workspace>.slack.com/archives/... The admin email is automatically resolved from the approver's identity via the team roster."
},
"version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The semver version string to pin to (e.g., '0.1.0'). Must be None if unset is True."
},
"unset": {
"default": false,
"description": "If True, removes any existing version override. Cannot be True if version is provided.",
"type": "boolean"
},
"override_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Required when setting a version. Explanation for the override (min 10 characters)."
},
"override_reason_reference_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional URL with more context (e.g., issue link)."
},
"issue_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "URL to the GitHub issue providing context for this operation. Must be a valid GitHub URL (https://github.com/...). Required for authorization."
},
"ai_agent_session_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "URL to the AI agent session driving this operation, if applicable. Provides additional auditability for AI-driven operations."
},
"force": {
"default": false,
"description": "If `True`, allow overwriting an existing version pin. Existing pins may have been set by rollouts, breaking-change migrations, or other operators. Defaults to `False`. NOTE: `force=True` only bypasses the existing-pin check \u2014 major-version crossings are always blocked and cannot be overridden.",
"type": "boolean"
},
"config_api_root": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional API root URL override for the Config API. Defaults to Airbyte Cloud (https://cloud.airbyte.com/api/v1). Use this to target local or self-hosted deployments."
},
"customer_tier_filter": {
"default": "TIER_2",
"description": "Required tier filter: 'TIER_0', 'TIER_1', 'TIER_2', 'UNKNOWN', or 'ALL'. The operation will be rejected if the actual customer tier does not match. Use 'ALL' to proceed regardless of tier (a warning is shown for sensitive tiers).",
"enum": [
"TIER_0",
"TIER_1",
"TIER_2",
"UNKNOWN",
"ALL"
],
"type": "string"
}
},
"required": [
"organization_id",
"connector_name",
"connector_type"
],
"type": "object"
}
Show output JSON schema
{
"description": "Result of an organization-level version override operation.\n\nThis model provides detailed information about the outcome of an organization-level\nversion pinning or unpinning operation.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"type": "boolean"
},
"message": {
"description": "Human-readable message describing the result",
"type": "string"
},
"organization_id": {
"description": "The organization ID",
"type": "string"
},
"connector_name": {
"description": "The connector name (e.g., 'source-github')",
"type": "string"
},
"connector_type": {
"description": "The type of connector (source or destination)",
"enum": [
"source",
"destination"
],
"type": "string"
},
"version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The version that was pinned (None if cleared or failed)"
},
"customer_tier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Customer tier of the organization (TIER_0, TIER_1, TIER_2, UNKNOWN). Included as a guardrail annotation."
},
"tier_warning": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Warning message if the operation targets a sensitive customer tier."
},
"warnings": {
"description": "Warnings raised by this operation.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"success",
"message",
"organization_id",
"connector_name",
"connector_type"
],
"type": "object"
}
set_workspace_connector_version_override
Set or clear a workspace-level version override for a connector type.
This pins ALL instances of a connector type within a workspace to a specific version. For example, pinning 'source-github' at workspace level means all GitHub sources in that workspace will use the pinned version.
This creates a regular version override, not a progressive-rollout pin. The
rollout does not track it, count it toward its progress, or remove it at
finalization, and an actor with this override is never picked by a rollout.
To include a specific actor in a running rollout, use
progress_connector_rollout with actor_ids instead.
Admin-only operation - Requires:
- AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io environment variable
- issue_url parameter (GitHub issue URL for context)
- approval_comment_url (Slack approval record URL from
escalate_to_human)
You must specify EXACTLY ONE of version OR unset=True, but not both.
When setting a version, override_reason is required.
The customer_tier_filter parameter gates the operation: the call fails if
the actual tier of the workspace's organization does not match. Use ALL
to bypass the check (a warning is still emitted for sensitive tiers).
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
workspace_id |
string | enum("266ebdfe-0d7b-4540-9817-de7e4505ba61") |
yes | — | The Airbyte Cloud workspace ID (UUID) or alias. Accepts '@devin-ai-sandbox' as an alias for the Devin AI sandbox workspace. |
connector_name |
string |
yes | — | The connector name (e.g., 'source-github', 'destination-bigquery'). |
connector_type |
enum("source", "destination") |
yes | — | The type of connector (source or destination) |
approval_comment_url |
string | null |
no | null |
URL to the Slack approval record. Obtain this by calling the escalate_to_human tool with approval_requested=True; the backend delivers the approval record URL when a human clicks Approve. Format: https:// |
version |
string | null |
no | null |
The semver version string to pin to (e.g., '0.1.0'). Must be None if unset is True. |
unset |
boolean |
no | false |
If True, removes any existing version override. Cannot be True if version is provided. |
override_reason |
string | null |
no | null |
Required when setting a version. Explanation for the override (min 10 characters). |
override_reason_reference_url |
string | null |
no | null |
Optional URL with more context (e.g., issue link). |
issue_url |
string | null |
no | null |
URL to the GitHub issue providing context for this operation. Must be a valid GitHub URL (https://github.com/...). Required for authorization. |
ai_agent_session_url |
string | null |
no | null |
URL to the AI agent session driving this operation, if applicable. Provides additional auditability for AI-driven operations. |
force |
boolean |
no | false |
If True, allow overwriting an existing version pin. Existing pins may have been set by rollouts, breaking-change migrations, or other operators. Defaults to False. NOTE: force=True only bypasses the existing-pin check — major-version crossings are always blocked and cannot be overridden. |
config_api_root |
string | null |
no | null |
Optional API root URL override for the Config API. Defaults to Airbyte Cloud (https://cloud.airbyte.com/api/v1). Use this to target local or self-hosted deployments. |
customer_tier_filter |
enum("TIER_0", "TIER_1", "TIER_2", "UNKNOWN", "ALL") |
no | "TIER_2" |
Required tier filter: 'TIER_0', 'TIER_1', 'TIER_2', 'UNKNOWN', or 'ALL'. The operation will be rejected if the actual customer tier does not match. Use 'ALL' to proceed regardless of tier (a warning is shown for sensitive tiers). |
Show input JSON schema
{
"additionalProperties": false,
"properties": {
"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"
}
],
"description": "The Airbyte Cloud workspace ID (UUID) or alias. Accepts '@devin-ai-sandbox' as an alias for the Devin AI sandbox workspace."
},
"connector_name": {
"description": "The connector name (e.g., 'source-github', 'destination-bigquery').",
"type": "string"
},
"connector_type": {
"description": "The type of connector (source or destination)",
"enum": [
"source",
"destination"
],
"type": "string"
},
"approval_comment_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "URL to the Slack approval record. Obtain this by calling the `escalate_to_human` tool with `approval_requested=True`; the backend delivers the approval record URL when a human clicks Approve. Format: https://<workspace>.slack.com/archives/... The admin email is automatically resolved from the approver's identity via the team roster."
},
"version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The semver version string to pin to (e.g., '0.1.0'). Must be None if unset is True."
},
"unset": {
"default": false,
"description": "If True, removes any existing version override. Cannot be True if version is provided.",
"type": "boolean"
},
"override_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Required when setting a version. Explanation for the override (min 10 characters)."
},
"override_reason_reference_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional URL with more context (e.g., issue link)."
},
"issue_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "URL to the GitHub issue providing context for this operation. Must be a valid GitHub URL (https://github.com/...). Required for authorization."
},
"ai_agent_session_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "URL to the AI agent session driving this operation, if applicable. Provides additional auditability for AI-driven operations."
},
"force": {
"default": false,
"description": "If `True`, allow overwriting an existing version pin. Existing pins may have been set by rollouts, breaking-change migrations, or other operators. Defaults to `False`. NOTE: `force=True` only bypasses the existing-pin check \u2014 major-version crossings are always blocked and cannot be overridden.",
"type": "boolean"
},
"config_api_root": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional API root URL override for the Config API. Defaults to Airbyte Cloud (https://cloud.airbyte.com/api/v1). Use this to target local or self-hosted deployments."
},
"customer_tier_filter": {
"default": "TIER_2",
"description": "Required tier filter: 'TIER_0', 'TIER_1', 'TIER_2', 'UNKNOWN', or 'ALL'. The operation will be rejected if the actual customer tier does not match. Use 'ALL' to proceed regardless of tier (a warning is shown for sensitive tiers).",
"enum": [
"TIER_0",
"TIER_1",
"TIER_2",
"UNKNOWN",
"ALL"
],
"type": "string"
}
},
"required": [
"workspace_id",
"connector_name",
"connector_type"
],
"type": "object"
}
Show output JSON schema
{
"description": "Result of a workspace-level version override operation.\n\nThis model provides detailed information about the outcome of a workspace-level\nversion pinning or unpinning operation.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"type": "boolean"
},
"message": {
"description": "Human-readable message describing the result",
"type": "string"
},
"workspace_id": {
"description": "The workspace ID",
"type": "string"
},
"connector_name": {
"description": "The connector name (e.g., 'source-github')",
"type": "string"
},
"connector_type": {
"description": "The type of connector (source or destination)",
"enum": [
"source",
"destination"
],
"type": "string"
},
"version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The version that was pinned (None if cleared or failed)"
},
"customer_tier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Customer tier of the workspace's organization (TIER_0, TIER_1, TIER_2, UNKNOWN). Included as a guardrail annotation."
},
"is_eu": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether the workspace is in the EU region."
},
"tier_warning": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Warning message if the operation targets a sensitive customer tier."
},
"warnings": {
"description": "Warnings raised by this operation.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"success",
"message",
"workspace_id",
"connector_name",
"connector_type"
],
"type": "object"
}
start_connector_rollout
Start or configure a connector rollout workflow.
This tool configures and starts a connector rollout workflow. It can be called multiple times while the rollout is in INITIALIZED state to update the configuration (strategy, percentages). Once the Temporal workflow starts and the state transitions to WORKFLOW_STARTED, the configuration is locked and cannot be changed.
Behavior:
- If rollout is INITIALIZED: Updates configuration and starts the workflow
- If rollout is already started: Returns an error (configuration is locked)
Configuration Parameters:
- rollout_strategy: 'manual' (default), 'automated', or 'overridden'
- initial_rollout_pct: Step size for progression (default: 25%)
- final_target_rollout_pct: Maximum percentage to pin (default: 50%)
- customer_tier: Customer tier to target - 'TIER_0', 'TIER_1', 'TIER_2', or 'ALL' (default: TIER_2)
Admin-only operation - Requires:
- AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io environment variable
approval_comment_url(Slack approval record URL fromescalate_to_human), ORadmin_user_email_overridewhen running inside the Ops Webapp.
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
docker_repository |
string |
yes | — | The docker repository (e.g., 'airbyte/source-pokeapi') |
docker_image_tag |
string |
yes | — | The docker image tag (e.g., '0.3.48-rc.1') |
actor_definition_id |
string |
yes | — | The actor definition ID (UUID) |
approval_comment_url |
string | null |
no | null |
URL to the Slack approval record. Obtain this by calling the escalate_to_human tool with approval_requested=True; the backend delivers the approval record URL when a human clicks Approve. Format: https:// |
admin_user_email_override |
string | null |
no | null |
Direct admin email override for webapp-initiated actions. When the Ops Webapp env var is set, this bypasses the approval URL requirement. Ignored in agent/cron environments. |
rollout_strategy |
enum("manual", "automated", "overridden") |
no | "manual" |
The rollout strategy: 'manual' for manual control of rollout progression, 'automated' for automatic progression based on metrics, 'overridden' for special cases where normal rules are bypassed. |
initial_rollout_pct |
integer | null |
no | null |
Initial/step percentage for rollout progression (0-100). For automated rollouts, this is the percentage increment per step. For example, 25 means the rollout will advance by 25% each step. Default is 25% if not specified. |
final_target_rollout_pct |
integer | null |
no | null |
Maximum percentage of actors to pin (0-100). The rollout will not exceed this percentage. For example, 50 means at most 50% of actors will be pinned to the RC. Default is 50% if not specified. |
customer_tier |
enum("TIER_0", "TIER_1", "TIER_2", "ALL") | null |
no | null |
The customer tier to target for this rollout. Each tier represents a different group of customers: 'TIER_0' for the highest-priority customers, 'TIER_1' for mid-tier customers, 'TIER_2' for the broadest customer group (default if not specified), 'ALL' to target all customer tiers. When not specified, the platform defaults to TIER_2 only. |
Show input JSON schema
{
"additionalProperties": false,
"properties": {
"docker_repository": {
"description": "The docker repository (e.g., 'airbyte/source-pokeapi')",
"type": "string"
},
"docker_image_tag": {
"description": "The docker image tag (e.g., '0.3.48-rc.1')",
"type": "string"
},
"actor_definition_id": {
"description": "The actor definition ID (UUID)",
"type": "string"
},
"approval_comment_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "URL to the Slack approval record. Obtain this by calling the `escalate_to_human` tool with `approval_requested=True`; the backend delivers the approval record URL when a human clicks Approve. Format: https://<workspace>.slack.com/archives/... The admin email is automatically resolved from the approver's identity via the team roster."
},
"admin_user_email_override": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Direct admin email override for webapp-initiated actions. When the Ops Webapp env var is set, this bypasses the approval URL requirement. Ignored in agent/cron environments."
},
"rollout_strategy": {
"default": "manual",
"description": "The rollout strategy: 'manual' for manual control of rollout progression, 'automated' for automatic progression based on metrics, 'overridden' for special cases where normal rules are bypassed.",
"enum": [
"manual",
"automated",
"overridden"
],
"type": "string"
},
"initial_rollout_pct": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Initial/step percentage for rollout progression (0-100). For automated rollouts, this is the percentage increment per step. For example, 25 means the rollout will advance by 25% each step. Default is 25% if not specified."
},
"final_target_rollout_pct": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum percentage of actors to pin (0-100). The rollout will not exceed this percentage. For example, 50 means at most 50% of actors will be pinned to the RC. Default is 50% if not specified."
},
"customer_tier": {
"anyOf": [
{
"enum": [
"TIER_0",
"TIER_1",
"TIER_2",
"ALL"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The customer tier to target for this rollout. Each tier represents a different group of customers: 'TIER_0' for the highest-priority customers, 'TIER_1' for mid-tier customers, 'TIER_2' for the broadest customer group (default if not specified), 'ALL' to target all customer tiers. When not specified, the platform defaults to TIER_2 only."
}
},
"required": [
"docker_repository",
"docker_image_tag",
"actor_definition_id"
],
"type": "object"
}
Show output JSON schema
{
"description": "Result of a connector rollout start operation.\n\nThis model provides detailed information about the outcome of starting\na connector rollout workflow.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"type": "boolean"
},
"message": {
"description": "Human-readable message describing the result",
"type": "string"
},
"docker_repository": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The docker repository (e.g., 'airbyte/source-github')"
},
"docker_image_tag": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The docker image tag (e.g., '1.2.0-rc.2')"
},
"actor_definition_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The actor definition ID (UUID)"
},
"rollout_strategy": {
"anyOf": [
{
"enum": [
"manual",
"automated",
"overridden"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The rollout strategy used"
}
},
"required": [
"success",
"message"
],
"type": "object"
}
1# Copyright (c) 2025 Airbyte, Inc., all rights reserved. 2"""MCP tools for connector version lifecycle: cloud version overrides, progressive rollouts, and pre-release publishing. 3 4## MCP reference 5 6.. include:: ../../../docs/mcp-generated/connector_versions.md 7 :start-line: 2 8""" 9 10# NOTE: We intentionally do NOT use `from __future__ import annotations` here. 11# FastMCP has issues resolving forward references when PEP 563 deferred annotations 12# are used. See: https://github.com/jlowin/fastmcp/issues/905 13# Python 3.12+ supports modern type hint syntax natively, so this is not needed. 14 15__all__: list[str] = [] 16 17import base64 18import logging 19from dataclasses import dataclass 20from enum import StrEnum 21from typing import Annotated, Literal 22 23import requests 24import yaml 25from airbyte import constants 26from airbyte.exceptions import PyAirbyteInputError 27from fastmcp import Context, FastMCP 28from fastmcp_extensions import get_mcp_config, mcp_tool, register_mcp_tools 29from pydantic import BaseModel, Field 30 31from airbyte_ops_mcp.airbyte_repo.bump_version import strip_prerelease_suffix 32from airbyte_ops_mcp.approval_resolution import ( 33 ApprovalStatus, 34 check_approval_status, 35) 36from airbyte_ops_mcp.cloud_admin import api_client 37from airbyte_ops_mcp.cloud_admin.auth import ( 38 CloudAuthError, 39 require_internal_admin_flag_only, 40) 41from airbyte_ops_mcp.cloud_admin.models import ( 42 ConnectorRolloutFinalizeResult, 43 ConnectorRolloutPauseResult, 44 ConnectorRolloutProgressResult, 45 ConnectorRolloutStartResult, 46 ConnectorVersionInfo, 47 OrganizationVersionOverrideResult, 48 VersionOverrideOperationResult, 49 WorkspaceVersionOverrideResult, 50) 51from airbyte_ops_mcp.cloud_admin.version_overrides import ( 52 VersionOverrideTarget, 53 get_connector_version_info, 54 set_version_override, 55) 56from airbyte_ops_mcp.connector_ops.rollouts._helpers import ( 57 count_eligible_or_pinned_actors, 58) 59from airbyte_ops_mcp.connector_ops.rollouts.state_transitions import ( 60 pause_rollout, 61 unpause_rollout, 62) 63from airbyte_ops_mcp.constants import ServerConfigKey, WorkspaceAliasEnum 64from airbyte_ops_mcp.github_actions import trigger_workflow_dispatch 65from airbyte_ops_mcp.github_api import ( 66 GITHUB_API_BASE, 67 get_pr_head_ref, 68 resolve_ci_trigger_github_token, 69) 70from airbyte_ops_mcp.mcp.cloud_auth import resolve_cloud_auth 71from airbyte_ops_mcp.tier_cache import TierFilter, resolve_workspace 72 73logger = logging.getLogger(__name__) 74 75 76@dataclass(frozen=True) 77class _ResolvedCloudAuth: 78 """Resolved authentication for Airbyte Cloud API calls. 79 80 Either bearer_token OR (client_id AND client_secret) will be set, not both. 81 """ 82 83 bearer_token: str | None = None 84 client_id: str | None = None 85 client_secret: str | None = None 86 87 88@mcp_tool( 89 read_only=True, 90 idempotent=True, 91 open_world=True, 92) 93def get_cloud_connector_version( 94 workspace_id: Annotated[ 95 str | WorkspaceAliasEnum, 96 Field( 97 description="The Airbyte Cloud workspace ID (UUID) or alias. " 98 "Accepts '@devin-ai-sandbox' as an alias for the Devin AI sandbox workspace." 99 ), 100 ], 101 actor_id: Annotated[ 102 str, "The ID of the deployed connector (source or destination)" 103 ], 104 actor_type: Annotated[ 105 Literal["source", "destination"], 106 "The type of connector (source or destination)", 107 ], 108 config_api_root: Annotated[ 109 str | None, 110 Field( 111 description="Optional API root URL override for the Config API. " 112 "Defaults to Airbyte Cloud (https://cloud.airbyte.com/api/v1). " 113 "Use this to target local or self-hosted deployments.", 114 default=None, 115 ), 116 ] = None, 117 *, 118 ctx: Context, 119) -> ConnectorVersionInfo: 120 """Get the current version information for a deployed connector. 121 122 Returns version details including the current version string and whether 123 an override (pin) is applied. 124 125 Authentication credentials are resolved in priority order: 126 127 1. Bearer token (Authorization header or AIRBYTE_CLOUD_BEARER_TOKEN env var) 128 2. HTTP headers: X-Airbyte-Cloud-Client-Id, X-Airbyte-Cloud-Client-Secret 129 3. Environment variables: AIRBYTE_CLOUD_CLIENT_ID, AIRBYTE_CLOUD_CLIENT_SECRET 130 """ 131 resolved_workspace_id = WorkspaceAliasEnum.resolve(workspace_id) 132 assert resolved_workspace_id is not None # workspace_id is required 133 134 return get_connector_version_info( 135 auth=resolve_cloud_auth(ctx), 136 workspace_id=resolved_workspace_id, 137 actor_id=actor_id, 138 actor_type=actor_type, 139 config_api_root=config_api_root, 140 ) 141 142 143@mcp_tool( 144 destructive=True, 145 idempotent=False, 146 open_world=True, 147) 148def set_cloud_connector_version_override( 149 workspace_id: Annotated[ 150 str | WorkspaceAliasEnum, 151 Field( 152 description="The Airbyte Cloud workspace ID (UUID) or alias. " 153 "Accepts '@devin-ai-sandbox' as an alias for the Devin AI sandbox workspace." 154 ), 155 ], 156 actor_id: Annotated[ 157 str, "The ID of the deployed connector (source or destination)" 158 ], 159 actor_type: Annotated[ 160 Literal["source", "destination"], 161 "The type of connector (source or destination)", 162 ], 163 approval_comment_url: Annotated[ 164 str | None, 165 Field( 166 description="URL to the Slack approval record. Obtain this by calling the " 167 "`escalate_to_human` tool with `approval_requested=True`; the backend delivers " 168 "the approval record URL when a human clicks Approve. " 169 "Format: https://<workspace>.slack.com/archives/... " 170 "The admin email is automatically resolved from the approver's identity " 171 "via the team roster.", 172 default=None, 173 ), 174 ], 175 version: Annotated[ 176 str | None, 177 Field( 178 description="The semver version string to pin to (e.g., '0.1.0'). " 179 "Must be None if unset is True.", 180 default=None, 181 ), 182 ], 183 unset: Annotated[ 184 bool, 185 Field( 186 description="If True, removes any existing version override. " 187 "Cannot be True if version is provided.", 188 default=False, 189 ), 190 ], 191 override_reason: Annotated[ 192 str | None, 193 Field( 194 description="Required when setting a version. " 195 "Explanation for the override (min 10 characters).", 196 default=None, 197 ), 198 ], 199 override_reason_reference_url: Annotated[ 200 str | None, 201 Field( 202 description="Optional URL with more context (e.g., issue link).", 203 default=None, 204 ), 205 ], 206 issue_url: Annotated[ 207 str | None, 208 Field( 209 description="URL to the GitHub issue providing context for this operation. " 210 "Must be a valid GitHub URL (https://github.com/...). Required for authorization.", 211 default=None, 212 ), 213 ], 214 ai_agent_session_url: Annotated[ 215 str | None, 216 Field( 217 description="URL to the AI agent session driving this operation, if applicable. " 218 "Provides additional auditability for AI-driven operations.", 219 default=None, 220 ), 221 ] = None, 222 force: Annotated[ 223 bool, 224 Field( 225 description="If `True`, allow overwriting an existing version pin. " 226 "Existing pins may have been set by rollouts, breaking-change migrations, " 227 "or other operators. Defaults to `False`. NOTE: `force=True` only " 228 "bypasses the existing-pin check — major-version crossings are always " 229 "blocked and cannot be overridden.", 230 default=False, 231 ), 232 ] = False, 233 config_api_root: Annotated[ 234 str | None, 235 Field( 236 description="Optional API root URL override for the Config API. " 237 "Defaults to Airbyte Cloud (https://cloud.airbyte.com/api/v1). " 238 "Use this to target local or self-hosted deployments.", 239 default=None, 240 ), 241 ] = None, 242 customer_tier_filter: Annotated[ 243 TierFilter, 244 Field( 245 description=( 246 "Required tier filter: 'TIER_0', 'TIER_1', 'TIER_2', 'UNKNOWN', or 'ALL'. " 247 "The operation will be rejected if the actual customer tier does not match. " 248 "Use 'ALL' to proceed regardless of tier (a warning is shown for sensitive tiers)." 249 ), 250 ), 251 ] = "TIER_2", 252 *, 253 ctx: Context, 254) -> VersionOverrideOperationResult: 255 """Set or clear a version override for a deployed connector. 256 257 This creates a regular version override, not a progressive-rollout pin. The 258 rollout does not track it, count it toward its progress, or remove it at 259 finalization, and an actor with this override is never picked by a rollout. 260 To include a specific actor in a running rollout, use 261 `progress_connector_rollout` with `actor_ids` instead. 262 263 **Admin-only operation** - Requires: 264 265 - AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io environment variable 266 - issue_url parameter (GitHub issue URL for context) 267 - approval_comment_url (Slack approval record URL from `escalate_to_human`) 268 269 The admin user email is automatically derived from the Slack approval record, 270 resolving the approver's @airbyte.io email via the team roster. 271 272 You must specify EXACTLY ONE of `version` OR `unset=True`, but not both. 273 When setting a version, `override_reason` is required. 274 275 The `customer_tier_filter` parameter gates the operation: the call fails if 276 the actual tier of the workspace's organization does not match. Use `ALL` 277 to bypass the check (a warning is still emitted for sensitive tiers). 278 279 Business rules enforced: 280 281 - Dev versions (-dev): Only creator can unpin their own dev version override 282 - Production versions: Require strong justification mentioning customer/support/investigation 283 - Release candidates (-rc): Any admin can pin/unpin RC versions 284 285 Authentication credentials are resolved in priority order: 286 287 1. Bearer token (Authorization header or AIRBYTE_CLOUD_BEARER_TOKEN env var) 288 2. HTTP headers: X-Airbyte-Cloud-Client-Id, X-Airbyte-Cloud-Client-Secret 289 3. Environment variables: AIRBYTE_CLOUD_CLIENT_ID, AIRBYTE_CLOUD_CLIENT_SECRET 290 """ 291 resolved_workspace_id = WorkspaceAliasEnum.resolve(workspace_id) 292 assert resolved_workspace_id is not None # workspace_id is required 293 294 ws_resolution = resolve_workspace( 295 workspace_id=resolved_workspace_id, 296 allow_degraded=True, 297 ) 298 if not ws_resolution.organization_id: 299 return VersionOverrideOperationResult( 300 success=False, 301 message="Could not resolve organization for workspace.", 302 connector_id=actor_id, 303 connector_type=actor_type, 304 ) 305 306 result = set_version_override( 307 auth=resolve_cloud_auth(ctx), 308 target=VersionOverrideTarget( 309 scope="actor", 310 organization_id=ws_resolution.organization_id, 311 workspace_id=resolved_workspace_id, 312 actor_id=actor_id, 313 connector_type=actor_type, 314 ), 315 approval_comment_url=approval_comment_url, 316 version=version, 317 unset=unset, 318 override_reason=override_reason, 319 override_reason_reference_url=override_reason_reference_url, 320 issue_url=issue_url, 321 ai_agent_session_url=ai_agent_session_url, 322 customer_tier_filter=customer_tier_filter, 323 force=force, 324 config_api_root=config_api_root, 325 ) 326 assert isinstance(result, VersionOverrideOperationResult) 327 return result 328 329 330@mcp_tool( 331 destructive=True, 332 idempotent=False, 333 open_world=True, 334) 335def set_workspace_connector_version_override( 336 workspace_id: Annotated[ 337 str | WorkspaceAliasEnum, 338 Field( 339 description="The Airbyte Cloud workspace ID (UUID) or alias. " 340 "Accepts '@devin-ai-sandbox' as an alias for the Devin AI sandbox workspace." 341 ), 342 ], 343 connector_name: Annotated[ 344 str, 345 Field( 346 description="The connector name (e.g., 'source-github', 'destination-bigquery')." 347 ), 348 ], 349 connector_type: Annotated[ 350 Literal["source", "destination"], 351 "The type of connector (source or destination)", 352 ], 353 approval_comment_url: Annotated[ 354 str | None, 355 Field( 356 description="URL to the Slack approval record. Obtain this by calling the " 357 "`escalate_to_human` tool with `approval_requested=True`; the backend delivers " 358 "the approval record URL when a human clicks Approve. " 359 "Format: https://<workspace>.slack.com/archives/... " 360 "The admin email is automatically resolved from the approver's identity " 361 "via the team roster.", 362 default=None, 363 ), 364 ], 365 version: Annotated[ 366 str | None, 367 Field( 368 description="The semver version string to pin to (e.g., '0.1.0'). " 369 "Must be None if unset is True.", 370 default=None, 371 ), 372 ], 373 unset: Annotated[ 374 bool, 375 Field( 376 description="If True, removes any existing version override. " 377 "Cannot be True if version is provided.", 378 default=False, 379 ), 380 ], 381 override_reason: Annotated[ 382 str | None, 383 Field( 384 description="Required when setting a version. " 385 "Explanation for the override (min 10 characters).", 386 default=None, 387 ), 388 ], 389 override_reason_reference_url: Annotated[ 390 str | None, 391 Field( 392 description="Optional URL with more context (e.g., issue link).", 393 default=None, 394 ), 395 ], 396 issue_url: Annotated[ 397 str | None, 398 Field( 399 description="URL to the GitHub issue providing context for this operation. " 400 "Must be a valid GitHub URL (https://github.com/...). Required for authorization.", 401 default=None, 402 ), 403 ], 404 ai_agent_session_url: Annotated[ 405 str | None, 406 Field( 407 description="URL to the AI agent session driving this operation, if applicable. " 408 "Provides additional auditability for AI-driven operations.", 409 default=None, 410 ), 411 ] = None, 412 force: Annotated[ 413 bool, 414 Field( 415 description="If `True`, allow overwriting an existing version pin. " 416 "Existing pins may have been set by rollouts, breaking-change migrations, " 417 "or other operators. Defaults to `False`. NOTE: `force=True` only " 418 "bypasses the existing-pin check — major-version crossings are always " 419 "blocked and cannot be overridden.", 420 default=False, 421 ), 422 ] = False, 423 config_api_root: Annotated[ 424 str | None, 425 Field( 426 description="Optional API root URL override for the Config API. " 427 "Defaults to Airbyte Cloud (https://cloud.airbyte.com/api/v1). " 428 "Use this to target local or self-hosted deployments.", 429 default=None, 430 ), 431 ] = None, 432 customer_tier_filter: Annotated[ 433 TierFilter, 434 Field( 435 description=( 436 "Required tier filter: 'TIER_0', 'TIER_1', 'TIER_2', 'UNKNOWN', or 'ALL'. " 437 "The operation will be rejected if the actual customer tier does not match. " 438 "Use 'ALL' to proceed regardless of tier (a warning is shown for sensitive tiers)." 439 ), 440 ), 441 ] = "TIER_2", 442 *, 443 ctx: Context, 444) -> WorkspaceVersionOverrideResult: 445 """Set or clear a workspace-level version override for a connector type. 446 447 This pins ALL instances of a connector type within a workspace to a specific version. 448 For example, pinning 'source-github' at workspace level means all GitHub sources 449 in that workspace will use the pinned version. 450 451 This creates a regular version override, not a progressive-rollout pin. The 452 rollout does not track it, count it toward its progress, or remove it at 453 finalization, and an actor with this override is never picked by a rollout. 454 To include a specific actor in a running rollout, use 455 `progress_connector_rollout` with `actor_ids` instead. 456 457 **Admin-only operation** - Requires: 458 459 - AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io environment variable 460 - issue_url parameter (GitHub issue URL for context) 461 - approval_comment_url (Slack approval record URL from `escalate_to_human`) 462 463 You must specify EXACTLY ONE of `version` OR `unset=True`, but not both. 464 When setting a version, `override_reason` is required. 465 466 The `customer_tier_filter` parameter gates the operation: the call fails if 467 the actual tier of the workspace's organization does not match. Use `ALL` 468 to bypass the check (a warning is still emitted for sensitive tiers). 469 """ 470 resolved_workspace_id = WorkspaceAliasEnum.resolve(workspace_id) 471 assert resolved_workspace_id is not None # workspace_id is required 472 473 ws_resolution = resolve_workspace( 474 workspace_id=resolved_workspace_id, 475 allow_degraded=True, 476 ) 477 if not ws_resolution.organization_id: 478 return WorkspaceVersionOverrideResult( 479 success=False, 480 message="Could not resolve organization for workspace.", 481 workspace_id=resolved_workspace_id, 482 connector_name=connector_name, 483 connector_type=connector_type, 484 ) 485 486 result = set_version_override( 487 auth=resolve_cloud_auth(ctx), 488 target=VersionOverrideTarget( 489 scope="workspace", 490 organization_id=ws_resolution.organization_id, 491 workspace_id=resolved_workspace_id, 492 connector_name=connector_name, 493 connector_type=connector_type, 494 ), 495 approval_comment_url=approval_comment_url, 496 version=version, 497 unset=unset, 498 override_reason=override_reason, 499 override_reason_reference_url=override_reason_reference_url, 500 issue_url=issue_url, 501 ai_agent_session_url=ai_agent_session_url, 502 customer_tier_filter=customer_tier_filter, 503 force=force, 504 config_api_root=config_api_root, 505 ) 506 assert isinstance(result, WorkspaceVersionOverrideResult) 507 return result 508 509 510@mcp_tool( 511 destructive=True, 512 idempotent=False, 513 open_world=True, 514) 515def set_organization_connector_version_override( 516 organization_id: Annotated[ 517 str, 518 Field(description="The Airbyte Cloud organization ID."), 519 ], 520 connector_name: Annotated[ 521 str, 522 Field( 523 description="The connector name (e.g., 'source-github', 'destination-bigquery')." 524 ), 525 ], 526 connector_type: Annotated[ 527 Literal["source", "destination"], 528 "The type of connector (source or destination)", 529 ], 530 approval_comment_url: Annotated[ 531 str | None, 532 Field( 533 description="URL to the Slack approval record. Obtain this by calling the " 534 "`escalate_to_human` tool with `approval_requested=True`; the backend delivers " 535 "the approval record URL when a human clicks Approve. " 536 "Format: https://<workspace>.slack.com/archives/... " 537 "The admin email is automatically resolved from the approver's identity " 538 "via the team roster.", 539 default=None, 540 ), 541 ], 542 version: Annotated[ 543 str | None, 544 Field( 545 description="The semver version string to pin to (e.g., '0.1.0'). " 546 "Must be None if unset is True.", 547 default=None, 548 ), 549 ], 550 unset: Annotated[ 551 bool, 552 Field( 553 description="If True, removes any existing version override. " 554 "Cannot be True if version is provided.", 555 default=False, 556 ), 557 ], 558 override_reason: Annotated[ 559 str | None, 560 Field( 561 description="Required when setting a version. " 562 "Explanation for the override (min 10 characters).", 563 default=None, 564 ), 565 ], 566 override_reason_reference_url: Annotated[ 567 str | None, 568 Field( 569 description="Optional URL with more context (e.g., issue link).", 570 default=None, 571 ), 572 ], 573 issue_url: Annotated[ 574 str | None, 575 Field( 576 description="URL to the GitHub issue providing context for this operation. " 577 "Must be a valid GitHub URL (https://github.com/...). Required for authorization.", 578 default=None, 579 ), 580 ], 581 ai_agent_session_url: Annotated[ 582 str | None, 583 Field( 584 description="URL to the AI agent session driving this operation, if applicable. " 585 "Provides additional auditability for AI-driven operations.", 586 default=None, 587 ), 588 ] = None, 589 force: Annotated[ 590 bool, 591 Field( 592 description="If `True`, allow overwriting an existing version pin. " 593 "Existing pins may have been set by rollouts, breaking-change migrations, " 594 "or other operators. Defaults to `False`. NOTE: `force=True` only " 595 "bypasses the existing-pin check — major-version crossings are always " 596 "blocked and cannot be overridden.", 597 default=False, 598 ), 599 ] = False, 600 config_api_root: Annotated[ 601 str | None, 602 Field( 603 description="Optional API root URL override for the Config API. " 604 "Defaults to Airbyte Cloud (https://cloud.airbyte.com/api/v1). " 605 "Use this to target local or self-hosted deployments.", 606 default=None, 607 ), 608 ] = None, 609 customer_tier_filter: Annotated[ 610 TierFilter, 611 Field( 612 description=( 613 "Required tier filter: 'TIER_0', 'TIER_1', 'TIER_2', 'UNKNOWN', or 'ALL'. " 614 "The operation will be rejected if the actual customer tier does not match. " 615 "Use 'ALL' to proceed regardless of tier (a warning is shown for sensitive tiers)." 616 ), 617 ), 618 ] = "TIER_2", 619 *, 620 ctx: Context, 621) -> OrganizationVersionOverrideResult: 622 """Set or clear an organization-level version override for a connector type. 623 624 This pins ALL instances of a connector type across an entire organization to a 625 specific version. For example, pinning 'source-github' at organization level means 626 all GitHub sources in all workspaces within that organization will use the pinned version. 627 628 **Admin-only operation** - Requires: 629 630 - AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io environment variable 631 - issue_url parameter (GitHub issue URL for context) 632 - approval_comment_url (Slack approval record URL from `escalate_to_human`) 633 634 You must specify EXACTLY ONE of `version` OR `unset=True`, but not both. 635 When setting a version, `override_reason` is required. 636 637 The `customer_tier_filter` parameter gates the operation: the call fails if 638 the actual tier of the organization does not match. Use `ALL` to bypass 639 the check (a warning is still emitted for sensitive tiers). 640 """ 641 result = set_version_override( 642 auth=resolve_cloud_auth(ctx), 643 target=VersionOverrideTarget( 644 scope="organization", 645 organization_id=organization_id, 646 connector_name=connector_name, 647 connector_type=connector_type, 648 ), 649 approval_comment_url=approval_comment_url, 650 version=version, 651 unset=unset, 652 override_reason=override_reason, 653 override_reason_reference_url=override_reason_reference_url, 654 issue_url=issue_url, 655 ai_agent_session_url=ai_agent_session_url, 656 customer_tier_filter=customer_tier_filter, 657 force=force, 658 config_api_root=config_api_root, 659 ) 660 assert isinstance(result, OrganizationVersionOverrideResult) 661 return result 662 663 664def _resolve_cloud_auth(ctx: Context) -> _ResolvedCloudAuth: 665 """Resolve authentication credentials for Airbyte Cloud API. 666 667 Credentials are resolved in priority order: 668 1. Bearer token (Authorization header or AIRBYTE_CLOUD_BEARER_TOKEN env var) 669 2. Client credentials (X-Airbyte-Cloud-Client-Id/Secret headers or env vars) 670 671 Args: 672 ctx: FastMCP Context object from the current tool invocation. 673 674 Returns: 675 `_ResolvedCloudAuth` with either bearer_token or client credentials set. 676 677 Raises: 678 CloudAuthError: If credentials cannot be resolved from headers or env vars. 679 """ 680 # Try bearer token first (preferred, but not required) 681 bearer_token = get_mcp_config(ctx, ServerConfigKey.BEARER_TOKEN) 682 if bearer_token: 683 return _ResolvedCloudAuth(bearer_token=bearer_token) 684 685 # Fall back to client credentials 686 try: 687 client_id = get_mcp_config(ctx, ServerConfigKey.CLIENT_ID) 688 client_secret = get_mcp_config(ctx, ServerConfigKey.CLIENT_SECRET) 689 return _ResolvedCloudAuth( 690 client_id=client_id, 691 client_secret=client_secret, 692 ) 693 except ValueError as e: 694 raise CloudAuthError( 695 f"Failed to resolve credentials. Ensure credentials are provided " 696 f"via Authorization header (Bearer token), " 697 f"HTTP headers (X-Airbyte-Cloud-Client-Id, X-Airbyte-Cloud-Client-Secret), " 698 f"or environment variables. Error: {e}" 699 ) from e 700 701 702@mcp_tool( 703 destructive=True, 704 idempotent=False, 705 open_world=True, 706) 707def start_connector_rollout( 708 docker_repository: Annotated[ 709 str, 710 Field(description="The docker repository (e.g., 'airbyte/source-pokeapi')"), 711 ], 712 docker_image_tag: Annotated[ 713 str, 714 Field(description="The docker image tag (e.g., '0.3.48-rc.1')"), 715 ], 716 actor_definition_id: Annotated[ 717 str, 718 Field(description="The actor definition ID (UUID)"), 719 ], 720 approval_comment_url: Annotated[ 721 str | None, 722 Field( 723 description="URL to the Slack approval record. Obtain this by calling the " 724 "`escalate_to_human` tool with `approval_requested=True`; the backend delivers " 725 "the approval record URL when a human clicks Approve. " 726 "Format: https://<workspace>.slack.com/archives/... " 727 "The admin email is automatically resolved from the approver's identity " 728 "via the team roster.", 729 default=None, 730 ), 731 ], 732 admin_user_email_override: Annotated[ 733 str | None, 734 Field( 735 description="Direct admin email override for webapp-initiated actions. " 736 "When the Ops Webapp env var is set, this bypasses the approval URL " 737 "requirement. Ignored in agent/cron environments.", 738 default=None, 739 ), 740 ], 741 rollout_strategy: Annotated[ 742 Literal["manual", "automated", "overridden"], 743 Field( 744 description="The rollout strategy: " 745 "'manual' for manual control of rollout progression, " 746 "'automated' for automatic progression based on metrics, " 747 "'overridden' for special cases where normal rules are bypassed.", 748 default="manual", 749 ), 750 ], 751 initial_rollout_pct: Annotated[ 752 int | None, 753 Field( 754 description="Initial/step percentage for rollout progression (0-100). " 755 "For automated rollouts, this is the percentage increment per step. " 756 "For example, 25 means the rollout will advance by 25% each step. " 757 "Default is 25% if not specified.", 758 default=None, 759 ), 760 ], 761 final_target_rollout_pct: Annotated[ 762 int | None, 763 Field( 764 description="Maximum percentage of actors to pin (0-100). " 765 "The rollout will not exceed this percentage. " 766 "For example, 50 means at most 50% of actors will be pinned to the RC. " 767 "Default is 50% if not specified.", 768 default=None, 769 ), 770 ], 771 customer_tier: Annotated[ 772 Literal["TIER_0", "TIER_1", "TIER_2", "ALL"] | None, 773 Field( 774 description="The customer tier to target for this rollout. " 775 "Each tier represents a different group of customers: " 776 "'TIER_0' for the highest-priority customers, " 777 "'TIER_1' for mid-tier customers, " 778 "'TIER_2' for the broadest customer group (default if not specified), " 779 "'ALL' to target all customer tiers. " 780 "When not specified, the platform defaults to TIER_2 only.", 781 default=None, 782 ), 783 ], 784 *, 785 ctx: Context, 786) -> ConnectorRolloutStartResult: 787 """Start or configure a connector rollout workflow. 788 789 This tool configures and starts a connector rollout workflow. It can be called 790 multiple times while the rollout is in INITIALIZED state to update the configuration 791 (strategy, percentages). Once the Temporal workflow starts and the state transitions 792 to WORKFLOW_STARTED, the configuration is locked and cannot be changed. 793 794 **Behavior:** 795 - If rollout is INITIALIZED: Updates configuration and starts the workflow 796 - If rollout is already started: Returns an error (configuration is locked) 797 798 **Configuration Parameters:** 799 - rollout_strategy: 'manual' (default), 'automated', or 'overridden' 800 - initial_rollout_pct: Step size for progression (default: 25%) 801 - final_target_rollout_pct: Maximum percentage to pin (default: 50%) 802 - customer_tier: Customer tier to target - 'TIER_0', 'TIER_1', 'TIER_2', or 'ALL' (default: TIER_2) 803 804 **Admin-only operation** - Requires: 805 - AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io environment variable 806 - `approval_comment_url` (Slack approval record URL from `escalate_to_human`), 807 OR `admin_user_email_override` when running inside the Ops Webapp. 808 """ 809 # Validate admin access (check env var flag) 810 try: 811 require_internal_admin_flag_only() 812 except CloudAuthError as e: 813 return ConnectorRolloutStartResult( 814 success=False, 815 message=f"Admin authentication failed: {e}", 816 docker_repository=docker_repository, 817 docker_image_tag=docker_image_tag, 818 actor_definition_id=actor_definition_id, 819 ) 820 821 # Resolve admin email: webapp bypass or external approval URL 822 approval = check_approval_status( 823 approval_comment_url=approval_comment_url, 824 user_email=admin_user_email_override, 825 ) 826 if approval.status != ApprovalStatus.APPROVED: 827 return ConnectorRolloutStartResult( 828 success=False, 829 message=approval.reason or "Approval check failed", 830 docker_repository=docker_repository, 831 docker_image_tag=docker_image_tag, 832 actor_definition_id=actor_definition_id, 833 ) 834 admin_user_email = approval.admin_email 835 836 # Resolve auth credentials 837 try: 838 auth = _resolve_cloud_auth(ctx) 839 except CloudAuthError as e: 840 return ConnectorRolloutStartResult( 841 success=False, 842 message=f"Failed to resolve credentials: {e}", 843 docker_repository=docker_repository, 844 docker_image_tag=docker_image_tag, 845 actor_definition_id=actor_definition_id, 846 ) 847 848 # Get user ID from admin email 849 try: 850 user_id = api_client.get_user_id_by_email( 851 email=admin_user_email, 852 config_api_root=constants.CLOUD_CONFIG_API_ROOT, 853 client_id=auth.client_id, 854 client_secret=auth.client_secret, 855 bearer_token=auth.bearer_token, 856 ) 857 except PyAirbyteInputError as e: 858 return ConnectorRolloutStartResult( 859 success=False, 860 message=f"Failed to get user ID for admin email '{admin_user_email}': {e}", 861 docker_repository=docker_repository, 862 docker_image_tag=docker_image_tag, 863 actor_definition_id=actor_definition_id, 864 ) 865 866 # Call the API to start the rollout 867 try: 868 api_client.start_connector_rollout( 869 docker_repository=docker_repository, 870 docker_image_tag=docker_image_tag, 871 actor_definition_id=actor_definition_id, 872 updated_by=user_id, 873 rollout_strategy=rollout_strategy, 874 config_api_root=constants.CLOUD_CONFIG_API_ROOT, 875 initial_rollout_pct=initial_rollout_pct, 876 final_target_rollout_pct=final_target_rollout_pct, 877 customer_tier=customer_tier, 878 client_id=auth.client_id, 879 client_secret=auth.client_secret, 880 bearer_token=auth.bearer_token, 881 ) 882 883 # Build message with configuration details 884 config_details = [] 885 if initial_rollout_pct is not None: 886 config_details.append(f"initial_rollout_pct={initial_rollout_pct}%") 887 if final_target_rollout_pct is not None: 888 config_details.append( 889 f"final_target_rollout_pct={final_target_rollout_pct}%" 890 ) 891 if customer_tier is not None: 892 config_details.append(f"customer_tier={customer_tier}") 893 config_str = ( 894 f" Configuration: {', '.join(config_details)}." if config_details else "" 895 ) 896 897 return ConnectorRolloutStartResult( 898 success=True, 899 message=f"Successfully started rollout workflow for " 900 f"{docker_repository}:{docker_image_tag}. " 901 f"The rollout state has transitioned from INITIALIZED to WORKFLOW_STARTED." 902 f"{config_str}", 903 docker_repository=docker_repository, 904 docker_image_tag=docker_image_tag, 905 actor_definition_id=actor_definition_id, 906 rollout_strategy=rollout_strategy, 907 ) 908 909 except PyAirbyteInputError as e: 910 return ConnectorRolloutStartResult( 911 success=False, 912 message=str(e), 913 docker_repository=docker_repository, 914 docker_image_tag=docker_image_tag, 915 actor_definition_id=actor_definition_id, 916 ) 917 918 919@mcp_tool( 920 destructive=True, 921 idempotent=False, 922 open_world=True, 923) 924def progress_connector_rollout( 925 docker_repository: Annotated[ 926 str, 927 Field(description="The docker repository (e.g., 'airbyte/source-pokeapi')"), 928 ], 929 docker_image_tag: Annotated[ 930 str, 931 Field(description="The docker image tag (e.g., '0.3.48-rc.1')"), 932 ], 933 actor_definition_id: Annotated[ 934 str, 935 Field(description="The actor definition ID (UUID)"), 936 ], 937 rollout_id: Annotated[ 938 str, 939 Field( 940 description="The rollout ID (UUID). Can be found from query_prod_connector_rollouts." 941 ), 942 ], 943 approval_comment_url: Annotated[ 944 str | None, 945 Field( 946 description="URL to the Slack approval record. Obtain this by calling the " 947 "`escalate_to_human` tool with `approval_requested=True`; the backend delivers " 948 "the approval record URL when a human clicks Approve. " 949 "Format: https://<workspace>.slack.com/archives/... " 950 "The admin email is automatically resolved from the approver's identity " 951 "via the team roster.", 952 default=None, 953 ), 954 ], 955 admin_user_email_override: Annotated[ 956 str | None, 957 Field( 958 description="Direct admin email override for webapp-initiated actions. " 959 "When the Ops Webapp env var is set, this bypasses the approval URL " 960 "requirement. Ignored in agent/cron environments.", 961 default=None, 962 ), 963 ], 964 target_percentage: Annotated[ 965 int | None, 966 Field( 967 description="Target percentage of actors to pin to the RC (1-100). " 968 "Either target_percentage or actor_ids must be provided.", 969 default=None, 970 ), 971 ] = None, 972 actor_ids: Annotated[ 973 list[str] | None, 974 Field( 975 description="Specific actor IDs to pin to the RC. " 976 "Either target_percentage or actor_ids must be provided.", 977 default=None, 978 ), 979 ] = None, 980 *, 981 ctx: Context, 982) -> ConnectorRolloutProgressResult: 983 """Progress a connector rollout by pinning actors to the RC version. 984 985 This tool progresses a connector rollout by either: 986 - Setting a target percentage of actors to pin to the RC version 987 - Specifying specific actor IDs to pin 988 989 **Admin-only operation** - Requires: 990 - AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io environment variable 991 - `approval_comment_url` (Slack approval record URL from `escalate_to_human`), 992 OR `admin_user_email_override` when running inside the Ops Webapp. 993 """ 994 # Validate admin access (check env var flag) 995 try: 996 require_internal_admin_flag_only() 997 except CloudAuthError as e: 998 return ConnectorRolloutProgressResult( 999 success=False, 1000 message=f"Admin authentication failed: {e}", 1001 rollout_id=rollout_id, 1002 docker_repository=docker_repository, 1003 docker_image_tag=docker_image_tag, 1004 ) 1005 1006 # Validate that at least one of target_percentage or actor_ids is provided 1007 if target_percentage is None and actor_ids is None: 1008 return ConnectorRolloutProgressResult( 1009 success=False, 1010 message="Either target_percentage or actor_ids must be provided", 1011 rollout_id=rollout_id, 1012 docker_repository=docker_repository, 1013 docker_image_tag=docker_image_tag, 1014 ) 1015 1016 # Resolve admin email: webapp bypass or external approval URL 1017 approval = check_approval_status( 1018 approval_comment_url=approval_comment_url, 1019 user_email=admin_user_email_override, 1020 ) 1021 if approval.status != ApprovalStatus.APPROVED: 1022 return ConnectorRolloutProgressResult( 1023 success=False, 1024 message=approval.reason or "Approval check failed", 1025 rollout_id=rollout_id, 1026 docker_repository=docker_repository, 1027 docker_image_tag=docker_image_tag, 1028 ) 1029 admin_user_email = approval.admin_email 1030 1031 # Resolve auth credentials 1032 try: 1033 auth = _resolve_cloud_auth(ctx) 1034 except CloudAuthError as e: 1035 return ConnectorRolloutProgressResult( 1036 success=False, 1037 message=f"Failed to resolve credentials: {e}", 1038 rollout_id=rollout_id, 1039 docker_repository=docker_repository, 1040 docker_image_tag=docker_image_tag, 1041 ) 1042 1043 # Get user ID from admin email 1044 try: 1045 user_id = api_client.get_user_id_by_email( 1046 email=admin_user_email, 1047 config_api_root=constants.CLOUD_CONFIG_API_ROOT, 1048 client_id=auth.client_id, 1049 client_secret=auth.client_secret, 1050 bearer_token=auth.bearer_token, 1051 ) 1052 except PyAirbyteInputError as e: 1053 return ConnectorRolloutProgressResult( 1054 success=False, 1055 message=f"Failed to get user ID for admin email '{admin_user_email}': {e}", 1056 rollout_id=rollout_id, 1057 docker_repository=docker_repository, 1058 docker_image_tag=docker_image_tag, 1059 ) 1060 1061 # Guard: a percentage-based progression toward a tier with zero eligible 1062 # actors will throw `ConnectorRolloutNotEnoughActorsProblem` server-side 1063 # and silently wedge the rollout at `workflow_started` (the throw happens 1064 # before the `IN_PROGRESS` write and the `@Transactional` rolls back). 1065 # Detect this up front and return an actionable error instead. Skipped when 1066 # pinning specific `actor_ids` (the caller chose the actors explicitly). 1067 if target_percentage is not None and target_percentage > 0 and not actor_ids: 1068 try: 1069 sync_info = api_client.get_actor_sync_info( 1070 rollout_id=rollout_id, 1071 config_api_root=constants.CLOUD_CONFIG_API_ROOT, 1072 client_id=auth.client_id, 1073 client_secret=auth.client_secret, 1074 bearer_token=auth.bearer_token, 1075 ) 1076 except (PyAirbyteInputError, requests.exceptions.RequestException): 1077 # If eligibility can't be fetched (bad input or a network-level 1078 # failure), fall through and let the progress call surface the 1079 # underlying error rather than crashing the pre-check. 1080 sync_info = None 1081 if sync_info is not None and count_eligible_or_pinned_actors(sync_info) == 0: 1082 return ConnectorRolloutProgressResult( 1083 success=False, 1084 message=( 1085 "Zero eligible actors: this rollout's tier has no actors to " 1086 "pin, so progressing to " 1087 f"target_percentage={target_percentage}% would throw " 1088 "ConnectorRolloutNotEnoughActorsProblem server-side and " 1089 "silently wedge the rollout at 'workflow_started'. " 1090 "TIER_1/TIER_0 are named strategic accounts; a connector " 1091 "with no customers in this tier can never pin anyone here. " 1092 "Do not progress this tier. If the last non-empty tier is " 1093 "healthy at 100%, cancel this empty rollout " 1094 "(retain_pins_on_cancellation=true) and finalize the healthy " 1095 "rollout as 'succeeded' to promote to GA. See the " 1096 "'Rollout stuck at workflow_started with zero eligible " 1097 "actors' troubleshooting guide in docs/progressive-rollouts.md." 1098 ), 1099 rollout_id=rollout_id, 1100 docker_repository=docker_repository, 1101 docker_image_tag=docker_image_tag, 1102 ) 1103 1104 # Call the API to progress the rollout 1105 try: 1106 api_client.progress_connector_rollout( 1107 docker_repository=docker_repository, 1108 docker_image_tag=docker_image_tag, 1109 actor_definition_id=actor_definition_id, 1110 rollout_id=rollout_id, 1111 updated_by=user_id, 1112 config_api_root=constants.CLOUD_CONFIG_API_ROOT, 1113 target_percentage=target_percentage, 1114 actor_ids=actor_ids, 1115 client_id=auth.client_id, 1116 client_secret=auth.client_secret, 1117 bearer_token=auth.bearer_token, 1118 ) 1119 1120 progress_msg = ( 1121 f"target_percentage={target_percentage}%" 1122 if target_percentage 1123 else f"{len(actor_ids) if actor_ids else 0} specific actors" 1124 ) 1125 return ConnectorRolloutProgressResult( 1126 success=True, 1127 message=f"Successfully progressed rollout for " 1128 f"{docker_repository}:{docker_image_tag} to {progress_msg}.", 1129 rollout_id=rollout_id, 1130 docker_repository=docker_repository, 1131 docker_image_tag=docker_image_tag, 1132 target_percentage=target_percentage, 1133 ) 1134 1135 except PyAirbyteInputError as e: 1136 return ConnectorRolloutProgressResult( 1137 success=False, 1138 message=str(e), 1139 rollout_id=rollout_id, 1140 docker_repository=docker_repository, 1141 docker_image_tag=docker_image_tag, 1142 ) 1143 1144 1145@mcp_tool( 1146 destructive=False, 1147 idempotent=True, 1148 open_world=True, 1149) 1150def pause_connector_rollout( 1151 docker_repository: Annotated[ 1152 str, 1153 Field(description="The docker repository (e.g., 'airbyte/source-pokeapi')"), 1154 ], 1155 docker_image_tag: Annotated[ 1156 str, 1157 Field(description="The docker image tag (e.g., '0.3.48-rc.1')"), 1158 ], 1159 actor_definition_id: Annotated[ 1160 str, 1161 Field(description="The actor definition ID (UUID)"), 1162 ], 1163 rollout_id: Annotated[ 1164 str, 1165 Field( 1166 description="The rollout ID (UUID). Can be found from query_prod_connector_rollouts." 1167 ), 1168 ], 1169 admin_user_email: Annotated[ 1170 str, 1171 Field( 1172 description="Email of the admin the change is attributed to, resolved to " 1173 "the rollout's `updated_by` user ID." 1174 ), 1175 ], 1176 paused_reason: Annotated[ 1177 str, 1178 Field( 1179 description="Why the rollout is being held, recorded on the rollout " 1180 "(e.g., 'Sync failures reported on TIER_2'). Required unless " 1181 "`unpause=True`." 1182 ), 1183 ] = "", 1184 unpause: Annotated[ 1185 bool, 1186 Field( 1187 description="Resume a paused rollout instead of pausing it, handing it " 1188 "back to Autopilot without pinning new customers." 1189 ), 1190 ] = False, 1191 *, 1192 ctx: Context, 1193) -> ConnectorRolloutPauseResult: 1194 """Pause a connector rollout, or resume a paused one with `unpause=True`. 1195 1196 A paused rollout is held in place: Autopilot will not advance or promote it, and 1197 already-pinned actors stay on the release candidate. To withdraw the version 1198 entirely, yank it instead. 1199 1200 Resuming hands the rollout back to Autopilot from exactly where it stopped, pinning 1201 no additional customers. A rollout with nothing pinned yet resumes at 1%, pinning 1202 one customer, because the platform rejects a zero-sized step. If Autopilot paused 1203 the rollout over failing syncs, it will pause it again while those failures persist. 1204 1205 Prefer pausing over `finalize_connector_rollout(state="canceled")` when reacting to 1206 a problem: the platform re-creates a rollout for every still-advertised release 1207 candidate, so cancelling loops. 1208 1209 Unlike progress/finalize, neither direction needs Slack approval — both are 1210 reversible and hold or restore the current state rather than moving customers ahead 1211 of the normal cadence. Both require `AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io`. 1212 """ 1213 paused_reason = paused_reason.strip() 1214 if unpause and paused_reason: 1215 return ConnectorRolloutPauseResult( 1216 success=False, 1217 message="A paused_reason does not apply when unpause=True.", 1218 rollout_id=rollout_id, 1219 docker_repository=docker_repository, 1220 docker_image_tag=docker_image_tag, 1221 ) 1222 if not unpause and not paused_reason: 1223 return ConnectorRolloutPauseResult( 1224 success=False, 1225 message="A paused_reason is required.", 1226 rollout_id=rollout_id, 1227 docker_repository=docker_repository, 1228 docker_image_tag=docker_image_tag, 1229 ) 1230 1231 try: 1232 require_internal_admin_flag_only() 1233 except CloudAuthError as e: 1234 return ConnectorRolloutPauseResult( 1235 success=False, 1236 message=f"Admin authentication failed: {e}", 1237 rollout_id=rollout_id, 1238 docker_repository=docker_repository, 1239 docker_image_tag=docker_image_tag, 1240 ) 1241 1242 try: 1243 auth = _resolve_cloud_auth(ctx) 1244 except CloudAuthError as e: 1245 return ConnectorRolloutPauseResult( 1246 success=False, 1247 message=f"Failed to resolve credentials: {e}", 1248 rollout_id=rollout_id, 1249 docker_repository=docker_repository, 1250 docker_image_tag=docker_image_tag, 1251 ) 1252 1253 try: 1254 user_id = api_client.get_user_id_by_email( 1255 email=admin_user_email, 1256 config_api_root=constants.CLOUD_CONFIG_API_ROOT, 1257 client_id=auth.client_id, 1258 client_secret=auth.client_secret, 1259 bearer_token=auth.bearer_token, 1260 ) 1261 except PyAirbyteInputError as e: 1262 return ConnectorRolloutPauseResult( 1263 success=False, 1264 message=f"Failed to get user ID for admin email '{admin_user_email}': {e}", 1265 rollout_id=rollout_id, 1266 docker_repository=docker_repository, 1267 docker_image_tag=docker_image_tag, 1268 ) 1269 1270 try: 1271 if unpause: 1272 resume_percentage, _ = unpause_rollout( 1273 docker_repository=docker_repository, 1274 docker_image_tag=docker_image_tag, 1275 actor_definition_id=actor_definition_id, 1276 rollout_id=rollout_id, 1277 updated_by=user_id, 1278 config_api_root=constants.CLOUD_CONFIG_API_ROOT, 1279 client_id=auth.client_id, 1280 client_secret=auth.client_secret, 1281 bearer_token=auth.bearer_token, 1282 ) 1283 else: 1284 pause_rollout( 1285 docker_repository=docker_repository, 1286 docker_image_tag=docker_image_tag, 1287 actor_definition_id=actor_definition_id, 1288 rollout_id=rollout_id, 1289 updated_by=user_id, 1290 paused_reason=paused_reason, 1291 config_api_root=constants.CLOUD_CONFIG_API_ROOT, 1292 client_id=auth.client_id, 1293 client_secret=auth.client_secret, 1294 bearer_token=auth.bearer_token, 1295 ) 1296 except PyAirbyteInputError as e: 1297 return ConnectorRolloutPauseResult( 1298 success=False, 1299 message=str(e), 1300 rollout_id=rollout_id, 1301 docker_repository=docker_repository, 1302 docker_image_tag=docker_image_tag, 1303 ) 1304 1305 if unpause: 1306 return ConnectorRolloutPauseResult( 1307 success=True, 1308 message=f"Successfully resumed rollout for " 1309 f"{docker_repository}:{docker_image_tag} at {resume_percentage}%. " 1310 "Autopilot will advance it from here.", 1311 rollout_id=rollout_id, 1312 docker_repository=docker_repository, 1313 docker_image_tag=docker_image_tag, 1314 ) 1315 1316 return ConnectorRolloutPauseResult( 1317 success=True, 1318 message=f"Successfully paused rollout for " 1319 f"{docker_repository}:{docker_image_tag}. Existing pins retained.", 1320 rollout_id=rollout_id, 1321 docker_repository=docker_repository, 1322 docker_image_tag=docker_image_tag, 1323 paused_reason=paused_reason, 1324 ) 1325 1326 1327@mcp_tool( 1328 destructive=True, 1329 idempotent=False, 1330 open_world=True, 1331) 1332def finalize_connector_rollout( 1333 docker_repository: Annotated[ 1334 str, 1335 Field( 1336 description="The docker repository (e.g., 'airbyte/source-youtube-analytics')" 1337 ), 1338 ], 1339 docker_image_tag: Annotated[ 1340 str, 1341 Field(description="The docker image tag (e.g., '1.2.0-rc.2')"), 1342 ], 1343 actor_definition_id: Annotated[ 1344 str, 1345 Field(description="The actor definition ID (UUID)"), 1346 ], 1347 rollout_id: Annotated[ 1348 str, 1349 Field( 1350 description="The rollout ID (UUID). Can be found in the 'pin_origin' field " 1351 "of rollout data from query_prod_actors_by_pinned_connector_version." 1352 ), 1353 ], 1354 state: Annotated[ 1355 Literal["succeeded", "failed_rolled_back", "canceled"], 1356 Field( 1357 description="The final state for the rollout: " 1358 "'succeeded' promotes the RC to GA (default version for all users), " 1359 "'failed_rolled_back' rolls back the RC, " 1360 "'canceled' cancels the rollout without promotion or rollback." 1361 ), 1362 ], 1363 approval_comment_url: Annotated[ 1364 str | None, 1365 Field( 1366 description="URL to the Slack approval record. Obtain this by calling the " 1367 "`escalate_to_human` tool with `approval_requested=True`; the backend delivers " 1368 "the approval record URL when a human clicks Approve. " 1369 "Format: https://<workspace>.slack.com/archives/... " 1370 "The admin email is automatically resolved from the approver's identity " 1371 "via the team roster.", 1372 default=None, 1373 ), 1374 ], 1375 admin_user_email_override: Annotated[ 1376 str | None, 1377 Field( 1378 description="Direct admin email override for webapp-initiated actions. " 1379 "When the Ops Webapp env var is set, this bypasses the approval URL " 1380 "requirement. Ignored in agent/cron environments.", 1381 default=None, 1382 ), 1383 ], 1384 error_msg: Annotated[ 1385 str | None, 1386 Field( 1387 description="Optional error message for failed/canceled states.", 1388 default=None, 1389 ), 1390 ] = None, 1391 failed_reason: Annotated[ 1392 str | None, 1393 Field( 1394 description="Optional failure reason for failed/canceled states.", 1395 default=None, 1396 ), 1397 ] = None, 1398 retain_pins_on_cancellation: Annotated[ 1399 bool | None, 1400 Field( 1401 description="If True, retain version pins when canceling. " 1402 "Only applicable when state is 'canceled'.", 1403 default=None, 1404 ), 1405 ] = None, 1406 *, 1407 ctx: Context, 1408) -> ConnectorRolloutFinalizeResult: 1409 """Finalize a connector rollout by promoting, rolling back, or canceling. 1410 1411 This tool allows admins to finalize connector rollouts that are in progress. 1412 Use this after monitoring a rollout and determining it is ready for finalization. 1413 1414 **IMPORTANT: Finalization is asynchronous.** This tool sends a finalization 1415 request to the platform API, which transitions the rollout to `finalizing` 1416 state and triggers a Temporal workflow. The actual promotion (PR creation, 1417 connector publish, registry update) or rollback (GCS cleanup, registry 1418 recompile) happens asynchronously via the `finalize_rollout.yml` GitHub 1419 Actions workflow. A successful response from this tool means the request 1420 was accepted — NOT that the promotion/rollback is complete. 1421 1422 After calling this tool, you MUST verify: 1423 1. The `finalize_rollout.yml` workflow ran successfully in GitHub Actions 1424 2. For promotions: a merged PR exists (e.g., `chore: finalize promote for <connector>`) 1425 3. The rollout state transitioned to its terminal state (`succeeded`, 1426 `failed_rolled_back`, or `canceled`) via `query_prod_connector_rollouts` 1427 1428 **Admin-only operation** - Requires: 1429 - AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io environment variable 1430 - `approval_comment_url` (Slack approval record URL from `escalate_to_human`), 1431 OR `admin_user_email_override` when running inside the Ops Webapp. 1432 """ 1433 # Validate admin access (check env var flag) 1434 try: 1435 require_internal_admin_flag_only() 1436 except CloudAuthError as e: 1437 return ConnectorRolloutFinalizeResult( 1438 success=False, 1439 message=f"Admin authentication failed: {e}", 1440 rollout_id=rollout_id, 1441 docker_repository=docker_repository, 1442 docker_image_tag=docker_image_tag, 1443 ) 1444 1445 # Resolve admin email: webapp bypass or external approval URL 1446 approval = check_approval_status( 1447 approval_comment_url=approval_comment_url, 1448 user_email=admin_user_email_override, 1449 ) 1450 if approval.status != ApprovalStatus.APPROVED: 1451 return ConnectorRolloutFinalizeResult( 1452 success=False, 1453 message=approval.reason or "Approval check failed", 1454 rollout_id=rollout_id, 1455 docker_repository=docker_repository, 1456 docker_image_tag=docker_image_tag, 1457 ) 1458 admin_user_email = approval.admin_email 1459 1460 # Resolve auth credentials 1461 try: 1462 auth = _resolve_cloud_auth(ctx) 1463 except CloudAuthError as e: 1464 return ConnectorRolloutFinalizeResult( 1465 success=False, 1466 message=f"Failed to resolve credentials: {e}", 1467 rollout_id=rollout_id, 1468 docker_repository=docker_repository, 1469 docker_image_tag=docker_image_tag, 1470 ) 1471 1472 # Get user ID from admin email 1473 try: 1474 user_id = api_client.get_user_id_by_email( 1475 email=admin_user_email, 1476 config_api_root=constants.CLOUD_CONFIG_API_ROOT, 1477 client_id=auth.client_id, 1478 client_secret=auth.client_secret, 1479 bearer_token=auth.bearer_token, 1480 ) 1481 except PyAirbyteInputError as e: 1482 return ConnectorRolloutFinalizeResult( 1483 success=False, 1484 message=f"Failed to get user ID for admin email '{admin_user_email}': {e}", 1485 rollout_id=rollout_id, 1486 docker_repository=docker_repository, 1487 docker_image_tag=docker_image_tag, 1488 ) 1489 1490 # Call the API to finalize the rollout 1491 try: 1492 api_client.finalize_connector_rollout( 1493 docker_repository=docker_repository, 1494 docker_image_tag=docker_image_tag, 1495 actor_definition_id=actor_definition_id, 1496 rollout_id=rollout_id, 1497 updated_by=user_id, 1498 state=state, 1499 config_api_root=constants.CLOUD_CONFIG_API_ROOT, 1500 client_id=auth.client_id, 1501 client_secret=auth.client_secret, 1502 bearer_token=auth.bearer_token, 1503 error_msg=error_msg, 1504 failed_reason=failed_reason, 1505 retain_pins_on_cancellation=retain_pins_on_cancellation, 1506 ) 1507 1508 state_descriptions = { 1509 "succeeded": ( 1510 "GA promotion has been initiated (state: finalizing). " 1511 "The actual promotion (PR creation, publish, registry update) " 1512 "happens asynchronously via the finalize_rollout.yml GitHub Actions workflow. " 1513 "You MUST verify the workflow completes successfully and the rollout " 1514 "transitions to 'succeeded' state before reporting completion. " 1515 "Check: (1) GitHub Actions for a 'Finalize Progressive Rollout' workflow run, " 1516 "(2) a merged promotion PR, and " 1517 "(3) query_prod_connector_rollouts to confirm state is 'succeeded'." 1518 ), 1519 "failed_rolled_back": ( 1520 "rollback has been initiated (state: finalizing). " 1521 "The rollback happens asynchronously via the finalize_rollout.yml workflow. " 1522 "Verify the workflow completes and the rollout transitions to " 1523 "'failed_rolled_back' state." 1524 ), 1525 "canceled": "canceled", 1526 } 1527 state_desc = state_descriptions.get(state, state) 1528 1529 return ConnectorRolloutFinalizeResult( 1530 success=True, 1531 message=f"Finalization request accepted for {docker_repository}:{docker_image_tag}: " 1532 f"{state_desc}", 1533 rollout_id=rollout_id, 1534 docker_repository=docker_repository, 1535 docker_image_tag=docker_image_tag, 1536 state=state, 1537 ) 1538 1539 except PyAirbyteInputError as e: 1540 return ConnectorRolloutFinalizeResult( 1541 success=False, 1542 message=str(e), 1543 rollout_id=rollout_id, 1544 docker_repository=docker_repository, 1545 docker_image_tag=docker_image_tag, 1546 ) 1547 1548 1549class RolloutActorSelectionInfo(BaseModel): 1550 """Actor selection info for a connector rollout.""" 1551 1552 num_actors: int = Field(description="Total actors using this connector") 1553 num_pinned_to_connector_rollout: int = Field( 1554 description="Actors specifically pinned to this rollout" 1555 ) 1556 num_actors_eligible_or_already_pinned: int = Field( 1557 description="Actors eligible for pinning or already pinned" 1558 ) 1559 1560 1561class RolloutActorSyncStats(BaseModel): 1562 """Per-actor sync stats for a rollout (only syncs using the RC version).""" 1563 1564 actor_id: str = Field(description="Actor UUID") 1565 num_connections: int = Field(description="Number of connections using this actor") 1566 num_succeeded: int = Field( 1567 description="Number of successful syncs using the RC version" 1568 ) 1569 num_failed: int = Field(description="Number of failed syncs using the RC version") 1570 1571 1572class RolloutMonitoringResult(BaseModel): 1573 """Complete monitoring result for a rollout from the platform API. 1574 1575 This uses the platform API's /get_actor_sync_info endpoint which filters 1576 sync stats to only include syncs that actually used the RC version 1577 associated with the rollout. 1578 """ 1579 1580 rollout_id: str = Field(description="Rollout UUID") 1581 actor_selection_info: RolloutActorSelectionInfo = Field( 1582 description="Actor selection info for the rollout" 1583 ) 1584 actor_sync_stats: list[RolloutActorSyncStats] = Field( 1585 description="Per-actor sync stats for actors pinned to the rollout" 1586 ) 1587 1588 1589@mcp_tool( 1590 read_only=True, 1591 idempotent=True, 1592) 1593def query_prod_rollout_monitoring_stats( 1594 rollout_id: Annotated[ 1595 str, 1596 Field(description="Rollout UUID to get monitoring stats for"), 1597 ], 1598 *, 1599 ctx: Context, 1600) -> RolloutMonitoringResult: 1601 """Get monitoring stats for a connector rollout. 1602 1603 Returns actor selection info and per-actor sync stats for actors 1604 participating in the rollout. This uses the platform API's 1605 /get_actor_sync_info endpoint which filters sync stats to only include 1606 syncs that actually used the RC version associated with the rollout. 1607 1608 This is more accurate than SQL-based approaches which count all syncs 1609 regardless of which connector version was used. 1610 """ 1611 auth = _resolve_cloud_auth(ctx) 1612 1613 response = api_client.get_actor_sync_info( 1614 rollout_id=rollout_id, 1615 config_api_root=constants.CLOUD_CONFIG_API_ROOT, 1616 client_id=auth.client_id, 1617 client_secret=auth.client_secret, 1618 bearer_token=auth.bearer_token, 1619 ) 1620 1621 data = response.get("data", {}) 1622 actor_selection_info_data = data.get("actor_selection_info", {}) 1623 syncs_data = data.get("syncs", {}) 1624 1625 actor_selection_info = RolloutActorSelectionInfo( 1626 num_actors=actor_selection_info_data.get("num_actors", 0), 1627 num_pinned_to_connector_rollout=actor_selection_info_data.get( 1628 "num_pinned_to_connector_rollout", 0 1629 ), 1630 num_actors_eligible_or_already_pinned=actor_selection_info_data.get( 1631 "num_actors_eligible_or_already_pinned", 0 1632 ), 1633 ) 1634 1635 actor_sync_stats = [ 1636 RolloutActorSyncStats( 1637 actor_id=actor_id, 1638 num_connections=sync_info.get("num_connections", 0), 1639 num_succeeded=sync_info.get("num_succeeded", 0), 1640 num_failed=sync_info.get("num_failed", 0), 1641 ) 1642 for actor_id, sync_info in syncs_data.items() 1643 ] 1644 1645 return RolloutMonitoringResult( 1646 rollout_id=rollout_id, 1647 actor_selection_info=actor_selection_info, 1648 actor_sync_stats=actor_sync_stats, 1649 ) 1650 1651 1652class ConnectorRepo(StrEnum): 1653 """Repository where connector code is located.""" 1654 1655 AIRBYTE = "airbyte" 1656 AIRBYTE_ENTERPRISE = "airbyte-enterprise" 1657 1658 1659DEFAULT_REPO_OWNER = "airbytehq" 1660 1661DEFAULT_REPO_NAME = ConnectorRepo.AIRBYTE 1662 1663DEFAULT_BRANCH = "master" 1664 1665PRERELEASE_WORKFLOW_FILE = "publish-connectors-prerelease-command.yml" 1666 1667CONNECTOR_PATH_PREFIX = "airbyte-integrations/connectors" 1668 1669ENTERPRISE_REPO_NAME = ConnectorRepo.AIRBYTE_ENTERPRISE 1670 1671ENTERPRISE_DEFAULT_BRANCH = "main" 1672 1673ENTERPRISE_PRERELEASE_WORKFLOW_FILE = "publish_enterprise_connectors.yml" 1674 1675PRERELEASE_TOKEN_ENV_VARS = [ 1676 "GITHUB_CONNECTOR_PUBLISHING_PAT", 1677 "GITHUB_CI_WORKFLOW_TRIGGER_PAT", 1678 "GITHUB_TOKEN", 1679] 1680 1681PRERELEASE_TAG_PREFIX = "preview" 1682 1683PRERELEASE_SHA_LENGTH = 7 1684 1685 1686def compute_prerelease_docker_image_tag(base_version: str, sha: str) -> str: 1687 """Compute the pre-release docker image tag. 1688 1689 This is the SINGLE SOURCE OF TRUTH for pre-release version format. 1690 All other code should receive this value as a parameter, not recompute it. 1691 1692 The format is: {base_version}-preview.{short_sha} 1693 1694 Where: 1695 - base_version: The base version from metadata.yaml (e.g., "1.2.3"), 1696 which may already contain a pre-release suffix (e.g., "2.23.16-rc.1"). 1697 Any existing pre-release suffix is stripped before applying the preview tag. 1698 - short_sha: The first 7 characters of the git commit SHA 1699 1700 Examples: 1701 >>> compute_prerelease_docker_image_tag("1.2.3", "abcdef1234567890") 1702 '1.2.3-preview.abcdef1' 1703 >>> compute_prerelease_docker_image_tag("0.1.0", "1234567") 1704 '0.1.0-preview.1234567' 1705 >>> compute_prerelease_docker_image_tag("2.23.16-rc.1", "abcdef1234567890") 1706 '2.23.16-preview.abcdef1' 1707 1708 Args: 1709 base_version: The base version from metadata.yaml (e.g., "1.2.3" or "2.23.16-rc.1") 1710 sha: The full git commit SHA (or at least 7 characters) 1711 1712 Returns: 1713 Pre-release version tag (e.g., "1.2.3-preview.abcde12") 1714 """ 1715 short_sha = sha[:PRERELEASE_SHA_LENGTH] 1716 clean_version = strip_prerelease_suffix(base_version) 1717 return f"{clean_version}-{PRERELEASE_TAG_PREFIX}.{short_sha}" 1718 1719 1720class PrereleaseWorkflowResult(BaseModel): 1721 """Response model for publish_connector_to_airbyte_registry MCP tool.""" 1722 1723 success: bool 1724 message: str 1725 workflow_url: str | None = None 1726 connector_name: str | None = None 1727 pr_number: int | None = None 1728 docker_image: str | None = None 1729 docker_image_tag: str | None = None 1730 1731 1732def _get_connector_metadata( 1733 owner: str, 1734 repo: str, 1735 connector_name: str, 1736 ref: str, 1737 token: str, 1738) -> dict | None: 1739 """Fetch and parse connector metadata.yaml from the repository. 1740 1741 Args: 1742 owner: Repository owner (e.g., "airbytehq") 1743 repo: Repository name (e.g., "airbyte") 1744 connector_name: Connector name (e.g., "source-github") 1745 ref: Git ref to fetch from (branch name or SHA) 1746 token: GitHub API token 1747 1748 Returns: 1749 Parsed metadata dictionary, or None if not found. 1750 """ 1751 metadata_path = f"{CONNECTOR_PATH_PREFIX}/{connector_name}/metadata.yaml" 1752 url = f"{GITHUB_API_BASE}/repos/{owner}/{repo}/contents/{metadata_path}" 1753 headers = { 1754 "Authorization": f"Bearer {token}", 1755 "Accept": "application/vnd.github+json", 1756 "X-GitHub-Api-Version": "2022-11-28", 1757 } 1758 params = {"ref": ref} 1759 1760 response = requests.get(url, headers=headers, params=params, timeout=30) 1761 1762 # Guard: Return None if metadata file not found 1763 if response.status_code == 404: 1764 return None 1765 1766 response.raise_for_status() 1767 1768 content_data = response.json() 1769 1770 # Guard: Return None if content is not base64 encoded 1771 if content_data.get("encoding") != "base64": 1772 return None 1773 1774 content = base64.b64decode(content_data["content"]).decode("utf-8") 1775 return yaml.safe_load(content) 1776 1777 1778@mcp_tool( 1779 read_only=False, 1780 destructive=False, 1781 idempotent=False, 1782 open_world=True, 1783) 1784def publish_connector_to_airbyte_registry( 1785 connector_name: Annotated[ 1786 str, 1787 Field( 1788 description="The connector name to publish (e.g., 'source-github', 'destination-postgres')" 1789 ), 1790 ], 1791 pr_number: Annotated[ 1792 int, 1793 Field(description="The pull request number containing the connector changes"), 1794 ], 1795 repo: Annotated[ 1796 ConnectorRepo, 1797 Field( 1798 default=ConnectorRepo.AIRBYTE, 1799 description="Repository where the connector PR is located. " 1800 "Use 'airbyte' for OSS connectors (default) or 'airbyte-enterprise' for enterprise connectors.", 1801 ), 1802 ], 1803 prerelease: Annotated[ 1804 Literal[True], 1805 Field( 1806 default=True, 1807 description="Must be True. Only prerelease publishing is supported at this time.", 1808 ), 1809 ], 1810) -> PrereleaseWorkflowResult: 1811 """Publish a connector to the Airbyte registry. 1812 1813 Currently only supports pre-release publishing. This tool triggers the 1814 publish-connectors-prerelease workflow in the airbytehq/airbyte repository 1815 (for OSS connectors) or the publish_enterprise_connectors workflow in 1816 airbytehq/airbyte-enterprise (for enterprise connectors), which publishes 1817 a pre-release version of the specified connector from the PR branch. 1818 1819 Pre-release versions are tagged with the format: {version}-preview.{7-char-git-sha} 1820 These versions are available for version pinning via the scoped_configuration API. 1821 1822 Requires GITHUB_CONNECTOR_PUBLISHING_PAT or GITHUB_TOKEN environment variable 1823 with 'actions:write' permission. 1824 """ 1825 # Guard: Only prerelease publishing is supported 1826 if prerelease is not True: 1827 raise NotImplementedError( 1828 "Non-prerelease publishing is not implemented yet. Set prerelease=True." 1829 ) 1830 1831 # Guard: Check for required token 1832 token = resolve_ci_trigger_github_token(PRERELEASE_TOKEN_ENV_VARS) 1833 1834 # Determine repo-specific settings 1835 is_enterprise = repo == ConnectorRepo.AIRBYTE_ENTERPRISE 1836 target_repo_name = ENTERPRISE_REPO_NAME if is_enterprise else DEFAULT_REPO_NAME 1837 target_branch = ENTERPRISE_DEFAULT_BRANCH if is_enterprise else DEFAULT_BRANCH 1838 target_workflow = ( 1839 ENTERPRISE_PRERELEASE_WORKFLOW_FILE 1840 if is_enterprise 1841 else PRERELEASE_WORKFLOW_FILE 1842 ) 1843 1844 # Get the PR's head SHA for computing the docker image tag 1845 # Note: We no longer pass gitref to the workflow - it derives the ref from PR number 1846 head_info = get_pr_head_ref(DEFAULT_REPO_OWNER, target_repo_name, pr_number, token) 1847 1848 # Prepare workflow inputs 1849 workflow_inputs = { 1850 "repo": f"{DEFAULT_REPO_OWNER}/{target_repo_name}", 1851 "pr": str(pr_number), 1852 "connector": connector_name, 1853 } 1854 1855 # Trigger the workflow on the configured default branch. 1856 # The workflow will checkout the PR branch via inputs.gitref 1857 dispatch_result = trigger_workflow_dispatch( 1858 owner=DEFAULT_REPO_OWNER, 1859 repo=target_repo_name, 1860 workflow_file=target_workflow, 1861 ref=target_branch, 1862 inputs=workflow_inputs, 1863 token=token, 1864 find_run=True, 1865 ) 1866 # Use the specific run URL if found, otherwise fall back to the workflow URL 1867 workflow_url = dispatch_result.run_url or dispatch_result.workflow_url 1868 1869 # Try to compute docker_image and docker_image_tag from connector metadata 1870 docker_image: str | None = None 1871 docker_image_tag: str | None = None 1872 metadata = _get_connector_metadata( 1873 DEFAULT_REPO_OWNER, 1874 target_repo_name, 1875 connector_name, 1876 head_info.sha, 1877 token, 1878 ) 1879 if metadata and "data" in metadata: 1880 data = metadata["data"] 1881 docker_image = data.get("dockerRepository") 1882 base_version = data.get("dockerImageTag") 1883 if base_version: 1884 docker_image_tag = compute_prerelease_docker_image_tag( 1885 base_version, head_info.sha 1886 ) 1887 1888 repo_info = f" from {repo}" if is_enterprise else "" 1889 return PrereleaseWorkflowResult( 1890 success=True, 1891 message=f"Successfully triggered pre-release workflow for {connector_name}{repo_info} from PR #{pr_number}", 1892 workflow_url=workflow_url, 1893 connector_name=connector_name, 1894 pr_number=pr_number, 1895 docker_image=docker_image, 1896 docker_image_tag=docker_image_tag, 1897 ) 1898 1899 1900def register_connector_version_tools(app: FastMCP) -> None: 1901 """Register connector_versions tools with the FastMCP app.""" 1902 register_mcp_tools(app, mcp_module=__name__)