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

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

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

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

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

• 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 がコードを監視できなかったことを示しています。 このようなエラーが発生する理由として、次のようなものがあります。

1. 自動言語検出により、サポートされている言語が特定されたが、リポジトリにその言語の分析可能なコードがない。 一般的な例としては、言語検出サービスが .h や .gyp ファイルなどの特定のプログラミング言語に関連付けられたファイルを見つけたが、対応する実行可能コードがリポジトリに存在しない場合です。 この問題を解決するには、language マトリクスにある言語のリストを更新し、解析する言語を手動で定義します。 たとえば、次の設定では Go と JavaScript のみを分析します。

   strategy:
     fail-fast: false
     matrix:
       # Override automatic language detection by changing the list below
       # Supported options are:
       # ['csharp', 'cpp', 'go', 'java', 'javascript', 'python']
       language: ['go', 'javascript']
   

   詳しい情報については、上記「コンパイル言語の自動ビルドの失敗」にあるワークフローの抜粋を参照してください。

2. code scanning ワークフローはコンパイルされた言語（C、C++、C#、または Java）を分析しているが、コードはコンパイルされていない。 デフォルトでは、CodeQL 分析ワークフローには autobuild ステップが含まれていますが、このステップはベスト エフォートプロセスを表しており、特定のビルド環境によっては、コードのビルドに失敗する可能性があります。 autobuild ステップを削除し、ビルドステップを手動で含めない場合も、コンパイルが失敗する可能性があります。 ビルドステップの指定に関する詳細は、「コンパイル型言語の CodeQL ワークフローを設定する」を参照してください。

3. ワークフローはコンパイルされた言語（C、C++、C#、または Java）を分析しているが、パフォーマンスを向上させるためにビルドの一部がキャッシュされている（Gradle や Bazel などのビルドシステムで発生する可能性が最も高い）。 CodeQL はコンパイラのアクティビティを監視してリポジトリ内のデータフローを理解するため、CodeQL は分析を実行するために完全なビルドを実行する必要があります。

4. ワークフローはコンパイルされた言語（C、C++、C＃、または Java）を分析しているが、ワークフローの init ステップと analyze ステップの間でコンパイルが行われていない。 CodeQL では、コンパイラのアクティビティを監視して分析を実行するために、これらの 2 つのステップ間でビルドを行う必要があります。

5. コンパイルされたコード（C、C++、C#、または Java）は正常にコンパイルされたが、CodeQL がコンパイラの呼び出しを検出できない。 一般的な原因は次のようなものです。

   • ビルドプロセスを CodeQL とは別のコンテナで実行している。 詳しい情報については、「コンテナで CodeQL コードスキャンを実行する」を参照してください。
   • デーモンプロセスを使用して、GitHub Actions の外部で分散ビルドシステムによりビルドしている。
   • CodeQL は、使用されているコンパイラを認識していない。

   .NET Framework プロジェクト、および .NET Core 2 をターゲットとする dotnet build または msbuild を使用する C# プロジェクトでは、コードをビルドするときに、ワークフローの run ステップで /p:UseSharedCompilation=false を指定する必要があります。 .NET Core 3.0 以降では、UseSharedCompilation フラグは必要ありません。

   たとえば、次の C# に対する設定では、最初のビルドステップ中にフラグが渡されます。

   - run: |
       dotnet build /p:UseSharedCompilation=false 
   

   特定のコンパイラまたは設定で別の問題が発生した場合は、GitHub Support までお問い合わせください。

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

Lines of code scanned are lower than expected

For compiled languages like C/C++, C#, Go, and Java, CodeQL only scans files that are built during the analysis. Therefore the number of lines of code scanned will be lower than expected if some of the source code isn't compiled correctly. This can happen for several reasons:

1. The CodeQL autobuild feature uses heuristics to build the code in a repository. However, sometimes this approach results in an incomplete analysis of a repository. For example, when multiple build.sh commands exist in a single repository, the analysis may not be complete since the autobuild step will only execute one of the commands, and therefore some source files may not be compiled.
2. Some compilers do not work with CodeQL and can cause issues while analyzing the code. For example, Project Lombok uses non-public compiler APIs to modify compiler behavior. The assumptions used in these compiler modifications are not valid for CodeQL's Java extractor, so the code cannot be analyzed.

If your CodeQL analysis scans fewer lines of code than expected, there are several approaches you can try to make sure all the necessary source files are compiled.

Replace the autobuild step

