Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Zmienne środowiskowe

CLI aggrega odczytuje stały zestaw zmiennych środowiskowych z prefiksem AGGREGA_. Każda z nich nadpisuje w czasie wykonania odpowiednie ustawienie z .aggrega-config.yaml — jest to warstwa, którą kontroluje zadanie CI lub orkiestrator wstrzykujący sekrety bez edytowania śledzonych plików — przy czym flaga wiersza poleceń nadal ma pierwszeństwo przed wszystkim.

Kolejność pierwszeństwa

Zmienna środowiskowa ma pierwszeństwo przed zatwierdzonymi w repozytorium plikami konfiguracyjnymi — jest to nadpisanie w czasie wykonania, które potok lub orkiestrator wstrzykujący sekrety stosuje bez edytowania śledzonego pliku — i ustępuje fladze wiersza poleceń, dzięki czemu jawna wartość wpisana w wierszu poleceń nigdy nie zostaje po cichu nadpisana przez otaczające środowisko. Konfiguracja opisuje pełną hierarchię oraz warstwy plików poniżej.

Zmienna nieustawiona (lub pusta) przechodzi do warstwy niższej — nigdy nie nadpisuje skonfigurowanej wartości pustą. Aby zobaczyć konfigurację obowiązującą w danej chwili oraz to, która warstwa zdecydowała o każdym ustawieniu, należy uruchomić aggrega config show --origin.

Nazewnictwo

Nazwa zmiennej to AGGREGA_, po którym następuje jej ścieżka konfiguracji zapisana wielkimi literami w stylu snake case (kropki zamieniają się w podkreślenia): signing.fulcio_url staje się AGGREGA_SIGNING_FULCIO_URL. Jedna nazwa została skrócona dla wygody — workspace.catalog_dirs wiąże się z AGGREGA_CATALOG_DIRS, na wzór PATH.

Ustawienia poszczególnych rejestrów (registries[].*) nie mają zmiennej środowiskowej: listy bloków zasad dla poszczególnych hostów nie da się wyrazić jedną zmienną, a zasady zaufania i podpisywania rejestru są zatwierdzoną konfiguracją, a nie nadpisaniem pochodzącym ze środowiska. Flagi sytuacyjne, jednorazowe i pozycyjne (--dry-run, --trace, --detail, --output, --skip-verify, --release, --entity oraz rodzina lint --allow-*/--no-allow-*) również nie mają zmiennej środowiskowej — są to decyzje podejmowane przy każdym uruchomieniu.

Ustawienia oparte na konfiguracji

