Codacy GitHub Integration: Complete Setup and Configuration Guide

What You Will Learn

This guide walks through the complete process of integrating Codacy with GitHub - from installing the GitHub App to configuring pull request analysis, setting up quality gates, and uploading coverage reports from GitHub Actions. By the end, you will have a fully automated code quality pipeline where every pull request is scanned for bugs, security vulnerabilities, code smells, and coverage regressions before it can be merged.

Whether you are setting up Codacy for the first time or troubleshooting an existing integration that is not working as expected, this guide covers every step in detail. If you are looking for a broader overview of Codacy setup that includes GitLab and Bitbucket, see our complete Codacy setup guide.

Prerequisites

Before starting the Codacy GitHub integration, make sure you have the following in place:

• A GitHub account with admin or owner access to the repositories you want to connect. You need admin permissions to install GitHub Apps and configure webhooks.
• At least one repository with code in a language Codacy supports. Codacy analyzes 49 programming languages including JavaScript, TypeScript, Python, Java, Go, Ruby, PHP, C#, Kotlin, Swift, and Scala.
• A CI pipeline (optional but recommended) if you plan to upload code coverage. GitHub Actions is the most straightforward option since Codacy provides official Actions for both analysis and coverage reporting.
• Organization admin access if you are installing Codacy on a GitHub organization rather than a personal account. Only organization admins can approve third-party GitHub App installations.

The integration itself takes under ten minutes. Configuring code patterns, quality gates, and coverage reporting adds another 20 to 30 minutes depending on how much customization your team needs.

Step 1 - Sign Up with GitHub

The fastest way to get started with Codacy is to sign up directly through your GitHub account. This creates your Codacy account and links it to your GitHub identity in a single flow.

Creating your Codacy account

Navigate to app.codacy.com and click the sign-up button. Select Sign up with GitHub from the available options. GitHub will prompt you to authorize the Codacy OAuth application, which grants Codacy permission to read your GitHub profile and email address.

After authorizing, Codacy redirects you back to its dashboard. At this point, your account exists but no repositories are connected yet. The next step is installing the Codacy GitHub App, which is what actually enables repository analysis and pull request integration.

Installing the Codacy GitHub App

The Codacy GitHub App is the core integration mechanism. Unlike the older OAuth-based integrations, the GitHub App provides granular permissions and webhook management without requiring a personal access token.

To install the GitHub App:

1. From your Codacy dashboard, click Add repository or navigate to the organization settings
2. Codacy will prompt you to install its GitHub App if you have not already done so
3. Choose whether to install the app on your personal account or on a GitHub organization
4. Select the repository access level - either All repositories or Only select repositories

If you are evaluating Codacy, start with “Only select repositories” and pick one or two projects. You can always expand access later from your GitHub organization settings under Settings then GitHub Apps then Configure next to the Codacy app.

The GitHub App requests the following permissions:

Permission	Access Level	Purpose
Repository contents	Read	Analyze source code during scans
Repository metadata	Read	List repositories and branches
Pull requests	Read and Write	Post status checks and comments on PRs
Webhooks	Read and Write	Receive push and PR events to trigger analysis
Checks	Read and Write	Report analysis results as GitHub Checks

Codacy does not request write access to your repository contents. It reads the code for analysis but does not push commits or modify files. After analysis, the code is not stored permanently on Codacy’s servers.

Step 2 - Add Repositories

Once the GitHub App is installed, you can start adding repositories to Codacy for analysis.

Selecting repositories

From your Codacy dashboard, click Add repository in the top navigation. Codacy displays a list of all repositories the GitHub App has access to, filtered by your organization. Select the repository you want to analyze and click Add.

Codacy immediately begins the initial analysis, which involves several automated steps:

1. Cloning - Codacy clones the repository temporarily to access the source code
2. Language detection - it identifies which programming languages are present
3. Tool selection - Codacy enables default analysis tools for each detected language
4. Full scan - every file in the repository is analyzed against the enabled code patterns
5. Report generation - results are compiled into the repository dashboard

The initial analysis typically takes between 2 and 15 minutes depending on repository size. For a medium-sized repository with 50,000 to 100,000 lines of code, expect roughly 5 to 8 minutes.

