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:

  1. The finalize_rollout.yml workflow ran successfully in GitHub Actions
  2. For promotions: a merged PR exists (e.g., chore: finalize promote for <connector>)
  3. The rollout state transitioned to its terminal state (succeeded, failed_rolled_back, or canceled) via query_prod_connector_rollouts

Admin-only operation - Requires:

  • AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io environment variable
  • approval_comment_url (Slack approval record URL from escalate_to_human), OR admin_user_email_override when 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://.slack.com/archives/... The admin email is automatically resolved from the approver's identity via the team roster.
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:

  1. Bearer token (Authorization header or AIRBYTE_CLOUD_BEARER_TOKEN env var)
  2. HTTP headers: X-Airbyte-Cloud-Client-Id, X-Airbyte-Cloud-Client-Secret
  3. 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 from escalate_to_human), OR admin_user_email_override when 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://.slack.com/archives/... The admin email is automatically resolved from the approver's identity via the team roster.
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:

  1. Bearer token (Authorization header or AIRBYTE_CLOUD_BEARER_TOKEN env var)
  2. HTTP headers: X-Airbyte-Cloud-Client-Id, X-Airbyte-Cloud-Client-Secret
  3. 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://.slack.com/archives/... The admin email is automatically resolved from the approver's identity via the team roster.
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://.slack.com/archives/... The admin email is automatically resolved from the approver's identity via the team roster.
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://.slack.com/archives/... The admin email is automatically resolved from the approver's identity via the team roster.
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 from escalate_to_human), OR admin_user_email_override when 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://.slack.com/archives/... The admin email is automatically resolved from the approver's identity via the team roster.
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__)