Replace the autobuild step with the same build commands you would use in production. This makes sure that CodeQL knows exactly how to compile all of the source files you want to scan. 詳しい情報については、「コンパイル型言語の CodeQL ワークフローを設定する」を参照してください。

Inspect the copy of the source files in the CodeQL database

You may be able to understand why some source files haven't been analyzed by inspecting the copy of the source code included with the CodeQL database. To obtain the database from your Actions workflow, add an upload-artifact action after the analysis step in your code scanning workflow:

- uses: actions/upload-artifact@v2
  with:
    name: codeql-database
    path: ../codeql-database

This uploads the database as an actions artifact that you can download to your local machine. For more information, see "Storing workflow artifacts."

The artifact will contain an archived copy of the source files scanned by CodeQL called src.zip. If you compare the source code files in the repository and the files in src.zip, you can see which types of file are missing. Once you know what types of file are not being analyzed, it is easier to understand how you may need to change the workflow for CodeQL analysis.

Extraction errors in the database

The CodeQL team constantly works on critical extraction errors to make sure that all source files can be scanned. However, the CodeQL extractors do occasionally generate errors during database creation. CodeQL provides information about extraction errors and warnings generated during database creation in a log file. The extraction diagnostics information gives an indication of overall database health. Most extractor errors do not significantly impact the analysis. A small number of extractor errors is healthy and typically indicates a good state of analysis.

However, if you see extractor errors in the overwhelming majority of files that were compiled during database creation, you should look into the errors in more detail to try to understand why some source files weren't extracted properly.

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

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 イベントでのみ分析をトリガーすることをお勧めします。 詳しい情報については、「イベント」を参照してください。

分析プラットフォーム間で結果が異なる

Pythonで書かれたコードを分析しているなら、CodeQL分析ワークフローをLinux、macOS、Windowsのいずれで実行しているかによって、異なる結果が得られるかもしれません。

GitHubがホストするLinuxを使用したランナーでは、CodeQL分析ワークフローはPythonの依存関係をインストールして分析しようとし、それによってより多くの結果につながることがあります。 自動インストールを無効にするには、ワークフローの"Initialize CodeQL"ステップにsetup-python-dependencies: falseを追加してください。 Pythonの依存関係の分析の設定に関する詳しい情報については「Pythonの依存関係の分析」を参照してください。

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

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

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

On very large projects, CodeQL may run out of disk or memory on the hosted GitHub Actions runner. ホストされたGitHub Actionsランナーでこの問題が生じた場合は、弊社が問題を調査できるようGitHub Supportに連絡してください。

Dependabotを使用している際のError: 403 "Resource not accessible by integration"

Dependabotは、ワークフローの実行をトリガーする際に信頼できないと見なされ、ワークフローは読み取りのみのスコープで実行されます。 ブランチに対するcode scanningの結果をアップロードするには、通常security_events: writeスコープが必要になります。 ただし、pull_requestイベントがアクションの実行をトリガーした際には、code scanning初音に結果のアップロードを許可します。 これが、Dependabotブランチではpushイベントの代わりにpull_requestイベントを使うことをおすすめする理由です。

シンプルなアプローチは、このブランチ群に対してオープンされたPull Requestとともに、デフォルトブランチやその他の重要な長時間実行されるブランチに対するプッシュで実行することです。

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

別のアプローチは、Dependabotブランチを除くすべてのプッシュに対して実行することです。

on:
  push:
    branches-ignore:
      - 'dependabot/**'
  pull_request:

デフォルトブランチで分析が引き続き失敗する

CodeQL分析ワークフローがデフォルトブランチに対するコミットで依然として失敗するなら、以下を確認してください。

• Dependabotがそのコミットを作成したか
• コミットを含むPull Requestが@dependabot squash and mergeを使ってマージされたかどうか

この種のマージコミットはDependabotによって作成されるので、このコミットで実行されるワークフローは読み取りのみの権限を持つことになります。 code scanningとDependabotのセキュリティ更新またはバージョン更新をリポジトリで有効化した場合は、Dependabotの@dependabot squash and mergeコマンドは使わないことをおすすめします。 その代わりに、リポジトリで自動マージを有効化できます。 これは、すべての必須レビューが満たされ、ステータスチェックをパスしたら、Pyll Requestは自動的にマージされるということです。 自動マージの有効化に関する詳しい情報については「Pull Requestの自動マージ」を参照してください。

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 を編集する」を参照してください。