본문으로 건너뛰기

Auto CI 설정

코드를 푸시할 때마다 수동으로 빌드하고 배포하는 것은 번거롭고 실수가 발생하기 쉽습니다. Auto CI를 설정하면 GitLab에 코드를 푸시하는 순간 자동으로 빌드와 배포가 시작됩니다. 한 번 설정해 두면 개발에만 집중할 수 있습니다.

Auto CI를 왜 사용해야 하나요?
  • 시간 절약: 빌드와 배포를 기다리지 않아도 됩니다 .
  • 실수 방지: 수동 배포 시 발생하는 휴먼 에러를 줄입니다 .
  • 일관성 유지: 매번 동일한 방식으로 빌드/배포됩니다 .
  • 빠른 피드백: 코드 푸시 후 바로 결과를 확인할 수 있습니다 .

Auto CI 설정 모달

개요​

Auto CI는 GitLab의 Webhook 이벤트를 감지하여 자동으로 빌드 파이프라인을 실행합니다. 아래는 전체 흐름입니다:

graph LR
    A[GitLab Push] --> B[Webhook 트리거]
    B --> C[KIWI 빌드 시작]
    C --> D[Kaniko 빌드]
    D --> E[Harbor 푸시]
    E --> F[자동 배포]

지원 이벤트​

다양한 Git 이벤트에 대응하여 빌드를 자동으로 시작할 수 있습니다:

  • Push: 브랜치에 커밋을 푸시할 때 빌드됩니다. 개발 브랜치 자동 빌드, 지속적 통합에 사용합니다.
  • Merge Request: MR 생성/업데이트 시 빌드됩니다. 코드 리뷰 전 빌드 검증에 사용합니다.
  • Tag: 태그 생성 시 빌드됩니다. 릴리스 버전 빌드에 사용합니다.
  • Pipeline: GitLab CI 완료 시 빌드됩니다. 기존 GitLab CI 결과 연계에 사용합니다.

사전 요구사항​

Auto CI를 설정하기 전에 다음 조건이 충족되어야 합니다:

설정 전 체크리스트

아래 항목 중 하나라도 누락되면 Auto CI 버튼이 비활성화됩니다. 먼저 모든 항목을 완료하세요.

  • 서비스 등록 (필수): [서비스 관리] 페이지에서 서비스가 등록되어 있어야 합니다 .
  • GitLab 토큰 설정 (필수): 서비스 설정에서 GitLab Access Token이 입력되어 있어야 합니다 .
  • Registry 설정 (필수): 서비스 설정에서 Harbor/DockerHub 레지스트리 정보가 입력되어 있어야 합니다 .
  • Dockerfile 존재 (권장): 없다면 Build Wizard로 자동 생성하세요
  • K8s 클러스터 연결 (자동 배포 시 필수): **[런타임 환경]**에서 클러스터가 등록되어 있어야 합니다 .
버튼이 비활성화되어 있나요?

Auto CI 버튼이 회색으로 비활성화되어 있다면, 서비스 상세 페이지에서 누락된 설정을 확인하세요. 대부분 GitLab 토큰이나 Registry 설정이 누락된 경우입니다.

Step 1: Auto CI 설정 모달 열기​

1.1 서비스 목록에서 접근하기​

  1. [서비스 관리] 페이지(/services)로 이동합니다 .
  2. Auto CI를 설정할 서비스를 찾습니다 .
  3. 서비스 카드 우측의 번개 아이콘(Auto CI) 버튼을 클릭합니다 .
아이콘을 찾기 어려우신가요?

번개 모양 아이콘은 서비스 카드의 오른쪽 상단에 있습니다. 마우스를 올리면 "Auto CI" 툴팁이 표시됩니다.

1.2 파이프라인 뷰에서 접근하기​

서비스 카드에 표시된 4단계 파이프라인에서도 접근할 수 있습니다:

  • Source: GitLab 연동 상태 확인
  • Build: 빌드 설정 및 Auto CI 설정 모달 열기
  • Deploy: 배포 설정 확인
  • Operate: 배포된 서비스 모니터링

