CodeQL ワークフローのトラブルシューティング

ノート: この記事は、GitHub Enterprise Serverのこのバージョンにおける初期リリースに含まれる、このバージョンのCodeQLアクション及び関連するCodeQL CLIバンドルで利用できる機能について説明しています。 Enterpriseでさらに新しいバージョンのCodeQLアクションを使用しているなら、最新の機能に関する情報についてはGitHub Enterprise Cloudの記事を参照してください。最新バージョンの利用に関する詳しい情報については「アプライアンスのコードスキャンニングの設定」を参照してください。

デバッグ用の詳細なログを生成する

詳細なログ出力を生成するため、ステップのデバッグロギングを有効化することができます。詳しい情報については、「デバッグログの有効化」を参照してください。

CodeQLのデバッグ成果物の作成

CodeQLのデバッグに役立てるために、成果物を取得できます。デバッグ成果物は、debug-artifactsという名前の成果物としてワークフローの実行にアップロードされます。このデータには、CodeQLログ、CodeQLデータベース（群）、ワークフローが生成したSARIFファイル（群）が含まれます。

これらの成果物は、CodeQL code scanningの問題をデバッグするために役立ちます。 GitHubのサポートに連絡すると、このデータを求められることがあります。

ワークフローのフラグを利用したCodeQLのデバッグ用成果物の作成

CodeQLのデバッグ用成果物は、ワークフローのフラグを使って作成できます。そのためには、CodeQL分析ワークフローファイルのinitステップを変更し、debug: trueを設定しなければなりません。

- name: Initialize CodeQL
  uses: github/codeql-action/init@v1
  with:
    debug: true

コンパイル言語の自動ビルドの失敗

プロジェクト内のコンパイル言語のコードの自動ビルドが失敗した場合は、次のトラブルシューティングのステップを試してください。

code scanning ワークフローから autobuild ステップを削除し、特定のビルドステップを追加します。ワークフローの編集に関する詳しい情報は、「code scanning を設定する」を参照してください。 autobuild ステップの置き換えに関する詳細は、「コンパイル型言語の CodeQL ワークフローを設定する」を参照してください。
ワークフローが解析する言語を明示的に指定していない場合、CodeQL はコードベースでサポートされている言語を暗黙的に検出します。この設定では、コンパイル型言語である C/C++、C#、Java のうち、CodeQL はソースファイルの数が最も多い言語のみを解析します。ワークフローを編集し、解析する言語を指定したマトリクスを追加してください。デフォルトの CodeQL 解析では、こうしたマトリクスを使用しています。

以下はワークフローからの抜粋で、まず言語を指定するジョブ戦略におけるマトリクスの使用法を示し、次に「Initialize CodeQL」のステップで各言語を参照しています。
```
jobs:
  analyze:
    permissions:
      security-events: write
      actions: read
    ...
    strategy:
      fail-fast: false
      matrix:
        language: ['csharp', 'cpp', 'javascript']

    steps:
    ...
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v1
        with:
          languages: ${{ matrix.language }}
```
ワークフローの編集に関する詳しい情報については、「コードスキャンを設定する」を参照してください。

ビルド中にコードが見つからない

ワークフローでエラー No source code was seen during the build または The process '/opt/hostedtoolcache/CodeQL/0.0.0-20200630/x64/codeql/codeql' failed with exit code 32 が発生した場合、CodeQL がコードを監視できなかったことを示しています。このようなエラーが発生する理由として、次のようなものがあります。

