Custom executor를 사용하면 직접 실행 환경을 지정할 수 있습니다. GitLab Runner가 executor를 기본적으로 지원하지 않는 경우(예: LXD 또는 Libvirt), 환경을 프로비저닝하고, 실행하고, 정리하기 위해 사용자 정의 실행 파일을 사용하도록 GitLab Runner를 구성할 수 있습니다.

custom executor에 구성하는 스크립트를 드라이버라고 합니다. 예를 들어, LXD 드라이버 또는 Libvirt 드라이버를 만들 수 있습니다.

구성#

몇 가지 구성 키 중에서 선택할 수 있습니다. 일부는 선택 사항입니다.

다음은 사용 가능한 모든 구성 키를 사용한 Custom executor 구성 예제입니다:

[[runners]]
  name = "custom"
  url = "https://gitlab.com"
  token = "TOKEN"
  executor = "custom"
  builds_dir = "/builds"
  cache_dir = "/cache"
  shell = "bash"
  [runners.custom]
    config_exec = "/path/to/config.sh"
    config_args = [ "SomeArg" ]
    config_exec_timeout = 200

    prepare_exec = "/path/to/script.sh"
    prepare_args = [ "SomeArg" ]
    prepare_exec_timeout = 200

    run_exec = "/path/to/binary"
    run_args = [ "SomeArg" ]

    cleanup_exec = "/path/to/executable"
    cleanup_args = [ "SomeArg" ]
    cleanup_exec_timeout = 200

    graceful_kill_timeout = 200
    force_kill_timeout = 200

필드 정의 및 필수 항목에 대해서는 [runners.custom] 섹션 구성을 참조하세요.

또한 [[runners]] 내부의 builds_dir과 cache_dir 모두 필수 필드입니다.

작업 실행을 위한 필수 소프트웨어#

사용자는 환경을 설정해야 하며, PATH에 다음이 반드시 있어야 합니다:

• Git 및 Git LFS: 공통 필수 사항을 참조하세요.
• GitLab Runner: 아티팩트 및 캐시 다운로드/업데이트에 사용됩니다.

단계#

Custom executor는 작업 세부 사항 구성, 환경 준비 및 정리, 환경에서 작업 스크립트 실행을 위한 단계를 제공합니다. 각 단계는 특정 사항에 대한 책임이 있으며 고려해야 할 다양한 사항이 있습니다.

Custom executor가 실행하는 각 단계는 내장 GitLab Runner executor가 실행하는 시점과 동일한 시점에 실행됩니다.

실행된 각 단계는 실행 중인 작업에 대한 정보를 제공하는 특정 환경 변수에 접근할 수 있습니다. 모든 단계에서 다음 환경 변수를 사용할 수 있습니다:

• 표준 CI/CD 환경 변수, 포함 사전 정의 변수.
• Custom executor 러너 호스트 시스템에서 제공하는 모든 환경 변수.
• 모든 서비스 및 사용 가능한 설정. CUSTOM_ENV_CI_JOB_SERVICES로 JSON 형식으로 노출됩니다.

CI/CD 환경 변수와 사전 정의 변수 모두 시스템 환경 변수와의 충돌을 방지하기 위해 CUSTOM_ENV_ 접두사가 붙습니다. 예를 들어, CI_BUILDS_DIR은 CUSTOM_ENV_CI_BUILDS_DIR로 사용할 수 있습니다.

단계는 다음 순서로 실행됩니다:

1. config_exec
2. prepare_exec
3. run_exec
4. cleanup_exec

서비스#

서비스는 CUSTOM_ENV_CI_JOB_SERVICES로 JSON 배열로 노출됩니다.

예시:

custom:
  script:
    - echo $CUSTOM_ENV_CI_JOB_SERVICES
  services:
    - redis:latest
    - name: my-postgres:9.4
      alias: pg
      entrypoint: ["path", "to", "entrypoint"]
      command: ["path", "to", "cmd"]
      variables:
        POSTGRES_PASSWORD: secret
        POSTGRES_DB: mydb

위 예제는 CUSTOM_ENV_CI_JOB_SERVICES 환경 변수를 다음 값으로 설정합니다:

[{"name":"redis:latest","alias":"","entrypoint":null,"command":null},{"name":"my-postgres:9.4","alias":"pg","entrypoint":["path","to","entrypoint"],"command":["path","to","cmd"],"variables":{"POSTGRES_DB":"mydb","POSTGRES_PASSWORD":"secret"}}]

JSON 배열의 각 서비스 객체에는 다음 필드가 있습니다:

Config#

Config 단계는 config_exec에 의해 실행됩니다.

