히스토리

• GitLab 18.3에서 도입.

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

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

• IDE에서 실행되는 플로우는 로컬로 실행됩니다.

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

플로우 보안#

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

• 액세스를 제한하기 위해 복합 아이덴티티를 사용합니다.

• 플로우가 완료되면 제거되는 임시 워크로드 파이프라인을 생성합니다.

• 사용할 수 있는 도구는 플로우의 목적에 특화되어 있습니다. 이러한 도구에는 머지 리퀘스트 생성 또는 실행 환경에서 로컬 셸 명령 실행이 포함될 수 있습니다.

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

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

agent-config.yml의 보안 영향#

.gitlab/duo/agent-config.yml 파일은 setup_script에서 실행되는 명령을 포함하여 CI/CD에서 플로우가 실행되는 방식을 제어합니다. 플로우 실행 방식 때문에 이 파일의 변경 사항은 변경을 커밋한 사용자 외의 더 많은 사용자에게 영향을 미칩니다.

크로스 사용자 실행#

플로우는 복합 아이덴티티를 통해 플로우를 트리거한 사용자의 아이덴티티로 실행됩니다. setup_script의 명령은 구성을 커밋한 사용자의 자격 증명이 아닌, 트리거한 사용자의 복합 아이덴티티 자격 증명으로 실행됩니다.

.gitlab/duo/agent-config.yml에 대한 쓰기 액세스 권한이 있는 사용자는 다른 사용자의 러너 환경에서 실행되는 내용에 영향을 미칠 수 있습니다. 이 파일에 대한 수정은 나중에 프로젝트에서 플로우를 트리거하는 모든 사용자의 실행 컨텍스트에 영향을 미칩니다.

노출된 환경 변수#

Anthropic Sandbox Runtime(SRT) 외부에서 실행되는 setup_script 실행 중에 환경에 다음 민감한 변수가 존재합니다:

• GITLAB_OAUTH_TOKEN 및 GITLAB_TOKEN: 복합 아이덴티티를 통한 트리거 사용자의 OAuth 토큰.

• DUO_WORKFLOW_GIT_HTTP_PASSWORD: Git HTTP 비밀번호.

• DUO_WORKFLOW_SERVICE_TOKEN: 서비스 토큰.

• DUO_WORKFLOW_GIT_USER_EMAIL 및 DUO_WORKFLOW_GIT_USER_NAME: 트리거 사용자의 이메일 및 이름.

노출된 변수의 전체 목록은 플로우 실행 변수를 참조하세요.

권장 보호 조치#

.gitlab/duo/agent-config.yml 파일의 무단 변경 위험을 줄이려면:

기본 브랜치를 보호하여 직접 푸시를 방지합니다.

Code Owners를 사용하여 .gitlab/duo/agent-config.yml에 대한 변경 사항이 머지되기 전에 특정 Owner의 승인을 요구합니다. 예를 들어 CODEOWNERS 파일에 다음을 추가합니다:

.gitlab/duo/agent-config.yml @your-group/security-reviewers

이 파일을 수정하는 머지 리퀘스트에 대해 신뢰할 수 있는 메인테이너의 검토를 요구하는 승인 규칙을 구성합니다.

실행기 아키텍처#

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

• npm 레지스트리에서 @gitlab/duo-cli 패키지를 다운로드합니다.

• WebSocket을 사용하여 GitLab Duo Workflow Service에 연결하는 GitLab Duo CLI를 실행합니다.

• AI 모델의 지시에 따라 도구(파일 작업, Git 명령)를 실행합니다.

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

CI/CD 실행 구성#

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

구성 파일 생성#

• 프로젝트 리포지터리에 없는 경우 .gitlab/duo/ 폴더를 생성합니다.

• 폴더에 agent-config.yml이라는 구성 파일을 생성합니다.

• 필요한 구성 옵션을 추가합니다(아래 섹션 참조).

• 파일을 기본 브랜치에 커밋하고 푸시합니다.

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

기본 Docker 이미지 변경#

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

Docker 이미지를 변경하여 직접 지정할 수 있습니다. 특정 종속성이나 도구가 필요한 복잡한 프로젝트에 유용합니다. 이미지에서 네트워크 보호를 사용하려면 원하는 버전으로 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 이미지를 변경하려면 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/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"

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

• 기본 워크플로 명령 전에 실행됩니다.

• 지정된 순서로 실행됩니다.

• 단일 명령 또는 명령 배열이 될 수 있습니다.

setup_script에 대한 사용자 컨텍스트는 Docker 이미지에 따라 다릅니다. 기본 GitLab 이미지는 root로 실행됩니다. 사용자 지정 이미지는 이미지의 USER 지시어에 정의된 사용자로 실행됩니다. setup_script에 루트 액세스가 필요한 경우(예: 시스템 패키지 설치), 사용자 지정 이미지가 그에 맞게 구성되어 있는지 확인합니다.

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

러너가 외부 레지스트리에 접근할 수 없는 오프라인 환경에서는 @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를 사용하여 다음 명령을 실행합니다:

# 온라인 머신에서
docker save my-duo-executor:latest -o duo-executor.tar

# `duo-executor.tar`를 오프라인 환경으로 전송

# 오프라인 머신에서
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

캐싱 구성#

후속 플로우 실행 속도를 높이도록 캐싱을 구성하려면 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 변수를 지원합니다.

ID 토큰 구성#

히스토리

• GitLab 19.2에서 도입.

플로우에서 서드파티 서비스로 인증하려면 ID 토큰을 구성합니다.

