Skip to main content

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

CodeQL ワークスペースを使用すると、相互に依存する CodeQL パックのグループを開発および保守できます。

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

CodeQL は、次の種類のリポジトリで使用できます:

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

メモ: この記事では、このバージョンの 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-queriesdependencies ブロックは、ライブラリ パックのバージョンとして "*" を指定していることに注意してください。 ライブラリ パックは 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-librarymy-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き込まれます。