コンパイル済み言語の CodeQL ワークフローを構成する

CodeQL 分析ワークフローとコンパイル型言語について

CodeQL code scanning の場合、コードを解析し、code scanning を自動的に構成する既定の設定を使うか、編集できるワークフローファイルを生成する詳細設定を使うことができます。現在のところ、既定の設定ではコンパイルされた言語がサポートされないため、詳細設定を使う必要があります。詳しくは、「リポジトリの code scanning を構成する」を参照してください。

通常、code scanning の既定のワークフローファイルを編集する必要はありません。ただし、必要な場合にはワークフローを編集して設定の一部をカスタマイズできます。たとえば、GitHub の CodeQL 分析ワークフローを編集すると、スキャンの頻度、スキャンする言語やディレクトリ、CodeQL code scanning を使ったコード内での検索対象を指定できます。コードのコンパイルに特定のコマンドセットを使う場合にも、CodeQL 分析ワークフローの編集が必要となる場合があります。code scanning の構成とワークフローファイルの編集に関する一般的な情報については、「code scanning のカスタマイズ」と「GitHub Actions について」を参照してください。

CodeQL の autobuild について

Code scanning は、1 つ以上のデータベースに対してクエリを実行することにより機能します。各データベースには、リポジトリにあるすべてのコードを 1 つの言語で表わしたものが含まれています。コンパイル型言語の C/C++、C#、Go、Kotlin、Java では、このデータベースを生成するプロセスに、コードのビルドとデータの抽出が含まれています。これらの言語では、CodeQL は、ビルドされたリポジトリ内のソースファイルを分析します。これらの言語の場合は、autobuild を無効にし、その代わりにカスタムビルドコマンドによってビルドされたファイルのみを分析するためにこれらのカスタムコマンドを使用できます。

サポートされているコンパイル言語の場合、CodeQL 分析ワークフローの autobuild アクションを使ってコードをビルドできます。これにより、C/C++、C#、Go、Kotlin、Java の明示的なビルドコマンドを指定する必要がなくなります。

ワークフローで language マトリックスを使っている場合、autobuild はマトリックスに列記された各コンパイル型言語のビルドを試行します。マトリックスがない場合、autobuild は、サポートされているコンパイル型言語で、リポジトリ内のソースファイルの数が最も多いもののビルドを試みます。 Go を除いて、明示的にビルドコマンドを使用しない限り、リポジトリにある他のコンパイル型言語の解析は失敗します。

注: GitHub Actions にセルフホステッドランナーを使う場合は、autobuild プロセスを使うために追加のソフトウェアをインストールすることが必要になる場合があります。さらに、リポジトリに特定のバージョンのビルドツールが必要な場合は、手動でインストールする必要があります。詳しくは、「GitHub ホステッドランナーの概要」をご覧ください。

C/C++

サポートされているシステムの種類	システム名
オペレーティングシステム	Windows、macOS、Linux
ビルドシステム	Windows: MSbuild スクリプトと build スクリプト Linux と macOS: Autoconf、Make、CMake、qmake、 Meson、Waf、SCons、Linux Kbuild、build の各スクリプト

autobuild ステップの動作は、抽出を実行するオペレーティングシステムによって異なります。 Windows の autobuild ステップでは、以下の方法を使って C/C++ に適したビルド方法の自動検出が試みられます。

ルートに最も近いソリューション (.sln) またはプロジェクト (.vcxproj) ファイルで MSBuild.exe を呼び出します。 autobuild が最上位ディレクトリから同じ (最短) 深度で複数のソリューションまたはプロジェクトファイルを検出した場合、それらすべてのビルドが試みられます。
ビルドスクリプトのように見えるスクリプト、つまり build.bat、build.cmd、build.exe を、この順番で呼び出します。

Linux と macOS の autobuild ステップでは、リポジトリ内にあるファイルが確認されて、使われているビルドシステムが特定されます。

ルートディレクトリでビルドシステムを探します。
何も見つからない場合は、C/C++ のビルドシステムで一意のディレクトリをサブディレクトリで検索します。
適切なコマンドを実行してシステムを設定します。

C#

サポートされているシステムの種類	システム名
オペレーティングシステム	Windows と Linux
ビルドシステム	.NET と MSbuild、およびビルドスクリプト

autobuild プロセスは、次の方法を使って C# に適したビルド方法の自動検出を試みます。

ルートに最も近いソリューション (.sln) またはプロジェクト (.csproj) ファイルで dotnet build を呼び出します。
ルートに最も近いソリューションまたはプロジェクトファイルで、MSbuild (Linux) または MSBuild.exe (Windows) を呼び出します。 autobuild が最上位ディレクトリから同じ (最短) 深度で複数のソリューションまたはプロジェクトファイルを検出した場合、それらすべてのビルドが試みられます。
ビルドスクリプトのように見えるスクリプト、つまり build と build.sh (Linux の場合、この順序で) または build.bat、build.cmd、and build.exe (Windows の場合、この順序で) を呼び出します。

Go

サポートされているシステムの種類	システム名
オペレーティングシステム	Windows、macOS、Linux
ビルドシステム	Go モジュール、`dep`、Glide、およびメイクファイルや Ninja スクリプトを含むビルドスクリプト

autobuild プロセスは、すべての .go ファイルを抽出する前に、Go リポジトリで必要な依存関係をインストールする適切な方法の自動検出を試みます。

