CI/CD로 실행되는 플로는 Docker 이미지 안에서 동작합니다. 기본적으로 GitLab은 플로에 필요한 도구와 네트워크 보호 기능이 포함된 이미지를 제공합니다. 프로젝트 의존성을 추가하거나 컴플라이언스 요구 사항을 충족하거나 오프라인 환경에서 플로를 실행하려면, 기본 이미지를 사용자 지정 이미지나 하드닝된 이미지로 교체할 수 있습니다.

기본 Docker 이미지 변경#

CI/CD로 실행되는 모든 플로는 GitLab이 제공하는 Docker 이미지를 사용합니다. 이 Docker 이미지는 Anthropic Sandbox Runtime(srt)을 사용해 네트워크 보호 기능을 자동으로 포함합니다.

특정 의존성이나 도구가 필요한 복잡한 프로젝트라면 Docker 이미지를 변경할 수 있습니다.

기본 Docker 이미지를 변경하려면 agent-config.yml 파일에 다음 구성을 추가합니다.

image: YOUR_DOCKER_IMAGE

예를 들면 다음과 같습니다.

image: python:3.11-slim

image: node:20-alpine

네트워크 보호 추가#

이미지에서 네트워크 보호 기능을 사용하려면 원하는 버전의 srt를 Docker 이미지에 추가합니다.

# Install srt sandboxing with cache clearing and verification
ARG SANDBOX_RUNTIME_VERSION=0.0.63
RUN npm cache clean --force && \
    npm install -g @anthropic-ai/sandbox-runtime@${SANDBOX_RUNTIME_VERSION} && \
    test -s "$(npm root -g)/@anthropic-ai/sandbox-runtime/package.json" && \
    srt --version

SRT와 사용자 지정 이미지에 SRT를 설치하는 방법에 대한 자세한 내용은 원격 실행 환경 샌드박스를 참고합니다.

사용자 지정 이미지 사용#

사용자 지정 Docker 이미지를 사용하는 경우, 에이전트가 올바르게 동작하도록 다음 명령을 사용할 수 있는지 확인합니다.

• git
• curl. 플로 시작 시 GitLab Duo CLI 바이너리를 내려받습니다.

대부분의 베이스 이미지에는 이 명령이 기본으로 포함되어 있습니다. 다만 alpine 계열처럼 최소 구성 이미지에서는 직접 설치해야 할 수 있습니다. 필요하다면 설정 스크립트 구성에서 빠진 명령을 설치할 수 있습니다.

또한 플로 실행 중 에이전트가 호출하는 도구에 따라 다른 공통 유틸리티가 필요할 수 있습니다.

예를 들어 Alpine 기반 이미지를 사용한다면 다음과 같이 구성합니다.

image: python:3.11-alpine
setup_script:
  - apk add --update git curl

보안 및 성능#

사용자 지정 Docker 이미지를 사용하는 경우 환경 샌드박스는 사용자 지정 이미지에 Anthropic Sandbox Runtime(SRT)이 포함되어 있을 때만 적용됩니다. SRT가 포함되어 있지 않으면 플로가 러너에서 도달 가능한 모든 도메인과 전체 파일 시스템에 접근할 수 있습니다.

사용자 지정 이미지에서 네트워크 격리가 필요하다면 이미지에 SRT를 설치하고 네트워크 정책을 구성하거나, 러너에 네트워크 수준 제어를 구성합니다(예: 방화벽 규칙이나 네트워크 정책).

job 시작 시간을 약 15~20초 단축하려면 사용자 지정 이미지에 GitLab Duo CLI 바이너리와 glab CLI를 포함합니다. 하드닝된 이미지에는 두 도구가 미리 설치되어 있습니다.

오프라인 환경에서 사용자 지정 이미지 사용#

러너가 외부 레지스트리에 접근할 수 없는 오프라인 환경에서는 GitLab Duo CLI가 포함된 사용자 지정 실행기 이미지를 미리 빌드할 수 있습니다. GitLab Duo CLI가 이미 이미지에 있으면 플로를 시작할 때 다운로드 단계를 건너뜁니다.

사전 요건:

• 관리자 액세스 권한.
• GitLab 18.9 이상.
• 이미지를 빌드하고 아티팩트를 내려받을 수 있는 온라인 머신에 대한 접근 권한.

오프라인 환경에 맞게 플로를 구성하려면 다음 단계를 따릅니다.

