Advanced Configuration

As an alternative to the configurations available in your repository's Settings page, you can choose to commit a .codeclimate.yml or .codeclimate.json configuration file. This is helpful for those who prefer more finely-tuned configuration of maintainability checks and third-party plugins, or wish to keep their configuration in version control.

A committed config file is helpful for some of the following use cases:

• Fetching an external style guide
• Specifying versions of certain plugins
• Enabling/disabling individual checks from plugins

Sample .codeclimate.yml

You can find a sample .codeclimate.yml with default configurations here.

❗️

Adding a .codeclimate.yml when PR builds are erroring

Any branches that were branched off prior to adding a new commit containing your .codeclimate.yml will need to be rebased onto your default branch, or the analysis will continue to error on those branches as well.

• more about rebasing here

Table of Contents

• Configuration Formats
• Configuration File and Content
• Default Check Configurations
• Disabling Maintainability Checks
• Adding, Removing, and Configuring Plugins
• Exclusions
• Examples
• Analysis Configuration Versions

Configuration Formats

Code Climate supports configuration in the following formats:

• YML - Commit a .codeclimate.yml file to configure your analysis
• JSON - Commit a .codeclimate.json file to configure your analysis
• In-App - Configure your analysis on codeclimate.com

📘

If there are multiple configuration formats for the same repo, Code Climate will only use one. The priority order is:

1. .codeclimate.json
2. .codeclimate.yml
3. In-App config

Configuration File Structure and Content

Configuration files committed to your repo support five primary sections:

