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

Note

この記事では、このバージョンの GitHub Enterprise Server の初期リリースに含まれる CodeQL アクションのバージョンおよび関連する CodeQL CLI バンドルで使用できる機能について説明します。エンタープライズでより新しいバージョンの CodeQL アクションを使用する場合は、この記事の GitHub Enterprise Cloud バージョンで最新の機能に関する情報を参照してください。最新バージョンの使用については、「アプライアンス用コードスキャンの構成」を参照してください。

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

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

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

この記事の内容