For a chemical draw to be truly functional, drawing isn’t enough; the user must be able to interact with every element on the screen. Selecting an atom is intuitive, but how do you select a chemical bond (a line segment) with pixel-perfect precision? In this post, I’ll break down the mathematical process and the challenges of implementing this collision engine.

Selecting Atoms: The Easy Path

Detecting if the cursor is over an atom is the ideal scenario. Since our domain already stores the (x, y) coordinates of each node, the solution is applying Euclidean distance.

We calculate the separation between the mouse (P) and each atom (A) with the formula:

.

If the distance is shorter than a defined search radius, the atom is considered a candidate. To ensure precision, if multiple atoms are within range, we always select the one with the minimum distance.

class Molecule {
  // ...
  private findClosestAtom(
    x: number,
    y: number,
    radius: number,
  ): { atom: Atom; distance: number } | null {
    const candidates = [...this._atoms.values()]
      .map((atom) => ({
        atom,
        distance: Math.sqrt(Math.pow(atom.x - x, 2) + Math.pow(atom.y - y, 2)),
      }))
      .filter(({ distance }) => distance <= radius)
      .sort((a, b) => a.distance - b.distance);

    return candidates[0] || null;
  }
  // ...

Selecting Bonds: The “Infinite Line” Problem

With bonds, things get complicated. A bond is a line segment, not a single point. My first instinct was to use the classic equation for the distance from a point to a line:

The problem: This formula assumes the line is infinite. If you click miles away but happen to be perfectly aligned with the bond’s trajectory, the formula will trigger a “hit”. In a molecule with hundreds of bonds, this creates “ghost collisions” across the entire canvas.

The Solution: Projection and Clamping

To solve this, we need to find the closest point specifically within the segment bounded by atoms A and B. Here’s where the vector math comes in.

The algorithm projects the mouse coordinates onto the line and calculates the “projection factor” t.

• If t = 0, the closest point is atom A.
• If t = 1, the closest point is atom B.
• If t is between 0 and 1, the closest point lies somewhere along the bond.

Key here is clamping: forcing t to stay between 0 and 1 using Math.max(0, Math.min(1, t)). This effectively “encloses” the collision logic within the physical boundaries of the bond.

private pointToSegmentDistance(
  px: number, py: number, // Mouse point
  ax: number, ay: number, // Atom A (Start)
  bx: number, by: number  // Atom B (End)
): number {
  const abx = bx - ax;
  const aby = by - ay;
  const apx = px - ax;
  const apy = py - ay;

  const abLengthSq = abx * abx + aby * aby;

  // If atoms overlap, return distance to point A
  if (abLengthSq === 0) return Math.sqrt(apx * apx + apy * apy);

  // Scalar projection restricted to the [0, 1] range (Clamping)
  const t = Math.max(0, Math.min(1, (apx * abx + apy * aby) / abLengthSq));

  // Find the coordinates of the closest point on the segment
  const closestX = ax + t * abx;
  const closestY = ay + t * aby;

  // Final distance between mouse and the closest point on the segment
  return Math.sqrt(Math.pow(px - closestX, 2) + Math.pow(py - closestY, 2));
}

Atoms vs Bonds

A common UX challenge in chemical editors is overlap. What happens if the mouse is near a bond but also directly over an atom?

In chemistry, the atom is the primary unit of interaction. Therefore, I implemented a simple but effective business rule: Atoms always have priority. If the engine detects a collision with both an atom and a bond, the atom “hijacks” the selection event. This prevents users from accidentally deleting a bond when they intended to edit an element.

Conclusion: The “God Object” Warning

While this collision engine works perfectly, it has exposed a growing architectural debt. My Molecule class—which should only care about chemical valences and atoms—is now bloated with 2D geometry formulas and pixel coordinates.

I’ve created a God Object.

In the next post, I’ll perform “major surgery” on this architecture. We will split the system into two Bounded Contexts: a Chemistry context for the logic and a Spatial context for the geometry.

I used to think “clever code” made me a better developer.

You know the type: 5 layers of abstraction, every design pattern imaginable, optimizations sprinkled everywhere.

It looked impressive. Until a new teammate joined and spent half a day just figuring out how to make a tiny change.

That’s when it hit me:

Readability is the real standard of good code.

The Real Test of a Codebase

Forget patterns, frameworks, or architecture debates for a second. Here’s my rule:

If anyone on your team, new or experienced, can read, understand, and adapt your code within a day, your code is solid.

Everything else, optimization, abstraction, architectural elegance, still matters. But it should support readability, not replace it. Think of readability as the foundation and the fancy stuff sits on top.

This Isn’t About New Developers

A lot of people hear “readable code” and assume it’s a criticism of junior devs. It’s not.

Even the most skilled developer can waste hours untangling overly abstracted or over-engineered code. Readable code is about writing code that communicates intent clearly, so everyone can move fast and safely.

Think of it as writing a story. The plot, your logic, should be clear. The style, patterns and architecture, can be fancy, but no one should need a decoder ring to figure out what’s happening.

Why Readability Works

Readable code makes:

• Onboarding fast
• Collaboration smoother
• Bug tracking easier

It also doesn’t mean sacrificing good engineering:

• Optimizations are still important, but they shouldn’t make the code unreadable.
• Abstraction is fine, but if nobody understands why it exists, it’s too abstract.
• Architecture should guide, not confuse.

Readable first, clever second. Layer sophistication where it genuinely adds value.

Quick Wins for Readable Code

• Names matter. calculateTotal() beats calcT() any day.
• Organize files logically. Don’t make someone guess where a component lives.
• Keep it simple. Don’t over-engineer just to show off.
• Comments = context, not code. Explain why, not what.
• Readable commits. Your history should tell the story of the project, not confuse it.

My Personal Rule

Whenever I onboard someone new, I give them a small task.

If they can complete it without me explaining every step, the code passes my readability test.

If not, it’s a signal it’s time to rethink clarity.

Readable code doesn’t mean dumb code.

It means code that anyone can understand, adapt, and maintain, while still being optimized, abstracted, and architecturally elegant.

Software isn’t about showing off cleverness. It’s about solving problems together.

Why integrate Codacy with Bitbucket

Bitbucket and Atlassian’s tool ecosystem power a significant portion of the world’s software development teams, particularly in enterprises that rely on Jira, Confluence, and the broader Atlassian suite. If your team lives in Bitbucket, integrating Codacy gives you automated code quality analysis on every pull request without leaving your existing workflow.

The combination of Codacy and Bitbucket Pipelines covers everything a quality-focused team needs: static analysis across 49 programming languages, security vulnerability scanning (SAST), secrets detection, duplication checking, and test coverage tracking – all surfaced directly on your Bitbucket pull requests as status checks and inline comments.

This guide covers the end-to-end setup for both Bitbucket Cloud and Bitbucket Data Center users. You will learn how to install the Codacy app, configure your bitbucket-pipelines.yml to upload coverage reports, set up quality gates that can pass or fail your pipelines, configure PR status checks and webhooks, and troubleshoot the most common issues that come up during integration.

If you are new to Codacy altogether, our Codacy review gives a comprehensive overview of what the platform offers before you commit to the integration work.

Bitbucket Cloud vs Bitbucket Data Center

Before walking through the setup, it is worth clarifying the two distinct Bitbucket products and how Codacy supports each of them.

Bitbucket Cloud is Atlassian’s hosted service at bitbucket.org. The Codacy cloud platform at app.codacy.com supports Bitbucket Cloud natively. You install the Codacy app from the Atlassian Marketplace, authenticate with your Bitbucket account, and everything is managed through Codacy’s cloud infrastructure. This is the path covered in most of this guide.

Bitbucket Data Center (formerly Bitbucket Server) is the self-hosted, on-premise version that organizations run on their own infrastructure. Codacy supports Bitbucket Data Center through Codacy Self-Hosted, the on-premise edition of the platform. Self-Hosted is available on Enterprise plans and requires deploying Codacy containers in your own Kubernetes or Docker environment. The configuration steps differ from the cloud approach, and you will need to contact Codacy’s sales team to get started.

If you are on Bitbucket Cloud, continue with the steps below. If you are on Bitbucket Data Center, the conceptual steps are the same but the installation process involves deploying Codacy Self-Hosted on your infrastructure first.

Step 1: Install the Codacy Bitbucket app

The Codacy Bitbucket app handles the webhook integration that triggers analysis on every push and pull request. Installing it is the first step before any pipeline configuration.

Installing from the Atlassian Marketplace

1. Go to your Bitbucket workspace and click Settings in the left navigation
2. Under Workspace settings, click Installed apps then Find new apps
3. Search for “Codacy” in the Atlassian Marketplace
4. Click Try it free or Get it now on the Codacy listing
5. Follow the prompts to authorize the app to access your workspace

Alternatively, you can sign in at app.codacy.com using your Bitbucket credentials. Codacy will request Bitbucket OAuth permissions during the sign-in process, which effectively installs the integration.

Adding repositories to Codacy

After installing the app and signing in to Codacy:

1. Click Add repository in the Codacy dashboard
2. Select your Bitbucket workspace from the dropdown
3. Find the repository you want to analyze and click Add
4. Codacy begins an initial analysis of your default branch

Codacy automatically installs webhooks in your Bitbucket repository during this process. You can verify the webhooks were created by going to your Bitbucket repository settings, clicking Webhooks under Workflow, and checking that a Codacy webhook URL appears in the list.

Repository access levels

Codacy requires read access to your repository code to perform analysis and write access to post PR status checks and comments. When you add a repository, Codacy will prompt you to confirm these permissions. If your Bitbucket workspace uses IP allowlisting, add Codacy’s IP ranges to your allowlist to ensure webhook delivery succeeds.

Step 2: Get your Codacy project API token

The project API token authenticates the Codacy Coverage Reporter when it uploads coverage data from your Bitbucket Pipelines build to the Codacy platform.

To find the token:

1. Navigate to your repository in the Codacy dashboard
2. Click Settings in the left sidebar
3. Select Coverage (or Integrations on some plan levels)
4. Copy the Project API Token

Once you have the token, store it as a Bitbucket repository variable so your pipeline can use it without hardcoding it in your YAML file:

1. Go to your Bitbucket repository
2. Click Repository settings then Repository variables under Pipelines
3. Add a variable:
   • Name: CODACY_PROJECT_TOKEN
   • Value: Paste your Codacy project token
   • Secured: Check this box to mask the value in logs
4. Click Add

If you also want to check quality gates from your pipeline, you will need a Codacy account API token as well. Generate one from your Codacy account settings under Access tokens and store it as CODACY_ACCOUNT_TOKEN in your Bitbucket repository variables using the same process.

Step 3: Configure bitbucket-pipelines.yml for coverage upload

The core of the Bitbucket Pipelines integration is adding a coverage upload step to your bitbucket-pipelines.yml file. The Codacy Coverage Reporter is a shell script that you download and run after your tests complete.

Basic pipeline structure

Here is the general pattern that applies to any language:

pipelines:
  default:
    - step:
        name: Build, Test, and Upload Coverage
        script:
          - # Run your build and tests here
          - pipe: atlassian/git-secrets-scan:0.5.1
          - curl -Ls https://coverage.codacy.com/get.sh -o codacy-coverage-reporter.sh
          - bash codacy-coverage-reporter.sh report
              -r <path-to-coverage-report>
              --project-token $CODACY_PROJECT_TOKEN
              --commit-uuid $BITBUCKET_COMMIT

The $BITBUCKET_COMMIT environment variable is provided automatically by Bitbucket Pipelines and contains the full commit SHA. Passing it to the Coverage Reporter with --commit-uuid ensures Codacy associates the coverage data with the correct commit, which is critical for PR-level coverage display.

Java project with Maven and JaCoCo

image: maven:3.9-eclipse-temurin-17

pipelines:
  default:
    - step:
        name: Build and Test
        caches:
          - maven
        script:
          - mvn clean test
    - step:
        name: Upload Coverage to Codacy
        script:
          - curl -Ls https://coverage.codacy.com/get.sh -o codacy-coverage-reporter.sh
          - bash codacy-coverage-reporter.sh report
              -r target/site/jacoco/jacoco.xml
              --project-token $CODACY_PROJECT_TOKEN
              --commit-uuid $BITBUCKET_COMMIT

