Community
Questions Library
Docs
Blog
Events
Swag
Github
Slack
JupiterOne
Discussions
Release Notes
Contact Us
Bitbucket - AskJ1 Community
<main> <article class="userContent"> <h2 data-id="bitbucket-jupiterone-integration-benefits">Bitbucket + JupiterOne Integration Benefits</h2> <ul><li><p>Visualize Bitbucket workspaces, projects, repos, pull requests, groups, and<br> users in the JupiterOne graph.</p></li> <li><p>Map Bitbucket users to employees in your JupiterOne account.</p></li> <li>Monitor changes to Bitbucket users using JupiterOne alerts.</li> <li>Track which Bitbucket users opened, reviewed, and approved Bitbucket pull<br> requests.</li> </ul><h2 data-id="how-it-works">How it Works</h2> <ul><li><p>JupiterOne periodically fetches workspaces, projects, repos, groups, and users<br> from Bitbucket to update the graph.</p></li> <li><p>Optionally, JupiterOne fetches pull requests from the last 24 hours, along<br> with user activity on those PRs, and adds that information to the graph.</p></li> <li><p>Write JupiterOne queries to review and monitor updates to the graph, or<br> leverage existing queries.</p></li> <li><p>Configure alerts to take action when JupiterOne graph changes, or leverage<br> existing alerts.</p></li> </ul><h2 data-id="requirements">Requirements</h2> <ul><li><p>Bitbucket supports the OAuth2 Client Credential flow, so your Bitbucket<br> workspace will need an OAuth consumer configured.</p></li> <li><p>JupiterOne requires the name of your Bitbucket workspace and the OAuth client<br> key and secret from an OAuth consumer configured on that workspace.</p></li> <li><p>You must have permission in JupiterOne to install new integrations.</p></li> </ul><h2 data-id="support">Support</h2> <p>If you need help with this integration, please contact<br><a rel="nofollow" href="https://support.jupiterone.io">JupiterOne Support</a>.</p> <h2 data-id="integration-walkthrough">Integration Walkthrough</h2> <h3 data-id="in-bitbucket">In BitBucket</h3> <ol><li>From your profile avatar in the bottom left, click on the workspace in the<br> Recent workspaces list or click All workspaces to open an entire list from<br> which to choose.</li> <li>Click <strong>Settings</strong> on the left sidebar to open the Workspace settings.</li> <li>Click OAuth consumers under Apps and features on the left navigation.</li> <li>If you already have an OAuth consumer for this workspace, you can use it for<br> JupiterOne also. However, Bitbucket enforces rate-limiting per OAuth<br> consumer, so it may be wise to configure a new OAuth consumer specifically<br> for JupiterOne's use. To configure a new OAuth consumer, click the <strong>Add<br> consumer</strong> button.</li> <li>Add a <strong>Name</strong> for this consumer. This only appears in your list of OAuth<br> consumers for this workspace. For example, <code class="code codeInline" spellcheck="false" tabindex="0">JupiterOne integration</code>.</li> <li>Add a <strong>Callback URL</strong>. This URL is not used for anything, but the OAuth 2<br> authentication flow requires it, and it must be in URL format. For example,<br><code class="code codeInline" spellcheck="false" tabindex="0">https://jupiterone.com/</code>.</li> <li>Check the box labeled <strong>This is a private consumer</strong>. This is required for<br> the way the integration authenticates.</li> <li>Set permissions for this consumer. The integration requires Read access to<br><strong>Account</strong>, <strong>Projects</strong>, and <strong>Repositories</strong>. If you plan to ingest pull<br> requests into the JupiterOne graph, or think you might later, the integration<br> also needs Read access to <strong>Pull requests</strong>.</li> <li>Click <strong>Save</strong>. The system generates a key and a secret for you. Make a note<br> of the client id and client secret, along with the name of the workspace to<br> be accessed.</li> </ol><h3 data-id="in-jupiterone">In JupiterOne</h3> <ol><li>From the top navigation of the J1 Search homepage, select <strong>Integrations</strong>.</li> <li>Scroll to the <strong>Bitbucket</strong> integration tile and click it.</li> <li>Click the <strong>Add Configuration</strong> button and configure the following settings:</li> </ol><ul><li><p>Enter the <strong>Account Name</strong> by which you'd like to identify this Bitbucket<br> account in JupiterOne. Ingested entities will have this value stored in<br><code class="code codeInline" spellcheck="false" tabindex="0">tag.AccountName</code> when <strong>Tag with Account Name</strong> is checked.</p></li> <li><p>Enter a <strong>Description</strong> that will further assist your team when identifying<br> the integration instance.</p></li> <li><p>Select a <strong>Polling Interval</strong> that you feel is sufficient for your monitoring<br> needs. You may leave this as <code class="code codeInline" spellcheck="false" tabindex="0">DISABLED</code> and manually execute the integration.</p></li> <li><p>Enter the <strong>Bitbucket Client Key</strong> for your workspace.</p></li> <li>Enter the <strong>Bitbucket Client Secret</strong> for your workspace.</li> <li>Enter the <strong>Bitbucket Workspace</strong>, the name of your workspace.</li> <li><p>Optionally, set the <strong>Bitbucket Ingest Pull Requests</strong> field to false if you<br> want to disable the ingestion of pull requests into the JupiterOne graph. By<br> default, whenever the intergration is run, JupiterOne will ingest any PR<br> created or modified in the last 24 hours.</p></li> <li><p>Optionally, set the <strong>Bitbucket Enriched PRs</strong> field to true to get additional<br> information on each PR, such as who reviewed it. Note that this has<br> performance implications, which is why it is disabled by default. See<br><strong>Details on rate limiting</strong> below.</p></li> </ul><ol start="4"><li>Click <strong>Create Configuration</strong> once all values are provided.</li> </ol><h3 data-id="details-on-pull-request-ingestion">Details on pull request ingestion</h3> <p>Generally, when JupiterOne ingests data from an intregration, any entities not<br> ingested are deleted from the JupiterOne graph if they exist. For example, if a<br> Project gets deleted from your Bitbucket account, it will disappear from the<br> JupiterOne graph the next time the integration runs.</p> <p>Since Pull Requests are only ingested from the last 24 hours (for performance<br> reasons), previous Pull Requests in the JupiterOne graph are not deleted. Even<br> if the PR is deleted from Bitbucket, the JupiterOne integration will have no way<br> of knowing if the PR was deleted or is merely untouched in the last 24 hours.</p> <p>That said, if the Repo that owns that Pull Request is deleted from Bitbucket,<br> the JupiterOne graph will delete the Repo, and then it will delete any orphaned<br> Pull Request entities that were owned by it. This same "cascading delete" would<br> apply if higher-level objects (Projects, Workspaces) were deleted from your<br> Bitbucket account.</p> <h3 data-id="details-on-rate-limiting">Details on rate limiting</h3> <p>Bitbucket enforces a rate-limit of 1000 per hour per OAuth consumer, on API<br> calls related to Repositories and Pull Requests. JupiterOne ingestion exceeds<br> this rate, so you might see a rate-limit error on your account if your workspace<br> has enough data.</p> <p>You can get around this limit by adding additional OAuth consumers to your<br> Bitbucket workspace, and then updating your JupiterOne Bitbucket integration<br> configuration to use a comma-delimited list of OAuth keys and secrets.</p> <p>To do so, put the comma-delimited list of OAuth client keys in the <strong>Bitbucket<br> Client Key</strong> field of your integration configuration. Do the same for the<br> matching OAuth client secrets in the <strong>Bitbucket Client Secret</strong> field, being<br> careful to make sure the secrets are in the same order as the keys.</p> <p>Note that the integration will attempt to validate all of the key/secret pairs<br> before starting ingestion, and throw an error if any of them is invalid.<br> Assuming they are all valid, the integration will automatically switch to each<br> new OAuth consumer sequentially when it encounters a Bitbucket rate limit, and<br> will not throw a rate-limit error unless is exhausts all OAuth consumers.</p> <p>You can calculate the minimum number of API calls that count against this limit<br> as:</p> <ul><li>If not ingesting Pull Requests: (#Repos)/10</li> <li>With Pull Requests (default status): (#Repos)/10 + (#PRs)/10 + (2*#PRs)</li> <li>With Enriched PRs: (#Repos)/10 + (#PRs)/10 + (3*#PRs)</li> </ul><h1 data-id="how-to-uninstall">How to Uninstall</h1> <ol><li>From the configuration <strong>Gear Icon</strong>, select <strong>Integrations</strong>.</li> <li>Scroll to the <strong>Bitbucket</strong> integration tile and click it.</li> <li>Identify and click the <strong>integration to delete</strong>.</li> <li>Click the <strong>trash can</strong> icon.</li> <li>Click the <strong>Remove</strong> button to delete the integration.</li> </ol><p><br></p> <h2 data-id="data-model">Data Model</h2> <h3 data-id="entities">Entities</h3> <p>The following entities are created:</p> <table><thead><tr><th>Resources</th> <th>Entity <code class="code codeInline" spellcheck="false" tabindex="0">_type</code></th> <th>Entity <code class="code codeInline" spellcheck="false" tabindex="0">_class</code></th> </tr></thead><tbody><tr><td>Bitbucket Group</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_group</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">UserGroup</code></td> </tr><tr><td>Bitbucket Project</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_project</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">Project</code></td> </tr><tr><td>Bitbucket Pull Request</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_pullrequest</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">Review</code>, <code class="code codeInline" spellcheck="false" tabindex="0">PR</code></td> </tr><tr><td>Bitbucket Repo</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_repo</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">CodeRepo</code></td> </tr><tr><td>Bitbucket User</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_user</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">User</code></td> </tr><tr><td>Bitbucket Workspace</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_workspace</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">Account</code></td> </tr></tbody></table><h3 data-id="relationships">Relationships</h3> <p>The following relationships are created/mapped:</p> <table><thead><tr><th>Source Entity <code class="code codeInline" spellcheck="false" tabindex="0">_type</code></th> <th>Relationship <code class="code codeInline" spellcheck="false" tabindex="0">_class</code></th> <th>Target Entity <code class="code codeInline" spellcheck="false" tabindex="0">_type</code></th> </tr></thead><tbody><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_group</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_user</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_project</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_repo</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_repo</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_pullrequest</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_user</code></td> <td><strong>APPROVED</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_pullrequest</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_user</code></td> <td><strong>OPENED</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_pullrequest</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_user</code></td> <td><strong>OWNS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_group</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_user</code></td> <td><strong>REVIEWED</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_pullrequest</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_workspace</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_group</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_workspace</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_user</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_workspace</code></td> <td><strong>OWNS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_project</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_workspace</code></td> <td><strong>OWNS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">bitbucket_repo</code></td> </tr></tbody></table><p><br></p> </article> </main>
.png)