히스토리

• GitLab 18.3에서 도입.

플로우는 에이전트를 사용하여 태스크를 실행합니다.

• GitLab UI에서 실행되는 플로우는 CI/CD를 사용합니다.
• IDE에서 실행되는 플로우는 로컬로 실행됩니다.

플로우가 CI/CD를 사용하여 실행되는 환경을 구성할 수 있습니다. 또한 자체 러너를 사용하고 잡에서 변수를 지정하도록 선택할 수 있습니다.

플로우 보안#

플로우가 GitLab CI/CD에서 실행될 때:

• 액세스를 제한하기 위해 복합 아이덴티티를 사용합니다.
• 플로우가 완료되면 제거되는 임시 워크로드 파이프라인을 생성합니다.
• 사용할 수 있는 도구는 플로우의 목적에 특화되어 있습니다. 이러한 도구에는 머지 리퀘스트 생성 또는 실행 환경에서 로컬 셸 명령 실행이 포함될 수 있습니다.

기본적으로 플로우는 GitLab 인스턴스에 대해서만 네트워크 액세스가 가능합니다. 네트워크 액세스 규칙에 대한 자세한 내용은 네트워크 정책 구성 방법을 참조하세요. 이 별도 환경은 셸 명령 실행의 의도하지 않은 결과로부터 보호합니다.

GitLab UI에서 플로우가 자율적으로 실행되지 않도록 하려면 플로우 실행을 끌 수 있습니다.

실행기 아키텍처#

플로우가 CI/CD에서 실행될 때 러너:

1. npm 레지스트리에서 @gitlab/duo-cli 패키지를 다운로드합니다.
2. WebSocket을 사용하여 GitLab Duo Workflow Service에 연결하는 GitLab Duo CLI를 실행합니다.
3. AI 모델의 지시에 따라 도구(파일 작업, Git 명령)를 실행합니다.

실행기 버전은 GitLab에서 관리되며 정기적인 릴리스의 일부로 업데이트됩니다.

CI/CD 실행 구성#

프로젝트에 에이전트 구성 파일을 생성하여 CI/CD에서 플로우가 실행되는 방식을 사용자 지정할 수 있습니다.

구성 파일 생성#

1. 프로젝트 리포지터리에 없는 경우 .gitlab/duo/ 폴더를 생성합니다.
2. 폴더에 agent-config.yml이라는 구성 파일을 생성합니다.
3. 필요한 구성 옵션을 추가합니다(아래 섹션 참조).
4. 파일을 기본 브랜치에 커밋하고 푸시합니다.

구성은 CI/CD에서 프로젝트의 플로우가 실행될 때 적용됩니다.

기본 Docker 이미지 변경#

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

Docker 이미지를 변경하여 직접 지정할 수 있습니다. 특정 종속성이나 도구가 필요한 복잡한 프로젝트에 유용합니다. 이미지에서 네트워크 보호를 사용하려면 원하는 버전으로 srt를 Docker 이미지에 추가하세요:

# 캐시 정리 및 확인과 함께 srt 샌드박싱 설치
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 이미지를 변경하려면 agent-config.yml 파일에 다음 구성을 추가합니다:

image: YOUR_DOCKER_IMAGE

예를 들어:

image: python:3.11-slim

또는 Node.js 프로젝트의 경우:

image: node:20-alpine

Hardened UBI 9 Minimal 이미지#

히스토리

• GitLab 19.0에서 도입.

GitLab은 Red Hat Universal Base Image (UBI) 9 Minimal 기반의 강화된 최소화 이미지 변형도 제공합니다. 이 이미지는 더 작은 공격 표면, 비루트 실행, Red Hat UBI 기반이 필요한 네트워크 제한, FedRAMP 스타일 또는 기타 보안에 민감한 환경을 위해 설계되었습니다.

강화된 이미지는 다음 경로에 게시됩니다: 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>

이미지 구성 요소#

이미지에는 @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.

강화된 이미지를 사용해야 하는 경우#

