コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

環境変数

aggrega CLI は、AGGREGA_ で始まる決まった環境変数のセットを読み取ります。各環境変数は、対応する .aggrega-config.yaml の設定を実行時に上書きします。これは、CI ジョブやシークレットを注入するオーケストレーターが、追跡対象のファイルを編集せずに制御するレイヤーです。ただし、コマンドラインフラグは引き続きすべてに優先します。

優先順位

環境変数はコミットされた設定ファイルより上に位置し(パイプラインやシークレットを注入するオーケストレーターが、追跡対象のファイルを編集せずに適用する実行時のオーバーライドです)、コマンドラインフラグより下に位置します。そのため、コマンドラインで明示的に入力した値が周囲の環境によって暗黙のうちにオーバーライドされることはありません。完全な優先順位の段階と、その下にあるファイルの階層構造については Configuration を参照してください。

未設定(または空)の変数は下の層にフォールスルーします。設定済みの値を空白で上書きすることはありません。現在適用されている設定と、各設定をどの層が決定したかを確認するには、aggrega config show --origin を実行します。

命名

変数名は、AGGREGA_ の後に設定パスを大文字のスネークケースにしたもの(ドットはアンダースコアになります)を続けたものです。signing.fulcio_url は AGGREGA_SIGNING_FULCIO_URL になります。使いやすさのために短縮されている名前が 1 つあります。workspace.catalog_dirs は PATH にならって AGGREGA_CATALOG_DIRS にバインドされます。

レジストリごとの設定 (registries[].*) には環境変数がありません。ホストごとのポリシーブロックのリストは単一の変数では表現できず、またレジストリの信頼ポリシーと署名ポリシーはコミットされる設定であり、環境からの上書きではないためです。状況に応じたフラグ、一度限りのフラグ、位置を表すフラグ (--dry-run、--trace、--detail、--output、--skip-verify、--release、--entity、および lint --allow-*/--no-allow-* 系) にも環境変数はありません。これらは実行ごとに決めるものだからです。

設定ファイルに対応する設定

