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

CodeQL ワークスペースは、通常、相互に依存する一連のライブラリとクエリパックを開発するために使用されます。 CodeQL ワークスペースを使用すると、クエリを解決する CodeQL コマンドを実行するときに、ワークスペース内のすべての CodeQL パックを相互に "ソース依存関係" として使用できます。__ これにより、複数の関連する CodeQL パックの開発、保守、発行が容易になります。 CodeQL パックの詳細については、「AUTOTITLE」を参照してください。

ワークスペースは、関連するパックを一緒に開発して発行できるように、一般的に 1 つの Git リポジトリに格納されます。

ソース依存関係

CodeQL ワークスペースでは、ワークスペースに含まれるすべてのパックが相互の ソース依存関係 として扱われます。これは、CodeQL パッケージキャッシュからではなく、ローカルファイルシステムから直接解決されることを意味します。

ワークスペースパックはソースから解決するため、

1 つのパックのローカル変更は、ワークスペース内の他のパックにすぐに表示されます。
ワークスペースで見つかった依存関係は、パッケージキャッシュ内のバージョンをオーバーライドします。

        `qlpack.yml` ファイルのバージョン制約はワークスペースの依存関係では無視されます。これは、ワークスペースのコンテンツによってバージョンが決定されるためです。

この動作は、複数の関連パックを同時に開発する場合に特に便利です。例えば次が挙げられます。

依存関係はまだ発行されておらず、ローカルにのみ存在します。
複数のパック間で調整された変更を行っており、テスト中に互いに解決する必要があります。

ワークスペースの外部では、依存関係はパッケージキャッシュから解決され、 qlpack.ymlで定義されているバージョンの制約と一致する必要があります。ワークスペース内では、代わりに解像度によってローカルソースコンテンツが優先されます。

CodeQL ワークスペースとクエリ解決

ワークスペースの依存関係モデルは、パックのインストールと発行方法に影響します。

インストール中、ワークスペースで見つかった依存関係はパッケージキャッシュにダウンロードされず、 codeql-pack.lock.yml ファイルに書き込まれません。
発行時に、ワークスペースによって提供される依存関係は、パッケージキャッシュのバージョンではなく、ローカルソースコンテンツを使用してバンドルされます。

たとえば、ワークスペース内のパックディレクトリで codeql pack install を実行すると、パッケージキャッシュにダウンロードしたり、 codeql-pack.lock.yml ファイルに記録したりする代わりに、ワークスペース内で見つかった依存関係が使用されます。「CodeQL パックの作成と操作」を参照してください。

Example

CodeQL ワークスペースは、codeql-workspace.yml という名前の YAML ファイルで定義されます。次の 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 クエリパック dependencies の my-company/my-queries ブロックは、ライブラリパックのバージョンとして "*" を指定していることに注意してください。ライブラリパックは codeql-workspace.yml でソース依存関係として既に定義されているため、ライブラリパックのコンテンツは常にワークスペース内から解決されます。この場合、定義するバージョン制約はすべて無視されます。ソースの依存関係に "*" を使用すると、バージョンがワークスペースから継承されていることが明示的になります。

クエリパックディレクトリから codeql pack install を実行すると、codeql/cpp-all の適切なバージョンがローカルパッケージキャッシュにダウンロードされます。また、codeql-pack.lock.yml の解決済みバージョンを含む codeql/cpp-all ファイルが作成されます。ソース依存関係から解決されるため、ロックファイルには 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 コンテナーレジストリに発行されます。

          `codeql-workspace.yml` ファイルの例

CodeQL ワークスペースは、 codeql-workspace.ymlという名前の YAML ファイルによって定義されます。このファイルには、provide ブロックと、必要に応じて ignore および registries ブロックが含まれます。

        `provide` ブロックには、ワークスペースで使用可能な CodeQL パックを定義する glob パターンの一覧が含まれます。

        `ignore` ブロックには、ワークスペースで使用できない CodeQL パックを定義する glob パターンの一覧が含まれます。

        `registries` ブロックには、CodeQL パックの発行に使用されるコンテナー レジストリを制御する GHES URL とパッケージ パターンの一覧が含まれます。 「[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#working-with-codeql-packs-on-ghes)」を参照してください。

        `provide` または `ignore` セクションの各エントリは、`qlpack.yml` ファイルの場所にマップする必要があります。 すべての glob パターンは、ワークスペース ファイルを含むディレクトリを基準にして定義されます。 このファイルで受け入れられるパターンの一覧については、「[@actions/glob](https://github.com/actions/toolkit/tree/main/packages/glob#patterns)」を参照してください。

たとえば、次の 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 pack ls を実行することで、ワークスペースに含まれるパックを一覧表示できます。

          `${workspace}` ファイルのバージョン範囲として `qlpack.yml` を使用する

ワークスペース内の CodeQL パックでは、特殊な ${workspace}、~${workspace}``^${workspace} バージョン範囲プレースホールダーを使用できます。これらのプレースホルダーは、このパックが現在ワークスペース内にある指定されたパックのバージョンに依存していることを示します。このプレースホルダーは通常、ライブラリパック内の依存関係に使用され、公開時に qlpack.yml ファイルの依存関係に、発行時のワークスペースの状態が反映されます。

Example

同じワークスペース内の次の 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 Container Registry に my-company/my-library を発行すると、発行された my-company/my-library2 ファイルの qlpack.yml 依存関係のバージョンが 4.5.6 として書き込まれます。

同様に、依存関係がソースパックで my-company/my-library2: ^${workspace} であり、その後、パックが発行されると、発行された my-company/my-library2 ファイルの qlpack.yml 依存関係のバージョンは、^4.5.6 として書き込まれ、バージョン >= 4.5.6 と < 5.0.0 はすべて、このライブラリパックと互換性があることを示します。

依存関係がソースパックで my-company/my-library2: ~${workspace} であり、その後、パックが発行されると、発行された my-company/my-library2 ファイルの qlpack.yml 依存関係のバージョンは、~4.5.6 として書き込まれ、バージョン >= 4.5.6 と < 4.6.0 はすべて、このライブラリパックと互換性があることを示します。

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

この機能を使用できるユーザーについて

この記事で