CodeQL ワークスペース

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

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

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

  • GitHub.com のパブリック リポジトリについては、「GitHub CodeQL の使用条件」を参照してください
  • GitHub Team が有効になっている GitHub Code Security 上の organization 所有のリポジトリ

この記事で

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

通常、 CodeQL ワークスペースは、相互に依存するライブラリとクエリ パックのセットを開発するために使用されます。 CodeQL ワークスペースを使用する場合、クエリを解決する CodeQL コマンドを実行すると、ワークスペース内のすべての__ パックがCodeQLとして使用できます。 これにより、関連する複数の CodeQL パックの開発、保守、発行が容易になります。 CodeQL パックの詳細については、「CodeQL パックを使った分析のカスタマイズ」を参照してください。

ワークスペースは、関連するパックを一緒に開発して発行できるように、一般的に 1 つの Git リポジトリに格納されます。

ソース依存関係

CodeQL ワークスペースでは、ワークスペースに含まれるすべてのパックは、相互のソース依存関係として扱われます。 つまり、 CodeQL パッケージ キャッシュからではなく、ローカル ファイル システムから直接解決されます。

ワークスペースパックはソースから解決するため、

  • 1 つのパックのローカル変更は、ワークスペース内の他のパックにすぐに表示されます。
  • ワークスペースで見つかった依存関係は、パッケージ キャッシュ内のバージョンをオーバーライドします。
  • qlpack.yml ファイルのバージョン制約はワークスペースの依存関係では無視されます。これは、ワークスペースのコンテンツによってバージョンが決定されるためです。

この動作は、複数の関連パックを同時に開発する場合に特に便利です。 例えば次が挙げられます。

  • 依存関係はまだ発行されておらず、ローカルにのみ存在します。
  • 複数のパック間で調整された変更を行っており、テスト中に互いに解決する必要があります。

ワークスペースの外部では、依存関係はパッケージ キャッシュから解決され、 qlpack.ymlで定義されているバージョンの制約と一致する必要があります。 ワークスペース内では、代わりに解像度によってローカル ソース コンテンツが優先されます。

CodeQL ワークスペースとクエリ解決

ワークスペースの依存関係モデルは、パックのインストールと発行方法に影響します。

  • インストール中、ワークスペースで見つかった依存関係はパッケージ キャッシュにダウンロードされず、 codeql-pack.lock.yml ファイルに書き込まれません。
  • 発行時に、ワークスペースによって提供される依存関係は、パッケージ キャッシュのバージョンではなく、ローカル ソース コンテンツを使用してバンドルされます。

たとえば、ワークスペース内のパック ディレクトリで codeql pack install を実行すると、パッケージ キャッシュにダウンロードしたり、 codeql-pack.lock.yml ファイルに記録したりする代わりに、ワークスペース内で見つかった依存関係が使用されます。 「CodeQL パックの作成と操作」を参照してください。

例

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

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 ファイルは次のようになります。

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 パックを発行して使用する」を参照してください。

provide または ignore セクションの各エントリは、qlpack.yml ファイルの場所にマップする必要があります。 すべての glob パターンは、ワークスペース ファイルを含むディレクトリを基準にして定義されます。 このファイルで受け入れられるパターンの一覧については、「@actions/glob」を参照してください。

たとえば、次のcodeql-workspace.yml ファイルは、CodeQL ディレクトリ内のパックを除き、codeql-packs ディレクトリ内で再帰的に見つかったすべてのexperimental パックを含むワークスペースを定義します。 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 ファイルの依存関係に、発行時のワークスペースの状態が反映されます。

例

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

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