CodeQL ワークスペースについて

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き込まれます。