파이프라인의 Build 단계를 클릭하면 빌드 관련 설정에 접근할 수 있습니다.

Step 2: 기본 설정 (Settings 탭)​

Auto CI 모달이 열리면 기본 설정 탭이 표시됩니다. 여기서 Auto CI의 핵심 옵션들을 설정합니다.

2.1 Auto CI 활성화​

  • Enable Auto CI: Auto CI 기능을 켜고 끄는 토글 스위치입니다 .

    • 권장: ON (처음 설정 후 바로 활성화하세요)

  • Git Branch: Webhook을 감지할 브랜치를 선택합니다 .

    • 개발 환경: develop 브랜치 권장
    • 운영 환경: main 또는 master 브랜치 권장
브랜치 선택 시 주의사항

모든 브랜치(*)를 선택하면 feature 브랜치 푸시마다 빌드가 실행되어 리소스가 낭비될 수 있습니다. 가능하면 특정 브랜치만 선택하세요.

환경별 브랜치 전략
  • 개발(Dev): develop 브랜치 권장, 자동 배포 ON
  • 스테이징(Staging): main 브랜치 권장, 자동 배포 ON
  • 프로덕션(Production): main + 태그 권장, 자동 배포 OFF (수동 승인 권장)

2.2 Registry 정보 확인​

Registry 정보는 서비스 등록 시 입력한 값이 자동으로 표시됩니다. 빌드된 이미지가 저장되는 곳입니다.

  • Registry URL: 이미지가 저장될 레지스트리 주소 (예: harbor.mipllab.com)
  • Registry Type: 레지스트리 종류 (Harbor 또는 Docker Hub)
  • Project/Namespace: 이미지 저장 위치 (예: library, myproject)
  • Image Name: 빌드될 이미지 이름 (기본값: 서비스명과 동일)
Registry 정보가 보이지 않나요?

Registry 정보가 표시되지 않으면 서비스 상세 페이지에서 Registry 설정을 먼저 완료해야 합니다. 서비스 카드를 클릭하여 상세 페이지로 이동한 후 설정을 확인하세요.

Step 3: 빌드 대상 서비스 감지​

KIWI는 Git 저장소를 분석하여 프로젝트 정보를 자동으로 감지합니다. 이 단계는 Dockerfile 위치와 프로젝트 구조를 파악하는 데 도움이 됩니다.

3.1 프로젝트 타입 자동 감지​

  1. Detect Services 버튼을 클릭합니다 .
  2. KIWI가 Git 저장소를 분석하여 프로젝트 정보를 자동 감지합니다 (보통 몇 초 소요)
왜 감지가 필요한가요?

프로젝트 타입에 따라 빌드 방식이 달라집니다. 예를 들어, Node.js 프로젝트는 npm install로 의존성을 설치하고, Python 프로젝트는 pip install을 사용합니다. KIWI가 이를 자동으로 파악해 최적의 빌드 설정을 제안합니다.

3.2 감지 결과 항목​

감지가 완료되면 다음 정보가 표시됩니다:

  • Language: 사용된 프로그래밍 언어 (예: Node.js, Java, Python, Go)
  • Framework: 사용된 프레임워크 (예: React, Spring Boot, Django)
  • Package Manager: 패키지 관리 도구 (예: npm, yarn, Maven, pip)
  • Build Type: 저장소 구조 (예: Single-repo, Mono-repo)
  • TypeScript: TypeScript 사용 여부 (Yes / No)
  • Dockerfile: Dockerfile 위치 (예: ./Dockerfile, ./docker/Dockerfile)

3.3 모노레포(Monorepo) 프로젝트 처리​

모노레포란?

하나의 Git 저장소에 여러 프로젝트(frontend, backend 등)가 함께 있는 구조를 모노레포라고 합니다. 대규모 프로젝트에서 코드 공유와 버전 관리를 쉽게 하기 위해 사용됩니다.

