# Release Blocks

Release blocks prevent a connector from being published while a known-bad version still exists in the Airbyte monorepo. They are meant to be used with the connector yank flow: yanking removes a bad version from registry selection, and a release block prevents later PRs from republishing the same bad connector code.

## When to use a release block

Use a release block after yanking a connector version when the broken code still exists on `master` and could be published again by an unrelated PR. Common cases include:

- A connector version was yanked because it has a severe regression.
- The fix is not ready yet, but other connector maintenance PRs might touch or publish the connector.
- A progressive rollout was rolled back and the connector source tree still points at the bad version.

Do not use release blocks as a long-term substitute for fixing or reverting the connector code. A release block is an operational guardrail.

## How release blocks work

A release block is a `block-release.yaml` marker file in a connector directory:

```text
airbyte-integrations/connectors/source-faker/block-release.yaml
```

The marker file contains the block reason, optional yanked version, timestamp, optional requester, and instructions:

```yaml
reason: Version 5.0.1 yanked due to a regression.
yanked_version: 5.0.1
blocked_at: "2026-04-08T15:00:00Z"
blocked_by: release-manager@airbyte.io
instructions: |
  This connector's release is blocked due to a known issue.
  The broken code from the yanked version still lives on master.
  To unblock, use the 'block-release.yml' workflow with action=unblock
  or merge a PR that deletes this file.
```

While the marker exists:

- The Airbyte publish workflow checks for `block-release.yaml` before build and publish steps.
- Blocked connector matrix jobs are skipped with a warning annotation.
- Other connectors in the same publish workflow continue normally.
- PRs that touch blocked connectors receive an idempotent warning comment from the release-block check workflow.

## Relationship to yanking

Yanking and release blocks protect different points in the release pipeline:

- `version-yank.yml` lives in the registry bucket under a specific published version. Registry compile excludes that version when choosing `latest/`.
- `block-release.yaml` lives in the connector source tree. Publish CI skips the connector before it can publish new artifacts.

Use both when a published connector version is bad and the source tree is not fixed yet:

1. Yank the bad published version.
2. Add a release block for the connector.
3. Fix or revert the connector source code.
4. Clear the release block after the connector is safe to publish again.

## Add a release block

For production operations, prefer the MCP tool. It triggers the Airbyte monorepo `block-release.yml` workflow, which creates the marker file, opens a PR, approves it with the configured admin bot, and force-merges it so the block takes effect quickly.

```bash
poe mcp-tool-test block_connector_release '{
  "connector_name": "source-faker",
  "reason": "Version 5.0.1 yanked due to a regression.",
  "yanked_version": "5.0.1",
  "blocked_by": "release-manager@airbyte.io"
}'
```

The local CLI performs the filesystem edit directly in an Airbyte monorepo checkout:

```bash
airbyte-ops local connector release-block add \
  --name source-faker \
  --reason "Version 5.0.1 yanked due to a regression." \
  --yanked-version 5.0.1 \
  --blocked-by release-manager@airbyte.io \
  --repo-path /path/to/airbyte
```

The command writes JSON to stdout. Human-readable status messages are written to stderr so scripts can parse stdout safely.

## List release blocks

Use the MCP tool to list release blocks from GitHub:

```bash
poe mcp-tool-test list_blocked_connector_releases '{}'
```

Filter to one connector when you need a direct contents lookup:

```bash
poe mcp-tool-test list_blocked_connector_releases '{
  "connector_name": "source-faker"
}'
```

When listing all blocked connectors, the MCP tool uses GitHub code search for `block-release.yaml` files. GitHub search can have indexing delay, so a just-created block might take time to appear in the unfiltered list. A connector-specific lookup reads the file directly.

For local checkouts, use the CLI:

```bash
airbyte-ops local connector release-block list --repo-path /path/to/airbyte
airbyte-ops local connector release-block list --repo-path /path/to/airbyte --output-format json
airbyte-ops local connector release-block list --repo-path /path/to/airbyte --output-format csv
```

## Clear a release block

Clear the block only after the connector source tree is safe to publish. For example, clear it after the bad code is reverted, a fix is merged, or the connector version is bumped to a safe version.

For production operations, prefer the MCP tool:

```bash
poe mcp-tool-test unblock_connector_release '{
  "connector_name": "source-faker"
}'
```

For local filesystem edits:

```bash
airbyte-ops local connector release-block clear \
  --name source-faker \
  --repo-path /path/to/airbyte
```

## Operational checklist

When a connector publish needs to be blocked:

1. Yank the bad version in the registry.
2. Add a release block with the yanked version and a concise reason.
3. Verify the marker exists on `master` in the Airbyte monorepo.
4. Verify `list_blocked_connector_releases` returns the connector. Use a connector-specific lookup if the all-connector search has not indexed yet.
5. Fix or revert the connector code.
6. Clear the release block after the fix is safe to publish.
7. Confirm the next publish workflow does not skip the connector.

## Related documentation

- [Connector Registry](connector-registry.md) describes registry artifacts, yanking, and publish/compile behavior.
- [Connector Progressive Rollouts](progressive-rollouts.md) describes rollout promotion and rollback paths.