  pull-requests:
    '**':
      - step:
          name: Build and Test
          caches:
            - maven
          script:
            - mvn clean test
      - step:
          name: Upload Coverage to Codacy
          script:
            - curl -Ls https://coverage.codacy.com/get.sh -o codacy-coverage-reporter.sh
            - bash codacy-coverage-reporter.sh report
                -r target/site/jacoco/jacoco.xml
                --project-token $CODACY_PROJECT_TOKEN
                --commit-uuid $BITBUCKET_COMMIT

The pull-requests section tells Bitbucket Pipelines to run this pipeline whenever a pull request is opened or updated, regardless of the source branch name ('**' matches all branch names). This ensures every PR gets coverage uploaded to Codacy.

JavaScript and TypeScript with npm

image: node:20-alpine

pipelines:
  default:
    - step:
        name: Install and Test
        caches:
          - node
        script:
          - npm ci
          - npm test -- --coverage --coverageReporters=lcov
    - step:
        name: Upload Coverage to Codacy
        script:
          - apk add --no-cache curl bash
          - curl -Ls https://coverage.codacy.com/get.sh -o codacy-coverage-reporter.sh
          - bash codacy-coverage-reporter.sh report
              -r coverage/lcov.info
              --project-token $CODACY_PROJECT_TOKEN
              --commit-uuid $BITBUCKET_COMMIT

