GitLab CI 마이그레이션, YAML 변환보다 먼저 바뀌는 것

GitLab CI 마이그레이션을 몇 번 해보면 초반 착각이 거의 비슷합니다. 기존 Jenkinsfile이나 사내 CI 스크립트를 .gitlab-ci.yml로 옮기면 끝날 것 같지만, 실제로 흔들리는 지점은 YAML 문법이 아니라 실행 환경, 권한 경계, 캐시 수명, 배포 승인 습관입니다.

제가 제일 경계하는 실패는 빨간 파이프라인이 아닙니다. 차라리 실패는 빨리 보이거든요. 더 위험한 건 성공처럼 보이는데 산출물이 예전과 다른 경우입니다. 예를 들어 기존 빌드 서버에는 전역 패키지, 로컬 캐시, SSH known_hosts, 사내 CA 인증서가 이미 깔려 있었는데 GitLab Runner의 Docker Executor에서는 전부 사라질 수 있습니다.

그래서 저는 전환을 시작할 때 ‘CI 도구를 바꾼다’고 보지 않습니다. 빌드 지식을 어디에 둘 것인가, 운영 배포 권한을 누가 어떤 조건에서 행사할 것인가, 실패 로그를 누가 재현 가능한 방식으로 읽을 것인가를 다시 정하는 작업으로 봅니다. 결국 GitLab CI는 도구 선택보다 팀의 배포 습관을 저장소 중심으로 다시 쓸 준비가 되어 있는지의 문제에 가깝더라고요.

GitLab CI 마이그레이션이 바꾸는 운영 경계

GitLab CI/CD의 핵심은 저장소 안의 .gitlab-ci.yml을 기준으로 Job, Stage, Pipeline을 선언하는 데 있습니다. 그런데 실무에서 중요한 변화는 정의 파일의 위치가 아니라 책임의 위치입니다. 예전에는 빌드 서버 안에 있던 지식이 저장소로 들어오고, 운영팀 개인 계정에 묶여 있던 배포 절차가 Job과 Environment로 드러납니다.

저는 전환 전에 기존 CI를 다음 네 덩어리로 분해합니다. 이 과정을 생략하면 나중에 ‘왜 Jenkins에서는 됐는데 GitLab에서는 안 되죠?’라는 질문만 반복됩니다.

• 실행 환경: OS 패키지, 런타임 버전, Docker-in-Docker 사용 여부, 사내 인증서, DNS, 프록시 설정입니다.
• 상태 저장 지점: 캐시, 아티팩트, 빌드 번호, 릴리스 노트, 컨테이너 이미지 태그가 어디에 남는지입니다.
• 권한 경계: 배포 토큰, 레지스트리 인증, 클라우드 IAM, SSH 키, protected branch/tag 조건입니다.
• 사람의 개입: 운영 배포 승인, 장애 시 재실행 기준, 롤백 명령을 누가 실행하는지입니다.

이 네 가지가 정리되어 있으면 GitLab CI 문법은 금방 따라옵니다. 반대로 이게 흐릿하면 문법을 아무리 예쁘게 써도 파이프라인은 오래 못 갑니다. 관련해서는 이전에 정리한 CI/CD 체크리스트 글과 함께 보면 결정 기준을 더 빨리 잡을 수 있습니다.

마이그레이션 결정 요소: 저는 이 표를 먼저 채웁니다

도구 비교표보다 먼저 보는 건 팀의 현재 배포 습관입니다. 같은 GitLab CI라도 저장소가 이미 GitLab에 있는 팀과, Jenkins 플러그인에 배포 지식이 잔뜩 들어 있는 팀의 난이도는 완전히 다릅니다.

제 기준은 단순합니다. GitLab CI로 옮겼을 때 배포 이력과 권한이 더 잘 보이면 전환 가치가 큽니다. 반대로 기존 CI가 레거시 시스템의 접착제 역할을 하고 있다면, 전환이 아니라 먼저 분해가 필요합니다.

실전 구현: 기존 파이프라인을 작게 쪼개 옮기는 순서

처음부터 운영 배포까지 한 번에 옮기면 원인 추적이 지옥이 됩니다. 저는 테스트 전용 파이프라인, 산출물 생성, 수동 배포, 기존 CI 제거 순서로 갑니다. 느려 보이지만 장애 복구 시간을 줄여줍니다.