リポジトリには、CodeQLにサポートされている言語で書かれたソースコードは含まれていないかもしれません。サポートされている言語のリストを確認し、CodeQLワークフローを削除してください。詳しい情報については「CodeQLでのコードスキャンニングについて」を参照してください。
自動言語検出により、サポートされている言語が特定されたが、リポジトリにその言語の分析可能なコードがない。一般的な例としては、言語検出サービスが .h や .gyp ファイルなどの特定のプログラミング言語に関連付けられたファイルを見つけたが、対応する実行可能コードがリポジトリに存在しない場合です。この問題を解決するには、language マトリクスにある言語のリストを更新し、解析する言語を手動で定義します。たとえば、次の設定では Go と JavaScript のみを分析します。
```
strategy:
  fail-fast: false
  matrix:
    # 以下のリストを変更して、言語の自動検出をオーバーライド
    # サポートされているオプションは、デフォルトのワークフローのコメントにリストされている
    language: ['go', 'javascript']
```
詳しい情報については、上記「コンパイル言語の自動ビルドの失敗」にあるワークフローの抜粋を参照してください。
code scanning ワークフローはコンパイルされた言語（C、C++、C#、または Java）を分析しているが、コードはコンパイルされていない。デフォルトでは、CodeQL 分析ワークフローには autobuild ステップが含まれていますが、このステップはベストエフォートプロセスを表しており、特定のビルド環境によっては、コードのビルドに失敗する可能性があります。 autobuild ステップを削除し、ビルドステップを手動で含めない場合も、コンパイルが失敗する可能性があります。ビルドステップの指定に関する詳細は、「コンパイル型言語の CodeQL ワークフローを設定する」を参照してください。
ワークフローはコンパイルされた言語（C、C++、C#、または Java）を分析しているが、パフォーマンスを向上させるためにビルドの一部がキャッシュされている（Gradle や Bazel などのビルドシステムで発生する可能性が最も高い）。 CodeQL はコンパイラのアクティビティを監視してリポジトリ内のデータフローを理解するため、CodeQL は分析を実行するために完全なビルドを実行する必要があります。
ワークフローはコンパイルされた言語（C、C++、C＃、または Java）を分析しているが、ワークフローの init ステップと analyze ステップの間でコンパイルが行われていない。 CodeQL では、コンパイラのアクティビティを監視して分析を実行するために、これらの 2 つのステップ間でビルドを行う必要があります。
コンパイルされたコード（C、C++、C#、または Java）は正常にコンパイルされたが、CodeQL がコンパイラの呼び出しを検出できない。一般的な原因は次のようなものです。
- ビルドプロセスを CodeQL とは別のコンテナで実行している。詳しい情報については、「コンテナで CodeQL コードスキャンを実行する」を参照してください。
- デーモンプロセスを使用して、GitHub Actions の外部で分散ビルドシステムによりビルドしている。
- CodeQL は、使用されているコンパイラを認識していない。
.NET Framework プロジェクト、およびdotnet build または msbuild を使用する C# プロジェクトでは、コードをビルドするときに、ワークフローの run ステップで /p:UseSharedCompilation=false を指定する必要があります。

たとえば、次の C# に対する設定では、最初のビルドステップ中にフラグが渡されます。
```
- run: |
    dotnet build /p:UseSharedCompilation=false
```
特定のコンパイラまたは設定で別の問題が発生した場合は、your site administrator までお問い合わせください。

ビルドステップの指定に関する詳細は、「コンパイル型言語の CodeQL ワークフローを設定する」を参照してください。

スキャンされたコードの行数が期待よりも少ない

C/C++、C#、Go、Javaなどのコンパイル言語については、CodeQLは分析の際にビルドされるファイルだけをスキャンします。したがって、正しくコンパイルされなかったソースコードがある場合、スキャンされるコードの行数は期待よりも少なくなります。これが生じるにはいくつかの理由があります。

CodeQLのautobuild機能が、リポジトリ中のコードをビルドするのにヒューリスティックスを使う。しかし、このアプローチではリポジトリの分析が不完全に終わることがあります。たとえば単一のリポジトリ中に複数のbuild.shコマンドがある場合、autobuildステップがそれらのコマンドの1つだけを実行するため、コンパイルされないソースファイルがでてくることによって、分析が完全ではなくなるかもしれません。
CodeQLでは動作しないコンパイラがあり、コードの分析の際に問題が生じることがあります。たとえばProject Lombokは非公開のコンパイラAPIを使ってコンパイラの動作を変更しています。これらのコンパイラの変更で使われている推定はCodeQLのJava extractorでは有効ではないため、コードは分析できません。

CodeQL分析が期待よりも少ないコードの行数しかスキャンしない場合、必要なソースファイルが確実にすべてコンパイルされるようにするために試せる方法がいくつかあります。

`autobuild`ステップの置き換え

autobuildステップを本番環境で使っているのと同じビルドコマンドで置き換えてください。こうすることで、スキャンしたいすべてのソースファイルをコンパイルする正確な方法をCodeQLが知ることができます。詳しい情報については、「コンパイル型言語の CodeQL ワークフローを設定する」を参照してください。