1. 온라인 머신에서 GitLab 패키지 레지스트리에서 GitLab Duo CLI 바이너리를 내려받습니다.

   curl --location "https://gitlab.com/api/v4/projects/46519181/packages/generic/duo-cli/9.8.0/duo-linux-x64" \
     --output duo-linux-x64
   

2. 해당 바이너리가 포함된 사용자 지정 이미지를 빌드합니다.

   FROM registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image:v0.0.6
   COPY duo-linux-x64 /usr/bin/duo
   RUN chmod +x /usr/bin/duo
   

3. 이미지를 오프라인 환경으로 전송합니다. 예를 들어 Docker에서는 다음 명령을 실행합니다.

   # On an online machine
   docker save my-duo-executor:latest -o duo-executor.tar
   
   # Transfer `duo-executor.tar` to the offline environment
   
   # On an offline machine
   docker load -i duo-executor.tar
   

4. 이미지를 내부 컨테이너 레지스트리에 푸시합니다.

5. 사용자 지정 이미지 레지스트리를 설정합니다.

   1. 오른쪽 위 모서리에서 Admin을 선택합니다.
   2. 왼쪽 사이드바에서 GitLab Duo를 선택합니다.
   3. Change configuration을 선택합니다.
   4. Image registry 텍스트 상자에 내부 레지스트리 URL을 입력합니다 (예: registry.internal.example.com).

6. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.

7. 사용자 지정 이미지를 사용하려면 agent-config.yml 파일을 수정합니다.

   image: registry.internal.example.com/duo-executor:latest
   

Red Hat Universal Base Image 9 Minimal 사용#

GitLab은 Red Hat Universal Base Image(UBI) 9 Minimal을 기반으로 하드닝된 최소 구성 이미지 변형을 제공합니다.

다음이 필요한 환경에서는 하드닝된 이미지를 사용합니다.

• Red Hat UBI 베이스 이미지. 예를 들어 FedRAMP 또는 엔터프라이즈 컴플라이언스 요구 사항이 있는 경우입니다.
• 기본적으로 비루트 컨테이너 실행이 필요한 경우입니다.
• Agent Platform 자체에 필요한 것 외의 언어 런타임이 없는 최소 공격 표면이 필요한 경우입니다.
• 플로 실행 시점에 외부 인터넷 접근이 없어야 하는 경우입니다(모든 Agent Platform 의존성이 미리 설치되어 있습니다).

하드닝된 이미지는 다음 위치에 게시되어 있습니다. registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image-hardened

이 이미지는 linux/amd64와 linux/arm64 모두를 대상으로 빌드되며, 다음 태그 체계를 사용합니다.

• 빌드마다 :<short-sha>
• 릴리스마다 :<git-tag>

사전 요건:

• GitLab 18.10 이상

하드닝된 이미지를 사용하려면 agent-config.yml에 다음과 같이 설정합니다.

image: registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image-hardened:<tag>

이미지 구성 요소#

모든 구성 요소와 고정된 버전의 정본 최신 목록은 default-docker-image README의 런타임 인벤토리를 참고합니다.

다음 표는 현재 고정된 버전을 보여 줍니다.

이 이미지에는 GitLab Duo CLI와 glab 이 포함되어 있습니다. 플로 실행 시점에 registry.npmjs.org 나 registry.gitlab.com 으로의 외부 접근은 필요하지 않습니다.

Node.js와 npm은 Anthropic Sandbox Runtime(SRT)을 설치하기 위해서만 이미지에 남아 있습니다. GitLab Duo CLI 자체는 미리 컴파일된 바이너리이므로 이 둘이 필요하지 않습니다. SRT도 미리 컴파일된 바이너리로 배포되면, 이후 버전의 하드닝된 이미지에서는 Node.js와 npm 이 완전히 제거됩니다.

추가 패키지 추가#

하드닝된 이미지는 UID 1001(duo-runner)로 실행됩니다. agent-config.yml의 setup_script 역시 이 비루트 사용자로 실행되므로 microdnf로 시스템 패키지를 설치할 수 없습니다.

언어 런타임이나 시스템 패키지를 추가하려면 다음 단계를 따릅니다.

1. 직접 만든 FROM 레이어로 이미지를 확장합니다.

   FROM registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image-hardened:<tag>
   
   USER root
   RUN microdnf install -y python3.12 python3.12-pip && microdnf clean all
   USER 1001
   

2. 루트 권한이 필요하지 않은 프로젝트 의존성은 setup_script를 사용합니다. 예를 들어 pip install --user 나 npm install 입니다.