# CodeQL ワークスペースについて CodeQL ワークスペースを使用することで、複数の関連する CodeQL パックを統合して開発及び管理し、ソースから直接それらの依存関係を解決できます。 ## CodeQL ワークスペースについて CodeQL ワークスペースは、通常、相互に依存する一連のライブラリとクエリ パックを開発するために使用されます。 CodeQL ワークスペースを使用すると、クエリを解決する CodeQL コマンドを実行するときに、ワークスペース内のすべての CodeQL パックを相互に "ソース依存関係" として使用できます。\_\_ これにより、複数の関連する CodeQL パックの開発、保守、発行が容易になります。 CodeQL パックの詳細については、[「AUTOTITLE」](/ja/enterprise-cloud@latest/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs)を参照してください。 ワークスペースは、関連するパックを一緒に開発して発行できるように、一般的に 1 つの Git リポジトリに格納されます。 ## ソース依存関係 CodeQL ワークスペースでは、ワークスペースに含まれるすべてのパックが相互の**ソース依存関係**として扱われます。 これは、CodeQL パッケージ キャッシュからではなく、ローカル ファイル システムから直接解決されることを意味します。 ワークスペース パックはソースから解決するため: * 1 つのパックのローカル変更は、ワークスペース内の他のパックにすぐに表示されます。 * ワークスペースで見つかった依存関係は、パッケージ キャッシュ内のバージョンをオーバーライドします。 * ``` `qlpack.yml` ファイルのバージョン制約はワークスペースの依存関係では無視されます。これは、ワークスペースのコンテンツによってバージョンが決定されるためです。 ``` この動作は、複数の関連パックを同時に開発する場合に特に便利です。 例えば次が挙げられます。 * 依存関係はまだ発行されておらず、ローカルにのみ存在します。 * 複数のパック間で調整された変更を行っており、テスト中に互いに解決する必要があります。 ワークスペースの外部では、依存関係はパッケージ キャッシュから解決され、 `qlpack.yml`で定義されているバージョンの制約と一致する必要があります。 ワークスペース内では、代わりに解像度によってローカル ソース コンテンツが優先されます。 ## CodeQL ワークスペースとクエリ解決 ワークスペースの依存関係モデルは、パックのインストールと発行方法に影響します。 * インストール中、ワークスペースで見つかった依存関係はパッケージ キャッシュにダウンロードされず、 `codeql-pack.lock.yml` ファイルに書き込まれません。 * 発行時に、ワークスペースによって提供される依存関係は、パッケージ キャッシュのバージョンではなく、ローカル ソース コンテンツを使用してバンドルされます。 たとえば、ワークスペース内のパック ディレクトリで `codeql pack install` を実行すると、パッケージ キャッシュにダウンロードしたり、 `codeql-pack.lock.yml` ファイルに記録したりする代わりに、ワークスペース内で見つかった依存関係が使用されます。 「[CodeQL パックの作成と操作](/ja/enterprise-cloud@latest/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#adding-and-installing-dependencies)」を参照してください。 ### Example CodeQL ワークスペースは、`codeql-workspace.yml` という名前の YAML ファイルで定義されます。 次の `codeql-workspace.yml` ファイルを考えてみます。 ```yaml provide: - "**/qlpack.yml" ``` さらに、ワークスペース内の次の CodeQL ライブラリ パック `qlpack.yml` ファイルと、 ```yaml name: my-company/my-library library: true version: 1.0.0 ``` ワークスペース内の次の CodeQL ライブラリ パック `qlpack.yml` ファイルについても考えてみましょう。 ```yaml 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` ファイルは次のようになります。 ```yaml 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` のレジストリからダウンロードし、そこに発行する必要があります。 ```yaml 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 つのライブラリ パックを考慮する: ```yaml name: my-company/my-library library: true version: 1.2.3 dependencies: my-company/my-library2: ${workspace} ``` ```yaml 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` はすべて、このライブラリ パックと互換性があることを示します。