  pull-requests:
    '**':
      - step:
          name: Install and Test
          caches:
            - node
          script:
            - npm ci
            - npm test -- --coverage --coverageReporters=lcov
      - step:
          name: Upload Coverage to Codacy
          script:
            - apk add --no-cache curl bash
            - curl -Ls https://coverage.codacy.com/get.sh -o codacy-coverage-reporter.sh
            - bash codacy-coverage-reporter.sh report
                -r coverage/lcov.info
                --project-token $CODACY_PROJECT_TOKEN
                --commit-uuid $BITBUCKET_COMMIT

Note the apk add --no-cache curl bash step – the Alpine-based Node image does not include curl or bash by default, so you need to install them before downloading the Coverage Reporter. If you are using a Debian-based image (e.g., node:20), replace apk with apt-get install -y curl.

Python with pytest

image: python:3.12-slim

pipelines:
  default:
    - step:
        name: Test with Coverage
        script:
          - pip install -r requirements.txt pytest pytest-cov
          - pytest --cov=src --cov-report=xml:coverage.xml
    - step:
        name: Upload Coverage to Codacy
        script:
          - apt-get update && apt-get install -y curl
          - curl -Ls https://coverage.codacy.com/get.sh -o codacy-coverage-reporter.sh
          - bash codacy-coverage-reporter.sh report
              -r coverage.xml
              --project-token $CODACY_PROJECT_TOKEN
              --commit-uuid $BITBUCKET_COMMIT

