CodeQL パックを発行して使用する

公開前に qlpack.yml ファイルを構成する

公開する前に、CodeQL パックの構成の詳細を確認して変更できます。 任意のテキスト エディターで qlpack.yml ファイルを開きます。

library: # set to true if the pack is a library. Set to false or omit for a query pack
name: <scope>/<pack>
version: <x.x.x>
description: <Description to publish with the package>
default-suite: # optional, one or more queries in the pack to run by default
    - query: <relative-path>/query-file>.ql
default-suite-file: default-queries.qls # optional, a pointer to a query-suite in this pack
license: # optional, the license under which the pack is published
dependencies: # map from CodeQL pack name to version range

• name: は/ 形式に従う必要があります。 は公開先の GitHub Organization、 はパックの名前です。

• default-suite または default-suite-file のうち、許可されるのは 1 つのみです。 この 2 つは、実行する既定のクエリ スイートを定義する異なる方法です。1 つ目は qlpack.yml ファイルにクエリを直接指定し、2 つ目はパックにクエリ スイートを指定します。

実行中 codeql pack publish

パックを GitHub Container registry に公開する準備ができたら、パック ディレクトリのルートで次のコマンドを実行できます。

codeql pack publish

公開されたパッケージは、qlpack.yml ファイル内のスコープで指定した GitHub Organization のパッケージ セクションに表示されます。

実行中 codeql pack download <scope>/<pack>

他のユーザーが作成したパックを実行するには、まず次のコマンドを実行してダウンロードする必要があります。

codeql pack download <scope>/<pack>@x.x.x

• <scope>: ダウンロード元の GitHub Organization の名前。
• <pack>: ダウンロードするパックの名前。
• @x.x.x: 省略可能なバージョン番号。 省略すると、最新バージョンがダウンロードされます。

このコマンドは、複数のパックの引数を受け入れます。

ダウンロードするクエリ パックの特定のバージョン番号を指定するスクリプトを記述する場合は、CodeQL のバージョンを新しいバージョンに更新する際に、クエリ パックも新しいバージョンに切り替える必要があることに留意してください。 CodeQL の新しいバージョンは、非常に古いバージョンに固定されているクエリ パックと一緒に使うと、パフォーマンスが低下する "可能性があります"。__ 詳しくは、「CodeQL パックの互換性について」を参照してください。

CodeQL パックを使って CodeQL データベースを分析する

CodeQL パックを使って CodeQL データベースを分析するには、次のコマンドを実行します。

codeql database analyze <database> <scope>/<pack>@x.x.x:<path>

• <database>: 分析対象の CodeQL データベース。
• <scope>: パックが公開されている GitHub Organization の名前。
• <pack>: 使うパックの名前。
• @x.x.x: 省略可能なバージョン番号。 省略すると、最新バージョンが使われます。
• :<path>: クエリ、ディレクトリ、またはクエリ スイートへの省略可能なパス。 省略すると、パックの既定のクエリ スイートが使われます。

analyze コマンドを使って、指定した CodeQL パックの既定のスイートを実行します。 CodeQL データベースの分析に使う CodeQL パックは複数指定できます。 次に例を示します。

codeql <database> analyze <scope>/<pack> <scope>/<other-pack>

CodeQL パックの互換性について

クエリ パックが公開されると、その中にすべてのクエリのプリコンパイル済みの表現が含まれます。 これらのプリコンパイル済みクエリは、一般に、分析中に QL ソースをゼロからコンパイルする場合よりもはるかに高速に実行できます。 ただし、プリコンパイル済みクエリは QL エバリュエーターの特定の内部にも依存するため、分析を実行する CodeQL のバージョンが codeql pack publish を実行したバージョンと大きく異なる場合は、代わりに分析中にソースからクエリをコンパイルする必要があるかもしれません。 再コンパイルは自動的に行われ、分析の "結果" には影響しませんが、分析速度が大幅に低下する可能性があります。__

通常、CodeQL のあるリリースでパックが公開されている場合、その中のプリコンパイル済みクエリは、リリース日が 6 か月を超えない限り、CodeQL の "以降" のリリースで直接使うことができると想定されます。__ 新しいリリースの互換性をそれよりも長期間保つために当然の努力をしますが、約束はしません。

また、CodeQL の "最新" のパブリック リリースによって公開されたパックは、code scanning と GitHub Actions で使われる CodeQL のバージョンでも使うことができると想定されます。ただし、それは多くの場合、少し古いリリースです。__

上記の例外として、"2.12.0 より前" のバージョンの CodeQL で公開されたパックは、それ以前のバージョンまたはそれ以降のバージョンと互換性がありません。 これらの古いバージョンでは、プリコンパイル済みクエリが、リリース間の互換性がサポートされていない形式で記述されています。 これらのバージョンで公開されたパックは、新しいバージョンでも "使う" ことができますが、最初にクエリを再コンパイルする必要があるため、分析速度が低下します。

公開されたクエリ パックのユーザーは、クエリ パックを使う分析実行のターミナル出力を調べると、CodeQL でプリコンパイル済みクエリを使っていることを確認できます。 次のような行が含まれている場合、プリコンパイル済みクエリが正常に使われました。

[42/108] Loaded /long/path/to/query/Filename.qlx.

一方、代わりに次のように表示される場合は、プリコンパイル済みクエリの使用に失敗しました。

Compiling query plan for /long/path/to/query/Filename.ql.
[42/108 comp 25s] Compiled /long/path/to/query/Filename.ql.

この場合でも分析の結果に問題はありませんが、最適なパフォーマンスを得るには、場合によっては CodeQL CLI またはクエリ パックの新しいバージョンにアップグレードする必要があります。

他のユーザーが使うことができるように GitHub.com の Container registry でクエリ パックを公開する場合は、CodeQL の最新リリースを使って codeql pack publish を実行し、使ったバージョンが 6 か月になる前に、更新された CodeQL バージョンのパックの新しいバージョンを公開することをお勧めします。 そうすることで、パックのユーザーが "自分" の CodeQL を最新の状態に保ち、パック内のプリコンパイル済みクエリの恩恵を受けられるようにできます。__

バンドルされている CodeQL バイナリを使う GitHub Enterprise Server インストールで使う目的でクエリ パックを公開する場合は、同じ CodeQL バージョンを使って codeql pack publish を実行します。 新しいバージョンで、GitHub Enterprise Server で認識されない可能性のあるプリコンパイル済みクエリが生成される場合があります。 GitHub Enterprise Server 管理者は、新しいバージョンの CodeQL に定期的にアップグレードすることを選ぶことができます。 その場合は、指示に従ってください。

GitHub Container registries への認証

適切な GitHub Container registry に対して認証することで、パックを公開し、プライベート パックをダウンロードできます。

次の 2 つの方法で GitHub.com の Container registry に対して認証できます。

1. CodeQL CLI に --github-auth-stdin オプションを渡し、標準入力を介して GitHub Apps トークンまたは personal access token を提供します。
2. GITHUB_TOKEN 環境変数を GitHub Apps トークンまたは personal access token に設定します。