모노레포 프로젝트의 경우 여러 서비스가 감지됩니다:

  1. 감지된 서브 프로젝트 목록이 테이블로 표시됩니다 .
  2. 빌드할 서브 프로젝트를 체크박스로 선택합니다 .
  3. 각 프로젝트별로 Dockerfile 경로를 확인/수정합니다 .

일반적인 모노레포 구조 예시:

my-project/
├── frontend/         → 이미지: my-project-frontend
│   └── Dockerfile
├── backend/          → 이미지: my-project-backend
│   └── Dockerfile
└── api-gateway/      → 이미지: my-project-gateway
    └── Dockerfile
모노레포 빌드 팁

선택한 서브 프로젝트 수만큼 병렬로 빌드가 실행됩니다. 리소스가 제한된 환경에서는 한 번에 빌드할 프로젝트 수를 조절하세요.

Step 4: Registry Secret 설정​

Kubernetes에서 Private Registry(예: Harbor)의 이미지를 가져오려면 인증 정보가 필요합니다. KIWI가 이 인증 정보를 Kubernetes Secret으로 자동 생성해 줍니다.

Registry Secret이란?

Private Registry(Harbor, 사설 Docker Registry 등)에서 이미지를 Pull하려면 로그인이 필요합니다. Kubernetes는 이 로그인 정보를 Secret이라는 리소스에 저장하고, Pod 생성 시 이 Secret을 사용하여 이미지를 가져옵니다.

4.1 Secret 존재 확인​

  1. Check Secret 버튼을 클릭합니다 .
  2. 결과에 따라 다음 중 하나가 표시됩니다:
    • "Secret already exists" - 이미 생성되어 있습니다. 다음 단계로 진행하세요.
    • "Secret not found" - Secret을 생성해야 합니다.

4.2 Secret 자동 생성​

Secret이 없는 경우 KIWI가 자동으로 생성해 줍니다:

  1. Create Registry Secret 버튼을 클릭합니다 .
  2. KIWI가 K8s 클러스터에 Secret을 생성합니다 .
  3. "Secret created successfully" 메시지를 확인합니다 .

생성되는 Secret 정보:

  • Secret 이름: {serviceName}-registry-cred
  • 네임스페이스: 서비스 배포 네임스페이스 (기본: 서비스명)
  • 타입: kubernetes.io/dockerconfigjson
  • 내용: Registry 인증 정보 (사용자명, 비밀번호)

4.3 Secret 재생성 (비밀번호 변경 시)​

Registry 비밀번호가 변경되었거나 Secret을 업데이트해야 하는 경우:

  1. 먼저 K8s 클러스터에서 기존 Secret을 삭제합니다 .
  2. Create Registry Secret 버튼으로 새로 생성합니다 .
Secret 생성 실패 시

Secret 생성에 실패하면 다음을 확인하세요:

  • K8s 클러스터 연결이 정상인지
  • 해당 네임스페이스에 Secret 생성 권한(RBAC)이 있는지
  • 네임스페이스가 존재하는지

권한 문제라면 클러스터 관리자에게 secrets 리소스에 대한 create 권한을 요청하세요.

Step 5: Webhook URL 및 Secret Token 설정​

이 단계에서는 GitLab이 KIWI에 이벤트를 전송할 수 있도록 Webhook을 설정합니다. 이 연결을 통해 코드 푸시 시 자동으로 빌드가 시작됩니다.

Webhook이란?

Webhook은 특정 이벤트(예: 코드 푸시)가 발생했을 때 지정된 URL로 알림을 보내는 방식입니다. GitLab에서 코드가 푸시되면 KIWI의 Webhook URL로 "새 코드가 푸시됐어요!"라는 알림이 전송되고, KIWI가 이를 받아 빌드를 시작합니다.

5.1 환경별 Webhook 설정 이해​

