콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

환경 변수

aggrega CLI는 AGGREGA_ 접두사가 붙은 정해진 환경 변수 집합을 읽습니다. 각 변수는 런타임에 해당하는 .aggrega-config.yaml 설정을 재정의합니다. 이는 CI 작업이나 비밀 값을 주입하는 오케스트레이터가 추적 대상 파일을 편집하지 않고 제어하는 계층이며, 명령줄 플래그는 여전히 모든 것보다 우선합니다.

우선순위

환경 변수는 커밋된 구성 파일보다 위에 있으며(파이프라인이나 비밀을 주입하는 오케스트레이터가 추적되는 파일을 편집하지 않고 적용하는 런타임 재정의입니다) 명령줄 플래그보다 아래에 있습니다. 따라서 명령줄에 명시적으로 입력한 값이 주변 환경에 의해 아무런 알림 없이 재정의되는 일은 없습니다. 전체 우선순위 단계와 그 아래에 있는 파일들의 계층 구조는 구성에서 설명합니다.

설정되지 않은(또는 비어 있는) 변수는 아래 계층으로 넘어갑니다. 구성된 값을 빈 값으로 덮어쓰는 일은 없습니다. 현재 적용되는 구성과 각 설정을 어느 계층이 결정했는지 확인하려면 aggrega config show --origin을 실행합니다.

이름 규칙

변수 이름은 AGGREGA_ 뒤에 해당 구성 경로를 대문자 스네이크 케이스로 바꾼 것(점은 밑줄로 바뀝니다)을 붙인 것입니다. 예를 들어 signing.fulcio_url은 AGGREGA_SIGNING_FULCIO_URL이 됩니다. 사용 편의를 위해 이름 하나는 줄여 씁니다. 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불리언. 모든 네트워크 송신을 금지합니다. 가져오기, 풀, 획득, 푸시, 서명 또는 레지스트리 접속을 하려는 모든 명령은 연결하는 대신 명시적으로 거부하며, 빌드는 머신이 이미 보유한 것만 사용합니다. 즉 lockfile, 캐시, 로컬 카탈로그 디렉터리를 사용하며, --auto-pull은 레지스트리에 접속하지 않고 이 디렉터리에서 lockfile의 카탈로그 엔터티를 채웁니다(차트를 원격 소스에서 가져오는 Recipe는 오프라인에서 여전히 중단됩니다). 이때 탐색은 로컬 인덱스를 읽습니다. 지원 중단 안내는 실시간으로 조회하는 대신 빌드된 인덱스에서 제공되며, 원격 레지스트리 카탈로그 확인 단계는 건너뜁니다. 인식되지 않는 명령이 출력하는 플러그인 힌트는 이 설정과 관계없이 로컬 인덱스만 읽습니다. 이미 캐시되었거나 고정된 자료의 검증은 계속 실행됩니다. 오프라인은 가져오기를 금지할 뿐 로컬 검사를 금지하지 않습니다. --offline은 양방향 모두에서 이 변수보다 우선하는 플래그입니다. 한 번의 실행에 대해 이 모드를 설정하며, --offline=false는 이 변수나 구성 파일이 오프라인을 설정한 경우에도 한 번의 실행에 대해 네트워크를 허용합니다.
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_ 변수가 아니며 설정을 재정의하지도 않습니다. 각 변수는 아무것도 파일을 지정하지 않을 때 파일을 찾는 위치를 나타냅니다.

변수읽는 플랫폼위치를 정하는 대상
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은 ID 토큰에 대한 sigstore 생태계 상호 운용 별칭으로 인정되며, AGGREGA_IDENTITY_TOKEN과 주변 GitHub Actions 엔드포인트보다 낮은 순위를 가집니다. 이는 더 넓은 sigstore 도구가 이미 설정하는 변수입니다.

동일한 ID 확인 과정이 세 가지 서명 명령 aggrega push --sign, aggrega sign, aggrega deprecate 모두에 사용됩니다. 대화형 터미널에서는 각 명령이 플래그 없이 브라우저 흐름을 통해 수명이 짧은 토큰을 획득합니다. GitHub Actions에서는 각 명령이 러너의 주변 엔드포인트에서 새 워크플로 OIDC 토큰을 자동으로 발급하므로 토큰을 export할 필요가 없습니다. 그 밖의 비대화형 실행에는 터미널도 주변 엔드포인트도 없으므로 토큰을 명시적으로 제공해야 합니다(AGGREGA_IDENTITY_TOKEN을 export하거나 --identity-token을 전달). 제공된 토큰, 주변 엔드포인트, 터미널이 모두 없으면 키리스 서명은 멈춘 채로 남지 않고 거부됩니다.

CI 안내(GitHub Actions)

GitHub Actions에서 CLI는 러너의 주변 OIDC 엔드포인트를 감지하고 서명마다 새 워크플로 토큰을 자동으로 발급합니다. 작업에 토큰 발급 권한을 부여하면 토큰을 export하지 않고 서명할 수 있습니다:

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

aggrega sign과 aggrega deprecate도 마찬가지입니다. 자동 발급된 ID 대신 특정 ID를 고정하려면 AGGREGA_IDENTITY_TOKEN을 명시적으로 export합니다. 명시적 토큰(또는 --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을 export하거나 --identity-token을 전달하십시오.

대화형 일괄 작업에 대응하는 방법은 aggrega auth token입니다. 이 명령은 브라우저 OIDC 흐름을 한 번 실행하고 ID 토큰을 stdout에 출력하므로 같은 방식으로 export할 수 있습니다:

Terminal window
export AGGREGA_IDENTITY_TOKEN=$(aggrega auth token)

aggrega-auth.md를 참고하십시오. 어느 방법이든 일련의 aggrega sign 호출이 아티팩트마다 브라우저를 오가지 않고 하나의 ID를 재사용할 수 있게 합니다.

AGGREGA_REGISTRY_PASSWORD보다 --password-stdin을 사용하십시오. 환경 변수는 자식 프로세스가 읽을 수 있고 셸에 남을 수 있습니다. 비밀번호에는 stdin이 더 안전한 경로입니다. 이 환경 변수는 CI 편의를 위해 존재합니다.

참고 항목