Ruby

All Qodana linters are based on JetBrains IDEs designed for particular programming languages and frameworks. To analyze Ruby projects, you can use the following linter:

Linter	Linter name	Based on	Available under licenses	Supported languages
Qodana for Ruby	`jetbrains/qodana-ruby:2025.1-eap`	RubyMine	Ultimate and Ultimate Plus licenses	Ruby, JavaScript and TypeScript

To see the list of supported technologies and features, you can navigate to the Supported technologies and features chapter of this section.

Before you start

Install project dependencies

For a basic Ruby project that has no external dependencies, no preliminary steps are required.

In case a project has external dependencies, you can set them up using the bootstrap key in the qodana.yaml file:

bootstrap: | 
  sudo apt-get update && 
  sudo apt-get install -y <list of libraries> && 
  bundle install

The command will be automatically executed before the analysis to install dependencies using the bundle install command.

Qodana Cloud

Because the Qodana for Ruby linter requires a Qodana Cloud project token for identifying and verifying a license, follow these steps to get it:

Navigate to Qodana Cloud and create an account there.
In Qodana Cloud, create an organization, a team, and a project.
On the project card, you can find the project token that you will be using further in this section.

Prepare your software

On the Settings tab of the GitHub UI, create the QODANA_TOKEN encrypted secret and save the project token as its value.

In Jenkins, make sure that these plugins are up and running:
- Docker and Docker Pipeline are required for running Docker images
- Git is required for Git operations in Jenkins projects
Make sure that Docker is installed and accessible to Jenkins.
If applicable, make sure that Docker is accessible to the jenkins user as described in the Manage Docker as a non-root user section of the Docker documentation.
In Jenkins, create the qodana-token credential and save the project token as its value.
In Jenkins, create a Multibranch Pipeline project as described on the Jenkins documentation portal.

Make sure that your project repository is accessible to GitLab CI/CD.
In GitLab CI/CD, create the QODANA_TOKEN variable and save the project token as its value.

In TeamCity, Create a project and a build configuration.

Install Docker on the machine you are going to run Qodana.

If you are using Linux, you should be able to run Docker under your current non-root user.

Follow the instructions from the Qodana CLI page on GitHub.

Run this command to pull the Docker image of Qodana:

docker pull jetbrains/qodana-ruby:2025.1-eap

Run Qodana

You can run Qodana using available Docker images.

To analyze the main branch, release branches and the pull requests coming to your repository in container mode, save this workflow configuration to the .github/workflows/code_quality.yml file:

                            name: Qodana
                            on:
                                workflow_dispatch:
                                pull_request:
                                push:
                                    branches: # Specify your branches here
                                        - main # The 'main' branch
                                        - 'releases/*' # The release branches
                            jobs:
                                qodana:
                                    runs-on: ubuntu-latest
                                    permissions:
                                        contents: write
                                        pull-requests: write
                                        checks: write
                                    steps:
                                        - uses: actions/checkout@v3
                                          with:
                                              ref: ${{ github.event.pull_request.head.sha }}  # to check out the actual pull request commit, not the merge commit
                                              fetch-depth: 0  # a full history is required for pull request analysis
                                        - name: 'Qodana Scan'
                                          uses: JetBrains/qodana-action@v2025.1
                                          with:
                                              args: --linter,jetbrains/qodana-ruby:2025.1-eap
                                          env:
                                              QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}
                        

More configuration examples are available in the GitHub Actions section.

Save this configuration to the Jenkinsfile:

                            pipeline {
                              environment {
                                QODANA_TOKEN=credentials('qodana-token')
                              }
                              agent {
                                docker {
                                  args '''
                                       -v "${WORKSPACE}":/data/project
                                       --entrypoint=""
                                       '''
                                  image 'jetbrains/qodana-ruby:2025.1-eap'
                                }
                              }
                              stages {
                                stage('Qodana') {
                                  steps {
                                    sh '''qodana'''
                                  }
                                }
                              }
                            }
                        

More configuration examples are available in the Jenkins section.

In the root directory of your project, save this snippet to the .gitlab-ci.yml file:

                          include:
                              - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2025.1
                                inputs:
                                    args: --linter,jetbrains/qodana-ruby:2025.1-eap
                        

More configuration examples are available in the GitLab CI/CD section.

In the TeamCity UI, navigate to the configuration page of a build where you would like to run Qodana.
On the Build Configuration Settings page, navigate to the Build steps page.
On the Build steps page, click the Add build step button.
On the page that opens, select the Qodana runner.
On the New Build Step: Qodana page, click Show advanced options and configure the Qodana runner:
- Step name uniquely identifies this step among other build steps.
- Step ID uniquely identifies this step among other build steps.
- Execute step configures the build condition that will trigger this build step.
- Working directory sets the directory for the build process, see the TeamCity documentation for details. You can leave this field empty if the Checkout directory parameter is specified on the Version Control Settings tab.
- Report ID uniquely identifies the report to let you distinguish between multiple reports when several analysis steps are configured within a single build.
- The Forward reports to TeamCity tests checkbox configures Qodana report availability in the Test tab of the TeamCity UI. Using this option, you can view codebase problems along with other problems detected.
- Linter configures the Qodana linter.
  Here, select Custom and in the field below specify the Qodana for Ruby linter.
