Skip to content
This documentation applies to Codacy Self-hosted v12.0.0

For the latest updates and improvements, see the latest Cloud documentation instead.

How do I block merging pull requests using Codacy as a quality gate?#

You can block merging pull requests until they pass the Codacy quality gate. This ensures the quality of the changes to your codebase, such as to prevent introducing security issues or adding code that isn't covered by tests.

To block merging pull requests that don't meet the quality standards of your team you must complete these main steps:

  1. Adding coverage to your repository (optional)
  2. Reviewing and adjusting the Codacy analysis settings
  3. Deciding which pull requests fail the Codacy quality gate
  4. Enabling the Codacy pull request status checks
  5. Configuring your Git provider to block merging pull requests

The next sections include detailed instructions on how to complete each step.

1. Adding coverage to your repository (optional)#

If you want to use code coverage to block merging pull requests that don't meet your quality standards, make sure that you add coverage to your repository.

It's important that you set up coverage beforehand because Codacy can only report the coverage status for pull requests after receiving reports for the last commits on both the pull request branch and the target branch.

Adding coverage to your repository

2. Reviewing and adjusting the Codacy analysis settings#

We recommend that you spend some time reviewing the Codacy analysis settings to focus on the tools and code patterns that bring more value to your team. Importantly, this eliminates the risk of having false positives block the work of your team once you start using Codacy as a quality gate.

  1. Ignore any files and directories that aren't relevant for the Codacy analysis, such as generated code or any third-party libraries included in your repositories.

    Ignoring files

  2. Configure the tools and code patterns that Codacy uses to analyze your repository.

    Tip

    To ensure that multiple repositories consistently follow the same global tool and code pattern configurations, use an organization coding standard instead.

    Configuring the tools and code patterns

3. Configuring the quality gate rules#

Review and adjust the quality settings of your repository to decide which pull requests should fail the Codacy quality gate.

Depending on factors such as the current code quality of your repository and the maturity of your team practices, consider the balance between implementing stricter quality gates and the possibility of delaying or blocking the development progress.

Tip

The default values of the quality gate rules are designed to help maintain the current code quality of your repository. In particular, the default value for the coverage rule might be demanding.

Because of this, Codacy generally recommends that on a first stage you configure rules that focus on stopping new critical issues from entering your code base, such as:

  • High severity issues
  • Security issues
  • Considerable drops in code coverage

Important

If you want to use code coverage to block merging pull requests that don't meet your standards, make sure that you enable the rule Diff coverage is under or Coverage variation is under. This is required for Codacy to report the coverage status directly on your pull requests.

Adjusting the quality settings

4. Enabling the Codacy pull request status checks#

Set up your repository so that Codacy reports the results of the analysis directly on your pull requests as status checks:

To do this, follow the instructions for GitHub, GitLab, or Bitbucket depending on your Git provider, and make sure that you:

  1. Enable the Git provider integration
  2. Enable the option Status checks (GitHub) or Pull request status (GitLab and Bitbucket)

Enabling your Git provider integration

5. Configuring your Git provider to block merging pull requests#

Important

At this stage we recommend that you:

This is important to eliminate any false positives that could inadvertently block the work of your team.

Finally, follow the instructions from your Git provider to block merging pull requests if they don't pass the Codacy status check:

Share your feedback 📢

Did this page help you?

Thanks for the feedback! Is there anything else you'd like to tell us about this page?

We're sorry to hear that. Please let us know what we can improve:

Alternatively, you can create a more detailed issue on our GitHub repository.

Thanks for helping improve the Codacy documentation.

If you have a question or need help please contact support@codacy.com.

Last modified July 13, 2022