make、ninja、または ./build を、これらのコマンドのいずれかが成功し、その後の ./build.sh も成功して、必要な依存関係がインストールされたことを示すまで、(この順序で) 呼び出go list ./...します。
これらのコマンドがいずれも成功しなかった場合は、go.mod、Gopkg.toml、または glide.yaml を探し、それぞれの go get (ベンダーが使用していない場合)、dep ensure -v、または glide install を実行して、依存関係のインストールを試みます。
最後に、これらの依存関係マネージャーの構成ファイルが見つからない場合は、GOPATH に追加するのに適したリポジトリディレクトリ構造に調整し直し、go get を使って依存関係をインストールします。抽出が完了すると、ディレクトリ構造は通常に戻ります。
go build ./... を実行するのと同じようにして、リポジトリ内のすべての Go コードを抽出します。

Java と Kotlin

サポートされているシステムの種類	システム名
オペレーティングシステム	Windows、macOS、Linux (制限なし)
ビルドシステム	Gradle、Maven、Ant

autobuild プロセスは、この戦略を適用して、Java コードベース用のビルドシステムの特定を試みます。

ルートディレクトリでビルドファイルを検索します。 Gradle、Maven、Ant の各ビルドファイルを確認します。
最初に見つかったビルドファイルを実行します。 Gradle ファイルと Maven ファイルの両方が存在する場合は、Gradle ファイルが使用されます。
それ以外の場合は、ルートディレクトリの直接サブディレクトリ内でビルドファイルを検索します。 1 つのサブディレクトリにのみビルドファイルが含まれている場合は、そのサブディレクトリで識別された最初のファイルを実行します（1 と同じ環境設定を使用）。複数のサブディレクトリにビルドファイルが含まれている場合は、エラーを報告します。

Swift

サポートされているシステムの種類	システム名
オペレーティングシステム	macOS
ビルドシステム	Xcode

autobuild プロセスでは、Xcode プロジェクトまたはワークスペースから最大のターゲットのビルドが試みられます。

コンパイル言語のビルドステップを追加する

autobuild が失敗した場合、または autobuild プロセスによってビルドされたものとは異なるソースファイルのセットを分析する場合は、ワークフローから autobuild ステップを削除し、ビルドステップを手動で追加する必要があります。 C/C++、C#、Go、Kotlin、Java、Swift プロジェクトの場合、CodeQL では、ユーザーが指定したビルド手順によってビルドされたソースコードが分析されます。ワークフローファイルの編集方法については、「code scanning のカスタマイズ」を参照してください。

autobuild ステップを削除したら、run ステップをコメント解除して、リポジトリに適したビルドコマンドを追加します。ワークフローの run ステップでは、オペレーティングシステムのシェルを使ってコマンドラインプログラムが実行されます。これらのコマンドを変更し、別のコマンドを追加してビルドプロセスをカスタマイズできます。

- run: |
    make bootstrap
    make release

run キーワードについて詳しくは、「GitHub Actions のワークフロー構文」をご覧ください。

リポジトリに複数のコンパイル済み言語が含まれている場合は、言語固有のビルドコマンドを指定できます。たとえば、リポジトリに C/C++、C#、Java が含まれていて、autobuild によって C/C++ と C# は正しくビルドされるが、Java のビルドは失敗する場合は、ワークフローの init ステップの後で次の構成を使用できます。これにより、C/C++ と C# には autobuild をそのまま使用しつつ、Java のビルドステップを指定します。

- if: matrix.language == 'cpp' || matrix.language == 'csharp'
  name: Autobuild
  uses: github/codeql-action/autobuild@v2

- if: matrix.language == 'java'
  name: Build Java
  run: |
    make bootstrap
    make release

if 条件について詳しくは、「GitHub Actions のワークフロー構文」をご覧ください。

autobuild でコードがビルドされない理由に関するヒントとテクニックについては、「CodeQL の詳細セットアップのトラブルシューティング」を参照してください。

コンパイル言語にマニュアルのビルドステップを追加しても、リポジトリで依然としてcode scanningが動作しない場合は、GitHub Supportにお問い合わせください。

Swift の構築に関する考慮事項

注:

Swift の CodeQL 分析は、現在ベータ版です。ベータ版の間、Swift のコードの分析、および付随するドキュメントは、他の言語ほど包括的ではありません。 Swift 5.8 はまだサポートされていません。
分析がフリーズし、ジョブがタイムアウトする場合があります。スタックまたはタイムアウトするジョブで使われる Actions 分の値を制限するため、通常のビルド時の 4 倍のタイムアウトを設定することをお勧めします。

Swift コードのコードスキャンでは、macOS ランナーが既定で使われます。 GitHub ホステッド macOS ランナーは、Linux や Windows のランナーよりコストが高いので、分析したいコードだけビルドすることをお勧めします。 GitHub ホステッドランナーの価格について詳しくは、「GitHub Actions の課金について」をご覧ください。

xcodebuild と swift build はどちらも Swift のビルドでサポートされています。ビルドの間は、1 つのアーキテクチャのみを対象にすることをお勧めします。たとえば、xcodebuild の場合は ARCH=arm64、swift build の場合は --arch arm64 です。

archive と test オプションを xcodebuild に渡すことができます。ただし、標準の xcodebuild コマンドが推奨されます。これは最も速く、CodeQL のスキャンが成功するために必要なものがすべて揃っているはずです。

Swift の分析では、CodeQL データベースを生成する前に、CocoaPods または Carthage によって管理されている依存関係を常に明示的にインストールする必要があります。

コンパイル済み言語の CodeQL ワークフローを構成する

この記事の内容