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

GitHub Enterprise Server で CodeQL パックを操作する

既定では、CodeQL CLI は、GitHub.com の Container registry から CodeQL パックをダウンロードし、そこにパックを公開することを想定しています。ただし、qlconfig.yml ファイルを作成して、各パックに使う Container registry を CLI に指示することで、GitHub Enterprise Server の Container registry 内の CodeQL パックを操作することもできます。

任意のテキストエディターを使って ~/.codeql/qlconfig.yml ファイル (Linux/MacOS) または %HOMEPATH%\.codeql\qlconfig.yml (Windows) を作成し、エントリを追加して、1 つ以上のパッケージ名パターンに使うレジストリを指定します。たとえば、次の qlconfig.yml ファイルは、GitHub.com の Container registry に関連付けられている、https://GHE_HOSTNAME にある Container registry にすべてのパック (codeql/\* または other-org/* の organization と一致するパックは除く) を関連付けます。

registries:
- packages:
  - 'codeql/*'
  - 'other-org/*'
  # Container registry on GitHub.com
  url: https://ghcr.io/v2/
- packages: '*'
  # Container registry hosted at `https://GHE_HOSTNAME`
  url: https://containers.GHE_HOSTNAME/v2/

CodeQL CLI は、registries リストで、そのパッケージ名に一致する packages プロパティを持つ最初の項目を見つけて、特定のパッケージ名に使うレジストリを決定します。つまり、通常は、最も明確なパッケージ名パターンを最初に定義したいと考えます。 packages プロパティには、単一のパッケージ名、glob パターン、またはパッケージ名と glob パターンの YAML リストを指定できます。

registries リストは、codeql-workspace.yml ファイル内に配置することもできます。そうすることで、特定のワークスペース内で使うレジストリを定義でき、ワークスペースの他の CodeQL ユーザー間で共有できるようにします。 codeql-workspace.yml 内の registries リストはマージされ、グローバルな qlconfig.yml 内のリストよりも優先されます。 codeql-workspace.yml について詳しくは、「CodeQL ワークスペースについて」をご覧ください。

codeql pack publish、codeql pack download、codeql database analyze を使って、GitHub Enterprise Server でパックを管理できるようになりました。

GitHub Container registries への認証

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

GitHub.com の Container registries への認証

Container registry への認証には 2 つの方法があります。

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

GitHub Enterprise Server の Container registries への認証

同様に、次の 2 つの方法で GitHub Enterprise Server の Container registry に対して認証、または複数のレジストリに対して同時に認証することができます (複数のレジストリからプライベートパックをダウンロードまたは実行する場合など)。

CodeQL CLI に --registries-auth-stdin オプションを渡し、標準入力を介してレジストリ認証文字列を提供します。
CODEQL_REGISTRIES_AUTH 環境変数をレジストリ認証文字列に設定します。

