# CodeQL ワークスペース

CodeQL ワークスペースを使用すると、関連する複数の CodeQL パックをまとめて開発および管理し、ソースから直接依存関係を解決できます。

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

> \[!NOTE]
> この記事では、このバージョンの CodeQL の初期リリースに含まれる CodeQL CLI アクションのバージョンおよび関連する GitHub Enterprise Server バンドルで使用できる機能について説明します。 エンタープライズでより新しいバージョンの CodeQL アクションを使用する場合は、この記事の [GitHub Enterprise Cloud バージョン](/ja/enterprise-cloud@latest/code-security/concepts/code-scanning/codeql/codeql-workspaces)で最新の機能に関する情報を参照してください。
> 最新バージョンの使用方法については、「[アプライアンスのコード スキャンの構成](/ja/enterprise-server@3.18/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance#configuring-codeql-analysis-on-a-server-without-internet-access)」を参照してください。

通常、 CodeQL ワークスペースは、相互に依存するライブラリとクエリ パックのセットを開発するために使用されます。
CodeQL ワークスペースを使用する場合、クエリを解決する CodeQL コマンドを実行すると、ワークスペース内のすべての\_\_ パックがCodeQLとして使用できます。 これにより、関連する複数の CodeQL パックの開発、保守、発行が容易になります。
CodeQL パックの詳細については、「[CodeQL パックを使った分析のカスタマイズ](/ja/enterprise-server@3.18/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-server@3.18/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#adding-and-installing-dependencies)」を参照してください。

### 例

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
```

`dependencies` クエリ パックのCodeQL ブロック`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 とパッケージ パターンの一覧が含まれています。 「[CodeQL パックを発行して使用する](/ja/enterprise-server@3.18/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 ディレクトリ内のパックを除き、`codeql-packs` ディレクトリ内で再帰的に見つかったすべての`experimental` パックを含むワークスペースを定義します。
`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` ファイルの依存関係に、発行時のワークスペースの状態が反映されます。

### 例

同じワークスペース内の次の 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
```

`my-company/my-library`がGitHub コンテナー レジストリに発行されると、発行された`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` はすべて、このライブラリ パックと互換性があることを示します。