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

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

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

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

실행기 아키텍처#

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

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

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

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

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

CI/CD 실행 구성#

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

지원되는 키와 해당 유형의 목록은 agent-config.yml 참조를 참조하세요.

에이전트 구성 파일 생성#

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

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

• 필요한 구성 옵션을 추가합니다.

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

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

전체 agent-config.yml 파일 예시는 agent-config.yml 참조를 참조하세요.

설정 스크립트 구성#

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

설정 스크립트를 추가하려면 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에 루트 액세스가 필요한 경우(예: 시스템 패키지 설치), 사용자 지정 이미지가 그에 맞게 구성되어 있는지 확인합니다.

캐싱 구성#

후속 플로우 실행 속도를 높이도록 캐싱을 구성하려면 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 토큰 구성#

플로우에서 서드파티 서비스로 인증하려면 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) 인증을 참조하세요.

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

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가 설치되지 않은 사용자 지정 이미지