Configure a Codacy Quality Gate for Pull Requests

The problem and the useful takeaway

Pull requests frequently merge with new lint violations, security findings, or complexity spikes because no automated check blocks them. Static analysis tools can catch these issues, but only if their results are enforced as a required status check before merge.

This guide covers adding a Codacy quality gate to a pull-request workflow. Codacy is a code-quality platform that runs static analysis—automated inspection of source code without executing it—and reports issues by rule, severity, and file. The takeaway is to commit a .codacy.yaml configuration, connect the repository to Codacy, configure a gate that fails on new issues, and require Codacy’s status check in branch protection so a failing pull request cannot be merged.

Prerequisites

• Write or admin access to the repository on GitHub, GitLab, or Bitbucket.
• A Codacy account (cloud or self-hosted) with permission to add repositories.
• A Codacy API token with repository scope, stored as a secret or environment variable, not committed to version control.
• Permission to edit branch-protection rules for the default branch.

This guide assumes the Codacy cloud edition. Self-hosted editions can differ in feature parity and upgrade cadence; verify your edition before relying on a specific gate option.

Step 1: Connect the repository

Add the repository to Codacy and install the Codacy application for your code host. The application posts status checks and inline comments on pull requests. If your organization does not permit code-host apps, you can run the Codacy analysis CLI in a generic CI job instead, though inline PR comments may not be available.

Step 2: Commit a Codacy configuration

Create .codacy.yaml in the repository root. This file selects analysis engines, excludes paths, and sets severity thresholds. The following example is illustrative; validate it against the current Codacy schema before rolling it out.

engines:
  eslint:
    enabled: true
    config: .eslintrc.json
  bandit:
    enabled: true
exclude_paths:
  - "tests/**"
  - "vendor/**"
  - "generated/**"

An engine is a language-specific analyzer, such as ESLint for JavaScript or Bandit for Python security issues. Exclude paths tell Codacy to skip directories that should not be gated, such as test fixtures or vendored dependencies.

Run this from your feature branch:

# Local machine. Requires read access to the repository.
git add .codacy.yaml
git commit -m "Add Codacy configuration for quality gate"
git push origin feature/codacy-quality-gate

Risk: pushing directly to the default branch bypasses pull-request review. Always push to a feature branch and open a pull request.

Step 3: Configure the quality gate for new issues

In Codacy, open the repository’s quality-gate settings and choose a mode that measures only issues introduced by the pull request, not pre-existing issues in the default branch. This prevents a legacy backlog from blocking the first rollout.

Gate mode	What it measures	Best for
New issues only	Issues introduced in the pull-request diff	Initial rollout; repositories with existing technical debt
All issues	Total issues across the repository	Mature repositories with a clean baseline

Set a threshold such as "fail when new issues greater than zero" or "fail when new high-severity issues greater than zero." Start with one or two high-signal tools—a linter plus a security rule pack—then ratchet thresholds over time as the team fixes findings.

Step 4: Require the Codacy status check

Open branch-protection settings for the default branch on your code host and add Codacy’s status check as a required check. Required permissions: admin or maintainer access to the repository.

Expected behavior: when a pull request is opened, Codacy analyzes the changed files and reports a status. If the quality gate is violated, the status shows as failed and the merge button is disabled.

Expected checks

• Open a test pull request that deliberately introduces a lint violation or security finding. Confirm the Codacy status check fails and the merge is blocked.
• Run the Codacy analysis CLI locally on the same branch to verify it reproduces the cloud result:

# Local machine or CI job. Requires a Codacy API token and read access to the repo.
# Replace  with a secret value; never commit it.
codacy-analysis-cli analyze --token "" --directory .

Expected check: the CLI exits non-zero when issues exceed the configured threshold and lists affected files and rule IDs. Risk: an incorrect token or outdated CLI version can produce a false pass; validate the configuration in the Codacy UI or with the CLI’s config check before relying on it.

Recovery when a gate blocks a merge

If Codacy blocks a pull request, choose one of the following recovery paths:

1. Fix the finding. Resolve the lint violation or security issue in the pull-request branch and re-run the check.
2. Add a narrow suppression. Ignore a specific rule for a specific line or file, with a justification comment. Prefer tool-specific suppressions over disabling an entire engine.
3. Adjust the configuration. Change .codacy.yaml to exclude a path or lower a severity, then submit the change through a pull request.
4. Temporarily relax the gate. Lower the threshold with a linked follow-up ticket. Treat this as a state-changing exception, not a permanent policy.

Rollback

Committing .codacy.yaml and enabling a required status check changes repository state. To roll back:

• Revert the commit that added .codacy.yaml.
• Remove Codacy’s status check from branch-protection rules.
• Disable or remove the repository from Codacy.
• Verify rollback by opening a pull request that previously failed and confirming it can merge without the Codacy check.

Limitations and practical verification

• A passing quality gate is not proof of correctness. Static analysis complements tests and human review; it does not replace them.
• Codacy’s supported languages, bundled tool versions, configuration schema, and plan-gated features change frequently. Verify against current documentation before adopting a specific gate option.
• Cloud and self-hosted editions differ in feature parity. Confirm which edition your team uses.
• Broad suppressions or disabled tools can mask real defects. Review suppressions during code review.

Practical verification: run the CLI locally on a feature branch, open a test pull request with a deliberate issue, and confirm the status check fails according to the configured gate. Review the vendor changelog before upgrading the integration.