database init

This content describes the most recent release of the CodeQL CLI. For more information about this release, see https://github.com/github/codeql-cli-binaries/releases.

To see details of the options available for this command in an earlier release, run the command with the --help option in your terminal.

構文

Shell

codeql database init --source-root=<dir> [--language=<lang>[,<lang>...]] [--github-auth-stdin] [--github-url=<url>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

説明

[プラミング] 空の CodeQL データベースを作成します。

まだ生の QL データセットは存在しないが、抽出ステップを実行する準備ができている CodeQL データベースのスケルトン構造を作成します。このコマンドが完了したら、1 つ以上の codeql database trace-command コマンドを実行し、続いて codeql database finalize を実行して、クエリ用にデータベースを準備します。

(この処理の一部として行われるのは、適切な言語パックの保存先を解決し、それをデータベースメタデータに格納することです。これにより、各抽出コマンドで再実行する必要はありません。抽出操作の途中でエクストラクターを切り替えることは、いずれにしても無効です。)

主なオプション

`<database>`

[必須] 作成する CodeQL データベースのパス。このディレクトリは作成され、既に存在していては "なりません" (ただし、その親は必要です)。**

--db-cluster オプションを指定すると、これはデータベース自体ではなく、同じソースルートから構築された複数の言語のデータベースを "含む" ディレクトリになります。**

このディレクトリは、構築プロセスが干渉する場所に存在しないことが重要です。たとえば、Maven プロジェクトの target ディレクトリは適切な選択肢ではありません。

`-s, --source-root=<dir>`

[必須] ソースコードのルートディレクトリ。多くの場合、これはチェックアウトルートになります。その中のファイルは、このデータベースのプライマリソースファイルと見なされます。一部の出力形式では、このディレクトリからの相対パスによってファイルが参照されます。

`--[no-]overwrite`

[詳細設定] データベースが既に存在する場合、失敗するのではなく、データベースを削除し、このコマンドを続行します。このオプションは、データベースディレクトリ全体を再帰的に削除する可能性があるため、注意して使用する必要があります。

`--codescanning-config=<file>`

[詳細設定] CodeQL データベースの作成方法と後の手順で実行するクエリについてのオプションを指定した Code Scanning 構成ファイルを読み取ります。この構成ファイルの形式について詳しくは、「code scanning のカスタマイズ」を参照してください。後の手順でこのファイルからクエリを実行するには、他のクエリを指定せずに codeql database analyze を呼び出します。

`--[no-]db-cluster`

1 つのデータベースを作成する代わりに、異なる言語のデータベースからなる "クラスター" を作成します。そのそれぞれは、コマンドラインで指定したディレクトリのサブディレクトリです。

`-l, --language=<lang>[,<lang>...]`

新しいデータベースが分析に使用される言語。

検索パスで見つかったプラグ可能な言語エクストラクターの一覧を取得するには、codeql resolve languages を使用します。

--db-cluster オプションを指定している場合は、これを複数回使用できます。または、値をコンマ区切りの言語のリストにすることができます。

このオプションを省略すると、分析対象のソースルートが GitHub リポジトリのチェックアウトである場合は、CodeQL CLI で GitHub API が呼び出され、分析する言語を自動的に決定することが試みられます。これを行うには、環境変数 GITHUB_TOKEN で、または --github-auth-stdin オプションを使用して標準入力経由で GitHub PAT トークンを指定する必要があることに注意してください。

`--[no-]calculate-baseline`

[詳細設定] 分析対象のコードに関するベースライン情報を計算し、データベースに追加します。既定では、これはソースルートがファイルシステムのルートである場合を除き、有効になります。このフラグを使用して、この動作を無効にするか、ファイルシステムのルートでも強制的に有効にすることができます。

`--[no-]allow-missing-source-root`

[詳細設定] 指定したソースルートが存在しない場合でも先に進みます。

`--[no-]begin-tracing`

[詳細設定] "間接ビルドトレース" を設定するために使用できるスクリプトをいくつか作成します。これにより、明示的なビルドコマンドが使用できない場合に既存のビルドワークフローへの統合が可能になります。どのような場合に、どのような方法でこの機能を使用するかについては、「CodeQL データベースの作成」のドキュメントを参照してください。

エクストラクターの選択オプション

`--search-path=<dir>[:<dir>...]`

エクストラクターパックが見つかる可能性があるディレクトリのリスト。ディレクトリは、エクストラクターパック自体、またはエクストラクターを直接サブディレクトリとして含むディレクトリのいずれかです。

パスに複数のディレクトリツリーが含まれている場合、それらの順序によってそれらの間の優先順位が定義されます。ターゲット言語が複数のディレクトリツリーで一致する場合、最初に指定されたものが優先されます。

CodeQL ツールチェーン自体にバンドルされているエクストラクターは常に検出されますが、個々に配布されたエクストラクターを使用する必要がある場合は、このオプションを指定する必要があります (または、より良い方法として、ユーザーごとの構成ファイルで --search-path を設定します)。

(注: Windows では、パスの区切り記号は ; です)。

GitHub API を呼び出して言語を自動検出する方法を構成するためのオプション。

`-a, --github-auth-stdin`

標準入力を使用して、GitHub Apps トークンまたは個人用アクセストークンを受け入れます。

これにより、GITHUB_TOKEN 環境変数がオーバーライドされます。

`-g, --github-url=<url>`

使用する GitHub インスタンスの URL。省略した場合、CLI でチェックアウトパスからこれを自動検出することが試みられます。これができない場合は、既定で https://github.com/ になります

パッケージマネージャーを構成するためのオプション。

`--registries-auth-stdin`

\<registry_url>=\ ペアのコンマ区切りリストを渡すことで、GitHub Enterprise Server コンテナーレジストリに対して認証を行います。

たとえば、https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2 を渡して、 2 つの GitHub Enterprise Server インスタンスに対して認証を行うことができます。

これは、CODEQL_REGISTRIES_AUTH and GITHUB_TOKEN 環境変数をオーバーライドします。 github.com コンテナーレジストリに対する認証のみが必要な場合は、代わりに、より単純な --github-auth-stdin オプションを使用して認証できます。

Windows トレースを構成するためのオプション

`--trace-process-name=<process-name>`

[Windows のみ] トレースを初期化するときに、名前がこの引数と一致する CodeQL CLI の親プロセスにトレーサーを挿入します。この名前の親プロセスが複数ある場合は、プロセスツリー内で最も下位のプロセスが選択されます。このオプションは --trace-process-level をオーバーライドするため、両方を渡した場合は、このオプションのみが使用されます。

`--trace-process-level=<process-level>`

[Windows のみ] トレース初期化時、現在のプロセスからこれだけ上位にトレーサーを挿入します。0 は、CodeQL CLI を呼び出すプロセスに対応します。引数が渡されない場合の CLI の既定の動作は、呼び出し元プロセスの親に挿入することです。

間接ビルドトレースを構成するためのオプション

`--no-tracing`

[詳細設定] 指定したコマンドをトレースしません。代わりに、必要なすべてのデータを直接生成するために使用します。

`--extra-tracing-config=<tracing-config.lua>`

[詳細設定] トレーサー構成ファイルのパス。ビルドトレーサーの動作を変更するために使用できます。ビルドコマンドの一部として実行されるコンパイラプロセスを選び、他のツールの実行をトリガーするために使用できます。エクストラクターにより、ほとんどの状況で機能する既定のトレーサー構成ファイルが提供されます。

抽出の動作を制御するオプション: 間接トレース環境にのみ適用

`-O, --extractor-option=<extractor-option-name=value>`

CodeQL エクストラクターのオプションを設定します。 extractor-option-name は、extractor_name.group1.group2.option_name または group1.group2.option_name という形式にする必要があります。 extractor_option_name がエクストラクター名で始まる場合、指定したエクストラクターはオプション group1.group2.option_name を宣言する必要があります。それ以外の場合、オプション group1.group2.option_name を宣言するエクストラクターにはオプションが設定されます。 value は、改行を含まない任意の文字列にすることができます。

このコマンドラインオプションを繰り返し使用して、複数のエクストラクターオプションを設定できます。同じエクストラクターオプションに複数の値を指定した場合、動作は、エクストラクターオプションで想定されている型によって異なります。文字列オプションでは、指定した最後の値が使用されます。配列オプションでは、指定したすべての値が順番に使用されます。このコマンドラインオプションを使用して指定したエクストラクターオプションは、--extractor-options-file で指定したエクストラクターオプションの後に処理されます。

codeql database init または codeql database begin-tracing に渡した場合、オプションは間接トレース環境にのみ適用されます。ワークフローで codeql database trace-command の呼び出しも行う場合は、必要に応じてオプションも渡す必要があります。

各エクストラクターによって宣言されたオプションの一覧を表示する方法など、CodeQL エクストラクターオプションについて詳しくは、https://codeql.github.com/docs/codeql-cli/extractor-options を参照してください。

`--extractor-options-file=<extractor-options-bundle-file>`

エクストラクターオプションのバンドルファイルを指定します。エクストラクターオプションバンドルファイルは、エクストラクターオプションを設定する JSON ファイル (拡張子 .json) または YAML ファイル (拡張子 .yaml または .yml) です。ファイルには最上位レベルのマップキー 'extractor' があり、その下にエクストラクター名が第 2 レベルのマップキーとして含まれている必要があります。それ以降のレベルのマップは入れ子になったエクストラクターグループを表し、文字列と配列のオプションは、文字列と配列の値を持つマップエントリです。

エクストラクターオプションバンドルファイルは、指定した順序で読み取られます。異なるエクストラクターオプションバンドルファイルで同じエクストラクターオプションを指定した場合、その動作はエクストラクターオプションで想定されている型によって異なります。文字列オプションでは、指定した最後の値が使用されます。配列オプションでは、指定したすべての値が順番に使用されます。このコマンドラインオプションを使用して指定したエクストラクターオプションは、--extractor-option で指定したエクストラクターオプションよりも前に処理されます。