レジストリ認証文字列は、<registry-url>=<token> ペアのコンマ区切りのリストです。registry-url は Container registry URL (https://containers.GHE_HOSTNAME/v2/ など)、token はその Container registry の GitHub Apps トークンまたは personal access token です。これにより、各トークンは、指定した Container registry にのみ確実に渡されます。

たとえば、次のレジストリ認証文字列は、CodeQL CLI の認証を次のように指定します。

トークン <token1> を使って、GitHub.com の Container registry に対して認証します。
トークン <token2> を使って、https://containers.GHE_HOSTNAME/v2/ で、エンタープライズの Container registry に対して認証します。

https://ghcr.io/v2/=<token1>,https://containers.GHE_HOSTNAME/v2/=<token2>

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

注: この記事では、GitHub Enterprise Server 3.12 の初期リリースに含まれている CodeQL CLI 2.15.5 バンドルで使用できる機能について説明します。

サイト管理者が CodeQL CLI のバージョンをより新しいリリースに更新している場合は、この記事の GitHub Enterprise Cloud バージョンで最新の機能に関する情報を参照してください。

公開する前に、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>
defaultSuite: # optional, one or more queries in the pack to run by default
    - query: <relative-path>/query-file>.ql
defaultSuiteFile: 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: は<scope>/<pack> 形式に従う必要があります。<scope> は公開先の GitHub Organization、<pack> はパックの名前です。
defaultSuite または defaultSuiteFile のうち、許可されるのは 1 つのみです。この 2 つは、実行する既定のクエリスイートを定義する異なる方法です。1 つ目は qlpack.yml ファイルにクエリを直接指定し、2 つ目はパックにクエリスイートを指定します。

実行中 `codeql pack publish`

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

codeql pack publish

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

注: 既定のセットアップ構成の一部として組織内のすべてのリポジトリにカバレッジを拡張するために、GitHub Container registry にモデルパックを発行する場合は、コードスキャンを実行しているリポジトリがそれらのモデルパックにアクセスできることを確認する必要があります。詳細については、「既定のセットアップの構成を編集する」および「パッケージのアクセス制御と可視性の設定」を参照してください。

実行中 `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 pack download コマンドでは、ダウンロードされたパックが、ローカルの変更を意図していない内部の場所に格納されます。パックをダウンロード後に変更すると、予期しない (トラブルシューティングが難しい) 動作が発生する可能性があります。パックのカスタマイズについて詳しくは、「CodeQL パックの作成と操作」をご覧ください。

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

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

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

また、CodeQL の "最新" のパブリックリリースによって公開されたパックは、code scanning と GitHub Actions で使われる 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 に定期的にアップグレードすることを選ぶことができます。その場合は、指示に従ってください。

`qlpack.yml` ファイルについて

クエリ関連のコマンドを実行する場合、CodeQL はまず、インストールディレクトリの兄弟 (およびそのサブディレクトリ) で qlpack.yml ファイルを検索します。次に、ダウンロードされた CodeQL パックのパッケージキャッシュを確認します。これは、クエリをローカルで開発している場合、インストールディレクトリ内のローカルパッケージによって、パッケージキャッシュ内の同じ名前のパッケージがオーバーライドされるため、ローカルの変更をテストできることを意味します。

各 qlpack.yml ファイルのメタデータは、パック内のクエリをコンパイルする方法、パックが依存するライブラリ、クエリスイート定義を検索する場所を CodeQL に指示します。

CodeQL パック (CodeQL 分析で使用されるクエリまたはライブラリ) の内容は、qlpack.yml と同じディレクトリまたはそのサブディレクトリに含まれます。

qlpack.yml ファイルを含むディレクトリは、CodeQL パックの内容のルートディレクトリとして機能します。つまり、パック内のすべての .ql および .qll ファイルについて、CodeQL は、パックのルートにある qlpack.yml ファイルを含むディレクトリに関連するすべてのインポートステートメントを解決します。

`qlpack.yml` プロパティ

qlpack.yml ファイルでは、次のプロパティがサポートされます。

`name`

すべてのパックで必須。
CodeQL パックが発行されるパックのスコープとパックの名前を定義します。名前は、英数字とハイフンを使用して定義します。 CodeQL では同じ名前の CodeQL パックを区別できないため、これは一意である必要があります。パック名を使用して、database analyze を使用して実行するクエリを指定し、CodeQL パック間の依存関係を定義します (次の例を参照)。次に例を示します。
```
name: octo-org/security-queries
```

`version`

発行されるすべてのパックで必須。
SemVer v2.0.0 仕様に準拠する必要がある、この CodeQL パックのセマンティックバージョンを定義します。次に例を示します。
```
version: 0.0.0
```

`dataExtensions`

モデルパックで必須。
クエリパックまたはライブラリパックのルートを基準にしてデータ拡張ファイルが配置される場所を指定する glob パターンの一覧を取得します。

`dependencies`

他のパックに対する CodeQL パッケージの依存関係を定義するクエリとライブラリパックで必須。モデルパックでは依存関係を定義できず、代わりに extensionTargets を使用できます。
パック参照から、このパックと互換性のあるセマンティックバージョン範囲へのマップを定義します。 CodeQL CLI バージョン v2.6.0 以降でサポートされています。次に例を示します。
```
dependencies:
  codeql/cpp-all: ^0.0.2
```
不明な場合、または使用するバージョンが重要でない場合は、この依存関係の任意のバージョンがこのパックと互換性があることを示す使用できます "*"。実際には、これは通常、公開されている依存関係の最も高いバージョンに解決されます。

特別なバージョンのプレースホルダーがあります。これは、 ${workspace}この CodeQL パックが、同じワークスペース内にある依存関係のバージョンによって異なっていることを示します。詳しくは、「CodeQL ワークスペースについて」を参照してください。

`defaultSuiteFile`

実行する一連の既定のクエリをエクスポートするパックで必須。
このパックが codeql database analyze コマンドに渡されたときに既定で実行されるすべてのクエリを含む、パッケージルートを基準とするクエリスイートファイルへのパスを定義します。 CLI バージョン v2.6.0 以降でサポートされています。 defaultSuiteFile または defaultSuite のいずれか 1 つのみを定義できます。次に例を示します。
```
defaultSuiteFile: cpp-code-scanning.qls
```

`defaultSuite`

実行する一連の既定のクエリをエクスポートするパックで必須。
このパックが codeql database analyze コマンドに渡されたときに既定で実行されるすべてのクエリを含むインラインクエリスイートを定義します。 CLI バージョン v2.6.0 以降でサポートされています。 defaultSuiteFile または defaultSuite のいずれか 1 つのみを定義できます。次に例を示します。
```
defaultSuite:
  queries: .
  exclude:
    precision: medium
```

`extensionTargets`

モデルパックで必須。
モデルパック内の拡張機能が適用されるクエリパックを宣言します。拡張機能パックは、指定されたバージョン範囲内にあり、評価で使用されている場合、extensionTargets ディクショナリに名前が付けられた各パックにデータ拡張機能を挿入します。

`groups`

省略可能。
CodeQL ワークスペース内のパックの論理グループを定義します。グループの使用は、ワークスペース内のパックのサブセットにパック操作を適用する方法です。たとえば、次のパックは、java グループと experimental グループの一部として定義されています。
```
groups:
  - java
  - experimental
```
codeql pack publish --groups java,-experimental を実行すると、java グループ内のすべてのパック (experimental パックを_除く_) がパブリッシュされます。 codeql pack ls --groups [-]<group>[,[-]<group>...] コマンドを実行すると、指定したグループのセットに一致するワークスペース内のパックを一覧表示できます。

次の場合、上記ワークスペースの CodeQL パックは一覧に含まれます。
- マイナス記号なしで一覧表示されているグループの少なくとも 1 つに属している (マイナス記号なしでリストされているグループがない場合、この条件は自動的に満たされます)。
- マイナス記号が付いたどのグループにも属していない。

`library`

ライブラリパックで必須。
このパックがライブラリパックであるかどうかを示すブール値を定義します。ライブラリパックにはクエリは含まれず、コンパイルされません。クエリパックでは、このフィールドを無視するか、明示的に false に設定できます。次に例を示します。
```
library: true
```

`suites`

クエリスイートを定義するパックの場合は省略可能。これにより、ユーザーは完全なパスを指定せずに、パック名を指定することで、指定したディレクトリに保存されているクエリスイートを実行できます。
現在、CodeQL CLI バンドルに含まれている標準クエリパックでのみサポートされています。
このオプションは、GitHub コンテナレジストリからダウンロードされた CodeQL パックではサポートされていません。

`tests`

CodeQL テストを含むパックの場合は省略可能。テストが含まれていないパックの場合は無視されます。
テストを含むパック内のディレクトリへのパスを定義します。これは、パックディレクトリを基準に定義されます。パック全体を指定するには、. を使用します。 --strict-test-discovery オプションを指定して test run を実行すると、このディレクトリ内のすべてのクエリがテストとして実行されます。 queries または qlpack 命令を使用して特定のパック内のすべてのクエリを要求するクエリスイート定義では、これらのクエリは無視されます。このプロパティがない場合、. と見なされます。次に例を示します。
```
tests: .
```

`extractor`

CodeQL テストを含むすべてのパックで必須。
パック内の CodeQL テストを実行するときに使用する CodeQL 言語抽出子を定義します。クエリのテストについて詳しくは、「カスタムクエリのテスト」をご覧ください。次に例を示します。
```
extractor: javascript-typescript
```

`authors`

省略可能。
CodeQL パックが発行されるアカウントのパッケージセクションでパッケージ検索ページに表示されるメタデータを定義します。次に例を示します。
```
authors: author1@github.com,author2@github.com
```

`license`

省略可能。
CodeQL パックが発行されるアカウントのパッケージセクションでパッケージ検索ページに表示されるメタデータを定義します。許可されているライセンスの一覧については、SPDX 仕様の SPDX ライセンスリストを参照してください。次に例を示します。
```
license: MIT
```

`description`

省略可能。
CodeQL パックが発行されるアカウントのパッケージセクションでパッケージ検索ページに表示されるメタデータを定義します。次に例を示します。
```
description: Human-readable description of the contents of the CodeQL pack.
```

`libraryPathDependencies`

省略可能、非推奨。代わりに、dependencies プロパティを使用してください。
以前は、この CodeQL パックが依存する CodeQL パックの名前を配列として定義するために使用されていました。これにより、パックは、依存関係で定義されたライブラリ、データベーススキーマ、クエリスイートにアクセスできるようになります。次に例を示します。
```
libraryPathDependencies: codeql/javascript-all
```

`dbscheme`

コア言語パックでのみ必須。
この CodeQL 言語用に記述されたすべてのライブラリとクエリのデータベーススキーマへのパスを定義します (次の例を参照)。次に例を示します。
```
dbscheme: semmlecode.python.dbscheme
```

`upgrades`

コア言語パックでのみ必須。
データベースアップグレードスクリプトを含むパック内のディレクトリへのパスを定義します。これは、パックディレクトリを基準に定義されます。データベースのアップグレードは、別のバージョンの CodeQL CLI で作成されたデータベースと CLI の現在のバージョンとの互換性を確保するために内部的に使用されます。次に例を示します。
```
upgrades: .
```

`warnOnImplicitThis`

省略可能。 warnOnImplicitThis プロパティが定義されていない場合、既定値は false に設定されます。
暗黙的な this 呼び出しレシーバー (つまり、明示的なレシーバーなし) を指定するメンバー述語呼び出しに関する警告をコンパイラが出力するかどうかを指定するブール値を定義します。 CodeQL CLI v2.13.2 以降で使用できます。次に例を示します。
```
warnOnImplicitThis: true
```

`codeql-pack.lock.yml` ファイルについて

codeql-pack.lock.yml ファイルには、CodeQL パックの解決された推移的依存関係のバージョンが格納されます。このファイルは、まだ存在していない場合、codeql pack install コマンドによって作成されます。これは、バージョン管理システムに追加する必要があります。 qlpack.yml ファイルの dependencies セクションには、パックと互換性のあるバージョン範囲が含まれます。 codeql-pack.lock.yml ファイルによって、バージョンが正確な依存関係にロックされます。これにより、このパックで codeql pack install を実行すると、互換性のある新しいバージョンが存在する場合でも、常に同じバージョンの依存関係が取得されます。

たとえば、qlpack.yml ファイルに次の依存関係が含まれている場合、

dependencies:
  codeql/cpp-all: ^0.1.2
  my-user/my-lib: ^0.2.3
  other-dependency/from-source: "*"

codeql-pack.lock.yml ファイルは、次のような内容になります。

dependencies:
  codeql/cpp-all:
    version: 0.1.4
  my-user/my-lib:
    version: 0.2.4
  my-user/transitive-dependency:
    version: 1.2.4

codeql/cpp-all 依存関係は、バージョン 0.1.4 にロックされます。 my-user/my-lib 依存関係は、バージョン 0.2.4 にロックされます。推移的な依存関係であり、qlpack.yml ファイルでは指定されていない my-user/transitive-dependency は、バージョン 1.2.4 にロックされます。 other-dependency/from-source は、ソースから解決されるため、ロックファイルには存在しません。この依存関係は、パックと同じ CodeQL ワークスペースで使用できる必要があります。 CodeQL ワークスペースと、ソースからの依存関係の解決について詳しくは、「CodeQL ワークスペースについて」をご覧ください。

ほとんどの場合、ライブラリパックは実行可能ファイルではなく、通常は推移的な依存関係を修正する必要がないため、codeql-pack.lock.yml ファイルはクエリパックにのみ関係があります。これに対する例外は、テストを含むライブラリパックの場合です。この場合、codeql-pack.lock.yml ファイルを使用して、テストが常に同じバージョンの依存関係で実行されるようにし、依存関係が一致しない場合に偽りのエラーが発生するのを回避します。

カスタム CodeQL パックの例

カスタムクエリまたはテストを記述する場合、それらをカスタム CodeQL パックに保存する必要があります。わかりやすくするために、各パックを論理的に整理してみてください。詳しくは、「CodeQL パックの作成と操作」を参照してください。クエリとテスト用のファイルを個別のパックに保存し、可能であれば、カスタムパックをターゲット言語ごとに特定のフォルダーに整理します。これは、CodeQL パックを発行して他のユーザーと共有したり、コードスキャンに使用したりする場合に特に役立ちます。詳しくは、「CodeQL によるコードスキャンについて」を参照してください。

カスタムライブラリ用の CodeQL パック

クエリやテストを含まないカスタム C++ ライブラリを含むカスタム CodeQL パックには、qlpack.yml ファイルが含まれる場合があります。このファイルの内容は次のようになります。

name: my-github-user/my-custom-libraries
version: 1.2.3
library: true
dependencies:
  codeql/cpp-all: ^0.1.2

ここで、codeql/cpp-all は、CodeQL リポジトリに含まれる C/C++ 分析用の CodeQL パックの名前です。バージョン範囲 ^0.1.2 は、このパックが、codeql/cpp-all の 0.1.2 以上で 0.2.0 未満のすべてのバージョンと互換性があることを示します。このパックで定義された CodeQL ライブラリファイル (拡張子が .qll のファイル) は、依存関係ブロックにこのパックを含むクエリパックで定義されたクエリで使用できます。

library プロパティは、このパックがライブラリパックであり、クエリが含まれていないことを示します。

カスタムクエリ用の CodeQL パック

カスタム C++ クエリとライブラリを含むカスタム CodeQL パックには、qlpack.yml ファイルが含まれる場合があります。このファイルの内容は次のようになります。

name: my-github-user/my-custom-queries
version: 1.2.3
dependencies:
  codeql/cpp-all: ^0.1.2
  my-github-user/my-custom-libraries: ^1.2.3

ここで、codeql/cpp-all は、CodeQL リポジトリに含まれる C/C++ 分析用の CodeQL パックの名前です。バージョン範囲 ^0.1.2 は、このパックが、codeql/cpp-all の 0.1.2 以上で 0.2.0 未満のすべてのバージョンと互換性があることを示します。 my-github-user/my-custom-libraries は、C++ 用のカスタム CodeQL ライブラリを含む CodeQL パックの名前です。このパックで定義されている CodeQL ライブラリファイル (拡張子が .qll のファイル) は、my-github-user/my-custom-queries パック内のクエリで使用できます。

カスタムテスト用の CodeQL パック

テストファイルを含むカスタム CodeQL パックの場合、test run コマンドでテストデータベースの作成方法を認識できるように、extractor プロパティも含める必要があります。 tests プロパティを指定することもできます。

次の qlpack.yml ファイルは、my-github-user/my-query-tests が 1.2.3 以上で 2.0.0 未満のバージョンの my-github-user/my-custom-queries に依存していることを示しています。また、テストデータベースの作成時に CLI で Java extractor を使用する必要があることを宣言します。 tests: . 行では、--strict-test-discovery オプションを指定して codeql test run を実行する際に、パック内のすべての .ql ファイルをテストとして実行する必要があることを宣言します。通常、テストパックに version プロパティは含まれません。これにより、それらが誤って発行されるのを防ぐことができます。

name: my-github-user/my-query-tests
dependencies:
  my-github-user/my-custom-queries: ^1.2.3
extractor: java-kotlin
tests: .

テストの実行について詳しくは、「カスタムクエリのテスト」をご覧ください。

CodeQL リポジトリ内の CodeQL パックの例

CodeQL リポジトリの各言語には、次の 4 つの主要な CodeQL パックがあります。

言語で使用されるデータベーススキーマ、CodeQL ライブラリ、クエリを含む言語用コアライブラリパック (<language>/ql/lib)
言語の既定のクエリとクエリスイートを含む言語用コアクエリパック (<language>/ql/src)
コア言語ライブラリとクエリのテスト (<language>/ql/test)
言語のクエリ例 (<language>/ql/examples)

コアライブラリパック

C/C++ 分析ライブラリコア言語パックの qlpack.yml ファイルの例を次に示します。

name: codeql/cpp-all
version: x.y.z-dev
dbscheme: semmlecode.cpp.dbscheme
library: true
upgrades: upgrades

次のプロパティに関する追加の注意事項:

library: これは、実行可能クエリが含まれていないライブラリパックであることを示します。他のパックの依存関係として使用することのみを目的としています。
dbscheme および upgrades: これらのプロパティは CodeQL CLI の内部用であり、言語のコア CodeQL クエリパックでのみ定義する必要があります。

コアクエリパック

C/C++ 分析クエリコアクエリパックの qlpack.yml ファイルの例を次に示します。

name: codeql/cpp-queries
version: x.y.z-dev
dependencies:
    codeql/cpp-all: "*"
    codeql/suite-helpers: "*"
suites: codeql-suites
defaultSuiteFile: codeql-suites/cpp-code-scanning.qls

次のプロパティに関する追加の注意事項:

dependencies: このクエリパックは、codeql/cpp-all と codeql/suite-helpers に依存します。これらの依存関係はソースから解決されるため、互換性のある CodeQL パックのバージョンは関係ありません。ソースからの依存関係の解決について詳しくは、「ソース依存関係」を参照してください。
suites: "既知" のクエリスイートを含むディレクトリを示します。
defaultSuiteFile: クエリスイートが指定されていない場合に使用される既定のクエリスイートファイルの名前。

コア CodeQL パックのテスト

C/C++ 分析クエリコアテストパックの qlpack.yml ファイルの例を次に示します。

name: codeql/cpp-tests
dependencies:
  codeql/cpp-all: "*"
  codeql/cpp-queries: "*"
extractor: cpp
tests: .

次のプロパティに関する追加の注意事項:

dependencies: このパックは、C++ のコア CodeQL クエリパックとライブラリパックに依存します。
extractor: これは、すべてのテストで同じ C++ 抽出子を使用してテスト用のデータベースを作成することを指定します。
tests: これは、テストの場所を指定します。この場合、テストは、パックのルートフォルダー (およびすべてのサブフォルダー) 内にあります。
version: テストパックの version プロパティはありません。これにより、テストパックが誤って発行されるのを防ぐことができます。

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

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

この記事の内容