> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blocks.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Bitbucket

## Getting Started

Interact with Blocks on Bitbucket by mentioning `@blocks` in any issue or pull request comment with your request. Manage issues, answer questions, review PRs, implement changes, and more.

<Note>
  Connect Bitbucket via **Settings > Integrations > Bitbucket** in the Blocks dashboard. OAuth connects to a Bitbucket workspace. Each team member must also link their individual Bitbucket account.
</Note>

<Note>
  Delegate your request to a specific agent by mentioning the agent keyword in a slash command. Example: /claude, /codex, /gemini, /kimi. If none are mentioned, the request will default to your default agent. To change it: Dashboard → Agents → Set as default agent.
</Note>

## Bot Identity Setup

Blocks will respond on Bitbucket using the identity of whoever authorized the integration. To give Blocks a distinct identity — so responses appear from a dedicated bot account rather than a personal user — we recommend creating a separate Bitbucket user for this purpose before completing the integration.

**Steps:**

1. Create a new Bitbucket user account for your bot identity (e.g. `Blocks Bot`)
2. Log into that Bitbucket account
3. Create a new Blocks workspace user using that account's email
4. Invite the new Blocks user to your workspace
5. While logged in as the bot's Blocks account, go to **Settings > Connected Accounts** and connect the Bitbucket account
6. Complete the Bitbucket integration via **Settings > Integrations > Bitbucket** while authenticated as the bot Blocks user

Once setup is complete, you can log back into your normal Bitbucket and Blocks accounts for everyday use. This is a one-time setup.

## What Blocks Can Do

Blocks can help you with a variety of tasks on Bitbucket:

* **Answer Questions**: Ask Blocks about an issue or PR
* **Update Issues**: Request changes to an issue such as additional details with context from your codebase
* **Create New Issues**: Ask Blocks to create additional tickets based on your requirements
* **Implementation**: Ask Blocks to create a PR from an issue
* **PR Review**: Ask Blocks to review a pull request. Optionally, include context for what to look out for
* **Make Changes**: Ask Blocks to make changes to an open PR

### Making a Request

Simply mention `@blocks` in any Bitbucket issue or PR comment followed by your request:

```
@blocks what does this function do?
```

```
@blocks can you implement this issue?
```

```
@blocks review this PR, focus on any potential runtime errors
```

```
@blocks can you change this to a class instead?
```

<Note>
  **Session Context**: Responding in a Bitbucket pull request thread will continue in the same session, preserving all context from the conversation. Creating a new comment on an issue or PR will create a fresh session with no prior context.
</Note>

### Plan Mode

Start a new session in Plan Mode to create an implementation plan before making changes:

```
@blocks /plan implement user authentication with OAuth
```

Plan Mode allows you to collaborate on the approach before any code is written. Learn more about [Plan Mode](/using-blocks/features/plan-mode).

<Note>
  Plan Mode must be started with a new session and cannot be entered once implementation has begun.
</Note>

### Blocks Response Process

1. **Acknowledgment**: Blocks will add 👀 (eye) emojis to indicate it has seen your message
2. **Dashboard Link**: Blocks responds with a link to the dashboard where you can track progress
3. **Progress Updates**: Blocks provides a realtime snippet about what it is currently working on
4. **Final Message**: Blocks responds with a final message which summarizes what it did

## Best Practices

* **Be Specific**: Provide clear and detailed requests to get the best results
* **Use Context**: Reference specific issues, sections of the code, or requirements when relevant
* **Check Progress**: Use the dashboard link to monitor Blocks' work on your request
* **Follow Up**: You can continue the conversation by mentioning `@blocks` again with additional questions or clarifications

## Next Steps

New to Blocks? Check out the [Getting Started guide](/using-blocks/getting-started) to learn the basics.

Learn more about:

* [Plan Mode](/using-blocks/features/plan-mode) for collaborative planning
* [Skills](/using-blocks/features/skills) for reusable prompts
* [Multi-Repo Support](/using-blocks/features/multi-repo-support) for working across repositories