  pull-requests:
    '**':
      - step:
          name: Test with Coverage
          script:
            - pip install -r requirements.txt pytest pytest-cov
            - pytest --cov=src --cov-report=xml:coverage.xml
      - step:
          name: Upload Coverage to Codacy
          script:
            - apt-get update && apt-get install -y curl
            - curl -Ls https://coverage.codacy.com/get.sh -o codacy-coverage-reporter.sh
            - bash codacy-coverage-reporter.sh report
                -r coverage.xml
                --project-token $CODACY_PROJECT_TOKEN
                --commit-uuid $BITBUCKET_COMMIT

Step 4: PR status checks in Bitbucket

Once Codacy is connected to your Bitbucket repository, it automatically posts a status check to each pull request. The status check appears in the PR’s merge button area and shows whether Codacy analysis passed or found issues.

Understanding Codacy status check states

Codacy posts one of three statuses to Bitbucket for each PR:

• Successful – The PR passes your configured quality gate thresholds and no blocking issues were found
• Failed – The PR violates one or more quality gate thresholds (too many new issues, coverage too low, etc.)
• Pending – Codacy is still processing the analysis or waiting for coverage data

The status check name in Bitbucket will appear as “Codacy Static Analysis” or similar, depending on your Codacy plan and configuration.

Requiring Codacy status checks before merge

To enforce code quality at the PR level, configure Bitbucket to require the Codacy status check to pass before any PR can be merged:

1. Go to your Bitbucket repository and click Repository settings
2. Under Workflow, click Branch restrictions
3. Click Add a branch restriction
4. Set the branch pattern to match your target branch (e.g., main or master)
5. Under Merge checks, enable Require minimum number of approvals if desired
6. Also enable any option for requiring CI/CD status checks to pass
7. Save the restriction

With this configured, a PR cannot be merged until Codacy’s analysis completes and returns a successful status. This effectively makes Codacy analysis a required gate in your development workflow.

Configuring what Codacy analyzes on PRs

By default, Codacy analyzes new code introduced in the PR and compares it against your quality gate thresholds. You can control this behavior in your Codacy repository settings:

• New issues gate – Fail if the PR introduces more than N issues (configurable per severity level)
• Coverage gate – Fail if coverage on new code falls below a threshold
• Duplication gate – Fail if the PR introduces duplicated code above a threshold

Navigate to your repository in Codacy, click Quality settings, and adjust the thresholds to match your team’s standards.

Step 5: Coverage reporting via Bitbucket Pipelines

Coverage reporting from Bitbucket Pipelines to Codacy is straightforward for most setups, but there are some nuances worth understanding for larger or more complex projects.

Uploading multiple coverage reports

If your project has separate test suites – unit tests and integration tests, for example – or if you run tests in parallel Bitbucket Pipelines steps, you can upload multiple partial coverage reports that Codacy aggregates into a single metric.

pipelines:
  pull-requests:
    '**':
      - parallel:
          - step:
              name: Unit Tests
              script:
                - mvn test -P unit-tests
                - curl -Ls https://coverage.codacy.com/get.sh -o codacy-coverage-reporter.sh
                - bash codacy-coverage-reporter.sh report
                    -r target/site/jacoco-unit/jacoco.xml
                    --partial
                    --project-token $CODACY_PROJECT_TOKEN
                    --commit-uuid $BITBUCKET_COMMIT
          - step:
              name: Integration Tests
              script:
                - mvn verify -P integration-tests
                - curl -Ls https://coverage.codacy.com/get.sh -o codacy-coverage-reporter.sh
                - bash codacy-coverage-reporter.sh report
                    -r target/site/jacoco-integration/jacoco.xml
                    --partial
                    --project-token $CODACY_PROJECT_TOKEN
                    --commit-uuid $BITBUCKET_COMMIT
      - step:
          name: Finalize Coverage
          script:
            - curl -Ls https://coverage.codacy.com/get.sh -o codacy-coverage-reporter.sh
            - bash codacy-coverage-reporter.sh final
                --project-token $CODACY_PROJECT_TOKEN
                --commit-uuid $BITBUCKET_COMMIT

The --partial flag tells Codacy to expect more coverage data before aggregating. The final command in the downstream step signals that all partial reports have been uploaded. Without the final command, Codacy keeps waiting and the coverage dashboard never updates.

Coverage for monorepos

For monorepos with multiple components in subdirectories, you can upload coverage from each component using separate reporter invocations with the --partial flag, then finalize once all uploads are complete. Keep in mind that the Codacy project token is per-repository, so all components in the same Bitbucket repository share the same token and coverage metrics.

If different monorepo components are treated as separate Codacy repositories, each has its own token and you upload coverage to the corresponding project independently.

Step 6: Quality gates with Bitbucket Pipelines

Quality gates let you fail a Bitbucket Pipelines build based on whether the code meets your configured thresholds. This gives you pipeline-level enforcement in addition to PR status checks.

Setting up quality gate thresholds in Codacy

Before querying quality gates from your pipeline, configure the thresholds:

1. Open your repository in Codacy
2. Click Quality settings in the sidebar
3. Set thresholds for the metrics relevant to your team:

Querying quality gates from bitbucket-pipelines.yml

After coverage is uploaded and analysis is triggered, query the Codacy API to check the quality gate status:

- step:
    name: Check Codacy Quality Gate
    script:
      - |
        COMMIT_SHA=$BITBUCKET_COMMIT
        ORG="your-org"
        REPO="your-repo"
        PROVIDER="bb"
        MAX_ATTEMPTS=20
        SLEEP_SECONDS=15
        PASSED=false

