---
name: version-pin-e2e-test
description: End-to-end test of connector version pin search, get, and set interfaces — multi-scope pin detection, exclude_pinned filtering, existing-pin guard, force override, and major-version hard blocker. Use when validating that pin-aware query tools and pin guard logic work correctly together.
devin-enabled: true
icon: flask-conical
---

# Version Pin E2E Test

Run an end-to-end test of the connector version pin interfaces. This test exercises:

1. **Search tools** — `query_prod_connections_by_connector` and `query_prod_recent_syncs_for_connector` with `exclude_pinned` flag
2. **Get tool** — `get_cloud_connector_version` to read pin status for individual actors
3. **Set tools** — `set_cloud_connector_version_override` (actor scope), `set_workspace_connector_version_override`, and `set_organization_connector_version_override` with existing-pin guard, `force` override, and major-version hard blocker
4. **Pin-specific queries** — `query_prod_actors_by_connector_version` and `query_prod_recent_syncs_for_version_pinned_connector`

## Prerequisites

- **Repos:** `~/repos/airbyte-ops-mcp`
- **Credentials:**
  - `AIRBYTE_CLOUD_CLIENT_ID`
  - `AIRBYTE_CLOUD_CLIENT_SECRET`
  - `AIRBYTE_INTERNAL_ADMIN_FLAG` (must be set to `airbyte.io`)
  - `GCP_GSM_CREDENTIALS` — Service account JSON key with prod DB replica read access

## Devin Secrets Needed

- `GCP_GSM_CREDENTIALS` — For prod DB replica queries
- `AIRBYTE_CLOUD_CLIENT_ID` — Cloud API client ID
- `AIRBYTE_CLOUD_CLIENT_SECRET` — Cloud API client secret
- `AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io` — Admin flag for set operations

## Test Connector

Use `source-faker` throughout this test:
- **Connector name:** `source-faker`
- **Actor definition ID:** `dfd88b22-b603-4c3d-aad7-3701784586b1`
- **Sandbox workspace alias:** `@devin-ai-sandbox`

All MCP tool invocations use:

```bash
cd ~/repos/airbyte-ops-mcp
uv run poe mcp-tool-test <tool_name> '<json_args>'
```

## Step 0: Collect Approval URL

Before any set operations, collect a single approval URL that will be reused for all pin/unpin operations. Use the `escalate_to_human` MCP tool:

```bash
uv run poe mcp-tool-test escalate_to_human '{
  "target_person": "<USER_EMAIL>",
  "message": "Requesting approval for version pin E2E test on source-faker in @devin-ai-sandbox. This will set and unset version pins to test guard logic.",
  "agent_session_url": "<DEVIN_SESSION_URL>",
  "approval_requested": true,
  "approval_request_summary": "Version pin E2E test: set pin, test guard, force override, unset pin on source-faker",
  "connector_name": "source-faker",
  "request_type": "approval"
}'
```

Wait for the user to click "Approve". Record the resulting URL as `APPROVAL_URL`.

---

## Phase 1: Search — Query Tools with Pin Detection

### Step 1.1: Query connections by connector (default — include pinned)

```bash
uv run poe mcp-tool-test query_prod_connections_by_connector '{
  "source_canonical_name": "source-faker",
  "limit": 10,
  "customer_tier_filter": "ALL"
}'
```

**Verify:**
- Returns a list of connection dicts
- Each row includes `pin_origin_type`, `pin_origin`, `pinned_version_id`, `pin_scope_type` fields
- `pin_scope_type` is one of `actor`, `workspace`, `organization`, or `null`
- Record the total count as `TOTAL_CONNECTIONS`
- Record a connection with `pin_scope_type != null` (if any) as `PINNED_CONNECTION`
- Record a connection with `pin_scope_type == null` as `UNPINNED_CONNECTION`

### Step 1.2: Query connections by connector (exclude_pinned=True)

```bash
uv run poe mcp-tool-test query_prod_connections_by_connector '{
  "source_canonical_name": "source-faker",
  "limit": 10,
  "customer_tier_filter": "ALL",
  "exclude_pinned": true
}'
```

**Verify:**
- Returns a list of connection dicts
- **Every** row has `pin_scope_type == null` — no pinned connections in the results
- Count is less than or equal to `TOTAL_CONNECTIONS`
- Record the count as `UNPINNED_CONNECTIONS`

### Step 1.3: Query recent syncs for connector (default — include pinned)

```bash
uv run poe mcp-tool-test query_prod_recent_syncs_for_connector '{
  "source_canonical_name": "source-faker",
  "status_filter": "all",
  "limit": 10,
  "customer_tier_filter": "ALL"
}'
```