ZmiennaŚcieżka w konfiguracjiUwagi
AGGREGA_DEFAULT_REGISTRYdefault_registryHost docelowy/rejestru (domyślnie hub.aggrega.ai). Zapisywany tak, jak zapisuje się default_registry w pliku — zob. jak zapisuje się host rejestru — a wartość zapisana inaczej jest odrzucana podczas rozwiązywania konfiguracji, z podaniem nazwy tej zmiennej.
AGGREGA_OFFLINEofflineWartość logiczna. Zabrania całego ruchu wychodzącego do sieci: każde polecenie, które pobierałoby, ściągało, pozyskiwało, wypychało, podpisywało lub kontaktowało się z rejestrem, zamiast nawiązywać połączenie, jawnie odmawia działania, a kompilacja korzysta wyłącznie z tego, co maszyna już posiada — z pliku blokady, pamięci podręcznej i lokalnych katalogów, z których --auto-pull uzupełnia encje katalogowe pliku blokady bez łączenia się z rejestrem (encja Recipe, której chart jest pobierany ze zdalnego źródła, nadal zatrzymuje się w trybie offline). Wykrywanie odczytuje wtedy lokalny indeks — informacja o wycofaniu jest serwowana ze zbudowanego indeksu zamiast sprawdzania na żywo, a poziom rozwiązywania katalogu ze zdalnego rejestru jest pomijany; podpowiedź dotycząca wtyczki, którą wyświetla nierozpoznane polecenie, odczytuje wyłącznie lokalny indeks, niezależnie od wartości tego ustawienia. Weryfikacja materiałów już zapisanych w pamięci podręcznej lub przypiętych nadal się odbywa — tryb offline zabrania pobierania, a nie lokalnego sprawdzenia. --offline to flaga nadrzędna wobec niej, w obu kierunkach: ustawia ten tryb dla jednego uruchomienia, a --offline=false zezwala na dostęp do sieci dla jednego uruchomienia tam, gdzie tę zmienną lub plik konfiguracyjny ustawiono.
AGGREGA_AUTO_PULLauto_pullWartość logiczna. Automatyczne pobieranie brakujących zależności podczas kompilacji.
AGGREGA_ARTIFACT_CACHE_DIRartifact_cache_dirKatalog pamięci podręcznej treści na dysku, zapisywany względem katalogu głównego obszaru roboczego, tak aby wskazywał ten sam katalog niezależnie od miejsca uruchomienia polecenia. Wartość bezwzględna jest odrzucana, podobnie jak wartość wskazująca sam katalog główny obszaru roboczego — pamięci podręcznej należy przydzielić osobny podkatalog.
AGGREGA_CATALOG_DIRSworkspace.catalog_dirsRozdzielana separatorem list ścieżek systemu operacyjnego (: w systemach Unix). Należy podawać ścieżki bezwzględne. Zastępuje skonfigurowaną listę; encja Release, która ma własną listę w workspace.releases, zachowuje tę listę.
AGGREGA_SIGNING_FULCIO_URLsigning.fulcio_urlURL urzędu certyfikacji Fulcio dla podpisywania bezkluczowego.
AGGREGA_SIGNING_REKOR_URLsigning.rekor_urlURL dziennika przejrzystości Rekor dla podpisywania bezkluczowego.
AGGREGA_SIGNING_TIMESTAMP_URLsigning.timestamp_urlURL urzędu znaczników czasu RFC3161 dla podpisywania bezkluczowego.
AGGREGA_SIGNING_KEY_PATHsigning.key_pathŚcieżka do posiadanego klucza ECDSA P-256 w formacie PEM do podpisywania kluczem. Wyłącznie wskaźnik ścieżki — nigdy materiał klucza.
AGGREGA_SIGNING_REQUIREDsigning.requiredWartość logiczna. Wymaga podpisu przy publikowaniu i używaniu rodzajów objętych przez signing.kinds. Włącza ten wymóg i nigdy go nie wyłącza: plik konfiguracji, który go ustawia, utrzymuje go włączonym.
AGGREGA_SIGNING_KINDSsigning.kindsRozdzielane separatorem listy ścieżek systemu operacyjnego (: w systemach Unix), każdy wpis to rodzaj zapisany tak jak jego kind: albo all. Poszerza rodzaje objęte wymogiem i nigdy ich nie zawęża; wartość, która nie jest rodzajem podlegającym podpisaniu, jest odrzucana ze wskazaniem tej zmiennej.
AGGREGA_SKIP_SIGNATURE_VERIFICATIONskip_signature_verificationWartość logiczna. Globalnie wyłącza weryfikację podpisów — jawnie: każde pobranie zapisuje ostrzeżenie w logu.
AGGREGA_WORKSPACE_ROOT(w parze z --workspace-root)Bezwzględny katalog główny obszaru roboczego, z pominięciem wykrywania — w każdym poleceniu i w każdym żądaniu do aggrega mcp, które nie wskazuje własnego obszaru roboczego. Nie jest polem konfiguracji; ustawiona flaga ma pierwszeństwo. Pusta wartość jest traktowana jak brak ustawienia — z wyjątkiem aggrega mcp działającego przez standardowe wejście i wyjście, z ustawioną AGGREGA_BUNDLE_VERSION i bez --workspace-root, czyli uruchomienia przez pakiet desktopowy z pustym ustawieniem Workspace folder, które na każde wywołanie niewskazujące własnego obszaru roboczego odpowiada odmową wskazującą to ustawienie. Jeśli wartość nie wskazuje istniejącego folderu, każde polecenie odczytujące swój obszar roboczy odmawia działania, zanim zrobi cokolwiek innego, aggrega serve i nasłuchujący aggrega mcp odmawiają uruchomienia, a aggrega mcp działający przez standardowe wejście i wyjście mimo to się uruchamia i na każde wywołanie działające w tym obszarze roboczym odpowiada odmową — każda z nich wskazuje tę zmienną wraz z ustawieniem Workspace folder aplikacji desktopowej, które ją ustawia, i przytacza wartość w podanej postaci.
AGGREGA_BUNDLE_VERSION(ustawiana przez pakiet desktopowy)Wersja pakietu desktopowego, który uruchomił aggrega mcp, ustawiana przez pakiet w środowisku serwera. Nie jest polem konfiguracji. Serwer odczytuje ją raz przy starcie i zgłasza obok własnej wersji w describe-capabilities wywołanym bez argumentów, informując, gdy obie pochodzą z różnych wydań; różnica nie powoduje żadnej odmowy. Jej obecność oznacza też uruchomienie przez pakiet, więc pusta AGGREGA_WORKSPACE_ROOT obok niej jest odrzucana, a nie traktowana jak brak ustawienia, jak opisano w wierszu powyżej. Pusta wartość jest traktowana jak brak ustawienia.

