liminfo

GitLab CI Reference

GitLab CI/CD 파이프라인 레퍼런스

27개 결과

GitLab CI Reference 소개

GitLab CI 레퍼런스는 GitLab 내장 CI/CD 시스템에서 사용하는 파이프라인 설정 파일인 .gitlab-ci.yml에 대한 검색 가능한 YAML 구문 치트 시트입니다. 파이프라인 수준 설정(stages, include, workflow rules, 전역 default 설정), 스테이지 순서 및 DAG 의존성(stage 지정, .pre/.post 예약 스테이지, 순서 무시 실행을 위한 needs, 아티팩트 전파를 위한 dependencies), 작업 정의(script, image, before_script/after_script, rules, only/except, 서비스 컨테이너), 변수 관리(인라인 변수, 내장 CI_COMMIT_SHA 및 CI_PIPELINE_ID, 컨테이너 빌드용 CI_REGISTRY_IMAGE, 작업 간 변수 전달을 위한 dotenv 아티팩트), 캐시 설정(캐시 키 전략, package-lock.json을 이용한 파일 기반 키, 읽기 전용 cache policy), 아티팩트 처리(경로 기반 아티팩트, JUnit 및 Cobertura 리포트, 조건부 아티팩트 저장, expose_as를 이용한 MR 미리보기 링크)의 여섯 가지 주요 영역을 다룹니다.

GitLab CI는 GitLab 저장소 내에서 빌드, 테스트, 배포 파이프라인을 자동화하기 위해 소프트웨어 개발 팀이 널리 채택하고 있습니다. 플랫폼 엔지니어, 백엔드 개발자, DevOps 실무자들이 MR 파이프라인, CI_REGISTRY_IMAGE를 이용한 컨테이너 레지스트리 빌드, 스케줄 작업, 다중 환경 배포 구현에 활용합니다. needs:를 통한 DAG 실행 모델은 엄격한 스테이지 순서를 우회하여 병렬 작업 실행을 가능하게 하므로, 복잡한 프로젝트의 파이프라인 실행 시간을 크게 줄일 수 있습니다.

이 레퍼런스의 모든 항목은 YAML 지시어 이름, 쉬운 설명, .gitlab-ci.yml 파일에 바로 복사할 수 있는 완전한 들여쓰기 YAML 블록을 제공합니다. 최신 rules: 구문과 레거시 only/except 방식의 차이, 캐시(반복 파이프라인 가속)와 아티팩트(작업 간 빌드 출력 전달)의 차이, dotenv 아티팩트를 이용한 동적 변수 전달 방법을 구체적으로 설명합니다.

주요 기능

  • 파이프라인 설정: .gitlab-ci.yml 구조, stages, include(템플릿/로컬/원격), workflow rules, default 블록
  • 스테이지 순서: .pre/.post 예약 스테이지, DAG 병렬 실행을 위한 needs, 아티팩트 제어를 위한 dependencies
  • 작업 정의: script, Docker 이미지 선택, before_script/after_script, if/when을 이용한 rules, 서비스 컨테이너
  • 변수: 인라인 변수, $CI_COMMIT_SHA, $CI_PIPELINE_ID, $CI_REGISTRY_IMAGE, 작업 간 전달을 위한 dotenv 아티팩트
  • 캐시: 브랜치 범위 캐시 키, 파일 기반 캐시 키(package-lock.json), 읽기 전용 작업을 위한 pull-only 정책
  • 아티팩트: 만료 설정이 포함된 경로 기반 아티팩트, JUnit/Cobertura 테스트 리포트, on_failure 저장, MR 링크용 expose_as
  • 커스텀 변수 정의와 함께 보여주는 내장 CI_ 사전 정의 변수 예제
  • 파이프라인 마이그레이션 팀을 위해 레거시 only/except와 최신 rules: 구문을 함께 제공

자주 묻는 질문

.gitlab-ci.yml이란 무엇이고 어디에 위치하나요?

