GitLab CI/CD 변수
GitLab CI/CD 변수 (Variables)
GitLab CI/CD 변수는 파이프라인을 실행할 때마다 값을 바꿔야 하는 설정값을 담는 데 쓰여요. 비밀값은 물론 환경별 차이까지, 변수로 관리하면 파이프라인을 유연하게 만들 수 있습니다. 먼저 어떤 변수가 있고 어떻게 정의하는지 전체 그림부터 함께 볼게요.
출처: 문서
본문
CI/CD 변수란 무엇인가요?
CI/CD 변수는 파이프라인 실행 전에 설정되는 key-value 쌍이에요. 변수는 러너가 job을 시작할 때 주입되며, 스크립트에서 $VARIABLE 형태로 참조할 수 있어요. 예를 들어 배포 대상 브랜치나 API 키 같은 값을 변수로 분리해 두면, 파이프라인 정의와 실제 값을 분리할 수 있습니다.
변수에는 크게 두 종류가 있어요:
- 사전 정의된 변수(Predefined variables): GitLab이 미리 만들어 두는 변수. 파이프라인이나 job에 대한 정보(
CI_COMMIT_BRANCH,CI_JOB_NAME,CI_PIPELINE_ID등)를 담고 있어요. 이름은 접두사CI_로 시작합니다. - 사용자 정의 변수(Custom variables): 프로젝트·그룹·인스턴스 설정이나
.gitlab-ci.yml파일에서 직접 정의하는 변수예요.
변수 정의 위치
사용자 정의 변수는 다음 위치에서 만들 수 있어요:
.gitlab-ci.yml파일: job이나 파이프라인 수준에서variables:키워드로 정의. 이 파일은 버전 관리되므로 모든 변경을 추적할 수 있어요.- GitLab UI: 프로젝트·그룹·인스턴스의 Settings > CI/CD > Variables에서 정의. 이 위치의 변수는 보호(protected), 마스킹(masked), 확장(expanded) 설정을 지정할 수 있어요.
- API: 프로젝트 변수를 프로그래밍 방식으로 관리할 때 사용.
변수 유형과 특성
- 파일 변수(File variables): 변수 값을 파일로 제공받고 싶을 때
file: true를 사용해요. 인증서나 키 파일처럼 파일 형태가 필요한 도구에 유용합니다. - 마스킹(Masking): job 로그에 값이 노출되지 않도록 숨기는 설정. 비밀번호나 토큰을 정의할 때 켜 두는 게 좋아요.
- 보호(Protected): 보호된 브랜치에서 실행되는 파이프라인에서만 사용할 수 있게 제한. 프로덕션 배포 같은 민감한 job의 변수 보호에 적합해요.
- 확장(Expanded): 변수 값 안에서 다른 변수를 참조(
$OTHER_VAR)할 수 있게 하는 설정.
변수 우선순위
한 job에서 같은 이름의 변수가 여러 곳에 정의되면 가장 구체적인 정의가 우선해요. 일반적인 우선순위는 다음과 같아요(낮은 것에서 높은 것으로):
- 트리거 job에 정의된 변수(
trigger:variables) - 파이프라인 수준의
variables키워드 - 프로젝트 수준의 변수(UI에서 정의)
- 그룹 수준의 변수
- 인스턴스 수준의 변수
- job 수준의
variables키워드 — 가장 높은 우선순위
즉 job 안에 정의한 변수가 다른 모든 정의를 덮어쓰는 구조예요.
변수 전달하기
- job 사이 전달:
artifacts:reports:dotenv를 사용하면 한 job이 만든 변수를 다음 job에서 사용할 수 있어요. - 파이프라인 사이 전달: 다운스트림 파이프라인으로 변수를 넘기려면
trigger의variables를 사용해요.
변수 사용하기
- 스크립트에서:
echo "$CI_JOB_NAME"처럼$접두사로 참조. .gitlab-ci.yml에서:image: $CI_JOB_IMAGE처럼 다른 키워드 값으로도 사용 가능.- 변수 값에 변수 참조가 포함된 경우, 기본적으로 **확장(expansion)**되어 실제 값으로 치환됩니다.
파이프라인 변수 비밀값 처리
API 키나 비밀번호 같은 값을 저장할 때는 보호·마스킹 설정을 함께 켜서 로그와 접근 통제를 강화하는 걸 권장해요. 비밀값은 가능하면 러너 로컬 파일 대신 GitLab 변수 저장소에 두고, job에서만 필요할 때 참조하는 방식이 안전합니다.