Skip to main content
ドキュメントへの更新が頻繁に発行されており、このページの翻訳はまだ行われている場合があります。 最新の情報については、「英語のドキュメント」を参照してください。

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

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

GitHub CodeQL は、インストール時にユーザーごとにライセンスされます。 CodeQL は、ライセンスの制限の下で特定のタスクでのみ使用できます。 詳しくは、「CodeQL CLI について」を参照してください。

GitHub Enterprise アカウントと GitHub Advanced Security ライセンスがある場合は、CodeQL を使用して、自動分析、継続的インテグレーション、継続的デリバリーを行うことができます。 営業チームに連絡することで、Enterprise アカウントを作成できます。 詳しくは、「GitHub Advanced Security について」を参照してください。

注: この記事は、2023 年 1 月に CodeQL ドキュメント Web サイトから移行されました。

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 コンテナー レジストリに発行されます。