1. 기존 CI 작업을 빌드, 테스트, 패키징, 이미지 빌드, 배포, 알림으로 나눕니다.
2. 각 단계가 읽는 파일, 쓰는 산출물, 필요한 환경 변수를 표로 만듭니다.
3. Runner Executor를 정합니다. 서버 상태 의존을 줄이고 싶으면 Docker Executor를 먼저 봅니다.
4. 배포 없는 테스트 Job부터 GitLab CI에 붙입니다.
5. 아티팩트와 캐시를 분리합니다. 결과물은 artifacts, 재사용 의존성은 cache입니다.
6. 운영 배포는 rules, when: manual, protected branch/tag를 함께 설계합니다.

아래 예시는 Node.js 프로젝트를 전제로 한 출발점입니다. 의도적으로 only 대신 rules를 썼습니다. GitLab 문서에서도 새 조건 설계는 rules 사용을 권장하고, only/except는 deprecated 키워드로 안내합니다.

stages:
  - test
  - build
  - deploy

default:
  image: node:20
  interruptible: true
  before_script:
    - node --version
    - npm --version

cache:
  key:
    files:
      - package-lock.json
  paths:
    - .npm/
  policy: pull-push

test:
  stage: test
  script:
    - npm ci --cache .npm --prefer-offline
    - npm test
  artifacts:
    when: always
    paths:
      - junit.xml
    reports:
      junit: junit.xml
    expire_in: 1 week

build:
  stage: build
  script:
    - npm ci --cache .npm --prefer-offline
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 week
  needs:
    - job: test
      artifacts: false

deploy_production:
  stage: deploy
  image: alpine:latest
  needs:
    - job: build
      artifacts: true
  script:
    - echo 'deploy script goes here'
  environment:
    name: production
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
      when: manual
    - when: never

여기서 needs는 단순한 보기 좋은 문법이 아닙니다. Stage 순서를 무작정 기다리지 않고 필요한 Job 관계를 명시합니다. 다만 남발하면 의존 그래프가 복잡해져 장애 때 읽기 어려워집니다. 빌드 시간이 길고 독립 테스트가 많은 저장소에는 적극적으로 쓰고, 작은 서비스에는 Stage만으로 단순하게 유지하는 편이 낫더라고요.

GitLab CI Runner 등록과 검증: 토큰 방식부터 확인하세요

Self-managed Runner를 쓴다면 등록 단계에서 예전 블로그 글을 그대로 따라 하면 막힐 수 있습니다. Runner registration token 방식은 deprecated 상태이며, 현재 GitLab Runner 등록 흐름은 GitLab UI나 API에서 Runner를 만든 뒤 발급되는 runner authentication token을 사용하는 쪽이 기준입니다. 명령어 예시도 --registration-token이 아니라 --token을 기준으로 잡는 게 안전합니다.

sudo gitlab-runner register \
  --url https://gitlab.example.com \
  --token glrt-REPLACE_WITH_RUNNER_AUTH_TOKEN \
  --executor docker \
  --docker-image alpine:latest \
  --description docker-runner-01

Runner 태그와 protected 설정은 GitLab UI에서 관리되는 경우가 많습니다. 등록 명령만 성공했다고 Job이 실행되는 건 아닙니다. Pipeline이 계속 pending이면 저는 아래 순서로 봅니다.

sudo gitlab-runner status
sudo gitlab-runner verify
sudo gitlab-runner list
sudo gitlab-runner --debug run

verify가 통과하면 GitLab 서버와 Runner의 통신은 일단 됩니다. 그래도 Job이 안 잡히면 네트워크보다 태그 매칭, protected branch/tag, Runner scope, locked 설정을 먼저 봅니다. Job에 tags가 있는데 Runner에 같은 태그가 없으면 정상적으로 대기합니다. 이건 장애가 아니라 스케줄링 조건 불일치입니다.

test_with_tagged_runner:
  stage: test
  tags:
    - docker
    - linux
  image: alpine:latest
  script:
    - echo 'runner tag matched'
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

Executor 선택도 비용과 안정성에 직접 영향을 줍니다. Shell Executor는 빠르고 단순하지만 호스트 오염 위험이 큽니다. Docker Executor는 격리가 좋아 마이그레이션 검증에 유리하지만 이미지 pull, 캐시, Docker 데몬 접근 정책을 설계해야 합니다. Kubernetes Executor는 확장성은 좋지만 클러스터 운영 역량이 없으면 CI 문제가 곧 플랫폼 문제가 됩니다.

트러블슈팅: 겉으로는 CI 문제, 뿌리는 운영 습관 문제

로컬에서는 되는데 CI에서 깨지는 상황은 대부분 암묵적 환경 때문입니다. 제가 실제로 본 문제들은 문법 오류보다 환경 차이, 권한 범위, 캐시 오염이 훨씬 많았습니다. 이거 진짜 한 번 겪으면, 다음 마이그레이션부터는 환경 목록부터 보게 됩니다.