        for i in $(seq 1 $MAX_ATTEMPTS); do
          RESPONSE=$(curl -s -w "n%{http_code}" 
            "https://app.codacy.com/api/v3/analysis/organizations/${PROVIDER}/${ORG}/repositories/${REPO}/commits/${COMMIT_SHA}/quality" 
            -H "api-token: $CODACY_ACCOUNT_TOKEN" 
            -H "Accept: application/json")

          HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
          BODY=$(echo "$RESPONSE" | head -n -1)

          if [ "$HTTP_CODE" = "200" ]; then
            IS_UP=$(echo "$BODY" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('data',{}).get('isUpToStandards','null'))")

            if [ "$IS_UP" = "True" ]; then
              echo "Codacy quality gate PASSED."
              PASSED=true
              break
            elif [ "$IS_UP" = "False" ]; then
              echo "Codacy quality gate FAILED. Check the Codacy dashboard for details."
              exit 1
            fi
          fi

          echo "Waiting for Codacy analysis (attempt $i of $MAX_ATTEMPTS)..."
          sleep $SLEEP_SECONDS
        done

        if [ "$PASSED" = "false" ]; then
          echo "WARNING: Quality gate check timed out. Proceeding."
        fi

The provider code for Bitbucket is bb. For GitHub it is gh and for GitLab it is gl. Replace your-org with your Bitbucket workspace slug and your-repo with the repository slug as they appear in your Bitbucket URL.

The polling loop waits up to 5 minutes (20 attempts x 15 seconds) for Codacy to complete analysis before timing out. Adjust these values based on your repository size and typical Codacy analysis duration.

Using Python to parse the API response

The shell-based JSON parsing above uses Python, which is available in most CI images. If your pipeline image does not have Python, you can use jq instead:

IS_UP=$(echo "$BODY" | jq -r '.data.isUpToStandards')

Or install jq if needed:

apt-get install -y jq

Step 7: Webhook setup and configuration

Webhooks are the mechanism that tells Codacy when to start analyzing your code. For most teams, the Codacy Bitbucket app configures webhooks automatically. This section covers manual webhook setup for cases where automatic configuration does not work, and how to verify your webhooks are functioning.

Verifying automatic webhook installation

After connecting your repository to Codacy, verify the webhook exists:

1. Go to your Bitbucket repository
2. Click Repository settings then Webhooks under Workflow
3. You should see a webhook with a URL pointing to app.codacy.com or webhooks.codacy.com
4. Check that the webhook triggers are set to at least Repository push and Pull request events

If the webhook is missing, you can try removing and re-adding your repository in Codacy to trigger automatic webhook re-installation.

Manual webhook configuration

If you need to configure webhooks manually – for example in a Bitbucket Data Center environment or when automatic installation fails:

1. Go to your Bitbucket repository settings and click Webhooks
2. Click Add webhook
3. Fill in the webhook details:
   • Title: Codacy
   • URL: Copy the webhook URL from your Codacy repository settings under Integrations
   • Status: Active
   • SSL/TLS: Verify SSL (keep enabled unless you have certificate issues)
4. Under Triggers, select:
   • Repository: Push
   • Pull Request: Created, Updated, Approved, Comment created
5. Click Save

After adding the webhook, trigger it by pushing a commit or creating a test PR. Check the webhook delivery history in Bitbucket to confirm Codacy received the payload and responded with a 200 status code.

Webhook delivery failures

If Codacy is not triggering on your pushes or PRs, check the webhook delivery history. Common causes of delivery failures include:

• Network restrictions – If your Bitbucket instance (Data Center) cannot reach Codacy’s servers, webhook deliveries will fail. Check firewall rules and ensure outbound HTTPS to Codacy’s domain is allowed.
• Incorrect webhook URL – Regenerate the webhook URL from Codacy’s settings and update the Bitbucket webhook accordingly.
• IP allowlisting – If Bitbucket Cloud’s webhook delivery IPs are blocked on your end, add Atlassian’s webhook IP ranges to your allowlist.

Step 8: Complete bitbucket-pipelines.yml example

Here is a complete, production-ready bitbucket-pipelines.yml that combines build, test, coverage upload, and quality gate checking for a Java project. Adapt the language-specific parts to match your stack.

image: maven:3.9-eclipse-temurin-17

definitions:
  caches:
    maven: ~/.m2/repository
  steps:
    - step: &build-and-test
        name: Build and Test
        caches:
          - maven
        script:
          - mvn clean test
        artifacts:
          - target/site/jacoco/**
          - target/surefire-reports/**

    - step: &upload-coverage
        name: Upload Coverage to Codacy
        script:
          - curl -Ls https://coverage.codacy.com/get.sh -o codacy-coverage-reporter.sh
          - bash codacy-coverage-reporter.sh report
              -r target/site/jacoco/jacoco.xml
              --project-token $CODACY_PROJECT_TOKEN
              --commit-uuid $BITBUCKET_COMMIT

    - step: &quality-gate
        name: Check Codacy Quality Gate
        script:
          - |
            COMMIT_SHA=$BITBUCKET_COMMIT
            ORG="your-workspace"
            REPO="your-repo"
            MAX_ATTEMPTS=20
            SLEEP_SECONDS=15
            PASSED=false

            for i in $(seq 1 $MAX_ATTEMPTS); do
              RESPONSE=$(curl -s -w "n%{http_code}" 
                "https://app.codacy.com/api/v3/analysis/organizations/bb/${ORG}/repositories/${REPO}/commits/${COMMIT_SHA}/quality" 
                -H "api-token: $CODACY_ACCOUNT_TOKEN" 
                -H "Accept: application/json")

              HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
              BODY=$(echo "$RESPONSE" | head -n -1)

              if [ "$HTTP_CODE" = "200" ]; then
                IS_UP=$(echo "$BODY" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('data',{}).get('isUpToStandards','null'))")

                if [ "$IS_UP" = "True" ]; then
                  echo "Codacy quality gate PASSED."
                  PASSED=true
                  break
                elif [ "$IS_UP" = "False" ]; then
                  echo "Codacy quality gate FAILED."
                  exit 1
                fi
              fi

              echo "Waiting for Codacy analysis (attempt $i of $MAX_ATTEMPTS)..."
              sleep $SLEEP_SECONDS
            done

            if [ "$PASSED" = "false" ]; then
              echo "Quality gate timed out. Check Codacy dashboard manually."
            fi

pipelines:
  default:
    - step: *build-and-test
    - step: *upload-coverage

  pull-requests:
    '**':
      - step: *build-and-test
      - step: *upload-coverage
      - step: *quality-gate

  branches:
    main:
      - step: *build-and-test
      - step: *upload-coverage
      - step: *quality-gate
    develop:
      - step: *build-and-test
      - step: *upload-coverage
      - step: *quality-gate

The YAML anchors (&build-and-test, *build-and-test) let you define pipeline steps once and reuse them across multiple pipeline configurations without duplication. The artifacts section in the build step ensures the JaCoCo coverage report file is available to the upload step even though they run as separate pipeline steps.

Codacy Bitbucket vs other CI integrations

Codacy’s Bitbucket integration compares favorably to its other CI integrations in terms of native support. The Bitbucket app is a first-class integration that provides automatic webhook setup, PR status checks, inline code comments, and dashboard integration out of the box.

For teams using GitHub, the experience is similar – see our Codacy GitHub integration guide for a side-by-side comparison. For GitLab users, check out Codacy GitLab integration.

The main difference between Bitbucket and GitHub/GitLab integrations is that Codacy’s GitHub App tends to get feature updates first, since GitHub represents the largest share of Codacy’s user base. That said, Bitbucket integration is mature and well-supported, and teams using Bitbucket Cloud should not experience meaningful feature gaps.

For Jenkins-based pipelines that supplement your Bitbucket Pipelines setup, our Codacy Jenkins guide covers that integration in detail.

Alternative: CodeAnt AI for Bitbucket teams

If you are evaluating code quality tools and want to compare Codacy against alternatives that also support Bitbucket, CodeAnt AI is worth a close look. Priced at $24-40 per user per month, CodeAnt AI offers AI-powered code review that goes beyond pattern matching to catch logic errors, design issues, and context-dependent problems that rule-based static analysis tools often miss.

CodeAnt AI supports Bitbucket Cloud and integrates with Bitbucket Pipelines for CI/CD-based analysis. The setup process is similar to Codacy – install the Bitbucket app, store an API token as a repository variable, and add a pipeline step to trigger analysis. Where CodeAnt AI differs is in the analysis engine itself: it uses large language models to review code in context, making its feedback more similar to what you would get from a senior developer code review than from a linter.

For teams that find Codacy’s rule-based approach produces too many false positives or misses the kinds of issues that come up in human code reviews, CodeAnt AI’s AI-first model is a compelling alternative. For a full comparison across tools in this space, our Codacy alternatives guide covers CodeAnt AI, SonarQube, DeepSource, Semgrep, and others.

Troubleshooting

Coverage not showing on Bitbucket PR

If coverage data is uploaded but not appearing on the Bitbucket PR:

• Check the pipeline logs – Look for errors in the coverage reporter output. Common errors include “project token not found” (wrong token), “commit not found” (SHA mismatch), and “report file not found” (wrong path).
• Verify the coverage file exists – Add ls -la target/site/jacoco/ before the reporter step to confirm the file was generated.
• Check the commit SHA – Ensure $BITBUCKET_COMMIT is the correct SHA. For PRs from forks, this may need adjustment.
• Wait longer – Codacy processes coverage data asynchronously. Coverage typically appears within 2-3 minutes of upload, but can take longer for large repositories.

Codacy status check not appearing on PR

If the Codacy status check is absent from your Bitbucket PR entirely:

• Verify the webhook – Check that the Codacy webhook exists in your repository settings and that recent deliveries succeeded (HTTP 200 response).
• Check the app permissions – Ensure the Codacy app still has access to your workspace. Token revocation or workspace permission changes can break this.
• Re-add the repository in Codacy – Sometimes removing and re-adding the repository in Codacy reinstalls the webhook and fixes the connection.

Quality gate API returning 404

A 404 from the Codacy API quality gate endpoint usually means:

• The organization slug or repository slug in your API URL does not match exactly what Codacy expects. Use your Bitbucket workspace slug (the URL identifier, not the display name) and the exact repository slug from your Bitbucket URL.
• The commit has not been analyzed yet. Increase the polling wait time.
• The account API token does not have access to the repository. Verify the token is from an account that has access to the repository in Codacy.

Pipeline running on PRs from forks

Bitbucket Pipelines has specific behavior for PRs from forked repositories regarding repository variables. By default, repository variables are not available to fork pipelines for security reasons. If your contributors submit PRs from forks, the $CODACY_PROJECT_TOKEN variable will be unavailable in those pipelines.

To address this, you can either allow secured variables to be used in fork pipelines (check your Bitbucket pipeline settings) or accept that fork PRs will not have coverage uploaded – Codacy will still perform static analysis triggered by the webhook.

Summary

Integrating Codacy with Bitbucket is a two-part process: installing the Codacy Bitbucket app for automatic webhook-driven static analysis on PRs, and configuring bitbucket-pipelines.yml for coverage uploading and optional quality gate enforcement.

The app installation handles the analysis side automatically – once connected, every PR in your repository gets static analysis, SAST scanning, and inline code comments from Codacy without any pipeline configuration. The pipeline configuration layer adds coverage tracking and the ability to fail builds based on quality thresholds, rounding out the integration into a comprehensive automated quality system.

For Bitbucket Data Center users, Codacy Self-Hosted is the path forward – the same capabilities in an on-premise deployment that keeps your code within your own infrastructure.

If Codacy does not fit your needs after the evaluation, CodeAnt AI ($24-40/user/month) offers a strong AI-powered alternative with Bitbucket support, and our Codacy alternatives guide covers the full landscape of options. For a deeper look at Codacy itself, visit our Codacy tool page and our Codacy review for an honest assessment of its strengths and limitations.

Further Reading

• Best AI Code Review Tools in 2026 – Expert Picks
• Best AI Code Review Tools for Pull Requests in 2026
• 13 Best Code Quality Tools in 2026 – Platforms, Linters, and Metrics
• I Reviewed 32 SAST Tools – Here Are the Ones Actually Worth Using (2026)
• Codacy Free vs Pro: Which Plan Do You Need in 2026?

Frequently Asked Questions

How do I connect Codacy to Bitbucket?

Install the Codacy app from the Bitbucket Marketplace under Settings then Find new apps, then authorize Codacy to access your workspace. Once authorized, go to app.codacy.com, sign in with your Bitbucket account, and add the repositories you want to analyze. Codacy will start analyzing pull requests automatically via webhooks that the app installs for you.

Does Codacy work with Bitbucket Pipelines?

Yes. Codacy integrates with Bitbucket Pipelines for coverage uploading and quality gate enforcement. You add pipeline steps to your bitbucket-pipelines.yml that download the Codacy Coverage Reporter, run it after your tests, and optionally query the Codacy API to check whether the commit passes your configured quality gate thresholds.

Does Codacy support Bitbucket Server (Data Center)?

Codacy supports Bitbucket Data Center (formerly Bitbucket Server) through Codacy Self-Hosted, the on-premise version of the platform. The cloud version at app.codacy.com supports Bitbucket Cloud only. Self-Hosted requires a dedicated deployment on your own infrastructure and is available on Enterprise plans.

How do I upload code coverage from Bitbucket Pipelines to Codacy?

Add a pipeline step that downloads the Codacy Coverage Reporter shell script with curl, then runs it pointing at your coverage report file and authenticated with your CODACY_PROJECT_TOKEN repository variable. Supported formats include LCOV, Cobertura XML, JaCoCo XML, Clover, and OpenCover. Store the project token as a repository variable in Bitbucket so it is not hardcoded in your YAML.

How do I set up Codacy quality gates with Bitbucket Pipelines?

Configure quality gate thresholds in the Codacy dashboard under Quality settings for your repository. In your bitbucket-pipelines.yml, after uploading coverage, query the Codacy API with your account token to check whether the commit’s isUpToStandards field is true or false. If it is false, exit the pipeline step with a non-zero code to fail the build. Use a polling loop to wait for Codacy to finish analysis before checking the gate.

What is the Codacy project API token and where do I find it?

The Codacy project API token authenticates the Coverage Reporter when uploading coverage data for a specific repository. Find it by going to your repository in Codacy, clicking Settings, then selecting the Coverage or Integrations section. Copy the project token and store it as a Bitbucket repository variable named CODACY_PROJECT_TOKEN so your pipeline can access it securely.

How do I get Codacy to comment on Bitbucket pull requests?

Codacy comments on Bitbucket pull requests automatically once you install the Codacy Bitbucket app and connect your repositories. No additional pipeline configuration is needed for PR comments – they are driven by Codacy’s webhook integration, which triggers static analysis whenever a PR is opened or updated. You can configure whether Codacy posts inline comments, a summary comment, or both in your Codacy repository settings.

How do I set up Codacy webhooks for Bitbucket?

Webhooks are configured automatically when you install the Codacy Bitbucket app. If you need to set up webhooks manually – for example in a self-hosted scenario – go to your Bitbucket repository settings, select Webhooks under Workflow, and add a webhook pointing to the Codacy webhook URL with push and pull request events enabled. The Codacy webhook URL is available in your repository’s Codacy settings under Integrations.

Why is Codacy not showing coverage on my Bitbucket PR?

The most common causes are a missing or incorrect CODACY_PROJECT_TOKEN, a coverage report path that does not match the actual generated file, or a commit SHA mismatch between what Pipelines reports and what Codacy expects. Also check that you are running the coverage upload step after the test step and that the test step actually generated a coverage file. Add an ls step in your pipeline to verify the file exists before running the reporter.

Can I use Codacy with Bitbucket branch restrictions?

Yes. You can require the Codacy status check to pass before merging a pull request by enabling branch restrictions in Bitbucket. Go to your repository settings, select Branch restrictions under Workflow, add a restriction for your target branch (e.g., main), and set the merge checks to require the Codacy status to be successful. This prevents any PR from being merged unless Codacy analysis passes.

Is there a Codacy alternative that supports Bitbucket?

CodeAnt AI ($24-40 per user per month) is a strong alternative that supports Bitbucket and provides AI-powered code review. SonarQube Cloud also integrates with Bitbucket Pipelines. DeepSource and Semgrep are additional options worth evaluating if you need different capabilities such as deep security scanning or a more flexible rule engine.

How long does Codacy analysis take on a Bitbucket PR?

Codacy typically completes analysis within 1 to 5 minutes for most repositories. Very large codebases with many files or slow analysis tools can take up to 15 minutes. The analysis runs in Codacy’s cloud infrastructure triggered by the Bitbucket webhook, so it does not affect your Bitbucket Pipelines build time directly. Coverage upload time from your pipeline is typically under 30 seconds.

Originally published at aicodereview.cc