feat(bitbucket): add gitUser field to support API token auth on Bitbucket Cloud

[brendan-kellam]

Summary

• Adds an optional gitUser field to the Bitbucket connection config, used for git clone authentication over HTTPS
• Bitbucket Cloud API tokens require different usernames for the REST API (email address) and git clone (Atlassian username) — user handles the API and gitUser handles git clone
• Fully backwards-compatible: existing configs without gitUser behave identically (falls back to user, then x-token-auth)
• Updates Bitbucket Cloud docs with a new API Token tab (first tab), including step-by-step token creation instructions and deprecation warning on App Passwords

Fixes #892

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added optional gitUser field for Bitbucket connections; git clone operations will use gitUser (falling back to user) when present.

• Documentation

  • Expanded Bitbucket Cloud auth guide with tabbed instructions for API Token, Access Token, and App Password (deprecation note).
  • Updated Bitbucket Data Center docs and removed obsolete token snippets, replacing them with explicit config and run examples.

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

Adds an optional gitUser field to Bitbucket connection config, updates schemas and types, prefers config.gitUser for HTTPS git clone credential selection in backend, and expands Bitbucket authentication documentation and changelog entries.

Changes

Cohort / File(s)	Summary
Backend Logic packages/backend/src/utils.ts	Use config.gitUser before config.user (then 'x-token-auth') when forming git clone credentials for Bitbucket.
Schema & Type Definitions packages/schemas/src/v3/bitbucket.schema.ts, packages/schemas/src/v3/bitbucket.type.ts, packages/schemas/src/v3/connection.schema.ts, packages/schemas/src/v3/connection.type.ts, packages/schemas/src/v3/index.schema.ts, packages/schemas/src/v3/index.type.ts, schemas/v3/bitbucket.json	Add optional gitUser property to BitbucketConnectionConfig and update user property descriptions to distinguish API tokens vs app passwords and describe gitUser fallback behavior.
Bitbucket Cloud Documentation docs/docs/connections/bitbucket-cloud.mdx	Reworked authentication docs: replaced snippet components with three tabs (API Token, Access Token, App Password), detailed instructions, examples, and deprecation note for App Passwords.
Bitbucket Data Center Documentation docs/docs/connections/bitbucket-data-center.mdx	Replaced token snippet components with explicit config and docker run examples using env vars.
Documentation Snippets Removed docs/snippets/bitbucket-app-password.mdx, docs/snippets/bitbucket-token.mdx	Removed Environment Variable tab content previously providing token/env guidance.
Changelog & Schema Docs CHANGELOG.md, docs/snippets/schemas/v3/...	Added changelog entry for gitUser; updated schema docs to reflect new field and updated descriptions.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat(bitbucket): add gitUser field to support API token auth on Bitbucket Cloud #918: Adds same gitUser field and updates credential selection for Bitbucket Cloud API tokens (directly related).
• feat(auth): github app #570: Modifies getAuthCredentialsForRepo in packages/backend/src/utils.ts (related change to auth credential selection logic).
• Add Bitbucket support #275: Earlier Bitbucket connection work that this change extends; updates schemas and auth behavior.

Suggested labels

sourcebot-team

Suggested reviewers

• msukkari

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title clearly and specifically describes the main change: adding a gitUser field to support API token authentication on Bitbucket Cloud.
Linked Issues check	✅ Passed	All coding requirements from issue #892 are met: gitUser field added as optional string, schema/type definitions updated, git clone credentials use gitUser fallback chain, backwards-compatible, and change enables API token auth with different usernames.
Out of Scope Changes check	✅ Passed	Documentation updates for Bitbucket Cloud (API Token/Access Token/App Password tabs) and snippet/schema updates align with issue scope. All changes directly support the gitUser implementation and are within scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch bkellam/bitbucket-gituser-SOU-487

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/snippets/schemas/v3/connection.schema.mdx`:
- Around line 693-696: The gitUser schema description is missing a trailing
period, causing punctuation inconsistency with the user description; update the
"gitUser" property's description in the generated schema (look for the "gitUser"
property in the v3 Bitbucket schema generation, e.g., in the generator output
for bitbucket.json) to end with a period ("...this is your Bitbucket username.")
or, if you prefer consistent styling, update the generator/template that
produces descriptions for properties like "gitUser" and "user" so all
descriptions in the schemas/v3/bitbucket.json output follow the same punctuation
convention.

In `@docs/snippets/schemas/v3/index.schema.mdx`:
- Around line 1104-1111: Update the description for the gitUser schema property
so it documents the full fallback chain: state that gitUser is the username for
git clone over HTTPS, and if unset it falls back to 'user', and if both gitUser
and user are unset it then falls back to 'x-token-auth'; reference the existing
properties by name (gitUser, user, x-token-auth) so readers can find the related
fields.

In `@packages/schemas/src/v3/bitbucket.type.ts`:
- Around line 12-15: The JSDoc for the Bitbucket property gitUser is missing a
trailing period; update the source description for the gitUser property (the
jsdoc/comment that generates gitUser) to end with a period ("...this is your
Bitbucket username."), then re-run the generation pipeline so the change
propagates to the generated artifacts (index.type.ts, connection.type.ts,
bitbucket.schema.ts, connection.schema.ts) and any other auto-generated copies;
ensure the updated comment is present in the original schema/type source that
drives generation.

In `@packages/schemas/src/v3/index.schema.ts`:
- Around line 1103-1110: The gitUser description currently only mentions falling
back to user but the implementation falls back gitUser → user → x-token-auth;
update the gitUser property description to document the full fallback chain
(e.g., "If not set, falls back to 'user', then to 'x-token-auth'") and make the
same textual change to the other generated schema files containing gitUser
(bitbucket.schema.ts and connection.schema.ts) so all schemas consistently
reflect the actual behavior.

---

Duplicate comments:
In `@docs/snippets/schemas/v3/bitbucket.schema.mdx`:
- Around line 12-19: The documentation snippet for the Bitbucket credentials
wrongly states the fallback for git clone auth; update the descriptions for
"user" and "gitUser" in bitbucket.schema.mdx to reflect the x-token-auth
fallback chain (gitUser falls back to x-token-auth then to user as defined in
the source schema), correct the text mentioning API token/email vs username
accordingly, and after fixing the source schema ensure you regenerate this
snippet so the docs mirror the schema's x-token-auth fallback behavior.

In `@packages/schemas/src/v3/connection.type.ts`:
- Around line 263-266: The JSDoc for the optional field gitUser in the
Connection type is missing a trailing period; update the comment above the
gitUser property (symbol: gitUser) to end the sentence with a period (making it
consistent with the similar comment in bitbucket.type.ts) so the documentation
punctuation is consistent.

In `@packages/schemas/src/v3/index.type.ts`:
- Around line 461-464: The JSDoc for the optional property gitUser is missing a
trailing period across generated copies; update the doc comment for gitUser
(symbol: gitUser) to end with a period in this file and correct the generator
source/template that produces bitbucket.type.ts and other duplicates so future
regenerations include the trailing period; specifically, change the comment text
"For API tokens, this is your Bitbucket username" to "For API tokens, this is
your Bitbucket username." in the generator and in the immediate occurrence here.

In `@schemas/v3/bitbucket.json`:
- Around line 10-17: The field descriptions for "user" and "gitUser" in
schemas/v3/bitbucket.json are missing the x-token-auth fallback; update the
"description" strings for both properties ("user" and "gitUser") to mention the
x-token-auth fallback behavior (i.e., that authentication may fall back to
x-token-auth where applicable) and then regenerate the schema output to keep it
in sync with the updated source schema.