Bitbucket Setup
Connect Bitbucket Cloud through OAuth, select a workspace and enable repositories for pull-request reviews.
Prerequisites
Use a Bitbucket Cloud account with access to the intended workspace and repositories. Repository webhook management requires appropriate provider permissions. The selected Codity account scope also applies when enabling repositories.
Setup Steps
Step 1: Sign In with Bitbucket
Choose Bitbucket on the Codity Platform sign-in page and authorize its OAuth connection. The current hosted flow uses OAuth credentials; it does not ask you to create an app password.
The deployed OAuth consumer defines the granted permissions. The platform's default request includes account, email, repository, pull-request read/write, webhook and pipeline scopes. Your deployment can configure the requested set. Additional integrations may need additional consumer permissions.
Step 2: Select Your Workspace
Finish the welcome flow and select the workspace you want to use. Account switching changes the active workspace; it does not combine every workspace into one repository list.
Step 3: Enable Repositories
- Open Repositories and choose Enable Repositories.
- On Bitbucket Repositories (
/bitbucket-repos), check the workspace and find the repository. - Choose Enable. Codity attempts to create its review webhook.
- Check that the repository shows as enabled. Read any returned error before continuing.
Step 4: Verify Setup
Open a small test PR in an enabled repository, targeting a branch allowed by your review settings. Check for review activity and completion; timing varies. If it does not start, check repository webhook deliveries and integration access in Bitbucket.
For a controlled verification:
- Confirm the intended workspace is active in Codity and the repository shows as enabled.
- Open a small authorized PR whose target branch matches the effective review configuration. Check that no opt-out marker suppresses it.
- Inspect the PR and Codity's review activity for a completed result. A completed review can have no findings.
- If no activity starts, open the repository's webhook settings in Bitbucket and inspect the relevant delivery and response when available.
- Resolve the reported connection, permission or review-eligibility error before repeating the test.
A successful webhook delivery establishes that an event reached its destination; it does not prove a review passed authorization, trigger and usage checks.
Managing Repositories
Use the same repository page to Disable a repository. Use the dashboard account menu's Switch Account choices to change workspace, then check which account is active before enabling more repositories.
Work with Multiple Workspaces
For example, if your identity belongs to both a personal workspace and a company workspace, select the company workspace before enabling a company repository. Repositories enabled in another account do not automatically move into the current one. Check the active workspace again after switching, especially before changing repository settings or subscription seats.
Stop Automatic Reviews
Choose Disable on the repository-management page and inspect the result. If you only want manual reviews while keeping a repository connected, use its automatic-review trigger instead. These choices control different parts of the workflow: repository connection and review eligibility.
How It Works
OAuth grants provider API access within the signed-in user's permissions. Repository enabling configures notifications; review triggers determine which eligible events start analysis. Authorization, workspace selection and repository enabling are separate steps.
Troubleshooting
OAuth scope error: the requested scopes must be supported by the deployment's configured OAuth consumer. Your deployment administrator must reconcile the consumer and sign-in configuration; replacing an app password is not the fix.
No workspaces or repositories: check the signed-in Bitbucket identity, workspace membership and selected account. Reauthorize if provider access was revoked.
Enable fails or comments cannot be posted: check both the user's repository permissions and the consumer's webhook/pull-request permissions. A token cannot grant access beyond its user.
Repository Missing from the List
- Verify the Bitbucket identity used to sign in and the active workspace in Codity.
- Confirm that identity can access the repository in Bitbucket. Check membership changes, repository transfers and revoked app authorization.
- Verify the OAuth consumer grants the required repository access for your deployment.
- If authorization was revoked, reconnect through the sign-in flow and recheck the selected workspace.
If only one repository is missing, compare its access and workspace with a repository that loads successfully. Switching to another workspace will not grant membership in the original one.
Webhook Creation Fails
Read the error returned by Enable. The signed-in identity needs the relevant repository rights, and the OAuth consumer must permit webhook operations. Ask the repository/workspace administrator to resolve missing rights, then retry enabling and check its saved state.
Do not copy an old webhook endpoint from another deployment or create a replacement with an arbitrary secret. The integration controls its endpoint and verification configuration.
No Review Starts
Check these layers in order:
- Connection: the intended repository is enabled under the active workspace.
- Provider notification: the relevant PR event was delivered to the configured integration webhook; inspect any provider delivery error.
- Eligibility: the account/repository trigger, target-branch scope and supported opt-out markers allow the event.
- Execution: inspect available run status and authorization, usage or service errors.
For an explicit review, post @codity review as its own PR comment and inspect the result. Manual review still requires repository authorization and available usage.
A Review Runs but Cannot Post Comments
Check the provider response for the failed write. Verify pull-request write permission in the OAuth consumer and the signed-in user's repository access. If a rate-limit error is reported, follow its retry guidance. If the action changes code, check that feature's enablement and required write access separately.
Include the workspace, repository, PR number and non-sensitive error details in a support request. Keep tokens and webhook secrets out of logs or screenshots you share.
Webhook Configuration
Codity manages the integration webhook when repositories are enabled. Check provider delivery results when diagnosing missing events; avoid changing secrets manually during routine setup.
For OAuth consent and scope behavior, see Atlassian's OAuth guide and OAuth scope reference.

