Bitbucket integration

Cloud agents work with any Git repository, including those hosted on Bitbucket. Unlike GitHub and GitLab, Bitbucket does not have a native Warp integration, but you can grant agents access to your Bitbucket repositories using an access token and Warp-managed secrets. Once configured, your environment works with any Automation Platform trigger—Slack, Linear, schedules, or the CLI.

This page explains how to generate a Bitbucket access token, store it securely, and configure a cloud agent environment that clones your repository at runtime.

Bitbucket Cloud and Bitbucket Data Center/Server use different token types:

• Bitbucket Cloud uses API tokens, created through your Atlassian Account settings.
• Bitbucket Data Center/Server uses HTTP access tokens, created through your Bitbucket profile settings.

Follow the section that matches your setup.

Prerequisites

• A Warp account (<a href=https://oz.warp.dev>create an account at https://oz.warp.dev)
• A repository hosted on Bitbucket (Cloud or Data Center/Server)
• The Oz CLI installed and authenticated

Bitbucket Cloud

Step 1: Generate an API token

1. Click your avatar in the upper-right corner of Bitbucket, then click Account settings.
2. On the Atlassian Account page that opens, click the Security tab.
3. Click Create and manage API tokens, then click Create API token with scopes.
4. Enter a name for the token (e.g. warp-oz-agent) and choose an expiration date.
5. Click Next.
6. Select Bitbucket as the app and click Next.
7. Search for repository in the Select Bitbucket scopes search box, then select read:repository:bitbucket (View your repositories).
8. Click Next.
9. Click Create token.
10. Copy the token value immediately. It is only shown once and cannot be retrieved later.

Step 2: Store the token as a Warp-managed secret

Warp injects managed secrets as environment variables at runtime and never exposes them in logs or configuration files. See the Secrets documentation for full details on scoping and managing secrets.

1. Run the following command:

oz secret create --team BITBUCKET_API_TOKEN

2. When prompted, paste the token.

The value is stored and encrypted, and cannot be retrieved after creation.

If you need to update a secret value, run:

oz secret update --value BITBUCKET_API_TOKEN

Step 3: Create an environment with a clone setup command

Create an environment that uses your token to clone the repository at the start of each agent run. Use the static username x-bitbucket-api-token-auth in the clone URL — this is a Bitbucket-specific placeholder that works with API tokens and means you don't need to store your Bitbucket username separately.

1. Run the following command:

oz environment create \
  --name "my-bitbucket-cloud-env" \
  --docker-image <image> \
  --setup-command 'git clone https://x-bitbucket-api-token-auth:[email protected]/your-workspace/your-repo.git' \
  --setup-command 'cd your-repo && <install dependencies>'

2. Replace the following placeholders:
   • <image> with your Docker image (for example, node:22, python:3.12, or a Warp prebuilt dev image)
   • bitbucket.org/your-workspace/your-repo.git with your actual repository URL
   • The second --setup-command with any dependency install or build steps your project requires (for example, npm ci or pip install -r requirements.txt)

3. Note the environment ID returned. You will need it in the next step.

Bitbucket Data Center / Server

Step 1: Generate an HTTP access token

1. Click your profile avatar in Bitbucket, then click Manage account.
2. In the left sidebar, click HTTP access tokens.
3. Click Create token.
4. Enter a name for the token (e.g. warp-oz-agent) and choose an expiration date if required by your administrator.
5. Under Permissions, choose Read for the Repository permission.
6. Click Create token.
7. Copy the token value immediately. It is only shown once and cannot be retrieved later.

Step 2: Store the token as a Warp-managed secret

Warp injects managed secrets as environment variables at runtime and never exposes them in logs or configuration files. See the Secrets documentation for full details on scoping and managing secrets.

1. Run the following command:

oz secret create --team BITBUCKET_TOKEN

2. When prompted, paste the token.

The value is stored and encrypted, and cannot be retrieved after creation.

If you need to update a secret value, run:

oz secret update --value BITBUCKET_TOKEN

Step 3: Create an environment with a clone setup command

Create an environment that uses your token to clone the repository at the start of each agent run.

1. Run the following command:

oz environment create \
  --name "my-bitbucket-dc-env" \
  --docker-image <image> \
  --setup-command 'git clone -c "http.extraHeader=Authorization: Bearer $BITBUCKET_TOKEN" https://your-server.com/scm/your-project/your-repo.git' \
  --setup-command 'cd your-repo && <install dependencies>'

2. Replace the following placeholders:
   • <image> with your Docker image (for example, node:22, python:3.12, or a Warp prebuilt dev image)
   • your-server.com/scm/your-project/your-repo.git with your Bitbucket Data Center/Server repository URL. The /scm/ path segment is standard for Bitbucket Data Center/Server.
   • The second --setup-command with any dependency install or build steps your project requires (for example, npm ci or pip install -r requirements.txt)

3. Note the environment ID returned. You will need it in the next step.

Test your environment

Before connecting to integrations, verify the environment works by running a one-off agent. This applies to both Bitbucket Cloud and Bitbucket Data Center / Server.

1. Run the following command, replacing `` with the environment ID from Step 3 of whichever setup you followed:

oz agent run-cloud --environment <ENV_ID> --prompt "Your task here"

Next steps

With your environment configured, you can connect it to any Warp trigger exactly as you would with a GitHub-backed environment:

• Slack — Tag @warp in a message to start an agent run against your Bitbucket repo. See Slack.
• Linear — Tag @warp on an issue to kick off a workflow. See Linear.
• Scheduled agents — Run agents on a recurring schedule. See Scheduled Agents.