- Version is by default set to Latest.
- Inspection profile defines an inspection profile:
  - qodana.starter (default) is one of the default profiles.
  - Profile name lets you specify a profile, see the Existing Qodana profiles section for details.
  - Profile path lets you specify the path to your custom profile. To use this option, make sure that you also configure the custom profile in the qodana.yaml file.
- Cloud Token configures a project token generated in Qodana Cloud.
- Additional Docker arguments configure the arguments accepted by a Docker image, see the Configuration options section for details.
- Additional Qodana arguments let you extend the default Qodana functionality, see the Types of options section for details.
- Qodana CLI version lets you specify the Qodana CLI version that you would like to use.
Click the Save button.

More configuration examples are available in the TeamCity section.

                                    qodana scan \
                                       -e QODANA_TOKEN="<qodana-cloud-token>" \
                                       -l jetbrains/qodana-ruby:2025.1-eap
                                

                                    docker run \
                                       -v <source-directory>/:/data/project/ \
                                       -e QODANA_TOKEN="<cloud-project-token>" \
                                       jetbrains/qodana-ruby:2025.1-eap
                                

If you are using another Qodana Cloud instance than https://qodana.cloud/, override it by declaring the QODANA_ENDPOINT environment variable.

In your browser, open Qodana Cloud to examine the analysis results and reconfigure the analysis. See the Analysis reports section of the documentation for full details.

Explore analysis results

After Qodana analyzed your project and uploaded the analysis results to Qodana Cloud, in Qodana Cloud navigate to your project and review the analysis results report.

To learn more about Qodana report UI, see the Analysis reports section.

Extend Qodana configuration

Adjusting the scope of analysis

Out of the box, Qodana provides two predefined profiles hosted on GitHub:

qodana.starter is the default profile and a subset of the more comprehensive qodana.recommended profile.
qodana.recommended is suitable for running in CI/CD pipelines and mostly implements the default RubyMine profile; see the RubyMine documentation for details.

You can customize Qodana profiles using configurations in YAML and XML formats. To learn more about configuration basics, visit the Configure Qodana your way section of the documentation.

Enabling the baseline feature

Save this snippet to the .github/workflows/code_quality.yml file containing the args: --baseline,qodana.sarif.json option that specifies the path to the SARIF-formatted baseline file:

                      name: Qodana
                      on:
                          workflow_dispatch:
                          pull_request:
                          push:
                              branches: # Specify your branches here
                                  - main # The 'main' branch
                                  - master # The 'master' branch
                                  - 'releases/*' # The release branches
                      jobs:
                          qodana:
                              runs-on: ubuntu-latest
                              permissions:
                                  contents: write
                                  pull-requests: write
                                  checks: write
                              steps:
                                  - uses: actions/checkout@v3
                                    with:
                                        ref: ${{ github.event.pull_request.head.sha }}  # to check out the actual pull request commit, not the merge commit
                                        fetch-depth: 0  # a full history is required for pull request analysis
                                  - name: 'Qodana Scan'
                                    uses: JetBrains/qodana-action@v2025.1
                                    with:
                                        args: |
                                            --baseline,<path/to/qodana.sarif.json>,
                                            --linter,jetbrains/qodana-ruby:2025.1-eap
                                    env:
                                        QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}
                  

In the Jenkinsfile, save the configuration containing the --baseline <path/to/qodana.sarif.json> line that specifies the path to the SARIF-formatted baseline file:

                        pipeline {
                          environment {
                            QODANA_TOKEN=credentials('qodana-token')
                          }
                          agent {
                            docker {
                              args '''
                                   -v "${WORKSPACE}":/data/project
                                   --entrypoint=""
                              '''
                              image 'jetbrains/qodana-ruby:2025.1-eap'
                            }
                          }
                          stages {
                            stage('Qodana') {
                              steps {
                                sh '''
                                   qodana \
                                   --baseline <path/to/qodana.sarif.json>
                                '''
                              }
                            }
                          }
                        }
                    

In the root directory of your project, save this snippet to the .gitlab-ci.yml file:

                    include:
                        - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2025.1
                          inputs:
                              args: --linter,jetbrains/qodana-ruby:2025.1-eap
                  

The --baseline <path/to/qodana.sarif.json> line in the script block invokes the baseline feature.

In the TeamCity UI, navigate to the configuration page of a build where you would like to run Qodana.
On the Build Configuration Settings page, navigate to the Build steps page.
On the Build steps page, click the Add build step button.
On the page that opens, select the Qodana runner.
On the New Build Step: Qodana page, click Show advanced options and configure the Qodana runner:
- Step name uniquely identifies this step among other build steps.
- Step ID uniquely identifies this step among other build steps.
- Execute step configures the build condition that will trigger this build step.
- Working directory sets the directory for the build process, see the TeamCity documentation for details. You can leave this field empty if the Checkout directory parameter is specified on the Version Control Settings tab.
- Report ID uniquely identifies the report to let you distinguish between multiple reports when several analysis steps are configured within a single build.
- The Forward reports to TeamCity tests checkbox configures Qodana report availability in the Test tab of the TeamCity UI. Using this option, you can view codebase problems along with other problems detected.
- Linter configures the Qodana linter.
  Here, select Custom and in the field below specify the Qodana for Ruby linter.