Understanding the initial results

Once the first analysis completes, your repository dashboard displays several key metrics:

• Grade - an overall letter grade from A (best) to F (worst) based on aggregated quality metrics
• Issues - total issues found, categorized by severity (error, warning, info) and type (security, error-prone, performance, code style, unused code)
• Complexity - file-level and function-level cyclomatic complexity scores
• Duplication - the percentage of duplicated code blocks across the repository
• Coverage - code coverage percentage, which will show as empty until you configure coverage reporting (covered in a later step)

Do not be alarmed if the initial grade is low. Legacy codebases often receive C or D grades on first analysis because Codacy runs all default patterns, including code style rules that may not match your team’s conventions. The next steps cover how to tune the analysis to focus on what matters for your project.

Step 3 - Configure Code Patterns

Code patterns are the individual rules that Codacy uses to analyze your source code. Each supported language has one or more analysis tools, and each tool contains a set of patterns that can be individually toggled.

Navigating to code patterns

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

For a JavaScript/TypeScript project, you might see ESLint, JSHint, and Codacy’s own analyzers listed. For Python, expect Pylint, Bandit, Prospector, and Ruff. For Java, PMD, SpotBugs, and Checkstyle are common.

Tuning analysis tools

Each tool has a master toggle to enable or disable it entirely. Within each tool, individual rules can be switched on or off. Here is a practical approach for tuning:

Start with defaults. Run the first analysis with Codacy’s default patterns and review the results. If a specific tool or rule category produces mostly noise for your codebase, disable it.

Disable redundant tools. If you already run ESLint locally with a custom configuration, you have two options. Either disable Codacy’s built-in ESLint to avoid duplicate findings, or enable the “Use the configuration file in my repository” toggle so Codacy respects your .eslintrc file. The second approach is generally better because it keeps analysis consistent between local development and CI.

Focus on high-severity rules first. Sort rules by severity and prioritize error-level patterns that catch actual bugs and security vulnerabilities. Info-level and style-level patterns can be enabled later once your team has addressed the critical findings.

Using your existing linter configuration

If your repository already contains linter configuration files like .eslintrc.js, .pylintrc, or .rubocop.yml, you can configure Codacy to use them:

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 repository’s configuration instead of its own defaults

This prevents drift between what developers see when running linters locally and what Codacy reports on pull requests. It also means your team can manage analysis rules through the same code review process used for application code.

Step 4 - PR Analysis Setup

Pull request analysis is the most impactful part of the Codacy GitHub integration. It provides automated feedback on every PR before code reaches your main branch, catching issues while the context is fresh and the fix is simple.

How PR analysis works with GitHub

When a developer opens or updates a pull request on a connected repository, the following sequence occurs:

1. GitHub sends a webhook event to Codacy via the GitHub App
2. Codacy fetches only the files changed in the PR (not the entire repository)
3. Each changed file is analyzed against the enabled code patterns
4. Results are compared against the target branch to distinguish new issues from existing ones
5. Codacy posts a status check on the PR indicating pass or fail
6. Optionally, Codacy posts a summary comment 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 look for the “Codacy Static Code Analysis” status check at the bottom of the PR.

Configuring what appears on PRs

You can customize the information Codacy reports on your pull requests:

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

Available options include:

• Status check behavior - post a single combined check or separate checks for issues, coverage, and duplication
• PR comment - toggle the summary comment on or off, and configure what information it includes (new issues, fixed issues, coverage delta, complexity changes)
• Inline annotations - add annotations directly on specific lines in the PR diff where issues were found

For most teams, the default configuration works well. The summary comment provides a quick overview, while inline annotations help developers locate specific issues without leaving the GitHub PR interface.

Making Codacy a required status check

To enforce quality standards and prevent PRs from being merged when they fail Codacy’s analysis, configure GitHub branch protection rules:

1. Go to your repository settings on GitHub
2. Click Branches in the sidebar
3. Click Add branch protection rule (or edit an existing one for your main branch)
4. Check Require status checks to pass before merging
5. Search for and select Codacy Static Code Analysis
6. Save the rule

# Example branch protection configuration
Branch name pattern: main

