GitLab CI/CD

GitLab CI/CD(英語) は、様々な CI/CD 手法を用いたソフトウェア開発ツールです。このセクションでは、Qodana Scan GitLab Pipeline コンポーネント(英語)の実行方法について説明します。

始める前に

Qodana クラウド

このセクションのすべての構成例では、Qodana Cloud によって生成されたプロジェクトトークンを使用します。このトークンは、有料の Qodana リンターでは必須であり、コミュニティリンターで使用する場合はオプションです。Qodana Cloud UI でプロジェクトトークンを生成する方法については、次のセクションを参照してください。

プロジェクト設定セクションでは、Qodana Cloud を初めて使用する際にプロジェクトトークンを生成する方法について説明します。
プロジェクトを管理するセクションでは、既存の Qodana Cloud 組織内でプロジェクトトークンを作成する方法について説明します。

プロジェクトトークンを取得したら、パイプラインまたはワークフローで識別するために QODANA_TOKEN 変数を使用できます。

https://qodana.cloud/ 以外の Qodana Cloud インスタンスを使用している場合は、QODANA_ENDPOINT 環境変数を設定して上書きします。

プロジェクトを準備する

プロジェクトリポジトリが GitLab CI/CD からアクセスできることを確認します。

GitLab CI/CD UI で、次の環境変数を作成します。

変数名	説明
`QODANA_TOKEN`	生成されたプロジェクトトークン。GitLab CI/CD Web サイト(英語)の説明に従って、GitLab CI/CD UI に保存してください。また、変数が保護されていないこと、および変数参照を展開フラグが有効になっていることを確認してください。
`QODANA_GITLAB_TOKEN`	クイックフィックスおよびサマリーレポートをマージリクエストのコメントとして表示するには、個人アクセストークン(英語)またはプロジェクトアクセストークン(英語)が必要です。個人アクセストークンの所有者は、すべての Qodana アクションの作成者として表示されるため、プロジェクトアクセストークンの使用をお勧めします。クイックフィックスの場合、アクセストークンを構成するときに `api` および `write_repository` 権限を有効にします。

変数名

説明

QODANA_TOKEN

生成されたプロジェクトトークン。GitLab CI/CD Web サイト(英語)の説明に従って、GitLab CI/CD UI に保存してください。また、変数が保護されていないこと、および変数参照を展開フラグが有効になっていることを確認してください。

QODANA_GITLAB_TOKEN

クイックフィックスおよびサマリーレポートをマージリクエストのコメントとして表示するには、個人アクセストークン(英語)またはプロジェクトアクセストークン(英語)が必要です。個人アクセストークンの所有者は、すべての Qodana アクションの作成者として表示されるため、プロジェクトアクセストークンの使用をお勧めします。

クイックフィックスの場合、アクセストークンを構成するときに api および write_repository 権限を有効にします。

プロジェクトのルートディレクトリに .gitlab-ci.yml ファイルを保存します。このファイルには、GitLab CI/CD で使用されるパイプライン設定が含まれます。

引数表記

Qodana は、引数を指定する際にシェルライクな表記法をサポートしています。この表記法では、キーと値をスペースで区切り、値をシングルクォートまたはダブルクォートで囲みます。これは、Qodana の設定時に引数を指定する推奨方法です。

この表には、両方の表記法の例が含まれています。

サンプル	実際の表記	従来の記法
単一の引数	--profile-name qodana.starter	--profile-name,qodana.starter
2 つの論点	--fail-threshold 10 --property key=value	--fail-threshold,10 --property,key=value
スペース文字を含む値に引用符を使用する	--property "key=some value"	--property,"key=some value"

後方互換性のために、従来のコンマ区切り表記は引き続きサポートされていますが、非推奨であり、Qodana の将来のバージョンで削除されます。

基本構成

Docker モードで Qodana を実行するには、クラウドベースの GitLab CI/CD バージョンで、次のコードスニペットを .gitlab-ci.yml ファイルに保存してください。

         include:
            - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
              inputs:
                 image: jetbrains/qodana-<image>:<version>
      

ここで、inputs:image 引数は、使用したい Docker イメージを指定します。

         include:
            - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
              inputs:
                 os: windows | mac
                 args: --image jetbrains/qodana-<image>:<version>
      

この設定では、inputs:os 引数を使用してオペレーティングシステムを指定します。

Qodana をネイティブモードで実行するには、以下の設定スニペットを使用してください。

         include:
            - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
              inputs:
                 image: <my-custom-docker-image>
                 args: --linter <linter> 
      

ここで、inputs:image は Qodana を実行するカスタム Docker イメージを指定し、inputs:args 引数は Qodana リンターを設定します。

         include:
            - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
              inputs:
                 os: windows | mac
                 args: --linter <linter> --within-docker false
      

ここで、inputs:args 引数は Qodana リンターを設定します。