変数設定パス備考
AGGREGA_DEFAULT_REGISTRYdefault_registry送信先レジストリのホスト(デフォルトは hub.aggrega.ai)。ファイル内で default_registry を書くのと同じ形式で書きます。詳しくはレジストリホストの書き方を参照してください。この形式に従わない値は、設定の解決時にこの変数名を示して拒否されます。
AGGREGA_OFFLINEofflineブール値。すべてのネットワーク送信を禁止します。取得、プル、入手、プッシュ、署名、またはレジストリへの接続を行うコマンドはすべて、接続を試みる代わりに明示的に拒否します。ビルドはマシンがすでに保持しているもの、つまりロックファイル、キャッシュ、ローカルのカタログディレクトリのみを使用し、--auto-pull はレジストリに接続せずにこれらのディレクトリからロックファイルのカタログエンティティを補充します(チャートをリモートソースから取得する Recipe は、オフラインでは引き続き停止します)。ディスカバリはローカルのインデックスを読み込みます。非推奨の通知はライブで問い合わせるのではなくビルド済みのインデックスから提供され、リモートレジストリによるカタログ解決の段階はスキップされます。認識されないコマンドが表示するプラグインのヒントは、この設定にかかわらずローカルのインデックスのみを読み込みます。キャッシュ済みまたは固定済みの素材の検証は引き続き実行されます。オフラインが禁止するのは取得であり、ローカルでの検査ではありません。--offline はこの変数より優先されるフラグで、どちらの方向にも働きます。1 回の実行についてこの状態を設定し、--offline=false は、この変数または設定ファイルがオフラインを設定している場合でも、1 回の実行についてネットワークを許可します。
AGGREGA_AUTO_PULLauto_pullブール値。ビルド時に不足している依存関係を自動的に取得します。
AGGREGA_ARTIFACT_CACHE_DIRartifact_cache_dirディスク上のコンテンツキャッシュのディレクトリ。ワークスペースのルートからの相対パスで書くため、コマンドをどこで実行しても同じディレクトリを指します。絶対パスの値は拒否され、ワークスペースのルートそのものを指す値も拒否されます。キャッシュには専用のサブディレクトリを指定してください。
AGGREGA_CATALOG_DIRSworkspace.catalog_dirsOS のパスリスト区切り文字で区切ります(Unix では :)。絶対パスを指定してください。設定済みのリストを置き換えます。workspace.releases で独自のリストを与えられた Release は、そのリストを維持します。
AGGREGA_SIGNING_FULCIO_URLsigning.fulcio_urlキーレス署名用の Fulcio CA の URL。
AGGREGA_SIGNING_REKOR_URLsigning.rekor_urlキーレス署名用の Rekor 透明性ログの URL。
AGGREGA_SIGNING_TIMESTAMP_URLsigning.timestamp_urlキーレス署名用の RFC3161 タイムスタンプ局の URL。
AGGREGA_SIGNING_KEY_PATHsigning.key_pathキー付き署名に使用する、保持している ECDSA P-256 キーの PEM へのパス。パスを指すだけであり、キーの素材そのものではありません。
AGGREGA_SIGNING_REQUIREDsigning.requiredブール値。signing.kinds が対象とする種別の公開と利用に署名を必須にします。要件をオンにするだけでオフにすることはなく、これを設定した設定ファイルは設定されたままにします。
AGGREGA_SIGNING_KINDSsigning.kindsOS のパスリスト区切り文字で区切ります (Unix では :)。各エントリは kind: に書くとおりの種別、または all です。要件の対象となる種別を広げるだけで狭めることはなく、署名可能な種別でない値は、この変数を示して拒否されます。
AGGREGA_SKIP_SIGNATURE_VERIFICATIONskip_signature_verificationブール値。署名の検証をグローバルに無効にします。この動作は明示的に通知され、プルのたびに警告が記録されます。
AGGREGA_WORKSPACE_ROOT(--workspace-root と対になります)ワークスペースルートの絶対パスで、ディスカバリをスキップします。すべてのコマンドと、独自のワークスペースを指定しない aggrega mcp へのすべてのリクエストに適用されます。設定フィールドではありません。フラグが設定されている場合はフラグが優先されます。空に設定すると未設定として扱われます。ただし例外として、AGGREGA_BUNDLE_VERSION を持ち、--workspace-root が指定されていない標準入出力経由の aggrega mcp、つまり Workspace folder 設定が空のままデスクトップバンドルから起動された場合は、独自のワークスペースを指定しないすべての呼び出しに対し、その設定名を示す拒否で応答します。既存のフォルダを指していない場合、ワークスペースを読み込むすべてのコマンドは他の処理を行う前に拒否し、aggrega serve と aggrega mcp のリスナーは起動を拒否します。標準入出力経由の aggrega mcp はそのまま起動し、そのワークスペースで動作するすべての呼び出しに拒否で応答します。いずれの拒否も、この変数と、それを設定するデスクトップアプリケーションの Workspace folder 設定を示し、与えられた値をそのまま引用します。
AGGREGA_BUNDLE_VERSION(デスクトップバンドルが設定します)aggrega mcp を起動したデスクトップバンドルのバージョンで、バンドルがサーバーの環境に設定します。設定フィールドではありません。サーバーは起動時に一度だけこれを読み込み、引数なしで呼び出された describe-capabilities で自身のバージョンと並べて報告し、両者が異なるリリースに由来する場合はその旨を示します。差異があっても拒否されることはありません。この変数の存在はバンドルからの起動であることも示すため、上の行で説明したとおり、これと並ぶ空の AGGREGA_WORKSPACE_ROOT は未設定として扱われずに拒否されます。空に設定すると未設定として扱われます。

AGGREGA_CONFIG は、プロジェクト自身のファイルの下位に読み込む明示的なグローバル設定ファイルを指します。個々の設定を上書きするのではなく、どのファイルを適用するかを選択します。未設定の場合、この層はプラットフォームのデフォルトの場所から自動的に読み込まれます。Windows では APPDATA 環境変数が指すディレクトリ内の aggrega\config.yaml、それ以外では XDG_CONFIG_HOME が指すディレクトリ内の aggrega/config.yaml で、フォールバックとして ~/.config/aggrega/config.yaml が使われます。設定を参照してください。

マシン自身のファイルの場所

グローバル設定ファイルとマシン全体のキャッシュは、各プラットフォームがユーザー自身のファイルを保持する場所に置かれるため、aggrega はそれらの場所を示す変数も読み込みます。いずれも AGGREGA_ 変数ではなく、設定を上書きすることもありません。それぞれ、何も指定されていないときにファイルを探す場所を示します。

変数読み込まれる OS配置するもの
APPDATAWindowsグローバル設定ファイル。APPDATA が指すディレクトリ内の aggrega\config.yaml に置かれます。
LOCALAPPDATAWindowsマシン全体のキャッシュ。LOCALAPPDATA が指すディレクトリ内の aggrega\cache 以下に置かれます。
XDG_CONFIG_HOME、次に HOMELinux、macOS、その他の Unix システムグローバル設定ファイル。XDG_CONFIG_HOME が指すディレクトリ内の aggrega/config.yaml、または XDG_CONFIG_HOME が未設定の場合は ~/.config/aggrega/config.yaml に置かれます。
XDG_CACHE_HOME、次に HOMELinux とその他の Unix システムマシン全体のキャッシュ。XDG_CACHE_HOME が指すディレクトリ内の aggrega ディレクトリ以下、または XDG_CACHE_HOME が未設定の場合は ~/.cache/aggrega 以下に置かれます。絶対パスでない XDG_CACHE_HOME はキャッシュを配置せず、その場合コンパイル済みのプラグインはその実行の間だけ保持されます。
HOMEmacOSマシン全体のキャッシュ。~/Library/Caches/aggrega 以下に置かれます。

