Bitbucket

Connect Bitbucket and the Coder reads your repository, its pull requests, and its build results, copies the repository into its own workspace, and hands you a pull request for review. When your house rules allow it, it can also merge.

At a glance#

Pick a token#

A repository access token is the narrowest choice and is enough for pull requests. Choose the Atlassian token if you want the Coder to read or open Bitbucket issues. On the Premium plan you can also create a project or workspace access token, which works like a repository token across many repositories.

What assistants can do#

Issues also need the repository's own issue tracker turned on, under the repository's Settings, Features. The Coder cannot create Bitbucket repositories. Create the repository yourself, then give it to the Coder.

Create a repository access token#

1. On bitbucket.org, open the repository.
2. Select ... next to the repository name, then Settings.
3. Under Security, select Access tokens, then Create access token.
4. Name it, such as "StellarFirm Coder", and choose when it expires. When it expires, the Coder stops as Blocked and asks you for a new one.
5. Under permissions, tick Repositories: Write and Pull requests: Write. Bitbucket ticks the matching Read for you.
6. Select Create and copy the token. Bitbucket shows it once.

Create an Atlassian token with scopes#

1. In Bitbucket, select your profile picture in the upper right, then Account settings.
2. On your Atlassian account page, open the Security tab and select Create and manage API tokens.
3. Select Create API token with scopes. Give it a name and an expiry date, then Next.
4. Choose Bitbucket as the app, then Next.
5. Select these scopes, then Next:
   • read:repository:bitbucket and write:repository:bitbucket
   • read:pullrequest:bitbucket and write:pullrequest:bitbucket
   • read:issue:bitbucket and write:issue:bitbucket
6. Select Create token and copy it. It is shown once.
7. Note the email of your Atlassian account. You can see it in Bitbucket under Personal settings, Email aliases.

Connect it in StellarFirm#

1. Open the StellarFirm desktop app and sign in.
2. Open Integrations and pick Bitbucket.
3. Paste the token into Access token.
4. For an Atlassian token only, enter your Atlassian account email. Leave it empty for a repository access token.
5. Leave Use live Bitbucket on and press Connect.
6. The card shows Connected. Your token is saved on your computer by the desktop app, never shown back to you, and handed to one git command at a time.

Tell the Coder where to work#

The Coder needs a repository, written as workspace/repository.

• In your message. Name it, or paste its link: "Coder, in acme/web, fix the login redirect."
• For good, per Coder. Open Settings, Coders, edit the Coder, and under Repository and login choose Bitbucket as source control and fill in Repository. See several Coders.

Each Coder can also use its own login. Choose Its own login, paste a token, and add the Atlassian account email only if it is an Atlassian token. A repository access token on its own is enough.

Good to know#

• Pushing and merging follow your house rules. The Coder pushes to a new branch of its own, never to your default branch, and never force pushes. Pushing waits for your Approve. Merging follows your merge policy: review only by default, never while builds are failing or still running, and always with a merge commit that keeps the branch. Your branch restrictions on Bitbucket still apply.
• Drafts cannot be merged. Open the pull request on Bitbucket and select Mark as ready before you ask the Coder to merge.
• "Pick up the top ticket" needs issues. With a repository access token, or with the issue tracker off, name the work in your message instead.
• If the clone fails, the job stops as Blocked before any coding and says what to fix.
• Several code hosts connected? A link or the word Bitbucket in your message picks Bitbucket.
• Bitbucket Data Center is not supported.
• Revoke at any time. Revoke the token in Bitbucket and the Coder loses access straight away. Then choose Turn off on the Bitbucket card.

Troubleshooting#

Prompts#

Coder, Bitbucket is connected. In [workspace]/[repository], add [feature]. Run the tests and open a pull request for review once I Approve.

Coder, list the open pull requests on [workspace]/[repository], say which ones are stuck, and what each is waiting for.

Coder, read the latest build results on [workspace]/[repository] and tell me whether the main branch is healthy.

Next#

• Connect your code: the checklist for every code host.
• House rules and approvals: what waits for you.
• GitHub and GitLab.