In the first post of this series we set the stage for the Backyard Quarry project.

Once you decide every rock in the yard should have a record, the next question appears immediately:

What exactly should we record?

It’s a deceptively simple question. And like most simple questions in engineering, it opens the door to a surprisingly large number of decisions.

The First Attempt

The most straightforward approach is to keep things minimal.

Each rock gets an identifier and a few attributes.

Something like:

rock_id
size
price

At first glance, this seems reasonable.

We can identify the rock. We can describe it in some vague way. We can assign a price.

But this model breaks down almost immediately.

“Size” is ambiguous. Is that weight? Volume? Longest dimension? All of the above?

Two rocks of the same “size” might behave very differently when you try to move them.

And more importantly, this model doesn’t capture anything about the rock beyond its most basic characteristics.

It’s enough to sell a rock.

It’s not enough to understand one.

Expanding the Model

To make the system more useful, we need to be more explicit.

A slightly richer model might look like this:

rock_id
weight_lb
length_cm
width_cm
height_cm
color
rock_type
location_found
status

Now we’re getting somewhere.

We can distinguish between rocks that look similar but behave differently.

We can track where each rock came from.

We can start to answer questions like:

• How many rocks do we have in a given area?
• What size distribution does the dataset have?
• Which rocks are suitable for different uses?

This is the point where the rock pile starts to feel less like a random collection and more like a dataset.

The Object Data Model

At a higher level, what we’re really doing is separating a physical object into a few distinct components.

A simple model for representing a physical object as structured data and associated assets.

Each rock has:

• metadata describing its properties
• images representing its appearance
• optionally, a 3D model capturing its shape

This separation turns out to be important.

Metadata is small, structured, and easy to query.

Images and 3D models are large, unstructured assets that need to be stored and referenced.

Keeping those concerns separate is a pattern that shows up in many real-world systems.

The Identity Problem

Once the schema starts to take shape, another question appears.

How do we uniquely identify a rock?

There are a few options:

• sequential IDs (rock_001, rock_002)
• UUIDs
• physical tags attached to rocks
• some form of image-based identification

For a small backyard dataset, almost anything works.

But the choice matters more as the system grows.

Sequential IDs are easy to read but require coordination.

UUIDs are globally unique but harder to work with manually.

Physical tags introduce a connection between the digital record and the real-world object.

Even in a simple system, identity becomes a design decision.

Classification: The Quarry Taxonomy

At some point, it becomes useful to introduce categories.

Originally this was just a convenience.

But like many things in this project, it quickly became something more formal.

A simple classification system might look like this:

Class 0 — Pebble
Class 1 — Hand Sample
Class 2 — Landscaping Rock
Class 3 — Wheelbarrow Class
Class 4 — Engine Block Class
Class 5 — Heavy Machinery Class

Each class roughly corresponds to how the rock is handled.

This turns out to be surprisingly useful.

Instead of asking for exact dimensions, we can filter by class:

• “Show me all Pebble Class rocks”
• “Exclude anything above Wheelbarrow Class”

In other words, we’ve introduced a derived attribute — something computed from the underlying data rather than stored arbitrarily.

This is exactly how classification systems evolve in real datasets.

Thinking About Lifecycle

Rocks don’t change much physically, but their role in the system does.

A rock might move through states like:

collected
cataloged
listed_for_sale
sold

Tracking this lifecycle introduces another dimension to the data.

Now we’re not just modeling objects.

We’re modeling *objects over *.

Even in a simple system, state and transitions begin to matter.

The Tradeoffs

At this point, the schema is already doing useful work.

But it’s also clear that there’s no perfect design.

Every decision involves tradeoffs:

• more fields vs simplicity
• normalized structure vs ease of use
• flexibility vs consistency

The goal isn’t to design the perfect schema on the first try.

The goal is to design something that can evolve.

Because as soon as we start capturing real data, we’ll learn what we got wrong.

What Comes Next

With a basic schema in place, the next challenge becomes obvious.

We know what we want to store.

Now we need to figure out how to capture it.

In the next post, we’ll look at how to turn a physical rock into images, measurements, and potentially a 3D model — and how that process introduces its own set of constraints.

Because it turns out that collecting data from the physical world is rarely as clean as designing a schema on paper.

The post The Backyard Quarry, Part 2: Designing a Schema for Physical Objects appeared first on Blog of Ken W. Alger.

What is Codacy and why use it?