Require status checks to pass before merging:
  - Codacy Static Code Analysis

Once this is configured, GitHub will block the merge button on any PR where Codacy reports a failing status check. This is the most effective way to ensure that quality gates are actually enforced rather than just advisory.

Step 5 - Quality Settings

Quality gates define the thresholds that determine whether a PR passes or fails Codacy’s analysis. Without properly configured quality gates, the status check will always pass regardless of the issues found.

Configuring quality gate thresholds

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

Metric	What It Measures	Recommended Starting Threshold
New issues	Number of new issues introduced by the PR	0 critical, 5 total
Coverage on new code	Test coverage percentage on new or changed lines	60%
Coverage variation	Maximum allowed decrease in overall coverage	-1%
Duplication on new code	Percentage of duplicated blocks in new code	3%
Complexity	Maximum file complexity score	No threshold initially

Practical rollout strategy

Setting quality gates too aggressively from day one will cause every PR to fail, frustrating developers and eroding trust in the tool. A more effective approach:

Weeks 1 to 2: Set quality gates to advisory mode. Codacy reports results but does not block merges. Use this period to observe how your team’s PRs perform against the thresholds and whether the thresholds are realistic.

Weeks 3 to 4: Enable blocking quality gates with achievable thresholds. Start with zero new critical issues and coverage must not decrease. These are standards most teams can meet immediately.

Month 2 and beyond: Gradually tighten thresholds. Increase minimum coverage on new code, reduce the total allowed new issues, and add complexity thresholds once the team is comfortable with the workflow.

This approach lets your team build familiarity with the tool before it starts blocking their work, which significantly improves adoption rates compared to a strict day-one enforcement.

Coverage Reports Setup

Code coverage tracking is one of Codacy’s most useful GitHub integration features. It shows exactly how well-tested each pull request is and prevents coverage regressions from being merged.

Why coverage requires separate configuration

Codacy does not run your test suite. It analyzes source code statically, but test execution and coverage measurement happen in your CI pipeline. You need to generate a coverage report in your CI environment and upload it to Codacy using the Coverage Reporter.

Step-by-step GitHub Actions setup

Generate a project API token:

1. Open your repository in the Codacy dashboard
2. Click Settings in the sidebar
3. Find the Coverage or Integrations section
4. Copy the Project API Token

Add the token to GitHub Actions secrets:

1. Go to your repository settings on GitHub
2. Click Secrets and variables then Actions
3. Click New repository secret
4. Name it CODACY_PROJECT_TOKEN and paste the token value

Add the coverage step to your workflow:

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 Python projects, the workflow looks similar but uses pytest:

      - 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

Codacy supports LCOV, Cobertura XML, JaCoCo, Clover, and OpenCover formats. Use whichever format your test framework generates natively.

Uploading coverage for monorepos

If your project has multiple test suites or components, upload partial reports and finalize them:

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

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

      - name: Finalize coverage
        uses: codacy/codacy-coverage-reporter-action@v1
        with:
          project-token: ${{ secrets.CODACY_PROJECT_TOKEN }}
          final: true

Once coverage is uploaded, Codacy displays coverage metrics on your repository dashboard and includes coverage deltas in every PR analysis comment. If you have configured a coverage quality gate, PRs that decrease coverage below the threshold will receive a failing status check.

Troubleshooting

Even with a straightforward setup, you may run into issues with the Codacy GitHub integration. Here are the most common problems and their solutions.

Codacy is not analyzing pull requests

Check GitHub App permissions. Go to your GitHub organization settings, click GitHub Apps, find the Codacy app, and click Configure. Verify that the repository in question is listed under repository access. If you chose “Only select repositories” during installation and later added new repositories, you need to update this list manually.

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 with non-200 status codes. If deliveries are failing, try redelivering a recent one. If the webhook is missing entirely, the GitHub App may need to be reinstalled.

Check repository status in Codacy. Navigate to the repository in your Codacy dashboard and look at the status indicator. If analysis is paused, click to resume it. If the status shows an error, the most common causes are a misconfigured default branch or the repository being archived on GitHub.

Coverage is not appearing on PRs

