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

CodeQL パックの作成と操作

この記事の内容

CodeQL パックを使用して、CodeQL クエリとライブラリを作成、共有、依存、および実行できます。

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

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

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

注: CodeQL パックを含む CodeQL パッケージ管理機能は、現在ベータ版リリースであり、変更される可能性があります。 ベータ版リリース中、CodeQL パックは GitHub パッケージ (Container registry) を使用してのみ利用できます。 このベータ機能を使用するには、 https://github.com/github/codeql-action/releases から最新バージョンの CodeQL CLI バンドルをインストールします。

CodeQL パックと CodeQL CLI について

CodeQL パックと CodeQL CLI のパッケージ管理コマンドを使用すると、カスタム クエリを発行してコードベース分析に統合できます。

CodeQL パックには、クエリ パックとライブラリ パックの 2 種類があります。

  • クエリ パックは、実行するように設計されています。 クエリ パックが発行されると、バンドルにはすべての推移的な依存関係と各クエリのプリコンパイル済み表現、およびクエリ ソースが含まれます。 これにより、パック内のクエリの一貫した効率的な実行が保証されます。
  • ライブラリ パックは、クエリ パック (またはその他のライブラリ パック) で使用するように設計されており、クエリ自体は含まれません。 ライブラリは個別にコンパイルされません。

CodeQL CLI の pack コマンドを使用して、CodeQL パックを作成したり、パックに依存関係を追加したり、依存関係をインストールまたは更新したりできます。 pack コマンドを使用して、CodeQL パックを発行してダウンロードすることもできます。 詳しい情報については、「CodeQL パックの発行と使用」を参照してください。

発行されたクエリ パックと異なる CodeQL リリース間の互換性について詳しくは、「CodeQL パックの互換性について」を参照してください。

CodeQL パックの作成

プロジェクトのチェックアウト ルートから次のコマンドを実行して、CodeQL パックを作成できます。

codeql pack init <scope>/<pack>

ユーザーは次のものを指定する必要があります。

  • <scope>: 発行先の GitHub Organization またはユーザー アカウントの名前。

  • <pack>: 作成するパックの名前。

codeql pack init コマンドにより、CodeQL パックのディレクトリ構造と構成ファイルが作成されます。 既定では、コマンドによってクエリ パックが作成されます。 ライブラリ パックを作成する場合は、library:true プロパティを含めることでファイルをライブラリ パックとして明示的に宣言するように qlpack.yml ファイルを編集する必要があります。

既存のレガシ QL パックを変更して CodeQL パックを作成する

既に qlpack.yml ファイルがある場合は、それを手動で編集して、CodeQL パックに変換できます。

  1. <scope>/<name> 形式と一致するように name プロパティを編集します。ここで、<scope> は発行先の GitHub Organization またはユーザー アカウントの名前です。

  2. qlpack.yml ファイルに、semver 識別子を持つ version プロパティと、省略可能な dependencies ブロックを含めます。

  3. libraryPathDependencies の依存関係の一覧を dependencies ブロックに移行します。 各依存関係のバージョン範囲を指定します。 範囲が重要でない場合、または互換性が不明な場合は、"\*" を指定できます。これは、任意のバージョンを受け入れることができ、codeql pack install を実行すると既定で最新バージョンに設定されることを示します。

プロパティについて詳しくは、「CodeQL パックについて」を参照してください。

CodeQL パックへの依存関係の追加とインストール

コマンド codeql pack add を使用して、CodeQL パックに依存関係を追加できます。 スコープ、名前、および (必要に応じて) 互換性のあるバージョン範囲を指定する必要があります。

codeql pack add <scope>/<name>@x.x.x <scope>/<other-name>

バージョン範囲を指定しない場合は、最新バージョンが追加されます。 それ以外の場合は、要求された範囲を満たす最新バージョンが追加されます。

このコマンドを実行すると、要求された依存関係で qlpack.yml ファイルが更新され、パッケージ キャッシュにダウンロードされます。 このコマンドを実行すると、ファイルが再フォーマットされ、すべてのコメントが削除されることに注意してください。

qlpack.yml ファイルを手動で編集して依存関係を含め、コマンドを使用して依存関係をインストールすることもできます。

codeql pack install

このコマンドを実行すると、すべての依存関係がローカル ディスク上の共有キャッシュにダウンロードされます。

注:

  • codeql pack add と codeql pack install コマンドを実行すると、codeql-pack.lock.yml ファイルが生成または更新されます。 このファイルはバージョン管理にチェックインする必要があります。 codeql-pack.lock.yml ファイルには、パックで使用される正確なバージョン番号が含まれています。 詳しくは、「codeql-pack.lock.yml ファイルについて」を参照してください。

  • 既定では、codeql pack install により、GitHub.com の Container registry から依存関係がインストールされます。 qlconfig.yml ファイルを作成することで、GitHub Enterprise Server Container registry から依存関係をインストールできます。 詳しい情報については、「CodeQL パックの発行と使用」を参照してください。

ダウンロードした CodeQL パックのカスタマイズ

パックの変更を試す場合は、ソース コードを含むリポジトリをクローンすることをお勧めします。

ソース リポジトリを使用できず、Container registry からダウンロードしたパックに基づいて変更を行う必要がある場合、これらのパックはダウンロード後に変更やカスタマイズされるものではなく、今後、十分な通知なしに形式が変更される可能性があることに注意してください。 コンテンツを変更する必要がある場合は、パックをダウンロードした後に次の手順を行うことをお勧めします。

  • qlpack.yml でパックの ''名前'' を変更して、変更されていないパックの結果との混同を避けるようにします。__

  • アンパックされたディレクトリ構造内の任意の場所にある *.qlx という名前のファイルをすべて削除します。 これらのファイルにはプリコンパイル済みバージョンのクエリが含まれており、場合によっては、CodeQL では、変更した QL ソースよりも優先して使用されます。