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

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 はすべて、このライブラリ パックと互換性があることを示します。