다음 환경 요구사항이 있을 때 강화된 이미지를 사용합니다:

• Red Hat UBI 기본 이미지가 필요한 경우. 예를 들어 FedRAMP 또는 엔터프라이즈 컴플라이언스.
• 기본적으로 비루트 컨테이너 실행이 필요한 경우.
• Agent Platform 자체에 필요한 것 이상의 언어 런타임이 없는 최소한의 공격 표면이 필요한 경우.
• 플로우 실행 시 인터넷 아웃바운드 액세스가 없는 경우 (모든 Agent Platform 종속성이 사전 설치됨).

연결된 환경에서 박스 기본 제공 다중 언어 런타임이 필요한 범용 플로우에는 기본 이미지를 사용합니다.

사용자 지정 이미지 요구사항#

사용자 지정 Docker 이미지를 사용하는 경우 에이전트가 올바르게 작동하려면 다음 명령이 사용 가능한지 확인합니다:

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

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

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

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

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

보안 및 성능#

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

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

잡 시작 시간을 약 15~20초 단축하려면 사용자 지정 이미지에 @gitlab-org/duo-cli npm 패키지와 glab CLI를 포함하세요. 이렇게 하면 플로우 시작 시 이러한 도구의 다운로드 단계를 건너뜁니다. 강화된 이미지는 두 도구를 모두 사전 설치합니다.

설정 스크립트 구성#

플로우가 실행되기 전에 실행되는 설정 스크립트를 정의할 수 있습니다. 종속성 설치, 환경 구성 또는 필요한 초기화 수행에 유용합니다.

설정 스크립트를 추가하려면 agent-config.yml 파일에 다음 명령을 추가합니다:

setup_script:
  - apt-get update && apt-get install -y curl
  - pip install -r requirements.txt
  - echo "Setup complete"

이러한 명령들은 다음 작업을 완료합니다:

• 기본 워크플로우 명령 전에 실행됩니다.
• 지정된 순서로 실행됩니다.
• 단일 명령 또는 명령 배열이 될 수 있습니다.

캐싱 구성#

후속 플로우 실행 속도를 높이도록 캐싱을 구성하려면 agent-config.yml 파일을 구성하여 실행 간에 파일과 디렉토리를 보존합니다. 캐싱은 node_modules 또는 Python 가상 환경과 같은 종속성 폴더에 유용합니다.

기본 캐시 구성#

특정 경로를 캐시하려면 agent-config.yml 파일에 다음을 추가합니다:

cache:
  paths:
    - node_modules/
    - .npm/

키로 캐시#

캐시 키를 사용하여 다양한 시나리오에 대한 서로 다른 캐시를 생성할 수 있습니다. 캐시 키는 프로젝트의 상태를 기반으로 캐시가 생성되도록 보장합니다.

문자열 키 사용#

cache:
  key: my-project-cache
  paths:
    - vendor/
    - .bundle/

파일 기반 캐시 키 사용#

파일 내용(잠금 파일 등)을 기반으로 동적 캐시 키를 생성합니다. 이 파일들이 변경되면 새 캐시가 생성됩니다. 지정된 파일의 SHA 체크섬을 생성합니다:

cache:
  key:
    files:
      - package-lock.json
      - yarn.lock
  paths:
    - node_modules/

파일 기반 키에 접두사 사용#

캐시 키 파일에 대해 계산된 SHA와 접두사를 결합합니다:

cache:
  key:
    files:
      - package-lock.json
    prefix: $CI_JOB_NAME
  paths:
    - node_modules/
    - .npm/

이 예시에서 잡 이름이 test이고 SHA 체크섬이 abc123이면 캐시 키는 test-abc123이 됩니다.

캐시 제한 사항#

• 캐시 키 생성에 최대 2개의 파일을 지정할 수 있습니다. 더 많은 파일이 지정되면 처음 두 개만 사용됩니다.
• 캐시 paths 필드가 필요합니다. 경로가 없는 캐시 구성은 효과가 없습니다.
• 캐시 키는 prefix 필드에서 CI/CD 변수를 지원합니다.