これらの構成にはすべて、Qodana Scan GitLab Pipeline コンポーネントが含まれており(英語)、キャッシュ、コード品質レポート生成、マージリクエスト分析、およびマージリクエストへのコメントが有効になります。これらの設定は、以下のセクションの説明と構成の章を参照して上書きできます。--image 引数は、Windows の場合は Qodana イメージを、それ以外の場合は macOS を指定します。

付属のコンポーネントは、GitLab CI/CD の他のジョブと同様に設定できる qodana ジョブを作成します。このジョブの定義済み設定は、テンプレート(英語)を使用して確認できます。

例: このコードスニペットでは、before_script を定義し、ジョブ実行ルールを変更し、環境変数を追加できます。

include:
  - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
    inputs:
       image: jetbrains/qodana-<image>:<version>

some-task:
  stage: test
  script:
    - echo "I am complete!"
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

qodana:
  before_script:
    - echo "Qodana job starts..."
  needs:
    - some-task
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  variables:
    MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

GitLab CI/CD のオンプレミスバージョンの場合、.gitlab-ci.yml ファイルに次の構成を保存します。

include:
   - component: $CI_SERVER_FQDN/<org>/<repo>/qodana-gitlab-ci@v2026.1
     inputs:
        image: jetbrains/qodana-<linter>:<version> | <any-custom-docker-image>

このスニペットでは、qodana-gitlab-ci は GitLab CI/CD Web サイト(英語)で説明されている GitLab CI/CD コンポーネントです。

キャッシュを構成する

デフォルトでは、Qodana では次のキーを使用してキャッシュが有効になっています。

      - key: qodana-2026.1-$CI_DEFAULT_BRANCH-$CI_COMMIT_REF_SLUG
        fallback_keys:
           - qodana-2026.1-$CI_DEFAULT_BRANCH-
           - qodana-2026.1-

デフォルトのキャッシュ設定を上書きする場合は、次の構成を使用します。

include:
   - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
     inputs:
        image: jetbrains/qodana-<linter>:<version> | <any-custom-docker-image>

qodana:
   cache:
      - key: qodana-2026.1-$CI_DEFAULT_BRANCH-$CI_COMMIT_REF_SLUG
        fallback_keys:
           - qodana-2026.1-$CI_DEFAULT_BRANCH-
           - qodana-2026.1-
        paths:
           - $[[ inputs.cache-dir ]]

オペレーティングシステムを上書きする

デフォルトでは、Qodana は Linux 用に構成されています。os キーワードを使用してオペレーティングシステムをオーバーライドできます。例: Microsoft Windows の場合は、以下の構成を使用できます。

include:
   - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
     inputs:
        os: windows
        args: --image jetbrains/qodana-<image>:<version>

特定のブランチ

デフォルトでは、Qodana は master および main、ブランチ、リリースブランチ、マージリクエストを分析するように構成されているため、追加の構成を指定する必要はなく、基本構成を使用します。

この動作を上書きしたい場合は、次の設定を変更できます。

include:
   - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
     inputs:
        image: jetbrains/qodana-<image>:<version>

qodana:
  rules:
     # GIT_DEPTH: 0 is required for checkout in case Qodana works in merge request mode 
     # (reports issues that appeared only in that merge request)
     - if: $CI_PIPELINE_SOURCE == "merge_request_event" && $QODANA_MR_MODE == "true"
       variables:
          GIT_DEPTH: 0
     # run analysis in case of merge request
     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
     # restrict branch analysis only to main/master and release branches
     - if: $CI_COMMIT_BRANCH =~ /^releases/ || $CI_COMMIT_BRANCH == "master" || $CI_COMMIT_BRANCH == "main"
        # mr-mode does not make any sense for branch analysis
       variables:
          QODANA_MR_MODE: false

この構成の rules ブロックは、Qodana にどのブランチをインスペクションするかを指示します。

クイックフィックス

次の 2 つの構成方法のいずれかを使用してクイックフィックス戦略を選択します。
# Possible values: apply | cleanup fixesStrategy: apply
# Possible values: --apply-fixes | --cleanup args: --apply-fixes
ニーズに応じて、パイプライン構成で push-fixes プロパティを定義します。
この構成を保存して、修正と元のブランチへのマージリクエストを含む新しいブランチを作成します。
push-fixes: merge-request
この構成を保存して、元のブランチに修正をプッシュします。
push-fixes: branch

以下は、パイプラインを構成するために inputs ブロックを使用する構成例です。

include:
   - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
     inputs:
        image: jetbrains/qodana-<image>:<version>
        push-fixes: merge-request
        args: --apply-fixes

Qodana レポートを公開する

Qodana Cloud を使用せずに、任意のマージリクエストでレポートを使用できるようにするには、upload-result キーワードを使用し、artifact-name キーワードを使用してアーティファクト名を指定します。例:

include:
   - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
     inputs:
        upload-result: true
        artifact-name: Qodana report
        image: jetbrains/qodana-<image>:<version>

