Skip to content

Commit a6844ac

Browse files
brendan-kellamclaude
brendan-kellam
and
claude
authored
feat(bitbucket): add gitUser field to support API token auth on Bitbucket Cloud (#918)
* feat(bitbucket): add gitUser field to support API token auth on Bitbucket Cloud BitBucket Cloud API tokens require different usernames for the REST API (email address) and git clone (Atlassian username). Add an optional `gitUser` field to the BitBucket connection config that, when set, is used for git clone credentials instead of `user`. Fixes #892 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * chore: update CHANGELOG for #918 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * chore: delete unused Bitbucket snippet files Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 6fd5b69 commit a6844ac

File tree

16 files changed

+171
-81
lines changed

16 files changed

+171
-81
lines changed

‎CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1616
- Skip calling `getCommitHashForRefName` for empty repositories to avoid noisy debug log output. [#914](https://github.com/sourcebot-dev/sourcebot/pull/914)
1717
- Fixed "Open in GitLab" links having a double slash when the GitLab host URL is configured with a trailing slash. [#915](https://github.com/sourcebot-dev/sourcebot/pull/915)
1818

19+
### Added
20+
- Added optional `gitUser` field to the Bitbucket connection config to support Bitbucket Cloud API tokens, which require an email address for the REST API but an Atlassian username for git clone. [#918](https://github.com/sourcebot-dev/sourcebot/pull/918)
21+
1922
## [4.11.4] - 2026-02-20
2023

2124
### Fixed

‎docs/docs/connections/bitbucket-cloud.mdx‎

Lines changed: 93 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,6 @@ sidebarTitle: Bitbucket Cloud
44
icon: Bitbucket
55
---
66

7-
import BitbucketToken from '/snippets/bitbucket-token.mdx';
8-
import BitbucketAppPassword from '/snippets/bitbucket-app-password.mdx';
97
import BitbucketSchema from '/snippets/schemas/v3/bitbucket.schema.mdx'
108

119
<Note>
@@ -78,25 +76,107 @@ If you're not familiar with Sourcebot [connections](/docs/connections/overview),
7876

7977
## Authenticating with Bitbucket Cloud
8078

81-
In order to index private repositories, you'll need to provide authentication credentials via a [token](/docs/configuration/config-file#tokens). You can do this using an `App Password` or an `Access Token`
79+
In order to index private repositories, you'll need to provide authentication credentials via a [token](/docs/configuration/config-file#tokens). You can do this using an `API Token`, `Access Token`, or `App Password`.
8280

8381
<Tabs>
84-
<Tab title="App Password">
85-
Navigate to the [app password creation page](https://bitbucket.org/account/settings/app-passwords/) and create an app password. Ensure that it has the proper permissions for the scope
86-
of info you want to fetch (i.e. workspace, project, and/or repo level)
87-
![Bitbucket App Password Permissions](/images/bitbucket_app_password_perms.png)
88-
89-
Next, provide your username + app password pair to Sourcebot:
90-
91-
<BitbucketAppPassword />
82+
<Tab title="API Token">
83+
1. Navigate to [Personal Settings → API tokens](https://id.atlassian.com/manage-profile/security/api-tokens) and click **Create API token with scopes**. Give the token a name and set an expiry date.
84+
85+
2. Select **Bitbucket** as the app.
86+
87+
3. Select the following scopes:
88+
- `read:repository:bitbucket` — View your repositories
89+
- `read:workspace:bitbucket` — View your workspaces
90+
91+
4. Click **Create token** and copy the token value.
92+
93+
5. Add the `user` (your account email), `gitUser` (your Bitbucket username), and `token` to your connection config. [Learn why both are needed](https://support.atlassian.com/bitbucket-cloud/docs/using-api-tokens/)
94+
95+
```json
96+
{
97+
"type": "bitbucket",
98+
"deploymentType": "cloud",
99+
"user": "you@example.com",
100+
"gitUser": "myusername",
101+
"token": {
102+
// note: this env var can be named anything. It
103+
// doesn't need to be `BITBUCKET_TOKEN`.
104+
"env": "BITBUCKET_TOKEN"
105+
}
106+
// .. rest of config ..
107+
}
108+
```
109+
110+
6. Pass this environment variable each time you run Sourcebot:
111+
112+
```bash
113+
docker run \
114+
-e BITBUCKET_TOKEN=<API_TOKEN> \
115+
/* additional args */ \
116+
ghcr.io/sourcebot-dev/sourcebot:latest
117+
```
92118
</Tab>
93119
<Tab title="Access Token">
94120
Create an access token for the desired scope (repo, project, or workspace). Visit the official [Bitbucket Cloud docs](https://support.atlassian.com/bitbucket-cloud/docs/access-tokens/)
95121
for more info.
96122

97-
Next, provide the access token to Sourcebot:
123+
1. Add the `token` property to your connection config:
124+
125+
```json
126+
{
127+
"type": "bitbucket",
128+
"deploymentType": "cloud",
129+
"token": {
130+
// note: this env var can be named anything. It
131+
// doesn't need to be `BITBUCKET_TOKEN`.
132+
"env": "BITBUCKET_TOKEN"
133+
}
134+
// .. rest of config ..
135+
}
136+
```
137+
138+
2. Pass this environment variable each time you run Sourcebot:
139+
140+
```bash
141+
docker run \
142+
-e BITBUCKET_TOKEN=<ACCESS_TOKEN> \
143+
/* additional args */ \
144+
ghcr.io/sourcebot-dev/sourcebot:latest
145+
```
146+
</Tab>
147+
<Tab title="App Password">
148+
<Warning>
149+
App Passwords are deprecated. Atlassian recommends migrating to API tokens. [Learn more](https://www.atlassian.com/blog/bitbucket/bitbucket-cloud-transitions-to-api-tokens-enhancing-security-with-app-password-deprecation)
150+
</Warning>
151+
152+
Navigate to the [app password creation page](https://bitbucket.org/account/settings/app-passwords/) and create an app password. Ensure that it has the proper permissions for the scope
153+
of info you want to fetch (i.e. workspace, project, and/or repo level)
154+
![Bitbucket App Password Permissions](/images/bitbucket_app_password_perms.png)
98155

99-
<BitbucketToken />
156+
1. Add the `user` (your Bitbucket username) and `token` properties to your connection config:
157+
158+
```json
159+
{
160+
"type": "bitbucket",
161+
"deploymentType": "cloud",
162+
"user": "myusername",
163+
"token": {
164+
// note: this env var can be named anything. It
165+
// doesn't need to be `BITBUCKET_TOKEN`.
166+
"env": "BITBUCKET_TOKEN"
167+
}
168+
// .. rest of config ..
169+
}
170+
```
171+
172+
2. Pass this environment variable each time you run Sourcebot:
173+
174+
```bash
175+
docker run \
176+
-e BITBUCKET_TOKEN=<APP_PASSWORD> \
177+
/* additional args */ \
178+
ghcr.io/sourcebot-dev/sourcebot:latest
179+
```
100180
</Tab>
101181
</Tabs>
102182

‎docs/docs/connections/bitbucket-data-center.mdx‎

Lines changed: 24 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,6 @@ sidebarTitle: Bitbucket Data Center
44
icon: Bitbucket
55
---
66

7-
import BitbucketToken from '/snippets/bitbucket-token.mdx';
8-
import BitbucketAppPassword from '/snippets/bitbucket-app-password.mdx';
97
import BitbucketSchema from '/snippets/schemas/v3/bitbucket.schema.mdx'
108

119
<Note>
@@ -75,9 +73,30 @@ In order to index private repositories, you'll need to provide an access token t
7573
Create an access token for the desired scope (repo, project, or workspace). Visit the official [Bitbucket Data Center docs](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html)
7674
for more info.
7775

78-
Next, provide the access token to Sourcebot:
79-
80-
<BitbucketToken />
76+
1. Add the `token` property to your connection config:
77+
78+
```json
79+
{
80+
"type": "bitbucket",
81+
"deploymentType": "server",
82+
"url": "https://mybitbucketdeployment.com",
83+
"token": {
84+
// note: this env var can be named anything. It
85+
// doesn't need to be `BITBUCKET_TOKEN`.
86+
"env": "BITBUCKET_TOKEN"
87+
}
88+
// .. rest of config ..
89+
}
90+
```
91+
92+
2. Pass this environment variable each time you run Sourcebot:
93+
94+
```bash
95+
docker run \
96+
-e BITBUCKET_TOKEN=<ACCESS_TOKEN> \
97+
/* additional args */ \
98+
ghcr.io/sourcebot-dev/sourcebot:latest
99+
```
81100

82101
## Troubleshooting
83102
If you're seeing errors like `TypeError: fetch failed` when fetching repo info, it may be that Sourcebot is refusing to connect to your self-hosted Bitbucket instance due to unrecognized SSL certs. Try setting the `NODE_TLS_REJECT_UNAUTHORIZED=0` environment variable or providing Sourcebot your certs through the `NODE_EXTRA_CA_CERTS` environment variable.

‎docs/snippets/bitbucket-app-password.mdx‎

Lines changed: 0 additions & 27 deletions
This file was deleted.

‎docs/snippets/bitbucket-token.mdx‎

Lines changed: 0 additions & 25 deletions
This file was deleted.

‎docs/snippets/schemas/v3/bitbucket.schema.mdx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,11 @@
1111
},
1212
"user": {
1313
"type": "string",
14-
"description": "The username to use for authentication. Only needed if token is an app password."
14+
"description": "The username to use for API authentication. For app passwords, this is your Bitbucket username. For API tokens, this is your Bitbucket account email address."
15+
},
16+
"gitUser": {
17+
"type": "string",
18+
"description": "The username to use for git clone authentication over HTTPS. If not set, falls back to 'user'. For API tokens, this is your Bitbucket username"
1519
},
1620
"token": {
1721
"description": "An authentication token.",

‎docs/snippets/schemas/v3/connection.schema.mdx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -688,7 +688,11 @@
688688
},
689689
"user": {
690690
"type": "string",
691-
"description": "The username to use for authentication. Only needed if token is an app password."
691+
"description": "The username to use for API authentication. For app passwords, this is your Bitbucket username. For API tokens, this is your Bitbucket account email address."
692+
},
693+
"gitUser": {
694+
"type": "string",
695+
"description": "The username to use for git clone authentication over HTTPS. If not set, falls back to 'user'. For API tokens, this is your Bitbucket username"
692696
},
693697
"token": {
694698
"description": "An authentication token.",

‎docs/snippets/schemas/v3/index.schema.mdx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1103,7 +1103,11 @@
11031103
},
11041104
"user": {
11051105
"type": "string",
1106-
"description": "The username to use for authentication. Only needed if token is an app password."
1106+
"description": "The username to use for API authentication. For app passwords, this is your Bitbucket username. For API tokens, this is your Bitbucket account email address."
1107+
},
1108+
"gitUser": {
1109+
"type": "string",
1110+
"description": "The username to use for git clone authentication over HTTPS. If not set, falls back to 'user'. For API tokens, this is your Bitbucket username"
11071111
},
11081112
"token": {
11091113
"anyOf": [

‎packages/backend/src/utils.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -182,7 +182,7 @@ export const getAuthCredentialsForRepo = async (repo: RepoWithConnections, logge
182182
const config = connection.config as unknown as BitbucketConnectionConfig;
183183
if (config.token) {
184184
const token = await getTokenFromConfig(config.token);
185-
const username = config.user ?? 'x-token-auth';
185+
const username = config.gitUser ?? config.user ?? 'x-token-auth';
186186
return {
187187
hostUrl: config.url,
188188
token,

‎packages/schemas/src/v3/bitbucket.schema.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,11 @@ const schema = {
1010
},
1111
"user": {
1212
"type": "string",
13-
"description": "The username to use for authentication. Only needed if token is an app password."
13+
"description": "The username to use for API authentication. For app passwords, this is your Bitbucket username. For API tokens, this is your Bitbucket account email address."
14+
},
15+
"gitUser": {
16+
"type": "string",
17+
"description": "The username to use for git clone authentication over HTTPS. If not set, falls back to 'user'. For API tokens, this is your Bitbucket username"
1418
},
1519
"token": {
1620
"description": "An authentication token.",

0 commit comments

Comments
 (0)