.gitlab-ci.yml은 GitLab CI/CD 파이프라인 설정 파일입니다. Git 저장소의 루트에 위치해야 합니다. GitLab이 이 파일을 감지하면 파일 내의 작업 정의와 트리거 조건에 따라 각 푸시 또는 MR에 대해 자동으로 파이프라인을 생성합니다.

GitLab CI에서 needs:와 dependencies:의 차이는 무엇인가요?

needs:는 작업이 나열된 선행 작업이 완료되는 즉시 시작할 수 있게 하여 엄격한 스테이지 순서를 우회합니다. 이를 통해 다양한 스테이지에 걸쳐 작업을 병렬로 실행하는 DAG 파이프라인을 구성할 수 있습니다. dependencies:는 현재 작업에 어떤 작업의 아티팩트를 다운로드할지만 제어하며 실행 순서에는 영향을 주지 않습니다.

GitLab CI에서 cache:와 artifacts:의 차이는 무엇인가요?

cache:는 npm install이나 pip install 같은 반복 작업을 빠르게 하기 위해 파이프라인 실행 간에 파일을 저장합니다. 같은 브랜치의 실행 간에 공유됩니다. artifacts:는 같은 파이프라인 실행 내에서 작업 간에 빌드 출력(컴파일된 바이너리, 테스트 리포트, 정적 파일)을 전달합니다. 아티팩트는 파이프라인 만료 후 삭제되지만 캐시는 파이프라인 실행 간에 유지됩니다.

GitLab CI에서 작업 간에 변수를 전달하려면 어떻게 하나요?

dotenv 아티팩트 메커니즘을 사용하세요. 소스 작업에서 파일에 KEY=VALUE 쌍을 작성하고 artifacts.reports.dotenv에 선언합니다. GitLab은 dependencies나 needs에 소스 작업을 선언한 이후 작업들에 해당 변수를 주입합니다. 이를 통해 버전 번호나 빌드 해시 같은 동적 값이 파이프라인 전체에 흐를 수 있습니다.

GitLab CI에서 rules:와 only/except의 차이는 무엇인가요?

rules:는 if 표현식, changes 필터, exists 검사, when 조건을 단일 목록으로 지원하는 현대적이고 권장되는 방식입니다. only/except는 브랜치 이름 패턴과 사전 정의 키워드만 지원하는 레거시 방식입니다. only/except가 단계적으로 폐기되고 있으므로 새 파이프라인에는 rules:를 사용해야 합니다.

GitLab CI의 .pre와 .post 스테이지는 무엇인가요?

.pre는 stages:에 정의된 순서와 관계없이 항상 다른 모든 스테이지보다 먼저 실행되는 예약 스테이지입니다. .post는 다른 모든 스테이지 이후에 실행됩니다. 이 스테이지들은 stages 배열에 나열하지 않아도 모든 파이프라인 실행을 감싸야 하는 전역 설정 및 정리 작업에 유용합니다.

GitLab CI에서 가장 유용한 내장 변수는 무엇인가요?

가장 자주 사용되는 변수는 $CI_COMMIT_SHA(전체 커밋 해시), $CI_COMMIT_BRANCH(브랜치 이름), $CI_PIPELINE_ID(고유 파이프라인 식별자), $CI_JOB_ID(고유 작업 식별자), $CI_REGISTRY_IMAGE(프로젝트의 컨테이너 레지스트리 이미지 경로), $CI_COMMIT_REF_SLUG(URL에 안전한 브랜치 이름, 캐시 키로 유용)입니다.

GitLab CI에서 Docker 이미지를 빌드하고 푸시하려면 어떻게 하나요?

docker build 및 docker push 명령에서 $CI_REGISTRY_IMAGE를 이미지 이름으로, $CI_COMMIT_SHA를 태그로 사용하세요. GitLab은 $CI_REGISTRY에서 접근 가능한 내장 컨테이너 레지스트리를 제공하며, $CI_REGISTRY_USER와 $CI_REGISTRY_PASSWORD로 인증할 수 있습니다. 먼저 docker login $CI_REGISTRY로 로그인하세요.