Skip to main content

Bitbucket

Visualize Bitbucket Cloud workspaces, map Bitbucket Cloud users to employees, and monitor changes through queries and alerts.

Installation​

To install the Bitbucket Cloud integration, you will need to configure settings both within Bitbucket and on JupiterOne. Before enabling in JupiterOne, ensure that you have completed the setup within Bitbucket.

This integration only works with Bitbucket Cloud and not Bitbucket Server.

Bitbucket configuration​

To set up this integration, you will need to ensure your Bitbucket workspace has an OAuth consumer configured. You will also need to provide the name of your Bitbucket Workspace and obtain the Oauth Client Key and Secret Key for use within JupiterOne.

To ensure your Bitbucket Workspace Oauth consumer is configured:

  1. From your profile avatar in the bottom left, click on the workspace in the Recent workspaces list or click All workspaces to open an entire list from which to choose.
  2. Click Settings on the left sidebar to open the Workspace settings.
  3. From the left-hand navigation, select Apps and features > OAuth consumers.
  4. If you already have an OAuth consumer for this workspace, you can use it for JupiterOne. However, Bitbucket enforces rate-limiting per OAuth consumer, so it may be wise to configure a new OAuth consumer specifically for JupiterOne's use. To configure a new OAuth consumer, click the Add consumer.
  5. Add a Name for this consumer. This only appears in your list of OAuth consumers for this workspace. For example, JupiterOne integration.
  6. Add a Callback URL. This URL is not used for anything, but the OAuth 2 authentication flow requires it, and it must be in URL format. For example, https://jupiterone.com/.
  7. Check the box labeled This is a private consumer. This is required for the way the integration authenticates.
  8. Set permissions for this consumer. The integration requires Read access to Account, Projects, and Repositories. If you plan to ingest pull requests into the JupiterOne graph, or think you might later, the integration also needs Read access to Pull requests. If you want to, you can also enable Admin access to Repositories to ingest permissions and branch restrictions.
  9. Click Save. The system generates a key and a secret for you. Make a note of the client id and client secret, along with the name of the workspace to be accessed.

With the above completed, continue to JupiterOne to complete the integration setup.

Configuration in JupiterOne​

To install the BitBucket integration in JupiterOne, navigate to the Integrations tab in JupiterOne and select Bitbucket. Click New Instance to begin configuring your integration.

Creating a configuration requires the following:

  • The Account Name used to identify the Bitbucket account in JupiterOne. Ingested entities will have this value stored in tag.AccountName when the AccountName toggle is enabled.

  • Description to assist in identifying the integration instance, if desired.

  • Polling Interval that you feel is sufficient for your monitoring needs. You may leave this as DISABLED and manually execute the integration.

  • Your Bitbucket Client Key, Secret Key, and Bitbucket Workspace (the name of your BitBucket Workspace).

    • Optional set the Bitbucket Ingest Pull Requests field to false if you want to disable the ingestion of pull requests into the JupiterOne graph. By default, whenever the integration is run, JupiterOne will ingest any PR created or modified in the last 24 hours.
    • Optional set the Bitbucket Enriched PRs field to true to get additional information on each PR, such as who reviewed it. Note that this has performance implications, which is why it is disabled by default. See below.

Click Create once all values are provided to finalize the integration.

Next steps​

Now that your integration instance has been configured, it will begin running on the polling interval you provided, populating data within JupiterOne. Continue on to our Instance management guide to learn more about working with and editing integration instances.

Details on pull request data ingestion​

Generally, when JupiterOne ingests data from an integration, any entities not ingested are deleted from the JupiterOne graph if they exist. For example, if a Project gets deleted from your Bitbucket account, it will disappear from the JupiterOne graph the next time the integration runs.

Since Pull Requests are only ingested from the last 24 hours (for performance reasons), previous Pull Requests in the JupiterOne graph are not deleted. Even if the PR is deleted from Bitbucket, the JupiterOne integration will have no way of knowing if the PR was deleted or is merely untouched in the last 24 hours.

That said, if the Repo that owns that Pull Request is deleted from Bitbucket, the JupiterOne graph will delete the Repo, and then it will delete any orphaned Pull Request entities that were owned by it. This same "cascading delete" would apply if higher-level objects (Projects, Workspaces) were deleted from your Bitbucket account.

Details on rate limiting​

Bitbucket enforces a rate-limit of 1000 per hour per OAuth consumer, on API calls related to Repositories and Pull Requests. JupiterOne ingestion exceeds this rate, so you might see a rate-limit error on your account if your workspace has enough data.

You can get around this limit by adding additional OAuth consumers to your Bitbucket workspace, and then updating your JupiterOne Bitbucket integration configuration to use a comma-delimited list of OAuth keys and secrets.

To do so, put the comma-delimited list of OAuth client keys in the Bitbucket Client Key field of your integration configuration. Do the same for the matching OAuth client secrets in the Bitbucket Client Secret field, being careful to make sure the secrets are in the same order as the keys.

note

The integration will attempt to validate all of the key/secret pairs before starting ingestion, and throw an error if any of them is invalid. Assuming they are all valid, the integration will automatically switch to each new OAuth consumer sequentially when it encounters a Bitbucket rate limit, and will not throw a rate-limit error unless is exhausts all OAuth consumers.

You can calculate the minimum number of API calls that count against this limit as:

  • If not ingesting Pull Requests: (#Repos)/10
  • With Pull Requests (default status): (#Repos)/10 + (#PRs)/10 + (2*#PRs)
  • With Enriched PRs: (#Repos)/10 + (#PRs)/10 + (3*#PRs)