**Verify:**
- Returns a list of sync job dicts
- Each row includes `pin_origin_type`, `pin_origin`, `pinned_version_id`, `pin_scope_type` fields
- Record a sync with `pin_scope_type != null` (if any) as `PINNED_SYNC`

### Step 1.4: Query recent syncs for connector (exclude_pinned=True)

```bash
uv run poe mcp-tool-test query_prod_recent_syncs_for_connector '{
  "source_canonical_name": "source-faker",
  "status_filter": "all",
  "limit": 10,
  "customer_tier_filter": "ALL",
  "exclude_pinned": true
}'
```

**Verify:**
- Returns a list of sync job dicts
- **Every** row has `pin_scope_type == null`

### Step 1.5: Query actors pinned to a specific version

If `PINNED_CONNECTION` was found in Step 1.1, use its `pinned_version_id`:

```bash
uv run poe mcp-tool-test query_prod_actors_by_connector_version '{
  "connector_version_id": "<PINNED_VERSION_ID>"
}'
```

**Verify:**
- Returns a list of actor dicts
- Each includes `actor_id`, `connector_definition_id`, `origin_type`, `origin`

If no pinned connections were found, skip this step and note it in the results.

---

## Phase 2: Get — Read Pin Status for Individual Actors

### Step 2.1: Get version info for a sandbox connector

Pick an actor ID from the sandbox workspace. If you don't have one readily available, query for one:

```bash
uv run poe mcp-tool-test query_prod_connections_by_connector '{
  "source_canonical_name": "source-faker",
  "organization_id": "@airbyte-internal",
  "limit": 5,
  "customer_tier_filter": "ALL"
}'
```

Then use `get_cloud_connector_version` on one of the returned actors:

```bash
uv run poe mcp-tool-test get_cloud_connector_version '{
  "workspace_id": "<WORKSPACE_ID>",
  "actor_id": "<SOURCE_ID>",
  "actor_type": "source"
}'
```

**Verify:**
- Returns a `ConnectorVersionInfo` dict with `connector_id`, `connector_type`, `version`, `is_version_pinned`
- `version` is a valid semver string
- `is_version_pinned` is a boolean
- Record the `version` as `CURRENT_VERSION` and `is_version_pinned` as `WAS_PINNED`

---

## Phase 3: Set — Pin Guard and Force Override

This phase uses the `@devin-ai-sandbox` workspace. **Only proceed if you have the approval URL from Step 0.**

### Step 3.1: Set a version pin (expect success or existing-pin guard block)

Use the actor from Step 2.1 (or find a source-faker actor in `@devin-ai-sandbox`):

```bash
uv run poe mcp-tool-test set_cloud_connector_version_override '{
  "workspace_id": "@devin-ai-sandbox",
  "actor_id": "<ACTOR_ID>",
  "actor_type": "source",
  "version": "<CURRENT_VERSION>",
  "override_reason": "E2E test: verifying pin guard logic",
  "override_reason_reference_url": "<DEVIN_SESSION_URL>",
  "issue_url": "<ISSUE_URL_OR_SESSION_URL>",
  "approval_comment_url": "<APPROVAL_URL>",
  "customer_tier_filter": "ALL"
}'
```

**Expected outcomes (one of):**

**A. Success** (actor was not previously pinned):
- Returns `VersionOverrideOperationResult` with `success=True`
- Record the result, then proceed to Step 3.2

**B. Blocked by existing-pin guard** (actor was already pinned):
- Returns `VersionOverrideOperationResult` with `success=False`
- Message contains "already pinned" and "Use force=True to override"
- Record the existing pin version, then proceed to Step 3.3 to test force override

### Step 3.2: Set the same pin again (expect guard to block)

If Step 3.1 succeeded, try pinning the same actor again:

```bash
uv run poe mcp-tool-test set_cloud_connector_version_override '{
  "workspace_id": "@devin-ai-sandbox",
  "actor_id": "<ACTOR_ID>",
  "actor_type": "source",
  "version": "<CURRENT_VERSION>",
  "override_reason": "E2E test: verifying pin guard blocks duplicate pin",
  "override_reason_reference_url": "<DEVIN_SESSION_URL>",
  "issue_url": "<ISSUE_URL_OR_SESSION_URL>",
  "approval_comment_url": "<APPROVAL_URL>",
  "customer_tier_filter": "ALL"
}'
```

**Verify:**
- Returns `VersionOverrideOperationResult` with `success=False`
- Message contains "already pinned" and mentions the existing pin version
- Message contains "Use force=True to override"

### Step 3.3: Force override the existing pin — same major version (expect success)