パイプラインを同様に構成した場合、次のようになります。

マージリクエストのパイプラインに関連付けられた Qodana レポート
特定の公開された Qodana アーティファクトに対して利用可能なアクション

品質ゲートとベースライン

inputs:args ブロックの --fail-threshold <number> 行と --baseline <path/to/qodana.sarif.json> 行を使用して、品質ゲートとベースライン機能を実行できます。

include:
   - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
     inputs:
        image: jetbrains/qodana-<image>:<version>
        args: |
            --baseline qodana.sarif.json 
            --fail-threshold <number-of-accepted-problems>

コード品質レポート

GitLab CI/CD のマージリクエスト UI を使用して、問題のあるコード行とその説明、および改善のための推奨事項を表示します。

この機能を実装するために、Qodana は、コード品質(英語)でサポートされ、gl-code-quality-report.json ファイルに含まれる JSON 形式の分析レポートを生成します。

この機能はデフォルトで true に設定されているため、追加の設定は必要ありません。必要に応じて、codequality オプションを使用してレポートへのパスを上書きできます。

include:
   - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
     inputs:
        image: jetbrains/qodana-<image>:<version>

qodana:
   artifacts:
      reports:
         codequality: $QODANA_RESULTS_DIR/gl-code-quality-report.json

Qodana ログ

GitLab CI/CD 上の Qodana からログデータを取得するには、次の構成を使用します。

include:
   - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
     inputs:
        image: jetbrains/qodana-<image>:<version>
        upload-result: true
        results-dir: $CI_PROJECT_DIR/.qodana/results

qodana:
   artifacts:
      paths:
         - .qodana/results/
      expose_as: 'Qodana report'
      when: always

この構成では、ログを生成するために .qodana/results ディレクトリを使用し、このディレクトリをアーティファクトとして公開します。

タイムアウトで失敗した Qodana ジョブからログをアップロードするには、パイプラインタイムアウトより小さい値を持つ RUNNER_SCRIPT_TIMEOUT 変数を追加します。

include:
   - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
     inputs:
        image: jetbrains/qodana-<image>:<version>
        upload-result: true
        results-dir: $CI_PROJECT_DIR/.qodana/results

qodana:
   timeout: <specify timeout>
   variables:
      RUNNER_SCRIPT_TIMEOUT: <specified timeout value minus 5 minutes>
   artifacts:
      paths:
         - .qodana/results/
      expose_as: 'Qodana report'
      when: always

詳細は GitLab CI/CD Web サイト(英語)を参照してください。

構成

この表には、inputs ブロックを使用して構成できるオプションのリストが含まれています。

名前	説明	デフォルト値
`stage`	Qodana 実行の CI ステージ	`test`
`job-name`	Qodana ジョブ名。同じパイプライン内で複数の Qodana ジョブを実行する順序をカスタマイズするために使用できます	`qodana`
`args`	追加の Qodana CLI `scan` コマンド(英語)引数。引数をコンマ (`,`) で分割します (例: `-i,frontend,--print-problems`)。オプション。	-
`results-dir`	分析レポートを保存するディレクトリ（プロジェクトルートからの相対パス）。オプション。	`$CI_PROJECT_DIR/.qodana/results`
`upload-result`	Qodana の結果 (SARIF、その他のアーティファクト、ログ) をアーティファクトとしてジョブにアップロードします。オプション。	`false`
`artifact-name`	結果のアップロードに使用する Qodana 結果アーティファクト名を指定します。オプション。	`Qodana report`
`cache-dir`	プロジェクトルートを基準とした Qodana キャッシュを保存するディレクトリ。オプション。	`$CI_PROJECT_DIR/.qodana/caches`
`use-caches`	Qodana 解析には GitHub キャッシュ(英語)を使用します。（任意）	`true`
`code-quality-report`	Qodana が生成したコード品質レポート(英語)を使用する	`true`
`mr-mode`	マージリクエスト内の変更されたファイルのみを分析します。オプション。	`true`
`post-mr-comment`	マージリクエストに Qodana の結果概要を記載したコメントを投稿します。オプションです。	`true`
`push-fixes`	Qodana 修正をリポジトリにプッシュします。`none`、`branch` から現在のブランチ、または `merge-request` にすることができます。オプション。	`none`
`commit-message`	クイックフィックスが適用されたときに使用されるコミットメッセージ	`Apply quick-fixes by Qodana`
`os`	パイプラインの実行に使用するオペレーティングシステム。事前設定に必要です。`linux`、`windows`、`mac` の値を指定できます。	`linux`
`image`	Linux 専用オプション。ジョブ実行に使用されるイメージ。バージョン 2026.1 以降必須	`docker:27.5.1`
`windows-tags`	Windows 専用オプション。ジョブにはカスタムランナータグが使用されます	`- saas-windows-medium-amd64`
`mac-tags`	macOS 専用オプション。作業にはカスタムランナータグが使用されます	`- saas-macos-medium-m1`