- Version is by default set to Latest.
- Inspection profile defines an inspection profile:
  - qodana.starter (default) is one of the default profiles.
  - Profile name lets you specify a profile, see the Existing Qodana profiles section for details.
  - Profile path lets you specify the path to your custom profile. To use this option, make sure that you also configure the custom profile in the qodana.yaml file.
- Cloud Token configures a project token generated in Qodana Cloud.
- Additional Docker arguments configure the arguments accepted by a Docker image, see the Configuration options section for details.
- Additional Qodana arguments let you extend the default Qodana functionality, see the Types of options section for details.
  In this field, specify the baseline feature using the --baseline <path/to/qodana.sarif.json> option.
- Qodana CLI version lets you specify the Qodana CLI version that you would like to use.
Click the Save button.

Choose how you would like to run the baseline feature from the command line:

                              qodana scan \
                                  -v <path_to_baseline>:/data/base/ \
                                  -e QODANA_TOKEN="<cloud-project-token>" \
                                  -l jetbrains/qodana-ruby:2025.1-eap \
                                  --baseline /data/base/<path-relative-to-project-dir>/qodana.sarif.json
                          

                              docker run \
                                  -v <source-directory>/:/data/project/ \
                                  -v <path_to_baseline>:/data/base/ \
                                  -e QODANA_TOKEN="<cloud-project-token>" \
                                  jetbrains/qodana-ruby:2025.1-eap \
                                  --baseline /data/base/<path-relative-to-project-dir>/qodana.sarif.json
                          

Enabling the quality gate

You can configure quality gates for:

The total number of project problems
Multiple quality gates for problem severities
Code coverage thresholds

Save this snippet to the qodana.yaml file:

            failureConditions:
                severityThresholds:
                    any: 50 # Total number of problems in all severities
                    critical: 1 # Severities
                    high: 2
                    moderate: 3
                    low: 4
                    info: 5
                testCoverageThresholds:
                    fresh: 6 # Fresh code coverage
                    total: 7 # Total percentage
        

Analyzing pull requests

The Qodana Scan GitHub action automatically analyzes all pull requests, so you do not have to provide any additional configuration. Save this configuration to the .github/workflows/code_quality.yml file:

            name: Qodana
            on:
                workflow_dispatch:
                pull_request:
                push:
                    branches: # Specify your branches here
                        - main # The 'main' branch
                        - 'releases/*' # The release branches
            jobs:
                qodana:
                    runs-on: ubuntu-latest
                    permissions:
                        contents: write
                        pull-requests: write
                        checks: write
                    steps:
                        - uses: actions/checkout@v3
                          with:
                              ref: ${{ github.event.pull_request.head.sha }}  # to check out the actual pull request commit, not the merge commit
                              fetch-depth: 0  # a full history is required for pull request analysis
                        - name: 'Qodana Scan'
                          uses: JetBrains/qodana-action@v2025.1
                          with:
                              args: --linter,jetbrains/qodana-ruby:2025.1-eap
                          env:
                              QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}
        

In the root directory of your project, save the .gitlab-ci.yml file containing the following snippet:

                  include:
                      - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2025.1
                        inputs:
                            args: --linter,jetbrains/qodana-ruby:2025.1-eap
                

This snippet enables merge request analysis.

Information about configuring TeamCity for analyzing pull and merge requests is available on the TeamCity documentation portal.

To analyze changes in your code, employ the --diff-start option and specify a hash of the commit that will act as a base for comparison:

                    qodana scan \
                       -e QODANA_TOKEN="<cloud-project-token>" \
                       -l jetbrains/qodana-ruby:2025.1-eap \
                       --diff-start=<GIT_START_HASH>
                

                    docker run \
                       -v $(pwd):/data/project/ \
                       -e QODANA_TOKEN="<cloud-project-token>" \
                       jetbrains/qodana-ruby:2025.1-eap \
                       --diff-start=<GIT_START_HASH>
                

Supported technologies and features

Qodana for Ruby provides inspections for the following technologies.

Programming languages	Ruby JavaScript and TypeScript
Frameworks and libraries	Cucumber Node.js RBS React Ruby on Rails Sass Vue
Databases and ORM	MongoDB MySQL Oracle PostgreSQL SQL SQL Server
Markup languages	CSS HTML JSON and JSON5 Less PostCSS RELAX NG XML YAML YARD
Scripting languages	Shell script
Other	HTTP Client Regular expressions Structural search

The Qodana for Ruby linter provides the following Qodana features:

Feature	Available under the license
Baseline	Ultimate and Ultimate Plus
Quality gate	Ultimate and Ultimate Plus

Last modified: 02 June 2025