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:
- From your Codacy dashboard, click Add repository or navigate to the organization settings
- Codacy will prompt you to install its GitHub App if you have not already done so
- Choose whether to install the app on your personal account or on a GitHub organization
- 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:
-
Cloning – Codacy clones the repository temporarily to access the source code
-
Language detection – it identifies which programming languages are present
-
Tool selection – Codacy enables default analysis tools for each detected language
-
Full scan – every file in the repository is analyzed against the enabled code patterns
-
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
- Open your repository in the Codacy dashboard
- Click Code patterns in the left sidebar
- 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:
- Go to Code patterns and select the relevant tool
- Enable the “Use the configuration file in my repository” toggle
- 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:
- GitHub sends a webhook event to Codacy via the GitHub App
- Codacy fetches only the files changed in the PR (not the entire repository)
- Each changed file is analyzed against the enabled code patterns
- Results are compared against the target branch to distinguish new issues from existing ones
- Codacy posts a status check on the PR indicating pass or fail
- 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:
- Navigate to your repository in the Codacy dashboard
- Click Settings in the left sidebar
- 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:
- Go to your repository settings on GitHub
- Click Branches in the sidebar
- Click Add branch protection rule (or edit an existing one for your main branch)
- Check Require status checks to pass before merging
- Search for and select Codacy Static Code Analysis
- 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
- Navigate to your repository in the Codacy dashboard
- Click Quality settings in the left sidebar
- 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:
- Open your repository in the Codacy dashboard
- Click Settings in the sidebar
- Find the Coverage or Integrations section
- Copy the Project API Token
Add the token to GitHub Actions secrets:
- Go to your repository settings on GitHub
- Click Secrets and variables then Actions
- Click New repository secret
- 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.
Further Reading
Frequently Asked Questions
How do I integrate Codacy with GitHub?
Go to app.codacy.com, click Sign up with GitHub, and authorize the Codacy OAuth app. Then install the Codacy GitHub App on your organization or personal account. Select the repositories you want to analyze, and Codacy will automatically create webhooks and begin scanning your code within minutes.
Is the Codacy GitHub App free?
The Codacy GitHub App is free to install. However, accessing the full cloud platform features like PR analysis, quality gates, and team dashboards requires a paid Team plan at $18/dev/month (annual billing). Open-source projects get the Team plan free. The Developer plan offers free IDE-based scanning but does not include GitHub PR integration.
How does Codacy analyze GitHub pull requests?
When you open a pull request, the Codacy GitHub App receives a webhook notification. It analyzes only the changed files, compares results against the target branch to identify new issues, posts a status check (pass or fail based on quality gates), and optionally adds a summary comment with detailed findings including coverage changes and complexity metrics.
Can I use Codacy with GitHub Actions?
Yes. Codacy provides an official GitHub Action called codacy-analysis-cli-action that runs static analysis inside your CI pipeline. You can also use the codacy-coverage-reporter-action to upload test coverage reports. Both actions authenticate using your project API token stored as a GitHub Actions secret.
How do I fix Codacy not analyzing my GitHub pull requests?
First, verify the Codacy GitHub App has permission to access the repository in your GitHub organization settings under GitHub Apps. Then check the webhook delivery status in your repository settings under Webhooks. Also confirm the repository is not paused in the Codacy dashboard. If permissions were recently changed, you may need to re-authorize the app.
How do I make Codacy a required check on GitHub?
Go to your GitHub repository settings, click Branches, and edit or create a branch protection rule for your main branch. Under Require status checks to pass before merging, search for and select the Codacy Static Code Analysis check. This prevents PRs from merging when they fail Codacy quality gates.
How do I upload code coverage from GitHub Actions to Codacy?
Add the codacy/codacy-coverage-reporter-action step to your GitHub Actions workflow after your test step. Provide your CODACY_PROJECT_TOKEN as a secret and specify the coverage report path. Codacy supports LCOV, Cobertura, JaCoCo, Clover, and OpenCover formats. The coverage data then appears on your Codacy dashboard and in PR comments.
What GitHub permissions does the Codacy app need?
The Codacy GitHub App requires read access to repository code and metadata, write access to pull request status checks and comments, and webhook access for push and pull request events. You can grant access to all repositories or select specific ones during installation. Codacy does not store your source code permanently.
How do I configure Codacy analysis rules for a GitHub repository?
Navigate to your repository in the Codacy dashboard, click Code patterns in the sidebar, and toggle individual analysis tools and rules on or off. Alternatively, create a .codacy.yml file in your repository root to define tool configuration, file exclusions, and language settings. The YAML file overrides UI settings and keeps configuration version-controlled.
Can I use Codacy with GitHub Enterprise?
Yes. Codacy supports GitHub Enterprise Cloud natively through the standard GitHub App integration. For GitHub Enterprise Server (self-hosted), you need the Codacy Business plan which supports self-hosted deployment. This requires additional infrastructure configuration and is priced through custom sales quotes.
How long does Codacy take to analyze a GitHub pull request?
Codacy typically analyzes pull requests in 1 to 3 minutes because it only scans changed files rather than the entire repository. The initial full repository analysis takes 2 to 15 minutes depending on codebase size. Very large repositories with hundreds of thousands of lines may take longer on the first scan.
Does Codacy work with GitHub monorepos?
Yes. Codacy supports monorepos by allowing you to configure different analysis tools and patterns for different directories using the .codacy.yml file. You can exclude irrelevant directories, scope analysis to specific services, and upload coverage separately for each component. Codacy aggregates all partial coverage reports into a single view.
Originally published at aicodereview.cc