Codacy is an automated code quality and security platform that analyzes your code for bugs, vulnerabilities, code smells, duplication, and complexity across 49 programming languages. It integrates directly with GitHub, GitLab, and Bitbucket to scan every pull request and provide actionable feedback before code reaches your main branch.

Instead of assembling a stack of separate tools for linting, SAST, SCA, secrets detection, and coverage tracking, Codacy bundles all of these into a single platform with a unified dashboard. For teams that want comprehensive code quality enforcement without managing multiple tools and CI configurations, this consolidation is the primary appeal.

This guide walks through every step of setting up Codacy from scratch – creating your account, connecting your repositories, configuring code patterns, enabling PR analysis, setting quality gates, uploading code coverage, writing a .codacy.yml configuration file, managing your team, and troubleshooting common issues. By the end, you will have a fully configured Codacy setup that scans every pull request automatically and enforces your team’s quality standards.

Prerequisites

Before you begin the setup process, make sure you have the following ready:

• A GitHub, GitLab, or Bitbucket account with admin access to the repositories you want to analyze
• At least one repository with code in a supported language (Codacy supports 49 languages including JavaScript, TypeScript, Python, Java, Go, Ruby, PHP, C#, Kotlin, and Swift)
• If you plan to upload code coverage, a CI pipeline (GitHub Actions, GitLab CI, CircleCI, Jenkins, or similar) that runs your test suite

The setup process itself takes under ten minutes for a single repository. Configuring code patterns, quality gates, and coverage reporting adds another 20-30 minutes depending on how much customization you need.

Step 1: Create your Codacy account

Navigate to app.codacy.com and click the sign-up button. Codacy supports sign-up through three Git providers:

• GitHub – recommended if your repositories are on GitHub
• GitLab – for GitLab cloud or self-managed instances
• Bitbucket – for Bitbucket Cloud or Data Center

Select your Git provider and authorize Codacy to access your account. For GitHub, this involves two authorization steps:

1. OAuth authorization – grants Codacy permission to read your profile and email address
2. GitHub App installation – grants Codacy access to your repositories, webhooks, and pull request status checks

When installing the GitHub App, you can choose to grant access to all repositories in your organization or select specific repositories. If you are evaluating Codacy, start with one or two repositories rather than your entire organization.

After authorization, Codacy redirects you to your dashboard. If you signed up with a GitHub organization, Codacy automatically creates a Codacy organization that mirrors your GitHub org structure.

Step 2: Connect and add your first repository

From your Codacy dashboard, click the “Add repository” button in the top navigation. Codacy displays a list of all repositories it has access to, filtered by your Git provider organization.

Select the repository you want to add and click “Add.” Codacy immediately begins the initial analysis, which involves:

1. Cloning the repository (Codacy accesses the code temporarily for analysis and does not store your source code permanently)
2. Detecting the programming languages present in the repository
3. Running the default analysis tools for each detected language
4. Generating an initial quality report

The first analysis typically takes between 2 and 15 minutes depending on the repository size. You can monitor the progress from the repository dashboard page.

Once the initial analysis completes, Codacy displays your repository’s quality metrics:

• Grade – an overall letter grade (A through F) based on the aggregated quality metrics
• Issues – the total number of issues found, categorized by severity (error, warning, info) and type (security, error-prone, performance, code style, compatibility, unused code)
• Complexity – file-level and function-level complexity scores
• Duplication – the percentage of duplicated code blocks
• Coverage – code coverage percentage (requires separate setup, covered in Step 7)

Step 3: Understand the Codacy dashboard

The repository dashboard is your central hub for monitoring code quality over time. It is worth spending a few minutes understanding its layout before diving into configuration.

The dashboard displays several key panels:

Quality evolution chart shows how your quality grade and issue count have changed over the past days, weeks, or months. This is useful for tracking whether your team’s code quality is improving or degrading over time.

Open issues panel lists all currently open issues grouped by category. You can filter by severity, category, language, and analysis tool to focus on what matters most. Each issue links to the specific file and line number where it was found.

Pull request analysis panel shows recent pull requests with their quality status – whether they passed or failed your quality gates, how many new issues were introduced, and what the coverage delta was.

File quality panel ranks your files by the number of issues, complexity, and coverage. This is useful for identifying the most problematic files in your codebase and prioritizing cleanup work.

Step 4: Configure code patterns

Code patterns are the rules that Codacy uses to analyze your code. Each supported language has one or more analysis tools, and each tool has a set of rules (called patterns) that can be individually enabled or disabled.

To configure code patterns:

1. Navigate to your repository in Codacy
2. Click Code patterns in the left sidebar
3. You will see a list of analysis tools grouped by language

For a JavaScript/TypeScript repository, you might see tools like ESLint, JSHint, and Codacy’s own analyzers. For Python, you might see Pylint, Bandit, Prospector, and Ruff. For Java, you might see PMD, SpotBugs, and Checkstyle.

Enabling and disabling tools

Each analysis tool has a toggle switch. If you already use a specific linter locally (for example, ESLint with a custom configuration), you may want to disable Codacy’s built-in ESLint to avoid conflicts. Alternatively, you can configure Codacy to use your repository’s existing ESLint configuration file.

Configuring individual patterns

Click on any tool to expand its rule list. Each rule shows:

• Rule name and description – what the rule checks for
• Severity – error, warning, or info
• Category – security, error-prone, performance, code style, compatibility, or unused code
• Toggle – enable or disable the rule

For a new setup, the recommended approach is to start with the default patterns enabled and then tune them based on your first analysis results. If the initial analysis produces too many low-value findings, disable the noisiest patterns first (typically code style patterns for legacy codebases).

Using your existing linter configuration

If your repository already has a linter configuration file (.eslintrc.js, pylintrc, .rubocop.yml, etc.), you can configure Codacy to use it instead of Codacy’s default patterns:

1. Go to Code patterns and select the relevant tool
2. Enable the “Use the configuration file in my repository” toggle
3. Codacy will use your existing configuration file for that tool

This is particularly useful for teams that have already invested time in customizing their linter rules and do not want to duplicate that work in the Codacy UI.

Step 5: Setup PR analysis

Pull request analysis is one of Codacy’s most valuable features because it catches issues before they reach your main branch. When configured, Codacy automatically analyzes every pull request and reports:

• New issues introduced by the PR
• Issues that were fixed by the PR
• Coverage changes (increase or decrease)
• Complexity changes
• Whether the PR passes or fails your quality gates

How PR analysis works

When you open a pull request on a connected repository, Codacy’s GitHub App receives a webhook notification. It then:

1. Analyzes only the files changed in the PR (not the entire repository)
2. Compares the results against the target branch to identify new versus existing issues
3. Posts a status check on the PR (pass or fail based on quality gates)
4. Optionally posts a summary comment on the PR with detailed findings

PR analysis is enabled by default when you connect a repository through the GitHub App. To verify it is working, open a pull request on your connected repository and check for the Codacy status check.

Configuring PR status checks

To customize what Codacy reports on your pull requests:

1. Navigate to your repository in Codacy
2. Click Settings in the left sidebar
3. Scroll to the Pull Requests section

Here you can configure:

• Status check behavior – whether to post a single combined status check or separate checks for issues, coverage, and duplication
• PR comment – whether to post a summary comment on the PR, and what information to include
• Annotations – whether to add inline annotations on specific lines in the PR diff

Making Codacy status checks required

To prevent pull requests from being merged when they fail Codacy’s quality gates, configure branch protection rules in your Git provider:

For GitHub:

1. Go to your repository settings on GitHub
2. Click Branches in the sidebar
3. Click Add branch protection rule (or edit an existing rule for your main branch)
4. Under “Require status checks to pass before merging,” search for and select the Codacy status checks
5. Save the rule

Branch name pattern: main

[x] Require status checks to pass before merging
    Required status checks:
      - Codacy Static Code Analysis

For GitLab:

1. Go to your project settings
2. Navigate to Merge Requests
3. Under “Merge checks,” enable “Pipelines must succeed”
4. Codacy reports its results as a pipeline job via the GitLab integration

Step 6: Configure quality gates

Quality gates define the minimum quality standards that your code must meet. They apply both at the repository level (tracking overall quality trends) and at the pull request level (blocking merges that degrade quality).

To configure quality gates:

1. Navigate to your repository in Codacy
2. Click Quality settings in the left sidebar
3. Set thresholds for each metric

Available quality gate metrics

Setting practical thresholds

The key to effective quality gates is starting with thresholds your team can actually meet. If your current code coverage is 40%, setting a quality gate at 80% coverage will cause every PR to fail and your team will quickly disable the gate.

A practical rollout strategy:

1. Week 1-2: Set quality gates to observe mode – track but do not block. Look at how your PRs perform against the default thresholds
2. Week 3-4: Enable blocking quality gates with achievable thresholds – zero new critical issues and coverage must not decrease
3. Month 2+: Gradually tighten thresholds as your team adapts – increase minimum coverage, reduce allowed new issues

Repository-level quality gates

In addition to PR-level gates, Codacy tracks quality at the repository level. The repository quality gate evaluates the overall codebase against thresholds you set for total issues, overall coverage, and overall duplication. This is useful for tracking long-term quality trends and setting goals for codebase cleanup.

Step 7: Setup code coverage with the Coverage Reporter

Code coverage tracking in Codacy requires uploading coverage reports from your CI pipeline. Codacy does not run your tests – it processes coverage reports generated by your existing test suite and displays the results alongside other quality metrics.

Step 7a: Generate a coverage report

First, make sure your test suite generates a coverage report in one of the supported formats:

• LCOV – common for JavaScript/TypeScript (Istanbul, c8, nyc)
• Cobertura XML – common for Python (pytest-cov, coverage.py) and Java (JaCoCo with Cobertura output)
• JaCoCo – standard for Java/Kotlin
• Clover – used by PHP (PHPUnit) and some Java projects
• OpenCover – common for .NET projects

For example, in a JavaScript project using Vitest:

{
  "test": {
    "coverage": {
      "provider": "v8",
      "reporter": ["lcov", "text"]
    }
  }
}

Or in a Python project using pytest:

pytest --cov=src --cov-report=xml:coverage.xml

Step 7b: Get your project API token

1. Navigate to your repository in Codacy
2. Click Settings in the left sidebar
3. Scroll to the Coverage section (or look under Integrations)
4. Copy the Project API Token – you will need this to authenticate the upload

Store this token as a secret in your CI environment:

• GitHub Actions: Add it as a repository secret named CODACY_PROJECT_TOKEN
• GitLab CI: Add it as a CI/CD variable named CODACY_PROJECT_TOKEN
• CircleCI: Add it as an environment variable

Step 7c: Add the Coverage Reporter to your CI pipeline

For GitHub Actions:

name: Tests and Coverage

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci

      - name: Run tests with coverage
        run: npm test -- --coverage

      - name: Upload coverage to Codacy
        uses: codacy/codacy-coverage-reporter-action@v1
        with:
          project-token: ${{ secrets.CODACY_PROJECT_TOKEN }}
          coverage-reports: coverage/lcov.info

For GitLab CI:

test:
  stage: test
  image: node:20
  script:
    - npm ci
    - npm test -- --coverage
  after_script:
    - bash <(curl -Ls https://coverage.codacy.com/get.sh) report
        -r coverage/lcov.info
        --project-token $CODACY_PROJECT_TOKEN
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml

For Python projects with GitHub Actions:

name: Tests and Coverage

on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: pip install -r requirements.txt pytest pytest-cov

      - name: Run tests with coverage
        run: pytest --cov=src --cov-report=xml:coverage.xml

      - name: Upload coverage to Codacy
        uses: codacy/codacy-coverage-reporter-action@v1
        with:
          project-token: ${{ secrets.CODACY_PROJECT_TOKEN }}
          coverage-reports: coverage.xml

Using the standalone CLI reporter:

If you prefer not to use the GitHub Action, you can use the Coverage Reporter CLI directly:

# Download the reporter
curl -Ls https://coverage.codacy.com/get.sh -o codacy-coverage-reporter.sh

# Upload the report
bash codacy-coverage-reporter.sh report 
  -r coverage/lcov.info 
  --project-token $CODACY_PROJECT_TOKEN

Uploading multiple coverage reports

If your project has multiple test suites or generates coverage reports for different components (common in monorepos), you can upload them as partial reports and finalize them:

# Upload first report as partial
bash <(curl -Ls https://coverage.codacy.com/get.sh) report 
  -r coverage/unit.lcov.info 
  --partial 
  --project-token $CODACY_PROJECT_TOKEN

# Upload second report as partial
bash <(curl -Ls https://coverage.codacy.com/get.sh) report 
  -r coverage/integration.lcov.info 
  --partial 
  --project-token $CODACY_PROJECT_TOKEN

# Finalize the coverage
bash <(curl -Ls https://coverage.codacy.com/get.sh) final 
  --project-token $CODACY_PROJECT_TOKEN

Once coverage is uploaded, Codacy displays coverage metrics on your repository dashboard and includes coverage changes in every PR analysis.

Step 8: Create a .codacy.yml configuration file

The .codacy.yml file gives you version-controlled configuration for your Codacy analysis. Instead of configuring everything through the Codacy UI, you can define your analysis settings in a file that lives in your repository root – making the configuration reviewable, consistent, and part of your standard code review process.

Basic .codacy.yml structure

Create a file named .codacy.yml in your repository root:

---
engines:
  eslint:
    enabled: true
    config: .eslintrc.js
  stylelint:
    enabled: true
  csslint:
    enabled: false
  duplication:
    enabled: true
    config:
      minimum_tokens: 50
  metrics:
    enabled: true

languages:
  javascript:
    extensions:
      - .js
      - .jsx
      - .mjs
  typescript:
    extensions:
      - .ts
      - .tsx

exclude_paths:
  - "node_modules/**"
  - "dist/**"
  - "build/**"
  - "coverage/**"
  - "**/*.min.js"
  - "**/*.bundle.js"
  - "vendor/**"
  - "public/assets/**"
  - ".next/**"

Enabling tools with custom configuration files

If your repository already has linter configuration files, reference them in .codacy.yml:

---
engines:
  eslint:
    enabled: true
    config: .eslintrc.json
  pylint:
    enabled: true
    config: .pylintrc
  rubocop:
    enabled: true
    config: .rubocop.yml
  checkstyle:
    enabled: true
    config: checkstyle.xml

When you specify a config path, Codacy uses your repository’s linter configuration instead of its default patterns. This ensures that Codacy’s analysis matches what developers see when running linters locally.

Complete .codacy.yml example for a full-stack project

Here is a comprehensive configuration for a typical full-stack project with JavaScript, Python, and Docker:

---
engines:
  eslint:
    enabled: true
    config: .eslintrc.json
  pylint:
    enabled: true
    config: .pylintrc
  bandit:
    enabled: true
  prospector:
    enabled: false
  duplication:
    enabled: true
    config:
      minimum_tokens: 70
  metrics:
    enabled: true
  hadolint:
    enabled: true
  shellcheck:
    enabled: true
  markdownlint:
    enabled: false

languages:
  javascript:
    extensions:
      - .js
      - .jsx
      - .mjs
  typescript:
    extensions:
      - .ts
      - .tsx
  python:
    extensions:
      - .py

exclude_paths:
  - "node_modules/**"
  - "dist/**"
  - "build/**"
  - "coverage/**"
  - "**/*.min.js"
  - "**/*.bundle.js"
  - "**/*.generated.*"
  - "vendor/**"
  - "migrations/**"
  - "static/vendor/**"
  - "tests/fixtures/**"
  - "**/__snapshots__/**"
  - ".github/**"
  - "docs/**"

When to use .codacy.yml vs. the UI

Use .codacy.yml when:

• You want configuration to be version-controlled and reviewable in PRs
• Multiple team members need to adjust analysis settings
• You have multiple repositories and want consistent configuration
• You want to reference existing linter configuration files

Use the Codacy UI when:

• You are evaluating Codacy and experimenting with different settings
• You need to quickly toggle rules without committing code
• You want to use Codacy’s visual rule browser to explore available patterns

Note that .codacy.yml settings override UI settings when both are present. If you define an engine in .codacy.yml, the UI configuration for that engine is ignored.

Step 9: Team management and permissions

Managing team access in Codacy follows your Git provider’s organization structure. When you connect an organization from GitHub, GitLab, or Bitbucket, Codacy mirrors the membership automatically.

How team syncing works

Codacy pulls team membership from your Git provider. When a developer joins your GitHub organization and has access to connected repositories, they automatically appear in Codacy. When someone leaves the organization, their access is revoked.

You do not need to manually invite every team member. However, you can invite members directly from Codacy if they have not yet logged in:

1. Go to your Organization settings in Codacy
2. Click People in the sidebar
3. Click Add people and enter their email address or Git provider username

Role-based access control

Codacy provides three permission levels:

To change a team member’s role:

1. Go to Organization settings and click People
2. Find the member in the list
3. Click the role dropdown and select the new role

Managing repository access

By default, Codacy syncs repository access from your Git provider. If a developer has read access to a repository on GitHub, they can view that repository’s analysis in Codacy. If they have write access, they can configure analysis settings (depending on their Codacy role).

You can also restrict which repositories are visible in Codacy by adjusting the GitHub App permissions:

1. Go to your GitHub organization settings
2. Click GitHub Apps in the sidebar
3. Click Configure next to the Codacy app
4. Under “Repository access,” select specific repositories instead of “All repositories”

Step 10: Ignoring files and directories

Not every file in your repository needs analysis. Generated code, vendored dependencies, build outputs, test fixtures, and third-party assets will produce noise that clutters your dashboard and obscures real issues.

Method 1: Using the Codacy UI

1. Navigate to your repository in Codacy
2. Click Settings in the left sidebar
3. Click Ignored files
4. Add glob patterns for files and directories to exclude

Common patterns to add:

**/node_modules/**
**/vendor/**
**/dist/**
**/build/**
**/.next/**
**/coverage/**
**/*.min.js
**/*.min.css
**/*.bundle.js
**/*.generated.*
**/migrations/**
**/fixtures/**
**/__snapshots__/**
**/*.lock
**/package-lock.json
**/yarn.lock

Method 2: Using .codacy.yml

Add an exclude_paths section to your .codacy.yml file (as shown in Step 8). This method is preferred because the exclusions are version-controlled.

Method 3: Tool-specific ignores

Some analysis tools respect their own ignore files. For example:

• ESLint reads .eslintignore
• Pylint reads ignore patterns from .pylintrc
• Bandit reads .bandit configuration

If you configure Codacy to use your repository’s linter configuration files, these tool-specific ignore patterns are respected automatically.

Step 11: Advanced configuration

Setting up Codacy with GitHub Actions as a standalone check

While Codacy’s GitHub App handles most analysis automatically, you can also run the Codacy CLI in your own CI pipeline for more control:

name: Codacy Analysis

on:
  pull_request:
    branches: [main]

jobs:
  codacy-analysis:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Codacy Analysis CLI
        uses: codacy/codacy-analysis-cli-action@master
        with:
          project-token: ${{ secrets.CODACY_PROJECT_TOKEN }}
          upload: true
          max-allowed-issues: 0

This approach is useful when you want Codacy analysis to run as part of your existing CI pipeline rather than as a separate webhook-triggered process.

Configuring the Codacy AI Reviewer

Codacy’s AI Reviewer uses large language models to provide contextual feedback on pull requests beyond what static analysis rules can catch. To configure it:

1. Navigate to your repository in Codacy
2. Click Settings in the left sidebar
3. Look for the AI Reviewer or AI features section
4. Enable the AI Reviewer toggle

The AI Reviewer posts additional comments on your PRs that cover logic issues, potential bugs, and improvement suggestions that static rules would not catch. Note that the AI Reviewer is available on paid plans (Team and Business).

Configuring SAST and secrets detection

Codacy includes built-in SAST (Static Application Security Testing) and secrets detection:

SAST scanning is enabled by default and uses security-focused rules from tools like Bandit (Python), SpotBugs with FindSecBugs (Java), and Codacy’s own security analyzers. Security issues appear in the Issues panel with a “Security” category tag.

Secrets detection scans for hardcoded credentials, API keys, and tokens. It is enabled at the organization level:

1. Go to Organization settings
2. Click Security or Integrations
3. Enable Secrets detection

When Codacy detects a potential secret in a pull request, it flags it as a critical security issue and blocks the PR if your quality gates are configured to block on critical issues.

Troubleshooting common issues

Even with a straightforward setup, you may encounter issues. Here are the most common problems and their solutions.

Codacy is not analyzing my pull requests

Check the GitHub App permissions. Go to your GitHub organization settings, click “GitHub Apps,” and verify that the Codacy app has access to the repository in question. If you recently changed the app’s repository access, Codacy may need a webhook re-delivery.

Check the repository status. In Codacy, navigate to your repository and look at the status indicator. If analysis is paused or errored, click into the status for details. Common causes include rate limiting (too many concurrent analyses) or a misconfigured default branch.

Verify webhook delivery. Go to your GitHub repository settings, click “Webhooks,” find the Codacy webhook, and check the “Recent Deliveries” tab. Look for failed deliveries (non-200 status codes) and redeliver them.

Coverage is not showing up

Verify the upload succeeded. Check your CI pipeline logs for the Codacy Coverage Reporter output. A successful upload prints a confirmation message with the commit SHA. If the upload fails, the most common causes are an incorrect project token or a malformed coverage report.

Check the commit SHA. Codacy matches coverage reports to specific commits. If your CI pipeline runs on a merge commit (common with GitHub Actions pull_request events), the SHA may not match the PR head. Use the --commit-uuid flag to specify the correct SHA:

bash <(curl -Ls https://coverage.codacy.com/get.sh) report 
  -r coverage/lcov.info 
  --commit-uuid ${{ github.event.pull_request.head.sha }} 
  --project-token $CODACY_PROJECT_TOKEN

Check the coverage report format. Codacy supports LCOV, Cobertura, JaCoCo, Clover, and OpenCover. If your report is in a non-standard format or is malformed, the upload may succeed but Codacy will not process it. Validate your coverage report locally before uploading.

Too many false positives

Disable noisy tools. If a specific analysis tool produces mostly irrelevant findings for your codebase, disable it in Code patterns. You can always re-enable it later after addressing higher-priority issues.

Use your own configuration files. Enable the “Use configuration file in repository” option for tools that support it. Your team’s existing linter configuration reflects patterns that have already been tuned for your codebase.

Exclude generated and vendored code. Files that are not authored by your team (generated code, vendored dependencies, migration files) should be excluded from analysis. See Step 10 for exclusion methods.

Start with high-severity rules only. In Code patterns, sort rules by severity and disable info-level and some warning-level rules initially. Focus on error-level rules that catch actual bugs and security vulnerabilities.

Analysis is slow

Check your repository size. Codacy’s initial analysis processes your entire repository, which takes longer for large codebases. Subsequent PR analyses only process changed files and should be significantly faster.

Reduce the number of enabled tools. Each analysis tool adds processing time. If you have ten tools enabled but only use three languages, disable the tools for languages not present in your repository.

Exclude large directories. Build output directories, vendored dependencies, and asset directories add files to the analysis queue without providing value. Exclude them using .codacy.yml or the Codacy UI.

Quality gate is too strict or too lenient

Review the gate thresholds. Navigate to Quality settings and check each threshold. If every PR is failing, your thresholds may be unrealistic for the current state of your codebase. If no PR ever fails, your thresholds are too lenient.

Use the “new code” focus. Configure quality gates to evaluate only new code introduced in the PR rather than the entire repository. This prevents legacy code issues from blocking new work and lets your team maintain quality standards going forward without requiring a full codebase cleanup first.

Best practices for ongoing Codacy usage

After the initial setup, maintaining your Codacy configuration requires periodic attention to keep it effective.

Review new issues weekly. Assign a rotating team member to triage new Codacy findings each week. Dismiss false positives with a reason, assign real issues to the appropriate developer, and adjust patterns when a rule consistently produces unhelpful feedback.

Update quality gate thresholds quarterly. As your codebase improves, tighten the thresholds to maintain pressure for quality improvement. If coverage started at 40% when you onboarded Codacy and has risen to 55%, update the minimum coverage threshold to 50% so it continues to serve as a meaningful gate.

Keep your .codacy.yml in sync with your linter configs. When you update your ESLint configuration locally, make sure Codacy is set to use the repository’s configuration file rather than its own copy. This prevents drift between what developers see locally and what Codacy reports on PRs.

Use Codacy’s organization-level settings for consistency. If you have multiple repositories, configure shared settings (default quality gates, default tool configurations, default exclusion patterns) at the organization level. Individual repositories can override these defaults when needed, but starting from a shared baseline keeps things consistent.

Monitor the Codacy status page. Codacy occasionally experiences service disruptions that affect analysis processing times. Check status.codacy.com if analyses are taking unusually long or not completing.

Summary

Setting up Codacy involves ten main steps: creating your account, connecting a repository, understanding the dashboard, configuring code patterns, enabling PR analysis, setting quality gates, uploading code coverage, creating a .codacy.yml configuration file, managing team permissions, and configuring file exclusions. The initial setup takes under 30 minutes for a single repository, and the ongoing maintenance is minimal once you have tuned the analysis to match your team’s standards.

Codacy’s biggest advantage is consolidation – it replaces the need for separate tools for linting, SAST, SCA, secrets detection, coverage tracking, and duplication analysis. For teams that want a single dashboard for code quality without assembling and maintaining a multi-tool stack, Codacy provides a compelling solution at a reasonable price point.

For more details on Codacy’s pricing tiers and how it compares to alternatives, see our Codacy pricing breakdown and Codacy alternatives guide.

Frequently Asked Questions

How do I setup Codacy for my GitHub repository?

Sign up at app.codacy.com using your GitHub account, authorize the Codacy GitHub App, select the repositories you want to analyze, and Codacy will automatically run its first analysis. The entire process takes under five minutes. Once connected, Codacy scans every new pull request and commits to your default branch automatically.

Is Codacy free to use?

Yes, Codacy offers a free Developer plan that includes the AI Guardrails IDE extension for VS Code, IntelliJ, Cursor, and Windsurf. For team features like PR analysis, quality gates, dashboards, and code coverage tracking, you need the Team plan at $18/dev/month (annual billing). Open-source projects get the full Team plan for free.

How do I connect Codacy to GitHub?

Go to app.codacy.com and click Sign up with GitHub. Authorize the Codacy OAuth app to read your profile, then install the Codacy GitHub App on your organization or personal account. Select the repositories you want Codacy to access. Codacy creates webhooks automatically so that every push and pull request triggers analysis.

How do I configure Codacy code patterns?

Navigate to your repository in Codacy, click Code patterns in the left sidebar, and you will see all available analysis tools listed by language. Each tool shows its individual rules which you can toggle on or off. You can also switch entire tools on or off. For bulk configuration, use a .codacy.yml file in your repository root to define which tools and rules to enable.

How do I setup Codacy PR analysis?

PR analysis is enabled by default when you connect a repository through the GitHub App integration. Codacy automatically posts a status check and summary comment on every pull request showing new issues, coverage changes, and quality gate status. You can customize what appears in the PR comment from your repository’s Settings page under Pull Requests.

How do I add code coverage to Codacy?

Install the Codacy Coverage Reporter in your CI pipeline using the bash script or CLI binary. Generate a coverage report in your test suite (LCOV, Cobertura, JaCoCo, or Clover format), then upload it with the codacy-coverage-reporter tool using your project API token. Codacy will display coverage metrics on your dashboard and in PR comments.

What is the .codacy.yml file used for?

The .codacy.yml file is a repository-level configuration file that lets you define which analysis tools and patterns are enabled, exclude files and directories from analysis, set language-specific overrides, and configure coverage settings. It lives in your repository root and overrides the Codacy UI settings, making configuration version-controlled and consistent across your team.

How do I ignore files in Codacy?

You can ignore files in Codacy through two methods. In the UI, go to your repository Settings, click Ignored files, and add glob patterns like /test/, /vendor/, or */.min.js. Alternatively, add an exclude_paths section to your .codacy.yml file. Both methods prevent Codacy from analyzing matching files and directories.

How do I setup Codacy quality gates?

Go to your repository in Codacy, click Quality settings in the sidebar, then configure thresholds for issues (new and total), complexity, duplication, and code coverage. Quality gates apply to both the overall repository and individual pull requests. When a PR fails a quality gate, Codacy reports a failing status check on the PR, which you can configure to block merges through branch protection rules.

Does Codacy work with GitLab and Bitbucket?

Yes, Codacy supports GitHub, GitLab (cloud and self-managed), and Bitbucket (cloud and Data Center). The setup process is similar across all platforms – sign up with your Git provider account, authorize the integration, and select repositories. PR analysis, quality gates, and coverage tracking work on all three platforms.

How do I add team members to Codacy?

Team members are added automatically when they join your Git provider organization and have access to repositories connected to Codacy. You can also invite members manually from the Organization settings page in Codacy. Role-based access control lets you assign Admin, Manager, or Developer roles with different permission levels for configuring tools, managing repositories, and viewing dashboards.

Why is Codacy not analyzing my repository?

The most common causes are: the repository language is not supported, the GitHub App does not have permission to access the repository, the repository is empty or has no analyzable files, or analysis is paused. Check the repository status page in Codacy for error messages. If the GitHub App permissions were recently changed, you may need to re-authorize from your GitHub organization settings.

How long does Codacy take to analyze a repository?

The initial full analysis typically takes 2-15 minutes depending on repository size, number of files, and languages used. Subsequent PR analyses are faster because Codacy only scans changed files, usually completing in 1-3 minutes. Very large repositories with hundreds of thousands of lines may take longer on the first scan.

Can I use Codacy with monorepos?

Yes, Codacy supports monorepos. You can configure different analysis tools and patterns for different directories within the same repository using the .codacy.yml file. File exclusion patterns let you scope analysis to specific services or packages. Coverage can be uploaded separately for each component and Codacy will aggregate the results.

Originally published at aicodereview.cc