CodeQL ワークスペースについて
メモ: この記事では、このバージョンの GitHub Enterprise Server の初期リリースに含まれる CodeQL アクションのバージョンおよび関連する CodeQL CLI バンドルで使用できる機能について説明します。 エンタープライズでより新しいバージョンの CodeQL アクションを使用する場合は、この記事の GitHub Enterprise Cloud バージョンで最新の機能に関する情報を参照してください。 最新バージョンの使用については、「アプライアンス用コードスキャンの構成」を参照してください。
複数の CodeQL パックをグループ化する場合は、CodeQL ワークスペースを使用します。 CodeQL ワークスペースの一般的なユース ケースは、相互に依存する CodeQL ライブラリとクエリ パックのセットを開発することです。 CodeQL パックについて詳しくは、「CodeQL パックを使った分析のカスタマイズ」をご覧ください。
CodeQL ワークスペースの主な利点は、複数の CodeQL パックの開発と保守が容易になることです。 CodeQL ワークスペースを使用すると、クエリを解決する CodeQL コマンドを実行するときに、ワークスペース内のすべての CodeQL パックを相互に "ソース依存関係" として使用できます。__ これにより、複数の関連する CodeQL パックの開発、保守、発行が容易になります。
ほとんどの場合、CodeQL ワークスペースと、それに含まれる CodeQL パックを 1 つの Git リポジトリに格納する必要があります。 これにより、CodeQL 開発環境を簡単に共有できます。
codeql-workspace.yml
ファイル
CodeQL ワークスペースは、codeql-workspace.yml
yaml ファイルで定義されます。 このファイルには、provide
ブロックと、必要に応じて ignore
および registries
ブロックが含まれます。
-
provide
ブロックには、ワークスペースで使用可能な CodeQL パックを定義する glob パターンの一覧が含まれます。 -
ignore
ブロックには、ワークスペースで使用できない CodeQL パックを定義する glob パターンの一覧が含まれます。 -
registries
ブロックには、CodeQL パックの発行に使用されるコンテナー レジストリを制御する GHES URL とパッケージ パターンの一覧が含まれます。 詳しくは、「CodeQL パックを発行して使用する」を参照してください。
provide
または ignore
セクションの各エントリは、qlpack.yml
ファイルの場所にマップする必要があります。 すべての glob パターンは、ワークスペース ファイルを含むディレクトリを基準にして定義されます。 このファイルで受け入れられるパターンの一覧については、「@actions/glob」を参照してください。
たとえば、次の codeql-workspace.yml
ファイルは、codeql-packs
ディレクトリ内のパックを除き、experimental
ディレクトリ内で再帰的に検出されたすべての CodeQL パックを含むワークスペースを定義しています。 registries
ブロックは、codeql/\*
パックを https://ghcr.io/v2/
からダウンロードする必要があることを指定します。これは、GitHub の既定のコンテナー レジストリです。 他のすべてのパックは、GHE_HOSTNAME
のレジストリからダウンロードし、そこに発行する必要があります。
provide:
- "*/codeql-packs/**/qlpack.yml"
ignore:
- "*/codeql-packs/**/experimental/**/qlpack.yml"
registries:
- packages: 'codeql/*'
url: https://ghcr.io/v2/
- packages: '*'
url: https://containers.GHE_HOSTNAME/v2/
想定する CodeQL パックが codeql-workspace.yml
ファイルに含まれていることを確認するには、ワークスペースと同じディレクトリで codeql pack ls
コマンドを実行します。 このコマンドの結果は、ワークスペース内のすべての CodeQL パックの一覧です。
ソース依存関係
ソース依存関係は、CodeQL パッケージ キャッシュの外部にあるローカル ファイル システムから解決される CodeQL パックです。 これらの依存関係は、同じ CodeQL ワークスペース内にあるか、--additional-packs
引数を使用してパス オプションとして指定できます。 クエリをローカルでコンパイルして実行すると、ソース依存関係によって、CodeQL パッケージ キャッシュ内にあるすべての依存関係と、qlpack.yml
で定義されているバージョン制約がオーバーライドされます。 同じワークスペース内の CodeQL パックへの参照はすべて、ソース依存関係として解決されます。
これは、次のようなシナリオで特に役立ちます。
-
実行しているクエリ パックの依存関係の 1 つがまだ発行されていない場合。 ソースから解決することが、そのパックを参照する唯一の方法です。
-
複数のパックを同時に変更し、それらをまとめてテストする必要がある場合。 ソースから解決することで、変更を含むパックのバージョンが確実に使用されます。
CodeQL ワークスペースとクエリ解決
ワークスペース内のすべての CodeQL パックは、クエリまたはパックを解決する CodeQL コマンドを実行するときに、相互にソース依存関係として使用できます。 たとえば、ワークスペース内のパック ディレクトリで codeql pack install
を実行する場合、ワークスペース内にある任意の依存関係をパッケージ キャッシュにダウンロードして codeql-pack.lock.yml
ファイルに追加する代わりに、その依存関係を使用できます。 詳しくは、「CodeQL パックの作成と操作」を参照してください。
同様に、codeql pack publish
を使用して CodeQL クエリ パックを GitHub コンテナー レジストリに発行する場合、このコマンドでは、ローカル パッケージ キャッシュ内にある依存関係を使用する代わりに、常にワークスペースからの依存関係を使用します。
これにより、依存関係内のクエリ ライブラリに対してローカルで行う変更はすべて、そのワークスペースから発行するすべてのクエリ パックに自動的に反映されます。
例
次の codeql-workspace.yml
ファイルを考えてみます。
provide:
- "**/qlpack.yml"
さらに、ワークスペース内の次の CodeQL ライブラリ パック qlpack.yml
ファイルと、
name: my-company/my-library
library: true
version: 1.0.0
ワークスペース内の次の CodeQL ライブラリ パック qlpack.yml
ファイルについても考えてみましょう。
name: my-company/my-queries
version: 1.0.0
dependencies:
my-company/my-library: "*"
codeql/cpp-all: ~0.2.0
CodeQL クエリ パック my-company/my-queries
の dependencies
ブロックは、ライブラリ パックのバージョンとして "*"
を指定していることに注意してください。 ライブラリ パックは codeql-workspace.yml
でソース依存関係として既に定義されているため、ライブラリ パックのコンテンツは常にワークスペース内から解決されます。 この場合、定義するバージョン制約はすべて無視されます。 バージョンがワークスペースから継承されていることを明確にするために、ソース依存関係に "*"
を使用することをお勧めします。
クエリ パック ディレクトリから codeql pack install
を実行すると、codeql/cpp-all
の適切なバージョンがローカル パッケージ キャッシュにダウンロードされます。 また、codeql/cpp-all
の解決済みバージョンを含む codeql-pack.lock.yml
ファイルが作成されます。 ソース依存関係から解決されるため、ロック ファイルには my-company/my-library
のエントリは含まれません。 codeql-pack.lock.yml
ファイルは次のようになります。
dependencies:
codeql/cpp-all:
version: 0.2.2
クエリ パック ディレクトリから codeql pack publish
を実行すると、パッケージ キャッシュからの codeql/cpp-all
依存関係とワークスペースからの my-company/my-library
が my-company/my-queries
にバンドルされ、GitHub コンテナー レジストリに発行されます。
ファイル内qlpack.yml
のバージョン範囲として使用${workspace}
する
ワークスペース内の CodeQL パックでは、特殊な ${workspace}
、 ~${workspace}
バージョン範囲のプレースホルダーを ^${workspace}
使用できます。 これらのプレースホルダーは、このパックが現在ワークスペース内にある指定されたパックのバージョンに依存していることを示します。 このプレースホルダーは通常、ライブラリ パック内の依存関係に使用され、公開時にファイル内 qlpack.yml
の依存関係に、発行時のワークスペースの状態が反映されます。
例
同じワークスペース内の次の 2 つのライブラリ パックについて考えてみましょう。
name: my-company/my-library
library: true
version: 1.2.3
dependencies:
my-company/my-library2: ${workspace}
name: my-company/my-library2
library: true
version: 4.5.6
GitHub コンテナー レジストリに発行されるとmy-company/my-library
、発行されたqlpack.yml
ファイル内の依存関係のmy-company/my-library2
バージョンは次のように4.5.6
書き込まれます。
同様に、依存関係がmy-company/my-library2: ^${workspace}
ソース パック内にあり、その後パックが発行された場合、発行されたqlpack.yml
ファイル内の依存関係のmy-company/my-library2
バージョンが 、バージョン>= 4.5.6
として書^4.5.6
き込まれ、すべてこのライブラリ パックと< 5.0.0
互換性があることを示します。
依存関係がmy-company/my-library2: ~${workspace}
ソース パック内にあり、その後、パックが発行された場合、発行されたqlpack.yml
ファイル内の依存関係のmy-company/my-library2
バージョンは、バージョンを示し>= 4.5.6
、すべてこのライブラリ パックと< 4.6.0
互換性があることを示すとして書~4.5.6
き込まれます。