AGGREGA_CONFIG または --config は、すべてのプラットフォームでグローバルファイルを直接指定し、これらより優先されます。プロジェクト自身のキャッシュはこれらのいずれによっても配置されず、プロジェクト内の artifact_cache_dir 以下に置かれます。aggrega config init は、実行したマシン上でグローバルファイルとマシン全体のキャッシュがどこにあるかを示します。

ブール値

ブール値の変数は true、false、1、0 を受け付けます(大文字と小文字を区別しません)。それ以外の空でない値は、黙って推測されるのではなく明示的なエラーになります。YAML とは異なり、yes/no/on/off は受け付けられません。

シークレット

シークレットは環境変数またはフラグで指定し、設定フィールドには決してなりません。

変数目的優先順位
AGGREGA_IDENTITY_TOKENキーレス署名用の OIDC ID トークン。--identity-token フラグ > AGGREGA_IDENTITY_TOKEN > 環境の GitHub Actions OIDC > SIGSTORE_ID_TOKEN。
AGGREGA_REGISTRY_PASSWORD非対話的な aggrega login のためのレジストリパスワード。--password-stdin > AGGREGA_REGISTRY_PASSWORD > 対話的プロンプト。

SIGSTORE_ID_TOKEN は、sigstore エコシステムとの相互運用のための ID トークンの別名として受け付けられ、優先順位は AGGREGA_IDENTITY_TOKEN と環境の GitHub Actions エンドポイントより下です。これは、より広い sigstore ツール群がすでに設定している変数です。

同じ ID 解決が 3 つの署名コマンド aggrega push --sign、aggrega sign、aggrega deprecate すべてに使われます。対話的なターミナルでは、いずれもフラグなしでブラウザフローを通じて短期間有効なトークンを取得します。GitHub Actions では、いずれもランナーの環境エンドポイントから新しいワークフロー OIDC トークンを自動的に発行するため、トークンをエクスポートする必要はありません。それ以外の非対話的な実行にはターミナルも環境エンドポイントもないため、トークンを明示的に指定する必要があります(AGGREGA_IDENTITY_TOKEN をエクスポートするか、--identity-token を渡します)。指定されたトークンも環境エンドポイントもターミナルもない場合、キーレス署名は待機状態のまま放置されるのではなく拒否されます。

CI のガイダンス(GitHub Actions)

GitHub Actions では、CLI がランナーの環境 OIDC エンドポイントを検出し、署名ごとに新しいワークフロートークンを自動的に発行します。ジョブにトークン発行の権限を付与すれば、トークンをエクスポートせずに署名できます。

permissions:
id-token: write # allow the job to mint a workflow OIDC token
# ...
- run: aggrega push <entity> --sign

aggrega sign と aggrega deprecate でも同様です。自動的に発行されるものではなく特定の ID に固定するには、AGGREGA_IDENTITY_TOKEN を明示的にエクスポートします。明示的なトークン(または --identity-token)は常に環境エンドポイントより優先されます。

- run: |
AGGREGA_IDENTITY_TOKEN=$(curl -s -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=sigstore" | jq -r .value)
export AGGREGA_IDENTITY_TOKEN
aggrega push <entity> --sign

GitHub Actions 以外の CI には環境エンドポイントがありません。そのプロバイダーの OIDC の仕組みから AGGREGA_IDENTITY_TOKEN をエクスポートするか、--identity-token を渡してください。

対話的なバッチの場合、対応するのは aggrega auth token です。これはブラウザの OIDC フローを 1 回実行し、ID トークンを stdout に出力するため、同じ方法でエクスポートできます。

Terminal window
export AGGREGA_IDENTITY_TOKEN=$(aggrega auth token)

aggrega-auth.md を参照してください。どちらの方法でも、一連の aggrega sign の呼び出しで 1 つの ID を再利用でき、アーティファクトごとのブラウザ往復は不要になります。

AGGREGA_REGISTRY_PASSWORD より --password-stdin を優先してください。 環境変数は子プロセスから読み取ることができ、シェルに残る場合があります。パスワードには stdin のほうが安全な経路です。この環境変数は CI での利便性のために存在します。

関連項目