```bash
uv run poe mcp-tool-test set_cloud_connector_version_override '{
  "workspace_id": "@devin-ai-sandbox",
  "actor_id": "<ACTOR_ID>",
  "actor_type": "source",
  "version": "<SAME_MAJOR_DIFFERENT_PATCH_VERSION>",
  "override_reason": "E2E test: verifying force override within same major",
  "override_reason_reference_url": "<DEVIN_SESSION_URL>",
  "issue_url": "<ISSUE_URL_OR_SESSION_URL>",
  "approval_comment_url": "<APPROVAL_URL>",
  "customer_tier_filter": "ALL",
  "force": true
}'
```

**Verify:**
- Returns `VersionOverrideOperationResult` with `success=True`
- `force=True` bypassed the existing-pin guard for a same-major version change
- No blocking error about major version crossing

### Step 3.3b: Force override — cross-major version (expect HARD BLOCK)

This is the core safety test. Major-version crossings are permanently blocked regardless of `force=True`.

```bash
uv run poe mcp-tool-test set_cloud_connector_version_override '{
  "workspace_id": "@devin-ai-sandbox",
  "actor_id": "<ACTOR_ID>",
  "actor_type": "source",
  "version": "<DIFFERENT_MAJOR_VERSION>",
  "override_reason": "E2E test: verifying major-version hard blocker",
  "override_reason_reference_url": "<DEVIN_SESSION_URL>",
  "issue_url": "<ISSUE_URL_OR_SESSION_URL>",
  "approval_comment_url": "<APPROVAL_URL>",
  "customer_tier_filter": "ALL",
  "force": true
}'
```

**Verify:**
- Returns `VersionOverrideOperationResult` with `success=False`
- Message contains "blocked" and "major version boundary"
- Message contains "cannot be overridden"
- `force=True` did NOT bypass the major-version check — this is a hard blocker with no override

### Step 3.4: Verify pin via get_cloud_connector_version

```bash
uv run poe mcp-tool-test get_cloud_connector_version '{
  "workspace_id": "<WORKSPACE_ID>",
  "actor_id": "<ACTOR_ID>",
  "actor_type": "source"
}'
```

**Verify:**
- `is_version_pinned` is `True`
- `version` matches the version you pinned in Step 3.3

### Step 3.5: Verify pin appears in search results

```bash
uv run poe mcp-tool-test query_prod_connections_by_connector '{
  "source_canonical_name": "source-faker",
  "limit": 50,
  "customer_tier_filter": "ALL",
  "exclude_pinned": true
}'
```

**Verify:**
- The actor pinned in Step 3.3 does NOT appear in the results (it should be filtered out)

**Note:** There may be a propagation delay between the Cloud API write and the prod DB replica. If the pin doesn't appear immediately, wait 30-60 seconds and retry.

---

## Phase 4: Cleanup — Unset the Pin

### Step 4.1: Unset the version pin

```bash
uv run poe mcp-tool-test set_cloud_connector_version_override '{
  "workspace_id": "@devin-ai-sandbox",
  "actor_id": "<ACTOR_ID>",
  "actor_type": "source",
  "unset": true,
  "issue_url": "<ISSUE_URL_OR_SESSION_URL>",
  "approval_comment_url": "<APPROVAL_URL>",
  "customer_tier_filter": "ALL"
}'
```

**Verify:**
- Returns `VersionOverrideOperationResult` with `success=True`
- Message indicates the pin was removed

### Step 4.2: Verify pin is removed

```bash
uv run poe mcp-tool-test get_cloud_connector_version '{
  "workspace_id": "<WORKSPACE_ID>",
  "actor_id": "<ACTOR_ID>",
  "actor_type": "source"
}'
```

**Verify:**
- `is_version_pinned` matches the state before testing (`WAS_PINNED` from Step 2.1)
- If the actor was not pinned before the test, it should now be unpinned

### Step 4.3: If the actor was not pinned before (WAS_PINNED=False), verify it reappears in unpinned search

```bash
uv run poe mcp-tool-test query_prod_connections_by_connector '{
  "source_canonical_name": "source-faker",
  "limit": 50,
  "customer_tier_filter": "ALL",
  "exclude_pinned": true
}'
```

**Verify:**
- The actor that was unpinned in Step 4.1 now appears in results (if it had connections and was originally unpinned)

---

## Phase 5: Workspace and Organization Scope Guards (Read-Only)

These tests verify the workspace and organization-scoped pin tools detect existing pins. They are **read-only** — they only attempt to set pins that should be blocked, and no actual state changes occur.

### Step 5.1: Test workspace-scoped pin guard

If you know of a workspace with an existing workspace-scoped pin, test that the guard blocks:

```bash
uv run poe mcp-tool-test set_workspace_connector_version_override '{
  "workspace_id": "<WORKSPACE_WITH_EXISTING_WS_PIN>",
  "connector_name": "source-faker",
  "connector_type": "source",
  "version": "0.0.1",
  "override_reason": "E2E test: verify workspace guard blocks when pin exists",
  "issue_url": "<ISSUE_URL>",
  "approval_comment_url": "<APPROVAL_URL>",
  "customer_tier_filter": "ALL"
}'
```

**Expected:** `success=False`, message mentions existing workspace or organization pin.

If no workspace-scoped pin exists for source-faker, note this in results and skip.

### Step 5.2: Test organization-scoped pin guard

Similarly, if you know of an organization with an existing org-scoped pin:

```bash
uv run poe mcp-tool-test set_organization_connector_version_override '{
  "organization_id": "<ORG_WITH_EXISTING_ORG_PIN>",
  "connector_name": "source-faker",
  "connector_type": "source",
  "version": "0.0.1",
  "override_reason": "E2E test: verify org guard blocks when pin exists",
  "issue_url": "<ISSUE_URL>",
  "approval_comment_url": "<APPROVAL_URL>",
  "customer_tier_filter": "ALL"
}'
```

**Expected:** `success=False`, message mentions existing organization pin.

If no org-scoped pin exists for source-faker, note this in results and skip.

---

## Pass/Fail Criteria

### Overall PASS requires ALL of:

- [ ] Phase 1: `query_prod_connections_by_connector` returns `pin_scope_type` field in results
- [ ] Phase 1: `exclude_pinned=True` filters out all rows with non-null `pin_scope_type`
- [ ] Phase 1: `query_prod_recent_syncs_for_connector` returns `pin_scope_type` field
- [ ] Phase 1: `exclude_pinned=True` on recent syncs filters correctly
- [ ] Phase 2: `get_cloud_connector_version` returns `version` and `is_version_pinned`
- [ ] Phase 3: Setting a pin on an unpinned actor succeeds
- [ ] Phase 3: Setting a pin on an already-pinned actor is blocked with descriptive error
- [ ] Phase 3: `force=True` overrides the existing-pin guard (same-major version)
- [ ] Phase 3: `force=True` is BLOCKED for cross-major version changes (hard blocker, no override)
- [ ] Phase 4: Unsetting a pin succeeds and restores original state
- [ ] No unhandled exceptions from any tool invocation

### Overall FAIL if ANY of:

- Any tool invocation raises an unhandled exception (500 error, traceback, etc.)
- `exclude_pinned=True` returns rows with `pin_scope_type != null`
- Existing-pin guard does not block when actor is already pinned
- `force=True` does not override the existing-pin guard (same-major)
- `force=True` is not blocked for cross-major version changes (hard blocker must fire)
- Pin set/unset operations fail with unexpected errors
- `get_cloud_connector_version` does not reflect pin state changes

---

## Troubleshooting

### Tool invocation errors

- If `mcp-tool-test` fails with import errors, ensure you're running from `~/repos/airbyte-ops-mcp` with `uv run`
- If auth errors occur, verify `AIRBYTE_CLOUD_CLIENT_ID`, `AIRBYTE_CLOUD_CLIENT_SECRET`, and `AIRBYTE_INTERNAL_ADMIN_FLAG` are set

### Prod DB query returns empty results

- `source-faker` may not have many active connections — try with a more popular connector like `source-github` for Phase 1
- Ensure `GCP_GSM_CREDENTIALS` is set and has prod DB replica access

### Pin state not reflected in queries

- There is a replication lag between the Cloud API (writes) and the prod DB replica (reads)
- Wait 30-60 seconds between setting a pin and querying for it
- The `get_cloud_connector_version` tool reads from the live API, not the replica, so it reflects changes immediately

### Guard not blocking

- Verify you are on a branch that includes the pin guard code (PR #668)
- Check that the actor actually has a pin by calling `get_cloud_connector_version` first

## Reference

- **Pin guard source:** `src/airbyte_ops_mcp/cloud_admin/version_guard.py`
- **MCP tool source (set/get):** `src/airbyte_ops_mcp/mcp/cloud_connector_versions.py`
- **MCP tool source (search):** `src/airbyte_ops_mcp/mcp/prod_db_queries.py`
- **SQL queries:** `src/airbyte_ops_mcp/prod_db_access/sql.py`
- **Query execution:** `src/airbyte_ops_mcp/prod_db_access/queries.py`
- **PR #668:** Existing-pin guard with force override and major-version hard blocker (no override)
- **PR #682:** Multi-scope pin detection, `exclude_pinned` filtering, `pin_scope_type` field
