Skip to Content
Infra & DevOpsGitLab CI/CD 사전 정의된 변수 레퍼런스
☁️ Infra & DevOps2019년 6월 9일

GitLab CI/CD 사전 정의된 변수 레퍼런스

#gitlab#ci-cd#infra-devops#pipeline#docker

1. 사전 정의된 변수(Predefined Variables)의 필요성

에서 빅데이터 모니터링 플랫폼을 MSA(Microservices Architecture)로 전환하면서, 수십 개의 백엔드 모듈을 각각 컴파일하고 Docker 이미지로 빌드하여 사내 K8s 클러스터에 배포하는 자동화 파이프라인(GitLab CI/CD) 구축이 필수적이었습니다.

이때 가장 큰 골칫거리는 버전 관리와 이미지 태깅이었습니다. 소스 코드가 푸시될 때마다 유니크한 이미지 태그를 달아 배포해야 롤백이 가능했는데, 스크립트 단에서 매번 git rev-parse HEAD 같은 명령어로 커밋 해시나 브랜치 명을 알아내는 것은 매우 번거롭고 파이프라인 코드를 지저분하게 만들었습니다.

이러한 문제를 깔끔하게 해결해 주는 것이 바로 GitLab Runner가 빌드 런타임에 컨테이너 환경 내부에 자동으로 주입해 주는 사전 정의된 환경 변수(Predefined Variables) 입니다.

2. CI/CD 변수의 핵심 개념

사전 정의된 변수란, 개발자가 별도로 .gitlab-ci.yml의 variables: 블록이나 GitLab UI 설정 화면에 등록하지 않아도 파이프라인이 실행되는 순간 기본적으로 시스템에 세팅(export)되는 환경 변수들입니다.

자주 사용되는 변수 그룹은 아래와 같습니다:

  • 커밋 식별자: 어떤 브랜치, 어떤 커밋 해시로 빌드 중인지.
  • 파이프라인 및 잡(Job) 정보: 현재 파이프라인 고유 ID, 잡 ID 등.
  • 프로젝트 메타데이터: 프로젝트 경로, 이름 등.
  • 컨테이너 레지스트리 정보: 로그인 토큰, 레지스트리 주소 등.

3. 자주 사용하는 주요 CI 변수와 활용 예시

아래는 파이프라인 컨테이너 컨텍스트 내에서 env 명령어를 쳤을 때 확인할 수 있는 핵심 변수들의 주입 예시입니다. 특히 도커 이미지 빌드 및 푸시 단계에서 CI_COMMIT_SHORT_SHA나 CI_REGISTRY 태그가 핵심적으로 사용됩니다.

① 잡 및 커밋 식별 정보

버전 태깅과 배포 이력 추적에 필수적인 변수들입니다.

bash
export CI_JOB_ID="50"
export CI_COMMIT_SHA="1ecfd275763eff1d6b4844ea3168962458c9f27a"  # Full 커밋 해시
export CI_COMMIT_SHORT_SHA="1ecfd275"                          # 짧은 8자리 커밋 해시 (가장 많이 씀)
export CI_COMMIT_REF_NAME="master"                             # 현재 브랜치 이름
export CI_COMMIT_TAG="1.0.0"                                   # git tag가 기반인 파이프라인일 경우

[활용 팁]: Docker 이미지 태깅 시 $CI_COMMIT_REF_NAME-$CI_COMMIT_SHORT_SHA (예: master-1ecfd275) 패턴을 사용하면, 이미지만 보고도 어느 브랜치의 어떤 커밋으로 만들어진 것인지 직관적으로 파악할 수 있습니다.

② 컨테이너 레지스트리 자동 로그인 (Auto-Login)

GitLab 내장 Container Registry를 사용할 때, 별도의 자격증명을 하드코딩할 필요 없이 러너가 제공하는 토큰으로 안전하게 인증할 수 있습니다.

bash
export CI_REGISTRY="registry.example.com"
export CI_REGISTRY_IMAGE="registry.example.com/gitlab-org/gitlab-ce"
export CI_REGISTRY_USER="gitlab-ci-token"
export CI_REGISTRY_PASSWORD="[MASKED_TEMPORARY_TOKEN]"

실제 로그인 적용 예시:

yaml
build:
  script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA

③ 기타 프로젝트 환경 정보

bash
export CI_PROJECT_NAME="gitlab-ce"
export CI_PROJECT_NAMESPACE="gitlab-org"
export CI_PROJECT_PATH="gitlab-org/gitlab-ce"
export CI_PIPELINE_IID="10"    # 파이프라인 실행 누적 횟수
export GITLAB_USER_EMAIL="user@example.com" # 빌드를 트리거한 사용자

4. 결론 및 회고

GitLab CI/CD의 사전 정의된 환경 변수들을 적극적으로 활용하면, 인프라 배포 코드에서 하드코딩된 값(Magic String) 들을 완벽하게 걷어낼 수 있습니다.

저희 인프라 팀 역시 변수 기반으로 .gitlab-ci.yml의 구성을 템플릿화(include 지시어 활용)한 후, 약 30여 개에 달하던 마이크로서비스들의 CI/CD 파이프라인 스크립트를 단일한 표준 템플릿 하나로 통일시키는 엄청난 생산성 향상을 거둘 수 있었습니다.

파이프라인을 구축하면서 매번 구글링을 하신다면, 공식 문서의 전체 변수 목록 페이지를 즐겨찾기 해두시는 것을 강력히 추천합니다.

Last updated on