전체 구성 예시#

다음은 사용 가능한 모든 옵션을 사용하는 agent-config.yml 파일 예시입니다:

# 사용자 지정 Docker 이미지
image: python:3.11

# 플로우 전에 실행할 설정 스크립트
setup_script:
  - apt-get update && apt-get install -y build-essential
  - pip install --upgrade pip
  - pip install -r requirements.txt

# 캐시 구성
cache:
  key:
    files:
      - requirements.txt
      - Pipfile.lock
    prefix: python-deps
  paths:
    - .cache/pip
    - venv/

# 네트워크 구성
network_policy:
  include_recommended_allowed: true
  allow_all_unix_sockets: true
  allowed_domains:
    - my-own-site.com
  denied_domains:
    - malicious.com

이 구성:

• Python 3.11을 기본 이미지로 사용합니다.
• 플로우 실행 전에 빌드 도구와 Python 종속성을 설치합니다.
• pip와 가상 환경 디렉토리를 캐시합니다.
• requirements.txt 또는 Pipfile.lock이 변경되면 새 캐시가 생성되며, python-deps 접두사를 사용합니다.

러너 구성#

CI/CD를 사용하는 플로우는 러너에서 실행됩니다. 이러한 러너는:

• Docker 이미지를 지원하는 실행기를 사용해야 합니다. 예를 들어 docker, docker-autoscaler, kubernetes 등. shell 실행기는 지원되지 않습니다.
• gitlab--duo 태그가 있어야 하므로 러너가 올바른 잡을 선택합니다.
• 인스턴스 러너이거나 최상위 그룹에 할당되어 있어야 합니다. 플로우는 서브그룹 또는 프로젝트에 구성된 러너를 사용할 수 없습니다. GitLab Self-Managed에서는 duo_runner_restrictions 피처 플래그를 비활성화하여 이 제한을 비활성화할 수 있습니다.

또한 GitLab Self-Managed의 러너에는 다음 요구사항이 적용됩니다:

• 러너는 GitLab 인스턴스에 대해 구성된 GitLab Duo Agent Platform 서비스로의 네트워크 트래픽을 허용해야 합니다.
  • GitLab Duo Agent Platform 서비스는 AI Gateway와 함께 제공됩니다. AI Gateway를 자체 호스팅하고 Agent Platform에 대한 로컬 URL을 설정하지 않으면, 에이전트 기능이 포트 443의 duo-workflow-svc.runway.gitlab.net으로 트래픽을 라우팅합니다.
• 러너는 registry.gitlab.com에서 기본 이미지를 다운로드하거나 지정한 Docker 이미지에 액세스할 수 있어야 합니다.

인증서 체인에 자체 서명 인증서가 있는 GitLab 인스턴스의 경우 GitLab Duo CLI에는 추가 구성이 필요합니다.

GitLab.com에서 플로우는 다음을 사용할 수 있습니다:

• GitLab에서 제공하는 호스팅 러너.

러너에서 실행되는 플로우는 네트워크 및 파일 시스템 격리를 제공하는 런타임 샌드박싱으로 보호될 수 있습니다. 샌드박싱을 사용하려면:

1. 러너 구성에서 privileged = true를 설정하여 특권 모드를 켭니다.
2. 다음 중 하나를 사용합니다:
   • GitLab Duo Agent Platform에 대한 기본 Docker 기본 이미지
   • SRT가 설치된 사용자 지정 이미지

러너 특권 모드#

특권 모드는 환경 샌드박스 보호를 위해 필요합니다. 이 요구사항은 GitLab에서 제공하는 기본 이미지 또는 SRT가 설치된 사용자 지정 이미지를 사용할 때 적용됩니다. SRT 없이 사용자 지정 Docker 이미지를 사용하는 경우 샌드박스를 적용할 수 없으므로 특권 모드가 필요하지 않습니다.