KIWI는 환경별로 다른 Webhook URL을 제공합니다. 현재 사용 중인 환경에 맞는 URL을 선택하세요.

  • Local: 로컬 개발용입니다 (ngrok 터널). URL 예시: https://xxx.ngrok.io/api/v1/webhook/gitlab
  • Dev: 개발 서버용입니다. URL 예시: https://dev.example.com/api/v1/webhook/gitlab
  • Staging: 스테이징 환경용입니다. URL 예시: https://staging.example.com/api/v1/webhook/gitlab
  • Production: 운영 환경용입니다. URL 예시: https://kiwi.example.com/api/v1/webhook/gitlab

5.2 Webhook URL 복사하기​

  1. Webhook Environments 섹션에서 사용할 환경을 찾습니다 .
  2. Copy URL 버튼을 클릭하여 Webhook URL을 복사합니다 .
  3. Copy Token 버튼을 클릭하여 Secret Token도 복사합니다 .

5.3 GitLab에 Webhook 등록하기​

이제 복사한 정보를 GitLab 프로젝트에 등록합니다.

단계별 가이드:

  1. GitLab 프로젝트 페이지로 이동합니다 .

  2. 왼쪽 메뉴에서 Settings → Webhooks 클릭

  3. 다음 정보를 입력합니다:

    • URL: KIWI에서 복사한 Webhook URL
    • Secret token: KIWI에서 복사한 Secret Token

  4. Trigger 섹션에서 이벤트를 선택합니다:

    • ✅ Push events (필수)
    • ✅ Merge request events (권장)
    • ✅ Tag push events (릴리스 빌드 시)

  5. SSL verification: ✅ Enable SSL verification 체크 (권장)

  6. Add webhook 버튼을 클릭합니다 .

Secret Token 보안

Secret Token은 서비스별로 고유하며, 외부에 노출되면 악의적인 빌드 트리거가 발생할 수 있습니다. 절대 공개 저장소나 문서에 노출하지 마세요.

Webhook 테스트

GitLab에서 Webhook을 등록한 후, Test 버튼을 클릭하여 연결을 테스트할 수 있습니다. "Hook executed successfully" 메시지가 나오면 정상입니다.

Step 6: 이벤트 설정​

어떤 Git 이벤트에서 빌드를 실행할지 설정합니다. 필요에 따라 여러 이벤트를 조합할 수 있습니다.

6.1 트리거 이벤트 선택하기​

  • Push: 지정 브랜치에 코드 푸시 시 빌드됩니다. 지속적 통합, 개발 브랜치 자동 빌드에 추천합니다.
  • Merge Request: MR 생성/업데이트/병합 시 빌드됩니다. 코드 리뷰 전 빌드 검증에 추천합니다.
  • Tag: 태그 생성 시 빌드됩니다. 릴리스 버전 빌드에 추천합니다.
이벤트 조합 예시
  • 개발 환경: Push 이벤트만 (빠른 피드백)
  • 스테이징 환경: Push + MR 이벤트 (병합 전 검증)
  • 프로덕션 환경: Tag 이벤트만 (릴리스 버전만 빌드)

6.2 브랜치 필터링​