ID 토큰은 GitLab CI/CD가 생성하여 플로우를 실행하는 잡에 주입하는 JSON 웹 토큰(JWT)으로, 장기 자격 증명을 저장하지 않고 키리스 OpenID Connect(OIDC) 인증을 수행합니다. 예를 들어 ID 토큰을 사용하여 시크릿 관리자에서 시크릿을 가져오거나 바이너리와 Git 커밋에 서명할 수 있습니다.

ID 토큰을 구성하려면 agent-config.yml 파일에 id_tokens 블록을 추가합니다. 각 토큰에는 aud(audience) 클레임이 필요합니다:

id_tokens:
  VAULT_ID_TOKEN:
    aud: https://vault.example.com

network_policy:
  allowed_domains:
    - vault.example.com

aud 클레임은 단일 문자열 또는 문자열 목록일 수 있습니다:

id_tokens:
  MY_ID_TOKEN:
    aud:
      - https://first.service.example.com
      - https://second.service.example.com

network_policy:
  allowed_domains:
    - first.service.example.com
    - second.service.example.com

각 토큰은 토큰 이름을 사용하는 환경 변수로 플로우 잡에서 사용할 수 있습니다. 이전 예시의 경우 플로우는 $VAULT_ID_TOKEN과 $MY_ID_TOKEN을 사용할 수 있습니다.

토큰 이름이 구성의 다른 곳에서 선언된 변수 이름과 일치하는 경우 ID 토큰이 우선합니다.

토큰 페이로드 및 서드파티 서비스와의 신뢰를 구성하는 방법에 대한 자세한 내용은 ID 토큰을 사용한 OpenID Connect(OIDC) 인증을 참조하세요.

전체 구성 예시#

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

# Custom Docker image
image: python:3.11

# Setup script to run before the flow
setup_script:
  - apt-get update && apt-get install -y build-essential
  - pip install --upgrade pip
  - pip install -r requirements.txt

# Cache configuration
cache:
  key:
    files:
      - requirements.txt
      - Pipfile.lock
    prefix: python-deps
  paths:
    - .cache/pip
    - venv/

# Network configuration
network_policy:
  include_recommended_allowed: true
  allow_all_unix_sockets: true
  allowed_domains:
    - vault.example.com
  denied_domains:
    - malicious.com

# ID tokens for OIDC authentication
id_tokens:
  VAULT_ID_TOKEN:
    aud: https://vault.example.com

이 구성:

• Python 3.11을 기본 이미지로 사용합니다.

• 플로우 실행 전에 빌드 도구와 Python 종속성을 설치합니다.

• pip와 가상 환경 디렉터리를 캐시합니다.

• requirements.txt 또는 Pipfile.lock이 변경되면 새 캐시가 생성되며, python-deps 접두사를 사용합니다.

• HashiCorp Vault와의 OIDC 인증을 위한 VAULT_ID_TOKEN ID 토큰을 제공합니다.

플로우를 실행하는 러너 구성#

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

GitLab.com에서 플로우는 GitLab이 제공하는 호스팅 러너를 사용할 수 있습니다. 이는 기본적으로 활성화되어 있습니다.

또한 플로우에 대한 자체 러너를 구성할 수도 있습니다.

플로우에 대한 자체 러너를 구성하려면:

인스턴스 러너 또는 최상위 그룹에 할당된 그룹 러너를 생성합니다. 플로우가 프로젝트 러너 또는 하위 그룹에 할당된 그룹 러너를 사용하도록 하려면 duo_runner_restrictions 피처 플래그를 끕니다(GitLab Self-Managed 전용).

러너가 플로우 잡을 선택하도록 러너에 gitlab--duo 태그를 추가합니다. 러너에 이 태그가 없으면 플로우 잡이 무기한 대기열에 남습니다. 다음 방법 중 하나를 사용합니다:

러너를 생성할 때 Tags 필드에 gitlab--duo를 입력합니다.

기존 러너의 경우 러너가 실행할 수 있는 잡을 편집하고 Tags 필드에 gitlab--duo를 입력합니다.

config.toml 파일로 러너를 구성하는 경우 [[runners]] 섹션에 태그를 추가합니다:

[[runners]]
  executor = "docker"
  tags = ["gitlab--duo"]

러너가 docker, docker-autoscaler, kubernetes와 같이 Docker 이미지를 지원하는 실행기를 사용하도록 구성합니다. shell 실행기는 지원되지 않습니다.

최상위 그룹에서 IP 주소 제한을 켠 경우, 러너가 그룹에 액세스할 수 있도록 러너의 IP 주소를 그룹의 IP 허용 목록에 추가합니다.

GitLab Self-Managed 전용. 러너가 플로우에 필요한 서비스에 도달할 수 있는지 확인합니다:

Agent Platform으로의 GitLab 인스턴스에서의 아웃바운드 연결을 허용합니다.

• Agent Platform으로의 러너에서의 아웃바운드 연결을 허용합니다.

• 인증서 체인에 자체 서명 인증서가 있는 인스턴스의 경우 추가 GitLab Duo CLI 구성을 완료합니다.

실행 환경 샌드박스를 사용하여 플로우 보안#

네트워크 및 파일 시스템 격리를 위해 실행 환경 샌드박스를 사용하여 러너에서 실행되는 플로우를 보호합니다.

샌드박스를 사용하려면 다음 이미지 중 하나를 사용해야 합니다:

• Agent Platform용 기본 Docker 기본 이미지

• SRT가 설치된 사용자 지정 이미지

샌드박스를 사용하도록 러너를 구성하려면 러너 구성에서 privileged = true를 설정합니다.

예를 들어:

[[runners]]
  executor = "docker"
  tags = ["gitlab--duo"]
  [runners.docker]
    privileged = true

다음 이미지로는 샌드박스를 사용할 수 없습니다:

• SRT가 설치되지 않은 사용자 지정 이미지

• Hardened UBI 9 Minimal 이미지