Bitbucket

GitComet Pro works with Bitbucket Cloud (bitbucket.org) and Bitbucket Data Center. Once connected, you can review pull requests and their comment threads and tasks, approve or request changes, merge pull requests, and follow, run, and stop Bitbucket Pipelines.

Bitbucket connects with a token only; there is no browser sign-in. App passwords are not supported.

Create an API token with scopes

Bitbucket Cloud tokens are created in your Atlassian account, not in Bitbucket. Atlassian offers two buttons there: Create API token and Create API token with scopes. Always choose Create API token with scopes. Bitbucket accepts only tokens with scopes for its API and for Git, so a token without scopes fails to connect.

1. Open id.atlassian.com/manage-profile/security/api-tokens. From Bitbucket, select your avatar, then Account settings, the Security tab, and Create and manage API tokens.

   In GitComet Pro, Create token in browser opens this page.

2. Choose Create API token with scopes.

3. Enter a name, such as GitComet Pro, and an expiry date, then choose Next. When the token expires, you create a new one and reconnect.

4. Choose Bitbucket as the app, then Next.

5. Select the scopes from the next section, then Next.

6. Review the token and choose Create token. Copy it right away: Atlassian shows it only once.

Atlassian documents the same steps in Create an API token.

Token scopes

Bitbucket scopes do not include each other. A write scope does not imply read, and pull request scopes do not give access to the repository's code, so select every scope in the table.

Add one more scope only if you need it:

• admin:repository:bitbucket: publish a local repository as a new Bitbucket Cloud repository. Nothing else needs it.

Choose a narrower set if you need less:

• Browse only: the three read: scopes for user, repository, and pull request, plus read:pipeline:bitbucket if you want pipelines. You can read pull requests, comment on them, and see pipelines, but approving, merging, and running pipelines fail with a permission error from Bitbucket.
• No pipelines: leave out both pipeline scopes. The pull request features keep working; pipeline views show a permission error from Bitbucket.

GitComet Pro does not need workspace, project, issue, webhook, snippet, runner, SSH key, or GPG key scopes, or any delete: scope. For details of each scope, see Atlassian's API token permissions.

A token never gives you more than your own Bitbucket permissions. If you cannot merge a pull request in the browser, a token with write:pullrequest:bitbucket will not let you do it either.

Use the same token for Git over HTTPS

GitComet Pro does not use the token for Git: fetching, pulling, and pushing work through your own Git setup. If you want to push over HTTPS with an API token, Bitbucket needs read:repository:bitbucket and write:repository:bitbucket on that token. You can use a separate token for that, or use SSH instead; see SSH Keys for Git Hosts.

Connect with the token

1. Open Settings (Cmd+, on macOS, Ctrl+, on Windows and Linux) and choose Forge connections.
2. Choose Create connection, then Bitbucket, then Use a token.
3. Fill in the form:
   • Instance URL (HTTPS): leave blank for bitbucket.org.
   • Organisation or workspace: your workspace ID, the first part of the path in https://bitbucket.org/<workspace>/<repository>.
   • Email or server username (optional): your Atlassian account email. An API token with scopes is used together with the email of the account that created it, so it does not work without one. With the field blank, GitComet Pro sends the token on its own as a bearer token.
   • Personal / API / access token: paste the token.
   • Repository URL (optional): leave blank.
4. Choose Connect with token.

GitComet Pro checks the token by asking Bitbucket who it belongs to, then saves it in your operating system's keychain. The token never leaves your device except to go to Bitbucket.

When the connection is saved, its Repository access list shows the workspace's repositories you are a member of. Select each repository you want to use in GitComet Pro to approve it on this device.

Bitbucket Data Center

Bitbucket Data Center uses an HTTP access token, created on your own server.

1. In Bitbucket Data Center, select your avatar, then Manage account → HTTP access tokens, and choose Create token. The address is https://<server>/plugins/servlet/access-tokens/manage, and Create token in browser in GitComet Pro opens it.
2. Enter a name and set the permissions:
   • Project permissions: Read.
   • Repository permissions: Write, to comment, approve, and merge pull requests. Read is enough to browse only.
3. Set an expiry date and choose Create. Copy the token right away.
4. In GitComet Pro, choose Use a token and enter:
   • Instance URL (HTTPS): your server's address, such as https://bitbucket.example.com.
   • Organisation or workspace: leave blank.
   • Email or server username (optional): leave blank. An HTTP access token is sent on its own.
   • Personal / API / access token: paste the token.
   • Repository URL: the clone URL of one of your repositories. Data Center tokens cannot identify their owner, so GitComet Pro checks the token against this repository instead. Checking a repository does not approve it.

Publishing a local repository as a new repository is not available for Bitbucket Data Center.

Atlassian documents the token page in HTTP access tokens.

When the token expires

Bitbucket rejects an expired or revoked token, and the connection shows Reconnect required. To fix it:

1. Create a new token with the same scopes or permissions.
2. In GitComet Pro, open the connection's menu and choose Reconnect.
3. Choose Use a token, paste the new token, and choose Reconnect with token.
4. Approve your repositories again. Reconnecting clears the approvals.

Troubleshooting

The token is rejected straight away. Check that you created it with Create API token with scopes and chose Bitbucket as the app, that Email or server username is the email of the Atlassian account that created it, and that it has not expired.

"Connected, but repositories could not be loaded." The token is valid but cannot list repositories. Make sure it has read:repository:bitbucket and that the workspace ID is correct, then choose Refresh repositories.

Pull requests load, but the diff or files are empty. The token has read:pullrequest:bitbucket but not read:repository:bitbucket. Pull request scopes do not include the repository's code.

Approving or merging fails. The token is missing write:pullrequest:bitbucket, or your account cannot merge into the target branch because of branch restrictions.

Pipelines do not load, or running a pipeline fails. The token is missing read:pipeline:bitbucket, or has it without write:pipeline:bitbucket, which running and stopping need.

Publishing a new repository fails. The token needs admin:repository:bitbucket, and your account needs permission to create repositories in the workspace.