실행 시간에 일부 설정을 지정하고 싶을 때가 있습니다. 예를 들어 프로젝트 ID에 따라 빌드 디렉터리를 설정하는 경우입니다. config_exec는 STDOUT에서 읽고 특정 키를 가진 유효한 JSON 문자열을 기대합니다.

예시:

#!/usr/bin/env bash

cat << EOS
{
  "builds_dir": "/builds/${CUSTOM_ENV_CI_CONCURRENT_PROJECT_ID}/${CUSTOM_ENV_CI_PROJECT_PATH_SLUG}",
  "cache_dir": "/cache/${CUSTOM_ENV_CI_CONCURRENT_PROJECT_ID}/${CUSTOM_ENV_CI_PROJECT_PATH_SLUG}",
  "builds_dir_is_shared": true,
  "hostname": "custom-hostname",
  "driver": {
    "name": "test driver",
    "version": "v0.0.1"
  },
  "job_env" : {
    "CUSTOM_ENVIRONMENT": "example"
  },
  "shell": "bash"
}
EOS

JSON 문자열 내의 추가 키는 무시됩니다. 유효한 JSON 문자열이 아니면 단계가 실패하고 두 번 더 재시도합니다.

실행 파일의 STDERR는 작업 로그에 출력됩니다.

GitLab Runner가 JSON 문자열을 반환하기 전에 프로세스를 종료하기까지 기다리는 시간 제한을 설정하려면 config_exec_timeout을 구성할 수 있습니다.

config_args를 정의하면 정의한 순서대로 config_exec 실행 파일에 추가됩니다. 예를 들어, 다음과 같은 config.toml 내용이 있을 때:

...
[runners.custom]
  ...
  config_exec = "/path/to/config"
  config_args = [ "Arg1", "Arg2" ]
  ...

GitLab Runner는 /path/to/config Arg1 Arg2로 실행합니다.

job_env 사용법#

job_env 구성의 주요 목적은 작업 실행의 후속 단계에서 custom executor 드라이버 호출의 컨텍스트에 변수를 전달하는 것입니다.

예를 들어, 작업 실행 환경과의 연결에 일부 자격 증명 준비가 필요한 드라이버가 있습니다. 이 작업은 비용이 많이 듭니다. 드라이버는 환경에 연결하기 전에 로컬 공급자에서 임시 SSH 자격 증명을 요청해야 합니다.

Custom Executor 실행 흐름에서 각 작업 실행 단계(prepare, 여러 run 호출, cleanup)는 자체 컨텍스트를 가진 별도 실행으로 실행됩니다. 자격 증명 해결 예제에서 자격 증명 공급자에 대한 연결은 매번 수행해야 합니다.

이 작업이 비용이 많이 드는 경우, 전체 작업 실행에 대해 한 번만 수행하고 모든 작업 실행 단계에서 자격 증명을 재사용하세요. job_env가 여기서 도움이 될 수 있습니다. 이를 통해 config_exec 호출 중에 공급자와 한 번 연결하고 job_env로 수신된 자격 증명을 전달할 수 있습니다. 그런 다음 custom executor가 prepare_exec, run_exec, cleanup_exec에 대해 받는 변수 목록에 추가됩니다. 이렇게 하면 드라이버가 매번 자격 증명 공급자에 연결하는 대신 변수를 읽고 존재하는 자격 증명을 사용할 수 있습니다.

중요한 것은 변수가 작업 자체에 자동으로 사용 가능하지 않다는 것입니다. 이는 완전히 Custom Executor 드라이버의 구현 방식에 따라 다르며, 많은 경우에 그곳에 없습니다.

job_env 설정을 사용하여 특정 러너가 실행하는 모든 작업에 변수 집합을 전달하는 방법에 대한 정보는 [[runners]]의 environment 설정을 참조하세요.

변수가 작업 간에 변경될 수 있는 값으로 동적인 경우, 드라이버 구현이 job_env로 전달된 변수를 실행 호출에 추가하는지 확인하세요.

Prepare#

Prepare 단계는 prepare_exec에 의해 실행됩니다.

이 시점에서 GitLab Runner는 작업에 대한 모든 정보(어디서 어떻게 실행되는지)를 알고 있습니다. 남은 것은 작업이 실행될 수 있도록 환경을 설정하는 것입니다. GitLab Runner는 prepare_exec에 지정된 실행 파일을 실행합니다.

이 작업은 환경을 설정하는 데 책임이 있습니다(예: 가상 머신 또는 컨테이너, 서비스 또는 기타 항목 생성). 이 작업이 완료되면 환경이 작업을 실행할 준비가 되었다고 예상합니다.

이 단계는 작업 실행에서 한 번만 실행됩니다.

