CodeQL ワークスペースについて
複数の 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
き込まれます。