1. 변수 이름은 같지만 범위가 달랐습니다

기존 CI에서 전역 토큰 하나를 모든 프로젝트가 공유하던 팀이 있었습니다. GitLab으로 옮기면서 프로젝트 변수에 넣었는데, 실제 배포 Job은 하위 템플릿 프로젝트에서 실행되고 있었습니다. 이름은 같은데 스코프가 달라 값이 비어 있었던 겁니다. 해결은 Group Variables로 올릴 값과 Project Variables로 제한할 값을 분리하고, 운영 배포용 변수는 protected branch/tag에서만 노출되도록 하는 것이었습니다.

git grep -n -E 'DEPLOY|TOKEN|PASSWORD|SECRET|PRIVATE_KEY' -- . ':!node_modules' ':!dist'
git grep -n -E 'ssh|scp|rsync|kubectl|helm|aws|gcloud|az' -- . ':!node_modules' ':!dist'

이 명령은 마이그레이션 전에 꼭 돌려봅니다. 결과가 많이 나온다는 건 나쁜 게 아닙니다. 숨어 있던 배포 지식을 드러낸 겁니다. 다만 평문 Secret이 나오면 즉시 회수, 재발급, 변수화까지 같이 해야 합니다. 단순히 YAML에서 지우는 건 보안 조치가 아닙니다.

2. 캐시가 실패를 숨겼습니다

node_modules를 통째로 캐시하면 처음엔 빨라 보입니다. 그런데 lock file이 바뀌었는데도 오래된 의존성이 남거나, Runner OS/아키텍처가 바뀌며 네이티브 모듈이 깨지는 경우가 있습니다. 그래서 저는 패키지 매니저 캐시 디렉터리를 캐시하고, 설치 결과 디렉터리를 산출물처럼 다루지 않습니다. npm이면 .npm/, pip이면 wheel/cache 계열처럼 재다운로드 비용을 줄이는 쪽이 낫습니다.

3. 아티팩트와 캐시를 섞었습니다

캐시는 다음 파이프라인에도 재사용될 수 있는 가속 장치입니다. 아티팩트는 이번 파이프라인의 결과물입니다. 배포에 필요한 dist/, 패키지 파일, 테스트 리포트는 cache가 아니라 artifacts에 둬야 합니다. 반대로 의존성 다운로드 캐시는 artifacts에 넣으면 보관 비용과 다운로드 시간이 불필요하게 커집니다.

4. 배포 자동화를 너무 빨리 켰습니다

마이그레이션 첫 주에는 운영 배포를 when: manual로 둡니다. 저는 이 기간에 로그 포맷, 배포 산출물, 롤백 명령, 승인자 권한을 확인합니다. 자동화는 마지막에 켜도 늦지 않습니다. 검증 안 된 자동 배포는 속도가 아니라 부채입니다.

GitLab CI 마이그레이션 검증 기준

마이그레이션 완료 기준을 ‘성공 표시가 떴다’로 잡으면 위험합니다. 저는 같은 커밋에서 같은 산출물이 나오는지, 누가 배포를 눌렀는지, 실패 로그만 보고 원인을 좁힐 수 있는지를 봅니다.

로그를 볼 때는 마지막 줄만 보면 안 됩니다. npm ci가 실패했다면 registry 인증, lock file, 네트워크, Node 버전 차이를 봅니다. docker build가 실패했다면 Dockerfile 단계와 build context를 확인합니다. kubectl apply가 실패했다면 kubeconfig 권한, namespace, server-side validation을 분리해서 봅니다.

git diff --name-only origin/main...HEAD
find dist -type f | sort > dist-files.txt
sha256sum package-lock.json dist-files.txt
printenv | sort | grep -E '^CI_|^GITLAB_|^NODE_|^NPM_'

로컬에서 Runner를 흉내 내는 방식은 빠른 확인에는 도움이 되지만, GitLab 서버의 모든 동작을 완전히 재현한다고 믿으면 안 됩니다. 특히 protected variables, merge request pipeline 조건, 환경 승인, Runner 스케줄링은 실제 GitLab Pipeline에서 확인해야 합니다.

CI/CD 전환 전략: 병행 운영이 느린 게 아니라 싸게 먹힙니다

제가 가장 효과를 본 방식은 기존 CI를 바로 끄지 않는 겁니다. GitLab CI를 먼저 읽기 전용으로 붙이고, 같은 커밋에 대해 테스트와 산출물을 비교합니다. 이 기간은 낭비가 아닙니다. 기존 자동화에 숨어 있던 전역 의존성, 권한 누수, 오래된 배포 스크립트를 찾는 보험입니다.