AGGREGA_CONFIG wskazuje jawnie globalny plik konfiguracyjny ładowany pod własnymi plikami projektu; wybiera, który plik obowiązuje, zamiast nadpisywać pojedyncze ustawienie. Gdy nie jest ustawiona, ta warstwa ładuje się automatycznie z domyślnej lokalizacji platformy — w systemie Windows z aggrega\config.yaml w katalogu wskazanym przez zmienną środowiskową APPDATA, a w pozostałych systemach z aggrega/config.yaml w katalogu wskazanym przez XDG_CONFIG_HOME, z rezerwową lokalizacją ~/.config/aggrega/config.yaml. Zob. Konfiguracja.

Gdzie znajdują się własne pliki maszyny

Globalny plik konfiguracyjny i pamięci podręczne dla całej maszyny znajdują się tam, gdzie każda platforma przechowuje własne pliki użytkownika, dlatego aggrega odczytuje też zmienne wskazujące te miejsca. Żadna z nich nie jest zmienną AGGREGA_ i żadna nie nadpisuje ustawienia: każda określa, gdzie szukać pliku, gdy nic go nie wskazuje.

ZmiennaOdczytywana wCo lokalizuje
APPDATAWindowsGlobalny plik konfiguracyjny, w aggrega\config.yaml w katalogu wskazanym przez APPDATA.
LOCALAPPDATAWindowsPamięci podręczne dla całej maszyny, w aggrega\cache w katalogu wskazanym przez LOCALAPPDATA.
XDG_CONFIG_HOME, następnie HOMELinux, macOS i pozostałe systemy UnixGlobalny plik konfiguracyjny, w aggrega/config.yaml w katalogu wskazanym przez XDG_CONFIG_HOME lub w ~/.config/aggrega/config.yaml, gdy XDG_CONFIG_HOME nie jest ustawiona.
XDG_CACHE_HOME, następnie HOMELinux i pozostałe systemy UnixPamięci podręczne dla całej maszyny, w katalogu aggrega wewnątrz katalogu wskazanego przez XDG_CACHE_HOME lub w ~/.cache/aggrega, gdy XDG_CACHE_HOME nie jest ustawiona. XDG_CACHE_HOME, która nie jest ścieżką bezwzględną, nie lokalizuje żadnej pamięci podręcznej, a skompilowane wtyczki są wtedy przechowywane tylko na czas uruchomienia.
HOMEmacOSPamięci podręczne dla całej maszyny, w ~/Library/Caches/aggrega.

AGGREGA_CONFIG lub --config wprost wskazuje plik globalny na każdej platformie i ma pierwszeństwo przed tymi zmiennymi. Żadna z nich nie lokalizuje własnych pamięci podręcznych projektu: znajdują się one wewnątrz projektu, w artifact_cache_dir. aggrega config init podaje, gdzie na maszynie, na której działa, znajdują się zarówno plik globalny, jak i pamięci podręczne dla całej maszyny.

