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

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

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

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

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

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

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

以下はワークフローからの抜粋で、まず言語を指定するジョブ戦略におけるマトリクスの使用法を示し、次に「Initialize CodeQL」のステップで各言語を参照しています。
```
jobs:
  analyze:
    ...
    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 ワークフローを設定する」を参照してく� さい。

リポジトリの一部が `autobuild` を使用して分析されない

CodeQL の autobuild 機能は、ヒューリスティックスを使用してリポジトリにコードをビルドしますが、このアプローチでは、リポジトリの分析が不完全になることがあります。たとえば、単一のリポジトリに複数の build.sh コマンドが存在する� �合、autobuild ステップはコマンドの 1 つしか実行しないため、分析が完了しない� �合があります。これを解決するには、autobuild ステップを、分析するすべてのソースコードをビルドするビルドステップに置き換えます。詳しい情� �については、「コンパイル型言語の 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 を編集する」を参照してく� さい。