1. Inventory 단계: 기존 Job, Secret, 산출물, 외부 연동을 목록화합니다.
2. Read-only 단계: GitLab CI에서 테스트만 돌리고 배포는 하지 않습니다.
3. Shadow 단계: 기존 CI와 GitLab CI를 같은 커밋에서 같이 돌립니다.
4. Manual Deploy 단계: 운영 배포를 수동 승인 Job으로 연결합니다.
5. Primary 단계: GitLab CI를 기본 파이프라인으로 바꾸고 기존 CI 트리거를 중지합니다.
6. Cleanup 단계: 기존 토큰, 빌드 서버 권한, 스케줄러, 웹훅을 제거합니다.

성능과 비용을 볼 때도 단순히 ‘GitLab CI가 빠른가’로 보면 답이 흐립니다. 비용을 좌우하는 건 Runner 대수보다 실패 재실행 횟수, 이미지 pull 정책, 캐시 설계, 병렬화된 Job의 대기 시간입니다. 작은 서비스는 단순한 Stage 기반 파이프라인이 더 안정적이고, 큰 모노레포는 rules:changes, needs, child pipeline을 검토할 가치가 있습니다. 다만 child pipeline은 관측 포인트가 늘어나므로 팀이 로그를 읽을 준비가 된 뒤에 넣는 편이 좋습니다.

자주 묻는 질문

GitLab CI 마이그레이션은 언제 하는 게 좋나요?

저는 코드가 GitLab에 있고, Merge Request 중심으로 리뷰하며, 빌드와 배포 이력을 커밋 기준으로 추적하고 싶을 때 추천합니다. 특히 운영 배포 승인과 결과물을 GitLab 안에서 보고 싶은 팀은 전환 효과가 큽니다.

Jenkins에서 바로 GitLab CI로 옮겨도 괜찮나요?

가능하지만 Jenkinsfile을 줄 단위로 번역하면 실패하기 쉽습니다. 먼저 stage 구조, 플러그인 의존성, credential 사용 위치, workspace에 남는 파일을 분해해야 합니다. Jenkins 플러그인이 해주던 일을 GitLab CI에서는 YAML, Runner 설정, 외부 CLI, protected variables 조합으로 다시 설계하는 경우가 많습니다.

가장 먼저 확인할 설정은 뭔가요?

Runner 태그, protected branch/tag, CI/CD Variables 범위, artifacts 경로, cache key를 먼저 봅니다. 제 경험상 초반 문제의 상당수는 이 다섯 가지에서 나왔습니다.

Shell Executor와 Docker Executor 중 무엇을 골라야 하나요?

기존 빌드 서버의 상태를 그대로 써야 하고 격리 요구가 낮으면 Shell Executor가 빠른 출발점이 될 수 있습니다. 하지만 마이그레이션 품질을 높이고 싶다면 Docker Executor가 낫습니다. 매번 비슷한 컨테이너 환경에서 실행되기 때문에 ‘그 서버에만 깔린 무언가’를 빨리 찾아냅니다.

마무리: GitLab CI 마이그레이션은 언제 밀어붙일까

GitLab CI 마이그레이션은 파이프라인 파일 하나를 만드는 작업이 아닙니다. 빌드 지식, 배포 권한, 장애 대응 루틴을 저장소 중심으로 다시 쓰는 일입니다. 그래서 저는 도구의 인기보다 운영 방식이 더 투명해지는지를 기준으로 봅니다.

GitLab에 코드가 있고, MR 리뷰가 일상이고, 운영 배포 이력까지 한곳에서 보고 싶다면 GitLab CI로 옮기세요. 이 경우에는 테스트 전용 파이프라인부터 시작해 manual deploy까지 붙이는 방식이 가장 무난합니다. 반대로 Jenkins 플러그인, 개인 SSH 키, 사내 배포 서버의 전역 상태에 강하게 묶여 있다면 바로 전환하지 마세요. 먼저 Shadow Pipeline으로 기존 결과와 GitLab CI 결과를 비교하고, Secret과 배포 권한을 정리한 뒤에 주 파이프라인으로 승격하는 편이 안전합니다.

제 경험상 성공적인 전환의 신호는 ‘파이프라인이 빨라졌다’보다 ‘실패했을 때 누구나 같은 방식으로 원인을 좁힐 수 있다’에 가깝습니다. 속도는 그다음에 옵니다. 파이프라인은 옮기는 게 아니라, 팀의 배포 습관을 코드로 다시 쓰는 일입니다.

참고한 1차 문서: GitLab Runner 등록 문서, GitLab CI deprecated keywords, GitLab CI caching 문서