CodeQLコードベース中にあるソースファイルのコピーの検査

CodeQLデータベース中に含まれているソースコードのコピーを調べることで、分析されなかったソースファイルがあるのはなぜなのかを知ることができるかもしれません。 Actionsワークフローからデータベースを取得するには、CodeQLワークフローファイルのinitステップを修正し、debug: trueを設定してください。

- name: Initialize CodeQL
  uses: github/codeql-action/init@v1
  with:
    debug: true

これで、データベースがアクションの成果物としてアップロードされ、ローカルマシンにダウンロードできるようになります。詳しい情報については「ワークフローの成果物の保存」を参照してください。

成果物には、CodeQLによってスキャンされたソースのアーカイブされたコピーがsrc.zipという名前で含まれます。リポジトリ中のソースコードファイルとsrc.zip中のファイルを比較すれば、どういった種類のファイルが欠けているかが分かります。分析されなかったファイルの種類が分かれば、CodeQL分析のためのワークフローをどのように変更しなければならないかは簡単に理解できるようになります。

生成されたコードで見つかったアラート

Java、C、C++、C# などのコンパイルされた言語の場合、CodeQL はワークフローの実行中に作成されたすべてのコードを分析します。分析するコードの量を制限するには、run ブロックで独自のビルドステップを指定して、分析するコードのみをビルドします。独自のビルドステップの指定と、pull_request および push イベントの paths または paths-ignore フィルタの使用を組み合わせて、特定のコードが変更されたときにのみワークフローが実行されるようにすることができます。詳細については、「GitHub Actionsのワークフロー構文」を参照してください。

ソースコードをコンパイルすることなく CodeQL が分析する Go、JavaScript、Python、TypeScript などの言語の場合、追加の設定オプションを指定して分析するコードの量を制限できます。詳しい情報については、「スキャンするディレクトリを指定する」を参照してください。

データベース中の抽出エラー

CodeQLチームは、すべてのそー祖ファイルが確実にスキャンできるようにするため、重要な抽出エラーに取り組んでいます。とはいえ、CodeQLの抽出部は、データベースの生成時にエラーを生成する事があります。 CodeQLは、データベースの生成の間に生成された抽出エラーと警告に関する情報を、ログファイル中に提供します。抽出の診断情報は、全体的なデータベースの健全性を示します。ほとんどの抽出部のエラーは、分析に大きな影響を与えません。少数の抽出部のエラーは健全なもので、通常は良好な分析状況を示します。

ただし、データベースの生成の間にコンパイルされたファイルの大部分で抽出部のエラーが出ているなら、エラーの詳細をみていくつかのソースファイルが正しく抽出されなかった理由を利用しようとしてみるべきです。

ビルドに時間がかかりすぎる

CodeQL 分析でのビルドの実行に時間がかかりすぎる場合は、ビルド時間を短縮するための方法がいくつかあります。

メモリまたはコアを増やす

セルフホストランナーを使用して CodeQL 解析を実行している場合、ランナーのメモリやコア数を増やすことができます。

マトリックスビルドを使用して分析を並列化する

デフォルトの CodeQL分析ワークフローは言語のマトリクスを使用しており、これにより各言語の解析が並列で実行される場合があります。「Initialize CodeQL」ステップで解析する言語を直接指定している場合、各言語の解析は順次行われます。複数の言語で解析を高速化するには、マトリクスを使用するようワークフローを変更してください。詳しい情報については、上記「コンパイル言語の自動ビルドの失敗」にあるワークフローの抜粋を参照してください。

1 つのワークフローで分析されるコードの量を減らす

一般的に、分析時間は分析されるコードの量に比例します。たとえば、テストコードを除外したり、一度にコードのサブセットのみを分析する複数のワークフローに分析を分割したりするなど、一度に分析されるコードの量を減らすことで、分析時間を短縮できます。

Java、C、C++、C# などのコンパイルされた言語の場合、CodeQL はワークフローの実行中に作成されたすべてのコードを分析します。分析するコードの量を制限するには、run ブロックで独自のビルドステップを指定して、分析するコードのみをビルドします。独自のビルドステップの指定と、pull_request および push イベントの paths または paths-ignore フィルタの使用を組み合わせて、特定のコードが変更されたときにのみワークフローが実行されるようにすることができます。詳細については、「GitHub Actionsのワークフロー構文」を参照してください。

