Bitbucket Setup

This guide will help you set up Codity with Bitbucket to start reviewing pull requests automatically.

Prerequisites

  • A Bitbucket Cloud account with required workspace access

Setup Steps

Step 1: Sign In with Bitbucket

  1. Navigate to Codity website and click "Log In"
  2. Select "Sign in with Bitbucket" or click "Connect Bitbucket"
  3. You'll be redirected to Bitbucket to authorize Codity
  4. Sign in with your Bitbucket credentials if prompted
  5. Review and grant Codity the requested permissions:
    • Repositories: Read - To read repository files and analyze code changes
    • Pull requests: Read & Write - To read PRs and post review comments
    • Account: Read - To access your account information
    • Webhooks: Read and write - To set up automatic PR review notifications
  6. Click "Grant access" or "Authorize"
  7. You'll be redirected back to Codity dashboard

Step 2: Select Your Workspace

After signing in, Codity will automatically detect your Bitbucket workspaces:

  1. If you have multiple workspaces, you'll see a list of available workspaces
  2. Select the workspace that contains the repositories you want to review
  3. The selected workspace will be saved for future use
  4. You can switch workspaces later from the dashboard settings

Note: If you only have one workspace, it will be automatically selected.

Step 3: Enable Repositories

  1. Navigate to Repository Management
    • From the dashboard, click "Enable Repositories"
  2. View Available Repositories
    • You'll see a list of all repositories in your selected workspace
    • Repositories are paginated (20 per page) for easier navigation
    • Use the search or pagination controls to find specific repositories
  3. Enable Repositories
    • Click "Enable" next to each repository you want Codity to review
    • You can enable multiple repositories at once
    • Enabled repositories will show an "Enabled" status
  4. Repository Information
    • Each repository shows:
      • Repository name and slug
      • Workspace name
      • Default branch
      • Current status (enabled/disabled)

Step 4: Verify Setup

  1. Check Repository Status
    • Go to your dashboard
    • You should see your enabled repositories listed
    • Each repository should show as "Active" or "Enabled"
  2. Test the Integration
    • Create a test pull request in one of your enabled repositories
    • Wait 1-3 minutes for Codity to analyze the PR
    • Check the PR comments to see Codity's review feedback
  3. Verify Webhooks
    • Codity automatically creates webhooks for enabled repositories
    • You can verify this in Bitbucket:
      • Go to your repository → Settings → Webhooks
      • Look for a webhook named "Codity AI – Automated PR Reviews"

Managing Repositories

View Enabled Repositories

  • Go to your Dashboard
  • Your enabled Bitbucket repositories will be listed
  • You can see repository details, last review time, and status

Disable a Repository

  1. Navigate to Repositories → Bitbucket Repositories
  2. Find the repository you want to disable
  3. Click "Disable" next to the repository
  4. Confirm the action
  5. The repository will stop receiving automatic PR reviews

Switch Workspaces

If you have access to multiple Bitbucket workspaces:

  1. Go to Settings → Providers → Bitbucket
  2. Select a different workspace from the dropdown
  3. Navigate back to Repositories to enable repos from the new workspace

How It Works

Automatic PR Reviews

Once a repository is enabled:

  1. Webhook Setup: Codity automatically creates a webhook in your Bitbucket repository
  2. PR Detection: When a pull request is created or updated, Bitbucket sends a webhook to Codity
  3. Code Analysis: Codity analyzes the PR changes, code quality, and compliance
  4. Review Comments: Codity posts detailed review comments directly on the PR

Webhook Events

Codity listens for the following Bitbucket events:

  • Pull request: Created - Triggers review when a new PR is opened
  • Pull request: Updated - Triggers review when PR code changes
  • Pull request: Comment created - May trigger re-review based on context
  • Pull request: Fulfilled - Logs when PR is merged

Best Practices

  1. Enable repositories selectively: Start with a few repositories to test, then enable more as needed
  2. Monitor webhook deliveries: Periodically check webhook status in Bitbucket repository settings
  3. Use workspace selection carefully: Select the workspace that contains the repositories you want to review
  4. Keep permissions up to date: Ensure your Bitbucket account has the necessary permissions for all enabled repositories
  5. Test after setup: After enabling repositories, create a test PR to verify everything works correctly
  6. Review webhook configuration: Verify webhooks are active and delivering successfully
  7. Organize by workspace: If you have multiple workspaces, enable repositories from one workspace at a time for better organization

Troubleshooting

Issue: "Sign in with Bitbucket" button doesn't work

Solution:

  • Check if your organization has configured the Bitbucket OAuth consumer
  • Contact your administrator to verify OAuth consumer setup
  • Ensure the callback URL is correctly configured

Issue: "No workspaces found"

Solution:

  • Verify you're signed in with the correct Bitbucket account
  • Check that you have access to at least one workspace
  • Try signing out and signing back in

Issue: "No access token found for repository"

Solution:

  • Verify you completed the OAuth sign-in flow
  • Check that you selected the correct workspace
  • Ensure the repository belongs to the selected workspace
  • Try disconnecting and reconnecting Bitbucket

Issue: "Repository not found" when enabling

Solution:

  • Verify the repository exists in the selected workspace
  • Check that you have read access to the repository
  • Ensure the repository slug is correct

Issue: "PR review not triggering"

Solution:

  • Verify the repository is enabled in Codity dashboard
  • Check that webhook is configured in Bitbucket repository settings
  • Verify webhook URL is accessible from Bitbucket
  • Review server logs for webhook receipt (contact support if needed)
  • Check webhook delivery status in Bitbucket repository settings

Issue: "Comments not posting"

Solution:

  • Verify OAuth permissions include "Pull requests: Write"
  • Check that your Bitbucket account has write access to the repository
  • Verify Bitbucket API rate limits haven't been exceeded
  • Try disabling and re-enabling the repository

Issue: "Webhook creation failed"

Solution:

  • Verify your Bitbucket account has webhook creation permissions
  • Check that the repository allows webhook creation
  • Ensure you have admin or write access to the repository
  • Try manually creating the webhook in Bitbucket (see Webhook Configuration below)

Webhook Configuration

Codity automatically creates webhooks when you enable a repository. If automatic webhook creation fails, you can create it manually:

  1. Navigate to Repository Settings
    • Go to your Bitbucket repository
    • Click Settings → Webhooks
  2. Create New Webhook
    • Click Add webhook
    • Fill in:
      • Title: Codity AI – Automated PR Reviews
      • URL: https://api.codity.ai/webhooks/bitbucket (or your Codity server URL)
      • Status: Active
      • Triggers: Select:
        • Pull request: Created
        • Pull request: Updated
        • Pull request: Comment created
        • Pull request: Fulfilled
  3. Save Webhook
    • Click Save
    • The webhook will now trigger Codity reviews

Next Steps