Verify the upload succeeded. Check your GitHub Actions logs for the coverage reporter step. A successful upload shows a confirmation message with the commit SHA. Common failure causes include an incorrect or expired project token, a malformed coverage report, or a network timeout reaching Codacy’s servers.

Check the commit SHA mismatch. Codacy matches coverage reports to specific commits. GitHub Actions pull_request events run on a merge commit by default, which may not match the PR head SHA. Use the --commit-uuid parameter to specify the correct SHA:

      - name: Upload coverage to Codacy
        uses: codacy/codacy-coverage-reporter-action@v1
        with:
          project-token: ${{ secrets.CODACY_PROJECT_TOKEN }}
          coverage-reports: coverage/lcov.info
        env:
          CODACY_COMMIT_UUID: ${{ github.event.pull_request.head.sha }}

Status check is stuck in “pending”

This usually means Codacy received the webhook but has not completed the analysis. Common causes include Codacy service delays (check status.codacy.com), very large PRs with thousands of changed files, or rate limiting if you are running many concurrent analyses. Wait 15 minutes and check again. If the check remains pending, try closing and reopening the PR to trigger a fresh webhook.

Too many false positives in PR comments

Tune your code patterns. Go to Code patterns in the Codacy dashboard and disable rules that consistently produce irrelevant findings. Focus on keeping error-severity and security rules enabled while disabling code style rules that conflict with your team’s conventions.

Use your repository’s linter config. Enable the “Use configuration file in repository” toggle for each tool that has a matching config file in your project. This ensures Codacy’s analysis matches your local linting setup.

Exclude non-application code. Add generated files, vendored dependencies, build outputs, and test fixtures to your .codacy.yml exclusion list or the Ignored Files section in the Codacy UI.

Alternatives to Codacy for GitHub Integration

While Codacy is a solid choice for GitHub-based code quality automation, several alternatives offer different strengths. If the Codacy GitHub integration does not meet your specific needs, here are tools worth evaluating.

CodeAnt AI

CodeAnt AI is a Y Combinator-backed platform that combines AI-powered PR reviews, SAST, secrets detection, IaC security scanning, and DORA metrics in a single tool. It provides line-by-line code review feedback, auto-generated PR summaries, and one-click auto-fix suggestions across 30+ languages.

CodeAnt AI is priced at $24/user/month for the Basic plan (AI PR reviews, summaries, and auto-fix) and $40/user/month for Premium (adds SAST, secrets detection, IaC scanning, DORA metrics, and SOC 2/HIPAA audit reports). For teams that want both AI code review and security scanning in one GitHub integration, CodeAnt AI is a strong contender - especially for teams in regulated industries that need compliance reporting alongside code quality.

Compared to Codacy, CodeAnt AI offers more advanced AI review capabilities with contextual feedback that considers PR descriptions and linked issues. The trade-off is that it supports fewer languages (30+ versus Codacy’s 49) and is a newer platform with a smaller user base.

Other alternatives to explore

For a comprehensive comparison of tools that can replace or complement Codacy, see our Codacy alternatives guide. If pricing is your primary concern, our Codacy pricing breakdown compares costs across different team sizes. And if you are still evaluating whether Codacy’s free tier meets your needs, check out our guide on whether Codacy is free.

Conclusion

The Codacy GitHub integration provides a comprehensive automated code quality pipeline that scans every pull request for bugs, security vulnerabilities, code smells, duplication, and coverage regressions. The setup process is straightforward - install the GitHub App, add your repositories, configure code patterns to match your team’s standards, set quality gates with realistic thresholds, and upload coverage reports from GitHub Actions.

The most impactful configuration decisions are making Codacy a required status check through GitHub branch protection rules, enabling the “Use configuration file in repository” option for linting tools you already run locally, and setting quality gates that focus on new code rather than the entire codebase. These three choices determine whether Codacy becomes a genuinely useful part of your development workflow or just another dashboard that developers learn to ignore.

For teams that want to go deeper with Codacy configuration beyond just the GitHub integration, our complete Codacy setup guide covers additional topics including the .codacy.yml configuration file, team management, advanced CI configurations, and best practices for long-term maintenance. For an honest assessment of the platform’s strengths and limitations, see our Codacy review.