ソースコードをコンパイルすることなく CodeQL が分析する Go、JavaScript、Python、TypeScript などの言語の場合、追加の設定オプションを指定して分析するコードの量を制限できます。詳しい情報については、「スキャンするディレクトリを指定する」を参照してください。

上記のように分析を複数のワークフローに分割する場合でも、リポジトリ内のすべてのコードを分析する schedule で実行されるワークフローを少なくとも 1 つ用意することをお勧めします。 CodeQL はコンポーネント間のデータフローを分析するため、一部の複雑なセキュリティ動作は完全なビルドでのみ検出される場合があります。

`schedule` イベント中にのみ実行する

それでも分析が遅すぎるために、push または pull_request イベント中に実行できない場合は、schedule イベントでのみ分析をトリガーすることをお勧めします。詳しい情報については、「イベント」を参照してください。

ワークフローが実行するクエリスイートの確認

デフォルトでは、各言語で3つの主なクエリスイートがあります。 CodeQLデータベースの構築を最適化し、それでもそのプロセスが長くなりすぎるのであれば、実行するクエリ数を減らすことができます。デフォルトのクエリスイートは自動的に実行されます。これには、最も誤判定結果の比率が低く、最も高速なセキュリティクエリが含まれます。

デフォルトのクエリに加えて、追加のクエリもしくはクエリスイートを実行することもできます。実行する追加のクエリスイートもしくは追加のクエリをワークフローが定義しているかは、queries要素を使って確認してください。追加のクエリスイートもしくはクエリを無効化して、試してみることができます。詳しい情報については、「code scanning を設定する」を参照してください。

エラー: 「サーバーエラー」

サーバーエラーにより code scanning のワークフローが実行できない場合は、ワークフローを再実行してください。問題が解決しない場合は、your site administrator にお問い合わせください。

エラー:「ディスク不足」または「メモリ不足」

非常に大きいプロジェクトの場合、CodeQLはランナーのディスクもしくはメモリを使い切ってしまうかもしれません。この問題が生じたら、ランナー上のメモリを増やしてみてください。

エラー: "is not a .ql file, .qls file, a directory, or a query pack specification"

CodeQLが名前付きクエリ、クエリスイート、あるいはクエリパックをワークフロー中のリクエストされた場所で見つけられなかった場合、このエラーが表示されます。このエラーには、2つの一般的な原因があります。

ワークフロー中にタイプミスがある。
ワークフローがパスで参照しているリソースの名前が変更されたり、削除されたり、新しい場所に移動されたりしている。

リソースの場所を確認したあと、ワークフローを更新して正しい場所を指定できます。 Goの分析で追加のクエリを実行する場合、ソースファイルの移動の影響を受けているかもしれません。詳しい情報については、github/codeql-goリポジトリの場所の移動のお知らせ:github/codeql-goはgithub/codeqlに移動しましたを参照してください。

Warning: "git checkout HEAD^2 is no longer necessary"

古いCodeQLワークフローを使っていると、"Initialize CodeQL"アクションからの出力に以下の警告が含まれていることがあります。

Warning: 1 issue was detected with this workflow: git checkout HEAD^2 is no longer 
necessary. Please remove this step as Code Scanning recommends analyzing the merge 
commit for best results.

これは、以下の行をCodeQLワークフローから削除することによって修正してください。これらの行は、初期バージョンのCodeQLワークフロー中のAnalyzeジョブのstepsセクションに含まれています。

        with:
          # これがPull Requestであればheadをチェックアウトできるよう、
          # 少なくとも直接の親をフェッチしなければならない。
          fetch-depth: 2

      # この実行がPull Requestのイベントでトリガされたのなら、
      # マージコミットの代わりにPull Requestのheadをチェックアウトする。
      - run: git checkout HEAD^2
        if: ${{ github.event_name == 'pull_request' }}

ワークフローの修正されたstepsセクションは以下のようになります。

    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      # CodeQL ツールをスキャンニングのために初期化。.
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v1

      ...

CodeQL ワークフローファイルの編集に関する詳しい情報については、「code scanning を編集する」を参照してください。