플로는 에이전트를 사용해 작업을 실행합니다.

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

플로가 CI/CD로 실행되는 환경을 구성할 수 있습니다. 자체 러너를 사용하거나 job에서 변수를 지정할 수도 있습니다.

실행기 아키텍처#

플로가 CI/CD에서 실행되면 러너는 다음을 수행합니다.

1. GitLab 패키지 레지스트리에서 운영 체제와 아키텍처에 맞는 GitLab Duo CLI 바이너리를 다운로드합니다. Node.js와 npm은 필요하지 않습니다.
2. WebSocket을 사용해 GitLab Duo Workflow Service에 연결하는 GitLab Duo CLI를 실행합니다.
3. AI 모델의 지시에 따라 도구(파일 작업, Git 명령)를 실행합니다.

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

CI/CD 실행 구성#

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

지원되는 키와 해당 유형의 목록은 agent-config.yml 참조를 참고합니다.

에이전트 구성 파일 생성#

GitLab Duo로 에이전트 구성 파일을 생성하거나 수동으로 만들 수 있습니다.

구성은 프로젝트의 플로가 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/

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

캐시 제한 사항#

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

ID 토큰 구성#

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

ID 토큰은 GitLab CI/CD가 생성해 플로를 실행하는 job에 주입하는 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

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

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

토큰 페이로드와 서드 파티 서비스와의 신뢰를 구성하는 방법은 ID 토큰을 사용하는 OpenID Connect(OIDC) 인증을 참고합니다.

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

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

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

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

플로에 자체 러너를 구성하려면 다음을 수행합니다.

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

2. 러너가 플로용 job을 가져가도록 러너에 gitlab--duo 태그를 추가합니다. 러너에 이 태그가 없으면 플로가 있는 job이 무기한 대기열에 남습니다. 다음 방법 중 하나를 사용합니다.

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

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

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

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

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

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

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

   • Agent Platform으로의 GitLab 인스턴스 아웃바운드 연결을 허용합니다.
   • Agent Platform으로의 러너 아웃바운드 연결을 허용합니다.
   • 인증서 체인에 자체 서명 인증서가 있는 인스턴스에서는 추가 GitLab Duo CLI 구성을 완료합니다.

러너 구성 확인#

플로에 러너가 올바르게 구성되었는지 확인하려면 다음을 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. GitLab Duo를 펼칩니다.
4. CI/CD runner 행에서 상태를 확인합니다.

이 확인은 러너가 온라인이고 올바른 태그, 실행기, 범위를 가지고 있는지 검증합니다.

러너를 등록하거나 수정한 뒤 확인을 다시 실행하려면 Check again을 선택합니다.

실행 환경 샌드박스를 사용해 플로 보호#

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

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

• Agent Platform의 기본 Docker 베이스 이미지
• 강화된 UBI 9 Minimal 이미지
• SRT가 설치된 사용자 지정 이미지

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

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

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

SRT가 설치되지 않은 사용자 지정 이미지에서는 샌드박스를 사용할 수 없습니다.

권한 모드 없이 충족하는 샌드박스 요구 사항#

권한 모드(privileged mode)는 샌드박스 요구 사항을 충족하는 한 가지 방법이지만, 그것만으로는 충분하지 않으며 항상 필요한 것도 아닙니다.

샌드박스의 요구 사항은 job이 사용자 및 마운트 네임스페이스를 생성할 수 있어야 한다는 것입니다. 런타임에 샌드박스는 먼저 unshare -m을 확인한 다음 unshare -rm으로 대체합니다.

• unshare -m에는 CAP_SYS_ADMIN이 필요하며, 러너가 privileged = true로 구성되었을 때 루트로 실행되는 컨테이너는 이를 가집니다.
• unshare -rm은 권한 없는 사용자 네임스페이스를 생성하며, 강화된 UBI 9 Minimal 이미지처럼 루트가 아닌 사용자로 실행되는 이미지에서 작동합니다. unshare -rm은 컨테이너 사용자를 새 네임스페이스 안에서만 루트로 매핑합니다. 러너 호스트에 대한 권한은 부여하지 않습니다.

privileged = true 설정이 샌드박스 초기화를 보장하지는 않습니다. 다음 경우에는 여전히 실패합니다.

• 러너 호스트에서 user.max_user_namespaces가 0으로 설정된 경우.
• seccomp 또는 AppArmor 프로필이 CLONE_NEWUSER 플래그를 차단하는 경우.
• 러너에 권한 모드가 설정되어 있지만 job 컨테이너에는 적용되지 않는 경우. 일부 docker-autoscaler 및 kubernetes 실행기 구성에서 이런 일이 발생할 수 있습니다.

사용할 수 있는 네임스페이스 모드가 없으면 플로는 샌드박스 없이 실행되며 job 로그에 다음 경고가 포함됩니다.

Warning: SRT found but can't create sandbox (insufficient privileges), running command directly