Wartości logiczne

Zmienna logiczna przyjmuje true, false, 1 lub 0 (bez rozróżniania wielkości liter). Każda inna niepusta wartość jest jawnym błędem, a nie cichym zgadywaniem — w odróżnieniu od YAML wartości yes/no/on/off nie są akceptowane.

Sekrety

Sekrety podaje się przez zmienną środowiskową lub flagę i nigdy nie są polami konfiguracji.

ZmiennaPrzeznaczenieKolejność pierwszeństwa
AGGREGA_IDENTITY_TOKENToken tożsamości OIDC do podpisywania bezkluczowego.Flaga --identity-token > AGGREGA_IDENTITY_TOKEN > otoczeniowy OIDC GitHub Actions > SIGSTORE_ID_TOKEN.
AGGREGA_REGISTRY_PASSWORDHasło do rejestru dla nieinteraktywnego aggrega login.--password-stdin > AGGREGA_REGISTRY_PASSWORD > interaktywny monit.

SIGSTORE_ID_TOKEN jest honorowany jako alias tokenu tożsamości zapewniający interoperacyjność z ekosystemem sigstore, o priorytecie niższym niż AGGREGA_IDENTITY_TOKEN i otoczeniowy endpoint GitHub Actions. Jest to zmienna, którą szersze narzędzia sigstore już ustawiają.

To samo rozwiązywanie tożsamości obsługuje wszystkie trzy polecenia podpisujące — aggrega push --sign, aggrega sign i aggrega deprecate. W interaktywnym terminalu każde z nich uzyskuje krótkotrwały token przez przepływ w przeglądarce, bez żadnych flag. W GitHub Actions każde automatycznie generuje świeży token OIDC przepływu pracy z otoczeniowego endpointu runnera, więc eksport tokenu nie jest potrzebny. Każde inne nieinteraktywne uruchomienie nie ma terminala ani otoczeniowego endpointu, więc musi jawnie podać token (należy wyeksportować AGGREGA_IDENTITY_TOKEN lub przekazać --identity-token). Bez podanego tokenu, bez otoczeniowego endpointu i bez terminala podpisywanie bezkluczowe jest odrzucane, zamiast się zawieszać.

Wskazówki dla CI (GitHub Actions)

W GitHub Actions CLI wykrywa otoczeniowy endpoint OIDC runnera i automatycznie generuje świeży token przepływu pracy dla każdego podpisu. Należy nadać zadaniu uprawnienie do generowania tokenu i podpisywać bez eksportu tokenu:

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

To samo dotyczy aggrega sign i aggrega deprecate. Aby przypiąć konkretną tożsamość zamiast generowanej automatycznie, należy jawnie wyeksportować AGGREGA_IDENTITY_TOKEN; jawny token (lub --identity-token) zawsze ma pierwszeństwo przed otoczeniowym endpointem:

- 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

CI inne niż GitHub Actions nie ma otoczeniowego endpointu: należy wyeksportować AGGREGA_IDENTITY_TOKEN z mechanizmu OIDC danego dostawcy lub przekazać --identity-token.

Dla partii interaktywnej odpowiednikiem jest aggrega auth token, które raz uruchamia przepływ OIDC w przeglądarce i wypisuje token tożsamości na stdout, aby można go było wyeksportować w ten sam sposób:

Terminal window
export AGGREGA_IDENTITY_TOKEN=$(aggrega auth token)

Zobacz aggrega-auth.md. Każda z tych dróg pozwala partii wywołań aggrega sign używać jednej tożsamości bez przechodzenia przez przeglądarkę dla każdego artefaktu.

Należy preferować --password-stdin zamiast AGGREGA_REGISTRY_PASSWORD. Zmienna środowiskowa jest czytelna dla procesów potomnych i może pozostać w powłoce; stdin jest bezpieczniejszą drogą przekazania hasła. Zmienna środowiskowa istnieje jako ułatwienie dla CI.

Zobacz także