GitLab Runner가 프로세스를 종료하기 전에 환경 준비를 기다리는 시간 제한을 설정하려면 prepare_exec_timeout을 구성할 수 있습니다.

이 실행 파일에서 반환된 STDOUT 및 STDERR는 작업 로그에 출력됩니다.

prepare_exec_args를 정의하면 정의한 순서대로 prepare_exec 실행 파일에 추가됩니다. 예를 들어, 다음과 같은 config.toml 내용이 있을 때:

...
[runners.custom]
  ...
  prepare_exec = "/path/to/bin"
  prepare_args = [ "Arg1", "Arg2" ]
  ...

GitLab Runner는 /path/to/bin Arg1 Arg2로 실행합니다.

Run#

Run 단계는 run_exec에 의해 실행됩니다.

이 실행 파일에서 반환된 STDOUT 및 STDERR는 작업 로그에 출력됩니다.

다른 단계와 달리, run_exec 단계는 아래에 순서대로 나열된 하위 단계로 분할되어 여러 번 실행됩니다:

1. prepare_script
2. get_sources
3. restore_cache
4. download_artifacts
5. step_*
6. build_script
7. step_*
8. after_script
9. archive_cache 또는 archive_cache_on_failure
10. upload_artifacts_on_success 또는 upload_artifacts_on_failure
11. cleanup_file_variables

위에 언급된 각 단계에 대해 run_exec 실행 파일은 다음과 함께 실행됩니다:

• 일반적인 환경 변수.
• 두 개의 인수:
  • Custom executor가 실행하기 위해 GitLab Runner가 생성하는 스크립트의 경로.
  • 단계 이름.

예시:

/path/to/run_exec.sh /path/to/tmp/script1 prepare_executor
/path/to/run_exec.sh /path/to/tmp/script1 prepare_script
/path/to/run_exec.sh /path/to/tmp/script1 get_sources

run_args가 정의되어 있으면, 이것이 run_exec 실행 파일에 전달되는 첫 번째 인수 집합이고 그 다음에 GitLab Runner가 다른 인수를 추가합니다. 예를 들어, 다음 config.toml이 있다고 가정합니다:

...
[runners.custom]
  ...
  run_exec = "/path/to/run_exec.sh"
  run_args = [ "Arg1", "Arg2" ]
  ...

GitLab Runner는 다음 인수로 실행 파일을 실행합니다:

/path/to/run_exec.sh Arg1 Arg2 /path/to/tmp/script1 prepare_executor
/path/to/run_exec.sh Arg1 Arg2 /path/to/tmp/script1 prepare_script
/path/to/run_exec.sh Arg1 Arg2 /path/to/tmp/script1 get_sources

이 실행 파일은 첫 번째 인수에 지정된 스크립트를 실행하는 데 책임이 있어야 합니다. 스크립트에는 GitLab Runner executor가 리포지터리 복제, 아티팩트 다운로드, 사용자 스크립트 실행 및 아래에 설명된 모든 다른 단계를 실행하기 위해 실행하는 모든 스크립트가 포함되어 있습니다. 스크립트는 다음 셸 중 하나일 수 있습니다:

• Bash
• PowerShell Desktop
• PowerShell Core
• Batch (지원 중단됨)

[[runners]] 내부의 shell로 구성된 셸을 사용하여 스크립트를 생성합니다. 아무것도 제공되지 않으면 OS 플랫폼의 기본값이 사용됩니다.

아래 표는 각 스크립트가 수행하는 작업과 해당 스크립트의 주요 목표에 대한 자세한 설명입니다.

Cleanup#

Cleanup 단계는 cleanup_exec에 의해 실행됩니다.

이 마지막 단계는 이전 단계 중 하나가 실패해도 실행됩니다. 이 단계의 주요 목표는 설정된 환경을 정리하는 것입니다. 예를 들어 VM을 종료하거나 컨테이너를 삭제합니다.

cleanup_exec의 결과는 작업 상태에 영향을 미치지 않습니다. 예를 들어, 다음이 발생해도 작업은 성공으로 표시됩니다:

• prepare_exec와 run_exec 모두 성공.
• cleanup_exec 실패.

GitLab Runner가 프로세스를 종료하기 전에 환경 정리를 기다리는 시간 제한을 설정하려면 cleanup_exec_timeout을 구성할 수 있습니다.

이 실행 파일의 STDOUT는 DEBUG 레벨에서 GitLab Runner 로그에 출력됩니다. STDERR는 WARN 레벨에서 로그에 출력됩니다.

cleanup_exec_args를 정의하면 정의한 순서대로 cleanup_exec 실행 파일에 추가됩니다. 예를 들어, 다음과 같은 config.toml 내용이 있을 때:

...
[runners.custom]
  ...
  cleanup_exec = "/path/to/bin"
  cleanup_args = [ "Arg1", "Arg2" ]
  ...

GitLab Runner는 /path/to/bin Arg1 Arg2로 실행합니다.

실행 파일 종료 및 강제 종료#

GitLab Runner는 다음 조건 중 하나가 충족되면 실행 파일을 정상적으로 종료하려고 합니다:

• config_exec_timeout, prepare_exec_timeout 또는 cleanup_exec_timeout에 도달했을 때.
• 작업이 타임아웃될 때.
• 작업이 취소될 때.

타임아웃에 도달하면 실행 파일에 SIGTERM이 전송되고 exec_terminate_timeout에 대한 카운트다운이 시작됩니다. 실행 파일은 이 신호를 수신하여 리소스를 정리해야 합니다. exec_terminate_timeout이 지나도 프로세스가 여전히 실행 중이면 SIGKILL이 전송되어 프로세스를 종료하고 exec_force_kill_timeout이 시작됩니다. exec_force_kill_timeout이 완료된 후에도 프로세스가 여전히 실행 중이면 GitLab Runner는 프로세스를 포기하고 더 이상 중지하거나 종료하려 하지 않습니다. 이 두 타임아웃이 config_exec, prepare_exec 또는 run_exec 중에 도달하면 빌드가 실패로 표시됩니다.

드라이버가 생성한 자식 프로세스도 UNIX 기반 시스템에서 위에서 설명한 정상 종료 프로세스를 수신합니다. 이는 메인 프로세스가 모든 자식 프로세스가 속하는 프로세스 그룹으로 설정됨으로써 달성됩니다.

오류 처리#

GitLab Runner는 두 가지 유형의 오류를 다르게 처리할 수 있습니다. 이러한 오류는 config_exec, prepare_exec, run_exec, cleanup_exec 내부의 실행 파일이 이러한 코드로 종료될 때만 처리됩니다. 사용자가 0이 아닌 종료 코드로 종료하면 아래 오류 코드 중 하나로 전파되어야 합니다.

사용자 스크립트가 이러한 코드 중 하나로 종료하면 실행 파일의 종료 코드로 전파되어야 합니다.

빌드 실패#

GitLab Runner는 작업 실패를 나타내기 위해 실행 파일이 종료 코드로 사용해야 하는 BUILD_FAILURE_EXIT_CODE 환경 변수를 제공합니다. 실행 파일이 BUILD_FAILURE_EXIT_CODE의 코드로 종료되면 GitLab CI에서 빌드가 적절하게 실패로 표시됩니다.

사용자가 .gitlab-ci.yml 파일 내에 정의한 스크립트가 0이 아닌 코드로 종료되면 run_exec은 BUILD_FAILURE_EXIT_CODE 값으로 종료해야 합니다.

빌드 실패 종료 코드#

빌드가 실패했을 때 종료 코드를 포함하는 파일을 선택적으로 제공할 수 있습니다. 파일의 예상 경로는 BUILD_EXIT_CODE_FILE 환경 변수를 통해 제공됩니다. 예시:

if [ $exit_code -ne 0 ]; then
  echo $exit_code > ${BUILD_EXIT_CODE_FILE}
  exit ${BUILD_FAILURE_EXIT_CODE}
fi

CI/CD 작업은 allow_failure 구문을 활용하기 위해 이 방법이 필요합니다.

시스템 오류#

SYSTEM_FAILURE_EXIT_CODE에 지정된 오류 코드로 프로세스를 종료하여 GitLab Runner에 시스템 오류를 전송할 수 있습니다. 이 오류 코드가 반환되면 GitLab Runner는 특정 단계를 재시도합니다. 재시도 중 성공하지 못하면 작업이 실패로 표시됩니다.

다음은 재시도되는 단계와 횟수를 나타낸 표입니다.

작업 응답#

문서화된 CI/CD 변수 우선순위에 따라 CUSTOM_ENV_ 변수를 관찰하면서 작업 수준의 변수를 변경할 수 있습니다. 이 기능이 유용할 수 있지만, 신뢰할 수 있는 작업 컨텍스트가 필요한 경우 전체 JSON 작업 응답이 자동으로 제공됩니다. 러너는 임시 파일을 생성하며, 이 파일은 JOB_RESPONSE_FILE 환경 변수에서 참조됩니다. 이 파일은 모든 단계에 존재하며 정리 중에 자동으로 제거됩니다.

$ cat ${JOB_RESPONSE_FILE}
{"id": 123456, "token": "jobT0ken",...}