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.20
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와 이를 사용자 지정 이미지에 설치하는 방법에 대한 자세한 내용은 원격 실행 환경 샌드박스를 참조하세요.

사용자 지정 이미지 사용#

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

• git

• @gitlab/duo-cli와 호환되는 Node.js 버전의 npm. 자세한 내용은 GitLab Duo CLI 전제 조건을 참조하세요.

대부분의 베이스 이미지는 이러한 명령을 기본적으로 포함합니다. 그러나 최소 구성 이미지(alpine 변형 등)는 명시적으로 설치해야 할 수 있습니다. 필요한 경우 설정 스크립트 구성에서 누락된 명령을 설치할 수 있습니다.

@gitlab/duo-cli 버전 8.71.0 이하를 사용하는 경우, 최신 Git 버전에서 플로우가 실패하는 것을 방지하려면 다음 중 하나를 수행할 수 있습니다:

• 사용자 지정 이미지에서 Git 버전 2.43.7 이하를 사용합니다.

• @gitlab/duo-cli 버전 8.71.0을 사용합니다.

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

예를 들어 Alpine 기반 이미지를 사용하는 경우:

image: python:3.11-alpine
setup_script:
  - apk add --update git nodejs npm

보안 및 성능#

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

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

잡 시작 시간을 약 15~20초 줄이려면 사용자 지정 이미지에 @gitlab/duo-cli npm 패키지와 glab CLI를 포함하세요. 하드닝된 이미지는 두 도구를 모두 사전 설치하고 있습니다.

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

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

전제 조건:

• 관리자 액세스.

• GitLab 18.9 이상.

• 이미지를 빌드하고 아티팩트를 다운로드할 온라인 머신에 대한 액세스.

오프라인 환경용으로 플로우를 구성하려면:

• 온라인 머신에서 GitLab Duo CLI가 포함된 사용자 지정 이미지를 빌드합니다:

FROM registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image:v0.0.6
RUN npm install -g @gitlab/duo-cli@8.86.0

또는 npm을 아예 사용하지 않으려면 GitLab 패키지 레지스트리에서 독립 실행형 바이너리를 다운로드합니다:

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

독립 실행형 바이너리를 다운로드하려면 다음 명령을 실행합니다:

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

• 이미지를 오프라인 환경으로 전송합니다. 예를 들어 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

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

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

  • 오른쪽 상단에서 Admin을 선택합니다.

  • 왼쪽 사이드바에서 GitLab Duo를 선택합니다.

  • Change configuration을 선택합니다.

  • Image registry 텍스트 상자에 내부 레지스트리 URL을 입력합니다 (예: registry.internal.example.com).

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

• 사용자 지정 이미지를 사용하려면 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에 대한 아웃바운드 접근은 필요하지 않습니다.

추가 패키지 추가#

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

언어 런타임이나 시스템 패키지를 추가하려면:

• 자체 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

• 루트 액세스가 필요하지 않은 프로젝트 종속성에는 setup_script를 사용합니다. 예를 들어 pip install --user나 npm install입니다.