특정 브랜치에서만 빌드가 실행되도록 필터링할 수 있습니다:

  • main: main 브랜치만
  • develop: develop 브랜치만
  • feature/*: feature/로 시작하는 모든 브랜치
  • release/*: release/로 시작하는 모든 브랜치
  • *: 모든 브랜치 (비권장)
모든 브랜치 빌드 주의

* 패턴을 사용하면 모든 feature 브랜치 푸시마다 빌드가 실행됩니다. 빌드 큐가 빠르게 차고 리소스가 낭비될 수 있으니 신중하게 선택하세요.

6.3 자동 배포 설정​

빌드 성공 후 자동으로 배포할지 설정합니다. 개발/스테이징 환경에는 자동 배포를, 프로덕션에는 수동 배포를 권장합니다.

  • Auto Deploy: 빌드 성공 시 자동 배포 활성화/비활성화
  • Deploy Environment: 배포 대상 환경 선택 (K8s 네임스페이스)
자동 배포 vs 수동 배포
  • 개발 환경: 자동 배포 ON 추천 (빠른 피드백 필요)
  • 스테이징 환경: 자동 배포 ON 추천 (최신 버전 검증 필요)
  • 프로덕션 환경: 자동 배포 OFF 추천 (신중한 배포 필요)

Step 7: 설정 저장 및 테스트​

설정이 완료되면 저장하고 테스트해 봅시다. 테스트를 통해 모든 연결이 정상인지 확인할 수 있습니다.

7.1 설정 저장​

  1. 모든 설정을 검토합니다 .
  2. Save 버튼을 클릭합니다 .
  3. "Auto CI 설정이 저장되었습니다" 메시지를 확인합니다 .

7.2 Webhook 테스트​

실제 코드를 푸시하기 전에 GitLab의 테스트 기능으로 연결을 확인합니다:

  1. GitLab 프로젝트 → Settings → Webhooks 이동
  2. 등록한 Webhook 항목을 찾습니다 .
  3. Test 드롭다운 버튼 클릭
  4. Push events 선택
테스트 결과 확인
  • Hook executed successfully: HTTP 200 - 정상 연결
  • HTTP 401/403 - Secret Token 불일치 또는 권한 문제
  • 연결 실패 - KIWI 서버 접근 불가 (방화벽, URL 오류 확인)

7.3 KIWI에서 빌드 확인​

테스트 이벤트 전송 후 KIWI에서 확인합니다:

  1. [서비스 관리] 페이지로 이동합니다 .
  2. 해당 서비스의 파이프라인에서 Build 단계가 "빌드 중" 상태인지 확인합니다 .
  3. 클릭하여 빌드 로그에서 "Triggered by Webhook" 메시지를 확인합니다 .

7.4 빌드 진행 상황 모니터링​

빌드가 시작되면 실시간으로 진행 상황을 모니터링할 수 있습니다:

  • Progress Bar: 빌드 진행률 (0~100%)
  • Current Step: 현재 실행 중인 단계 (Clone, Build, Push 등)
  • Build Log: 실시간 빌드 로그 (터미널 출력)
  • Duration: 빌드 경과 시간
빌드 시간 단축하기

첫 빌드는 이미지 캐시가 없어 오래 걸릴 수 있습니다. 두 번째 빌드부터는 캐시를 활용하여 빠르게 완료됩니다.

실제 사용 시나리오​

다양한 팀의 워크플로우에 맞는 Auto CI 설정 예시입니다. 자신의 상황에 맞는 시나리오를 참고하세요.

시나리오 1: 개발 브랜치 자동 빌드/배포​

상황: 개발자가 develop 브랜치에 코드를 푸시하면 개발 서버에 자동 배포되어 바로 확인하고 싶습니다.

설정 방법:

  • Auto CI: 활성화
  • Git Branch: develop
  • 트리거 이벤트: Push events 활성화
  • Auto Deploy: 활성화
  • Deploy Environment: dev

결과: develop 브랜치에 푸시하면 자동으로 빌드 → 개발 환경에 배포됩니다.

시나리오 2: 릴리스 태그 빌드​

상황: v1.0.0 같은 릴리스 태그를 생성할 때만 프로덕션용 이미지를 빌드하고, 배포는 수동으로 하고 싶습니다.

설정 방법:

  • Auto CI: 활성화
  • 트리거 이벤트: Tag push events 활성화
  • Auto Deploy: 비활성화

결과: git tag v1.0.0 && git push --tags 시 자동으로 빌드되고, 배포는 별도로 진행합니다.

시나리오 3: MR 검증 빌드​

상황: 코드 리뷰 전에 빌드가 성공하는지 자동으로 확인하고 싶습니다.

설정 방법:

  • Auto CI: 활성화
  • 트리거 이벤트: Merge request events 활성화
  • Auto Deploy: 비활성화

결과: MR 생성/업데이트 시 자동으로 빌드가 실행되어, 빌드 실패 시 병합을 막을 수 있습니다.

실무 팁

많은 팀이 시나리오 1(개발 환경)과 시나리오 2(프로덕션 환경)를 조합하여 사용합니다. 개발은 자동, 프로덕션은 신중하게!

문제 해결​

Auto CI 설정이나 빌드 중 문제가 발생하면 아래 가이드를 참고하세요.

Webhook이 트리거되지 않음​

  • GitLab 테스트에서 "Connection refused": KIWI 서버에 접근할 수 없습니다. 방화벽 설정과 KIWI 서버 상태를 확인하세요.
  • GitLab 테스트에서 "HTTP 401/403": Secret Token이 불일치합니다. KIWI에서 토큰을 다시 복사하여 GitLab에 등록하세요.
  • 테스트 성공했는데 빌드 안 됨: 브랜치 필터 문제입니다. 푸시한 브랜치가 Auto CI 브랜치 설정과 일치하는지 확인하세요.
  • 특정 이벤트만 안 됨: 이벤트 설정이 누락되었습니다. KIWI Auto CI 모달에서 해당 이벤트가 활성화되어 있는지 확인하세요.
디버깅 팁

GitLab의 Settings → Webhooks에서 Recent Deliveries를 확인하면 각 Webhook 호출의 요청/응답 내용을 볼 수 있습니다.

Registry Secret 생성 실패​

  • "Permission denied": K8s 권한이 부족합니다. 클러스터 관리자에게 secrets 리소스 create 권한을 요청하세요.
  • "Namespace not found": 네임스페이스가 없습니다. 먼저 네임스페이스를 생성하거나 다른 네임스페이스를 선택하세요.
  • "Secret already exists": 기존 Secret이 존재합니다. 기존 Secret을 삭제 후 재생성하세요.

빌드 실패​

  • "Dockerfile not found": Dockerfile이 없습니다. Build Wizard로 Dockerfile을 생성하세요.
  • "Build timeout": 빌드 시간이 초과되었습니다. 빌드 리소스를 증가시키거나 Dockerfile을 최적화하세요.
  • "Registry authentication failed": 레지스트리 인증에 실패했습니다. Registry 자격증명(사용자명/비밀번호)을 재확인하세요.
  • "Git clone failed": Git 접근에 실패했습니다. GitLab 토큰에 read_repository 권한이 있는지 확인하세요.

빌드가 계속 대기 중 (Pending)​

  • 원인: 동시 빌드 제한에 도달했거나 빌드 워커가 부족합니다 .
  • 해결: 이전 빌드가 완료될 때까지 대기하거나, 불필요한 빌드를 취소하세요
  • 참고: 5분 이상 building 상태가 지속되면 자동으로 실패 처리됩니다 .
관리자에게 문의할 상황
  • 빌드가 반복적으로 timeout되는 경우 (리소스 증가 필요)
  • Registry Secret 권한 문제가 해결되지 않는 경우
  • Webhook URL이 외부에서 접근 불가능한 경우

관련 가이드​

참고: 빌드 시스템 아키텍처​

                    ┌─────────────┐
                    │   GitLab    │
                    │   Server    │
                    └──────┬──────┘
                           │ Webhook (Push/MR/Tag)
                           ▼
                    ┌─────────────┐
                    │    KIWI     │
                    │   Backend   │
                    └──────┬──────┘
                           │ Build Queue
                           ▼
┌─────────────────────────────────────────────┐
│              Build Queue Worker             │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐     │
│  │ Build 1 │  │ Build 2 │  │ Build 3 │ ... │
│  └────┬────┘  └────┬────┘  └────┬────┘     │
└───────┼────────────┼────────────┼──────────┘
        │            │            │
        ▼            ▼            ▼
┌─────────────────────────────────────────────┐
│           Kubernetes Cluster                │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐    │
│  │ Kaniko   │ │ Kaniko   │ │ Kaniko   │    │
│  │ Pod 1    │ │ Pod 2    │ │ Pod 3    │    │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘    │
└───────┼────────────┼────────────┼──────────┘
        │            │            │
        └────────────┼────────────┘
                     ▼
              ┌─────────────┐
              │   Harbor    │
              │  Registry   │
              └─────────────┘