- version: The currently supported version is "2"
- prepare: Actions to perform before analysis begins
  - fetch: Remote files to fetch (files are placed relative to the repo's root directory)
    - url: url to fetch
      path: destination relative to repo's root directory
- checks: Configuration of maintainability checks
  - <name>
    - enabled: true|false
    - config: check configuration
- plugins: Enable optional plugins to run in addition to your analysis
  - <name>
    - enabled: true|false
    - channel: alternate channel to use (stable is default)
    - config: plugin configuration
- exclude_patterns: Exclude files and/or directories from analysis
  - <pattern>
  - <pattern>

As can be seen in the sample file above, the 3 major nodes for customization are:

• checks,
• plugins, and
• exclude_patterns

Default Checks & Thresholds

All maintainability checks are enabled by default with the following configurations. Any configuration value can by overridden in either .codeclimate.yml or .codeclimate.json configuration file formats.

version: "2"         # required to adjust maintainability checks
checks:
  argument-count:
    config:
      threshold: 4
  complex-logic:
    config:
      threshold: 4
  file-lines:
    config:
      threshold: 250
  method-complexity:
    config:
      threshold: 5
  method-count:
    config:
      threshold: 20
  method-lines:
    config:
      threshold: 25
  nested-control-flow:
    config:
      threshold: 4
  return-statements:
    config:
      threshold: 4
  similar-code:
    config:
      threshold: # language-specific defaults. an override will affect all languages.
  identical-code:
    config:
      threshold: # language-specific defaults. an override will affect all languages.

Disabling Maintainability Checks

All 10 maintainability checks are enabled by default. To disable a check, use a committed configuration file as seen below:

version: "2"
checks:
  argument-count:
    enabled: false
  complex-logic:
    enabled: false
  file-lines:
    enabled: false
  method-complexity:
    enabled: false
  method-count:
    enabled: false
  method-lines:
    enabled: false
  nested-control-flow:
    enabled: false
  return-statements:
    enabled: false
  similar-code:
    enabled: false
  identical-code:
    enabled: false

Plugins

Adding Plugins to your analysis

To add a plugin to your analysis, simply add the following to your .codeclimate.yml configuration file and commit to the root of your repository:

version: "2"
plugins:
  [plugin name]:
    enabled: true

You can find the complete list of available plugins here.

Removing plugins from your analysis

To remove a plugin from your analysis, you can simply mark the plugin as enabled: false in the .yml, as shown here:

version: "2"
plugins:
  rubocop:
    enabled: true
  eslint:
    enabled: false
  csslint:
    enabled: true

Configuring individual plugins

For configuration of specific plugins, please see the documentation for that plugin.

Exclude Patterns

The default Quality configuration comes with a list of exclusions that we think make sense for your project, including third party libraries, production assets (such as minimized or cross-compiled files), and automated test suites.

You can customize these or specify additional files or directories that you'd like to exclude using the exclude_patterns key.

📘

Exclude Patterns

Exclusions can only be made at the global level (excluding code from all analysis) or at the plugin-level (excluding code only from specific third-party plugins). Currently, exclusions cannot be made for individual maintainability checks.

To learn how to exclude:

• specific files and file types at any level
• tests and specs or a vendor directory at any level
• paths for specific engines, or
• single files

Please refer to our guide to Excluding Files and Folders.

🚧

.codeclimate.yml with NO exclude_patterns

If you commit a .codeclimate.yml with NO exclude_patterns, Code Climate will use the default exclude patterns listed here.

Examples

The following are identical examples in both JSON and YML formats. Click the file names at the top of the script to alternate between formats.

version: "2"
prepare:
  fetch:
    - url: "https://raw.githubusercontent.com/example/example/master/rubocop.yml"
      path: "alternate-rubocop-path.yml"
checks:
  method-lines:
    config:
      threshold: 100
  argument-count:
    enabled: false
plugins:
  rubocop:
    enabled: true
    channel: "rubocop-0-49"
    checks:
      Rubocop/Style/TrailingCommaInLiteral:
        enabled: false
    config:
      file: "alternate-rubocop-path.yml"
exclude_patterns:
  - "spec/"
  - "!spec/support/helpers"

{
  "version": "2",
  "prepare": {
    "fetch": [
      { 
        "url": "https://raw.githubusercontent.com/example/example/master/rubocop.yml/",
        "path": ".rubocop.yml"
      }
    ]
  },
  "checks": {
    "method-lines": {
      "config": {
        "threshold": 100
      }
    },
    "argument-count": {
      "enabled" false,
    }
  },
  "plugins": {
    "rubocop": {
      "enabled": true,
      "channel": "rubocop-0-49",
      "checks": {
        "Rubocop/Style/TrailingCommaInLiteral": {
          "enabled": false
        }
      },
      "config": {
        "file": "alternate-rubocop-path.yml"
      }
    }
  },
  "exclude_patterns": [
    "spec/",
    "!spec/support/helpers"
  ]
}

Analysis Configuration Versions

In the Fall of 2017, we launched our newest analysis model, which introduced our 10 maintainability checks. With the new model, we've launched a new configuration version which requires updated syntax. A few things to note when updating an older configuration file:

• version: "2" is required at the top of the .codeclimate.yml.
• engines has been changed to plugins.
• checks has been introduced. All maintainability checks are enabled by default, but can be disabled or tuned individually under the checks node.
• exclude_paths has been changed to exclude_patterns.
• ratings has been deprecated. All files in our supported languages for maintainability will receive maintainability ratings by default.

Check out the below example of how to upgrade an older configuration file:

version: "2"
checks:
  argument-count:
    enabled: true
    config:
      threshold: 4
  complex-logic:
    enabled: true
    config:
      threshold: 4
  file-lines:
    enabled: true
    config:
      threshold: 250
  method-complexity:
    enabled: true
    config:
      threshold: 5
  method-count:
    enabled: true
    config:
      threshold: 20
  method-lines:
    enabled: true
    config:
      threshold: 25
  nested-control-flow:
    enabled: true
    config:
      threshold: 4
  return-statements:
    enabled: true
    config:
      threshold: 4
  similar-code:
    enabled: true
    config:
      threshold: #language-specific defaults. overrides affect all languages.
  identical-code:
    enabled: true
    config:
      threshold: #language-specific defaults. overrides affect all languages.
plugins:
 rubocop:
  enabled: true
 eslint:
  enabled: true
exclude_patterns:
- "config/"
- "db/"
- "dist/"
- "features/"
- "**/node_modules/"
- "script/"
- "**/spec/"
- "**/test/"
- "**/tests/"
- "**/vendor/"
- "**/*.d.ts"

engines:
 rubocop:
  enabled: true
 eslint:
  enabled: true
 brakeman:
  enabled: true
ratings:
   paths:
   - "app/**/*"
   - "lib/**/*"
   - "**.rb"
   - "**.js"
exclude_paths:
- "config/
- "db/"
- "dist/"
- "features/"
- "**/node_modules/"
- "script/"
- "**/spec/"
- "**/test/"
- "**/tests/"
- "**/vendor/"
- "**/*.d.ts"