> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/saas-applications/bitbucket.md).

# Bitbucket

The Bitbucket integration allows you to connect your Bitbucket workspace to Harmony and automate user provisioning as part of your onboarding workflows. Once connected, Harmony agents can manage repository access and workspace membership automatically - no manual steps required.

This integration is ideal for engineering onboarding flows where new hires need to be added to your Atlassian organization and granted access to the right repositories from day one.

### Connecting Bitbucket

Harmony connects to Bitbucket with an Atlassian API token. First, create the token as a Bitbucket workspace admin:

1. In Bitbucket, select your profile in the upper-right corner and open **Account settings**.
2. Select the **Security** tab, then select **Create and manage API tokens**.
3. Select **Create API token with scopes**, enter a name and an expiry date, and continue.
4. Select **Bitbucket** as the app and select **Next**.
5. Select these scopes and select **Next**: `read:workspace:bitbucket`, `read:repository:bitbucket`, `admin:repository:bitbucket`, `write:permission:bitbucket`, and `delete:permission:bitbucket`.
6. Review the token, select **Create token**, and copy it. Atlassian shows the token only once.

To connect Bitbucket as a SaaS integration:

1. In Harmony, navigate to **Settings** > **Integrations**.
2. Find **Bitbucket (API Token)** under **SaaS Applications** (or search for it by name) and click its card.
3. Enter your **Workspace slug** (for example, `your-workspace` in `bitbucket.org/your-workspace`), the **Admin email** of the Atlassian account that created the token, and the **API token**.
4. Click **Connect**.
5. Once connected, Bitbucket will appear as a connected integration and will be available to use in your workflows.

The **Invite User** action runs through Atlassian Administration rather than Bitbucket, so it also needs the [Atlassian (Admin API)](https://docs.harmony.io/integrations/saas-applications/atlassian-admin-api.md) integration to be connected. **Set Repository Permission** and **Remove Repository Permission** need it too when you pick the user as an employee or by email, because Harmony looks up the user's Atlassian account through it. They don't need it when you give an Atlassian account ID.

### Available Actions

After connecting Bitbucket, the following actions are available to use in your onboarding workflows:

#### Invite User

Adds a new user to your Atlassian organization, through the Atlassian (Admin API) integration. Use this action at the start of an onboarding flow to give a new team member access to your organization before assigning them to specific repositories.

#### Set Repository Permission

Grants a user access to a specific repository at a defined permission level. Use this action to provision the exact level of access a new hire needs - for example, read access for internal documentation repos or write access for active development repos.

#### Remove Repository Permission

Revokes a user's access to a specific repository. Use this action in offboarding flows or when adjusting access as roles change.

#### List Workspace Members

Retrieves the members of your connected Bitbucket workspace. Use this action to dynamically reference workspace members within your workflow logic.

### Using Bitbucket Actions in Workflows

Once Bitbucket is connected, its actions are available in the workflow builder alongside other SaaS integration actions. You can combine them with actions from other integrations - such as sending a Slack message or creating a ticket in Jira - to build end-to-end onboarding automations.

A typical onboarding workflow with Bitbucket might look like this:

1. A new hire record is created in your HRIS.
2. Harmony triggers the onboarding workflow automatically.
3. The **Invite User** action adds the new hire to your Atlassian organization.
4. The **Set Repository Permission** action grants access to the relevant repositories based on their team or role.
5. A confirmation message is sent to the manager via Slack.

### Permissions and Scopes

The Bitbucket integration acts with the permissions of the Atlassian account that created the API token, limited to the scopes selected on the token. Bitbucket only lets repository admins change repository permissions, so create the token as a workspace admin, or as a user with admin access to every repository you plan to manage. The **Invite User** action, and the user lookup in **Set Repository Permission** and **Remove Repository Permission**, use the organization API key of the Atlassian (Admin API) integration, which must be created by an organization admin.

### Disconnecting Bitbucket

To disconnect the Bitbucket integration:

1. Navigate to **Settings** > **Integrations**.
2. Find **Bitbucket (API Token)** under **SaaS Applications** and click its card.
3. Click **Disconnect** and confirm your choice.

Disconnecting Bitbucket will stop all associated workflow actions from executing. Any workflows that include Bitbucket actions should be reviewed and updated before disconnecting.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.harmony.io/integrations/saas-applications/bitbucket.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
