Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Bitbucket

Scalekit connector
Open markdown

The Bitbucket connector lets your AI agent act in each user's Bitbucket account. Each user signs in to Bitbucket once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 171 tools.

Tools
171
What they doRead · write · destructive
87 · 59 · 2587 read59 write25 destructive
Users sign in with
OAuth app
Your own Bitbucket app

What you can do

  • Manage pull requests: open, update, approve, decline, and merge pull requests, and read their diffs and activity
  • Review code: comment on pull requests and commits, request changes, and track review tasks
  • Work with repositories: create, fork, and update repositories, and browse branches, tags, commits, and files
  • Run pipelines: trigger, stop, and schedule pipelines, read step logs, and manage pipeline variables
  • Track issues: create, update, and comment on issues, and attach files, vote, or watch
  • Manage deployments: set up deployment environments and variables, and report build statuses on commits

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the Bitbucket connection

    In AgentKit > Connections, create a Bitbucket connection and copy its redirect URI. The name you give it is the connection_name your code passes. See Configure connections.

  4. Register an OAuth app

    Bitbucket connections use your own OAuth app. Register one with Bitbucket and add the redirect URI you copied.

    Then enter the app's Client ID and Client Secret on the Bitbucket connection.

    Console steps with screenshots

    Register your Bitbucket OAuth consumer credentials with Scalekit so it can manage the OAuth 2.0 authentication flow and token lifecycle on your behalf. You’ll need a Key (Client ID) and Secret (Client Secret) from your Bitbucket workspace settings.

    1. Open OAuth consumers in your Bitbucket workspace

      • Go to Bitbucket and open your workspace by clicking your avatar in the top-right corner and selecting the workspace you want to use.

      • In the left sidebar, click Settings → OAuth consumers.

        Bitbucket workspace settings showing OAuth consumers page

      • Click Add consumer to create a new OAuth application.

    2. Create the OAuth consumer

      • Fill in the consumer details:

        • Name — enter a descriptive name (e.g., Scalekit-Agent)
        • Description — optional description
        • URL — your application’s homepage URL

      • Leave the Callback URL field empty for now — you’ll fill it in after getting the redirect URI from Scalekit.

        Bitbucket Add OAuth consumer form

      • Under Permissions, select the scopes your agent needs. Recommended minimum:

        PermissionScopeRequired for
        AccountReadUser profile access
        RepositoriesReadRead code and metadata
        RepositoriesWriteCreate branches, push commits
        Pull requestsReadRead PR data
        Pull requestsWriteCreate, approve, and merge PRs
        PipelinesReadView pipeline runs
        PipelinesWriteTrigger pipelines

      • Click Save to create the consumer.

    3. Get the redirect URI from Scalekit

      • In Scalekit dashboard, go to AgentKit > Connections > Create Connection. Search for Bitbucket and click Create.

        Searching for Bitbucket in the Scalekit Create Connection panel

      • Copy the Redirect URI shown in the connection configuration panel. It looks like https://<SCALEKIT_ENVIRONMENT_URL>/sso/v1/oauth/<CONNECTION_ID>/callback.

        Scalekit Configure Bitbucket Connection panel showing Redirect URI, Client Key, and Client Secret fields

    4. Add the callback URL in Bitbucket

      • Back in Bitbucket, open your OAuth consumer and click Edit.

      • Paste the Scalekit Redirect URI into the Callback URL field.

      • Click Save to apply the change.

        Bitbucket Edit OAuth consumer with Scalekit callback URL added to the Callback URL field

    5. Copy your OAuth credentials

      • In Bitbucket, go back to Workspace settings → OAuth consumers and click on your consumer name to expand it.

      • The Key and Secret will be shown. Click Reveal next to the secret to display it.

        Bitbucket OAuth consumer expanded showing Key and Secret with Reveal button

      • Copy both values. The secret is not stored by Bitbucket after you leave this page — save it securely.

    6. Add credentials in Scalekit

      • In Scalekit dashboard, go to AgentKit > Connections and open the Bitbucket connection you created.

      • Enter your credentials:

        • Client Key — the Key from your Bitbucket OAuth consumer
        • Client Secret — the Secret from your Bitbucket OAuth consumer
        • Scopes — select the scopes that match the permissions you granted in step 2

      • Click Save.

  5. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'bitbucket'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Bitbucket:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'bitbucket_user_emails_list',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • bitbucket_branch_getReturns details of a specific branch in a Bitbucket repository.Read-only

    Get Branch

    Returns details of a specific branch in a Bitbucket repository.

    Inputs

    namestringrequired
    The branch name.
    repo_slugstringrequired
    The repository slug or UUID.
    workspacestringrequired
    The workspace slug or UUID.
  • bitbucket_branch_restriction_getReturns a specific branch permission rule by ID.Read-only

    Get Branch Restriction

    Returns a specific branch permission rule by ID.

    Inputs

    idstringrequired
    The numeric ID of the branch restriction.
    repo_slugstringrequired
    The repository slug or UUID.
    workspacestringrequired
    The workspace slug or UUID.
  • bitbucket_branch_restrictions_listLists branch permission rules for a repository.Read-only

    List Branch Restrictions

    Lists branch permission rules for a repository.

    Inputs

    repo_slugstringrequired
    The repository slug or UUID.
    workspacestringrequired
    The workspace slug or UUID.
  • bitbucket_branches_listReturns all branches in a Bitbucket repository.Read-only

    List Branches

    Returns all branches in a Bitbucket repository.

    Inputs

    repo_slugstringrequired
    The repository slug or UUID.
    workspacestringrequired
    The workspace slug or UUID.
    pageinteger
    Page number for pagination (starts at 1).
    pageleninteger
    Number of items to return per page.
    qstring
    Query to filter branches, e.g. name~"feature".
    sortstring
    Sort field, e.g. -target.date for newest first.
  • bitbucket_branching_model_getReturns the effective branching model for a repository (e.g.Read-only

    Get Branching Model

    Returns the effective branching model for a repository (e.g. Gitflow config).

    Inputs

    repo_slugstringrequired
    The repository slug or UUID.
    workspacestringrequired
    The workspace slug or UUID.
  • bitbucket_branching_model_settings_getReturns the branching model configuration settings for a repository.Read-only

    Get Branching Model Settings

    Returns the branching model configuration settings for a repository.

    Inputs

    repo_slugstringrequired
    The repository slug or UUID.
    workspacestringrequired
    The workspace slug or UUID.
  • bitbucket_commit_build_status_getReturns the build status for a specific commit and build key.Read-only

    Get Commit Build Status

    Returns the build status for a specific commit and build key.

    Inputs

    commitstringrequired
    The commit hash.
    keystringrequired
    Unique identifier for the build.
    repo_slugstringrequired
    The repository slug or UUID.
    workspacestringrequired
    The workspace slug or UUID.
  • bitbucket_commit_comment_getReturns a specific comment on a commit.Read-only

    Get Commit Comment

    Returns a specific comment on a commit.

    Inputs

    comment_idstringrequired
    The numeric ID of the comment.
    commitstringrequired
    The commit hash.
    repo_slugstringrequired
    The repository slug or UUID.
    workspacestringrequired
    The workspace slug or UUID.

Workflows

Proxy API call
const user = await actions.request({
  connectionName: 'bitbucket',
  identifier: 'user_123',
  path: '/2.0/user',
  method: 'GET',
});
console.log(user);
Execute a tool
const result = await actions.executeTool({
  connector: 'bitbucket',
  identifier: 'user_123',
  toolName: 'bitbucket_branch_create',
  toolInput: {},
});
console.log(result);
All 117 in Developer Tools