스크립트 및 작업 로그

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

script 섹션에서 다음과 같은 특별한 문법을 사용할 수 있습니다:

script와 함께 특수 문자 사용하기

가끔 script 명령은 작은따옴표 또는 큰따옴표로 감싸야 합니다.
예를 들어, 콜론(:)을 포함하는 명령은 작은따옴표(')로 감싸야 합니다.
YAML 파서는 텍스트를 “키: 값” 쌍이 아닌 문자열로 해석해야 합니다.

예를 들어, 이 스크립트는 콜론을 사용합니다:

job:
  script:
    - curl --request POST --header 'Content-Type: application/json' "https://gitlab/api/v4/projects"

유효한 YAML로 간주되려면 전체 명령을 작은따옴표로 감싸야 합니다.
명령이 이미 작은따옴표를 사용하고 있다면 가능한 경우 큰따옴표(")로 변경해야 합니다:

job:
  script:
    - 'curl --request POST --header "Content-Type: application/json" "https://gitlab/api/v4/projects"'

CI Lint 도구를 사용하여 문법이 유효한지 확인할 수 있습니다.

다음 문자들을 사용할 때도 주의하세요:

  • {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, `.

비영(非零) 종료 코드 무시하기

스크립트 명령이 0이 아닌 종료 코드를 반환하면 작업이 실패하고 추가 명령이 실행되지 않습니다.

이런 동작을 피하기 위해 종료 코드를 변수에 저장하세요:

job:
  script:
    - false || exit_code=$?
    - if [ $exit_code -ne 0 ]; then echo "이전 명령이 실패했습니다"; fi;

모든 작업에 대한 기본 before_script 또는 after_script 설정하기

before_script 및 after_script를 사용하여
default와 함께 사용할 수 있습니다:

  • 모든 작업의 script 명령 전에 실행되어야 할 기본 명령 배열을 정의하기 위해 before_script와 default를 사용하세요.
  • 모든 작업이 완료되거나 취소된 후 실행될 기본 명령 배열을 정의하기 위해 after_script와 default를 사용하세요.

작업에서 다른 기본값을 정의하여 기본값을 덮어쓸 수 있습니다.
기본값을 무시하려면 before_script: [] 또는 after_script: []를 사용하세요:

default:
  before_script:
    - echo "모든 작업의 기본적으로 이 `before_script`를 실행하세요."
  after_script:
    - echo "모든 작업의 기본적으로 이 `after_script`를 실행하세요."

job1:
  script:
    - echo "이 스크립트 명령은 기본 `before_script` 이후에 실행됩니다,"
    - echo "그리고 기본 `after_script` 이전에 실행됩니다."

job2:
  before_script:
    - echo "기본 `before_script` 대신 이 스크립트를 실행하세요."
  script:
    - echo "이 스크립트는 작업의 `before_script` 이후에 실행됩니다,"
    - echo "그러나 작업은 기본 `after_script`를 사용하지 않습니다."
  after_script: []

작업이 취소될 경우 after_script 명령 건너뛰기

  • GitLab 17.0에서 도입됨 flag ci_canceling_status와 함께. 기본적으로 활성화됨. GitLab Runner 버전 16.11.1 필요.
  • GitLab 17.3에서 일반 제공. 기능 플래그 ci_canceling_status 제거됨.

after_script 명령은 작업의 before_script 또는 script 섹션이 실행되는 동안 작업이 취소되면 실행됩니다.

UI에서 작업의 상태는 after_script가 실행되는 동안 canceling이며, after_script 명령이 완료된 후에 canceled로 변경됩니다. $CI_JOB_STATUS 사전 정의 변수가 after_script 명령이 실행되는 동안 canceled 값을 가집니다.

작업을 취소한 후 after_script 명령이 실행되지 않도록 하려면 after_script 섹션을 다음과 같이 구성하십시오:

  1. after_script 섹션의 시작 부분에서 $CI_JOB_STATUS 사전 정의 변수를 확인합니다.

  2. 값이 canceled이면 조기에 실행을 종료합니다.

예를 들어:

job1:
  script:
    - my-script.sh
  after_script:
    - if [ "$CI_JOB_STATUS" == "canceled" ]; then exit 0; fi
    - my-after-script.sh

긴 명령 분할

긴 명령을 | (리터럴) 및 > (접는) YAML 다중 블록 스칼라 지시자를 사용하여 여러 줄 명령으로 분할하여 가독성을 향상시킬 수 있습니다.

경고: 여러 명령이 하나의 명령 문자열로 결합된 경우, 마지막 명령의 실패 또는 성공만 보고됩니다.

이전 명령의 실패는 버그로 인해 무시됩니다.

이를 해결하기 위해 각 명령을 별도의 script 항목으로 실행하거나 각 명령 문자열에 exit 1 명령을 추가하십시오.

| (리터럴) YAML 다중 블록 스칼라 지시자를 사용하여 작업 설명의 script 섹션에 여러 줄로 명령을 작성할 수 있습니다.

각 줄은 별도의 명령으로 처리됩니다.

첫 번째 명령만 작업 로그에 반복되지만 추가 명령은 여전히 실행됩니다:

job:
  script:
    - |
      echo "첫 번째 명령줄."
      echo "두 번째 명령줄."
      echo "세 번째 명령줄."

위 예제는 작업 로그에 다음과 같이 렌더링됩니다:

$ echo 첫 번째 명령줄. # collapsed multiline command
첫 번째 명령줄.
두 번째 명령줄.
세 번째 명령줄.

> (접는) YAML 다중 블록 스칼라 지시자는 섹션 사이의 빈 줄을 새 명령의 시작으로 처리합니다:

job:
  script:
    - >
      echo "첫 번째 명령줄
      두 줄로 나누어져 있습니다."

      echo "두 번째 명령줄."

이는 > 또는 | 블록 스칼라 지시자가 없는 다중 명령과 유사하게 동작합니다:

job:
  script:
    - echo "첫 번째 명령줄
      두 줄로 나누어져 있습니다."

      echo "두 번째 명령줄."

위 두 예제 모두 작업 로그에 다음과 같이 렌더링됩니다:

$ echo 첫 번째 명령줄 두 줄로 나누어져 있습니다. # collapsed multiline command
첫 번째 명령줄 두 줄로 나누어져 있습니다.
두 번째 명령줄.

> 또는 | 블록 스칼라 지시자를 생략하면, GitLab은 비어 있지 않은 줄을 연결하여 명령을 형성합니다. 연결될 수 있도록 줄이 실행 가능해야 합니다.

쉘 여기 문서는 | 및 > 연산자와 함께 작동합니다. 아래 예제는 소문자를 대문자로 변환합니다:

job:
  script:
    - |
      tr a-z A-Z << END_TEXT
        하나 둘 셋
        넷 다섯 여섯
      END_TEXT

결과는 다음과 같습니다:

$ tr a-z A-Z << END_TEXT # collapsed multiline command
  하나 둘 셋
  넷 다섯 여섯

스크립트 출력에 색상 코드 추가

스크립트 출력은 ANSI 이스케이프 코드를 사용하거나, ANSI 이스케이프 코드를 출력하는 명령 또는 프로그램을 실행하여 색상을 추가할 수 있습니다.

예를 들어, Bash에서 색상 코드 사용하기:

job:
  script:
    - echo -e "\e[31m이 텍스트는 빨간색,\e[0m 그러나 이 텍스트는 아닙니다\e[31m 하지만 이 텍스트는 다시 빨간색입니다."

Shell 환경 변수 또는 CI/CD 변수에 색상 코드를 정의할 수 있으며, 이는 명령을 더 읽기 쉽게 만들고 재사용이 가능하게 합니다.

예를 들어, 위와 동일한 예제를 사용하고 before_script에 정의된 환경 변수를 사용하는 경우:

job:
  before_script:
    - TXT_RED="\e[31m" && TXT_CLEAR="\e[0m"
  script:
    - echo -e "${TXT_RED}이 텍스트는 빨간색입니다,${TXT_CLEAR} 그러나 이 부분은 아닙니다${TXT_RED} 하지만 이 부분은 다시 빨간색입니다."
    - echo "이 텍스트는 색상이 없습니다."

또는 PowerShell 색상 코드 사용하기:

job:
  before_script:
    - $esc="$([char]27)"; $TXT_RED="$esc[31m"; $TXT_CLEAR="$esc[0m"
  script:
    - Write-Host $TXT_RED"이 텍스트는 빨간색입니다,"$TXT_CLEAR" 그러나 이 텍스트는 아닙니다"$TXT_RED" 하지만 이 텍스트는 다시 빨간색입니다."
    - Write-Host "이 텍스트는 색상이 없습니다."

작업 로그 섹션 확장 및 축소

작업 로그는 축소하거나 확장할 수 있는 섹션으로 나뉩니다. 각 섹션은 지속 시간을 표시합니다.

다음 예제에서:

  • 세 개의 섹션이 축소되어 있고 확장할 수 있습니다.
  • 세 개의 섹션이 확장되어 있고 축소할 수 있습니다.

축소 가능한 섹션

사용자 지정 축소 가능 섹션

수동으로 GitLab이 축소 가능한 섹션을 구분하는 데 사용하는 특별한 코드를 출력하여 작업 로그에서 축소 가능한 섹션을 생성할 수 있습니다:

  • 섹션 시작 마커: \e[0Ksection_start:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K + 섹션 헤더의 텍스트
  • 섹션 종료 마커: \e[0Ksection_end:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K

이 코드를 CI 구성의 스크립트 섹션에 추가해야 합니다. 예를 들어 echo를 사용하는 경우:

job1:
  script:
    - echo -e "\e[0Ksection_start:`date +%s`:my_first_section\r\e[0K첫 번째 축소 가능한 섹션의 헤더"
    - echo '이 줄은 축소 시 숨겨져야 합니다.'
    - echo -e "\e[0Ksection_end:`date +%s`:my_first_section\r\e[0K"

이스케이프 구문은 실행자가 사용하는 셸에 따라 다를 수 있습니다. 예를 들어 Zsh를 사용하는 경우, 특수 문자를 \\e 또는 \\r로 이스케이프해야 할 수 있습니다.

위의 예에서:

  • date +%s: Unix 타임스탬프를 생성하는 명령(예: 1560896352).
  • my_first_section: 섹션에 지정된 이름. 이름은 문자, 숫자 및 _, ., 또는 - 문자로만 구성할 수 있습니다.
  • \r\e[0K: 섹션 마커가 렌더링된 (색상 있는) 작업 로그에 표시되지 않도록 방지하는 이스케이프 시퀀스입니다. 원시 작업 로그를 보려면 작업 로그의 오른쪽 상단 모서리에 있는 Show complete raw ( )를 선택하여 액세스합니다.
    • \r: 캐리지 리턴 (커서를 줄의 시작으로 되돌림).
    • \e[0K: 커서 위치에서 줄 끝까지를 지우는 ANSI 이스케이프 코드입니다. (\e[K만으로는 작동하지 않습니다; 0이 포함되어야 합니다).

샘플 원시 작업 로그:

\e[0Ksection_start:1560896352:my_first_section\r\e[0K첫 번째 축소 가능한 섹션의 헤더
이 줄은 축소 시 숨겨져야 합니다.
\e[0Ksection_end:1560896353:my_first_section\r\e[0K

샘플 작업 콘솔 로그:

사용자 지정 축소 가능한 섹션

스크립트를 사용하여 접을 수 있는 섹션의 표시 개선하기

echo 문을 제거하여 작업 출력을 생성하는 섹션 마커를 삭제하려면, 작업 내용을 스크립트 파일로 이동하고 그 파일을 작업에서 호출할 수 있습니다:

  1. 섹션 헤더를 처리할 수 있는 스크립트를 만드세요. 예를 들면:

    # 섹션 시작을 위한 함수
function section_start () {
  local section_title="${1}"
  local section_description="${2:-$section_title}"

  echo -e "section_start:`date +%s`:${section_title}[collapsed=true]\r\e[0K${section_description}"
}

# 섹션 끝을 위한 함수
function section_end () {
  local section_title="${1}"

  echo -e "section_end:`date +%s`:${section_title}\r\e[0K"
}

# 섹션 생성
section_start "my_first_section" "첫 번째 접을 수 있는 섹션의 헤더"

echo "이 줄은 접었을 때 숨겨져야 합니다."

section_end "my_first_section"

# 필요에 따라 반복

  2. 스크립트를 .gitlab-ci.yml 파일에 추가하세요:

    job:
  script:
    - source script.sh

섹션 사전 접기

작업 로그가 자동으로 접을 수 있는 섹션을 접도록 하려면, 섹션 시작에 collapsed 옵션을 추가하세요. 섹션 이름 뒤와 \r 앞에 [collapsed=true]를 추가합니다. 섹션 종료 마커는 변경되지 않습니다:

  • [collapsed=true]가 포함된 섹션 시작 마커: \e[0Ksection_start:UNIX_TIMESTAMP:SECTION_NAME[collapsed=true]\r\e[0K + 섹션 헤더 텍스트
  • 섹션 종료 마커 (변경 없음): \e[0Ksection_end:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K

업데이트된 섹션 시작 텍스트를 CI 구성에 추가하세요. 예를 들어, echo를 사용할 때:

job1:
  script:
    - echo -e "\e[0Ksection_start:`date +%s`:my_first_section[collapsed=true]\r\e[0K첫 번째 접을 수 있는 섹션의 헤더"
    - echo '작업 로그 로딩 후 자동으로 숨겨져야 하는 이 줄'
    - echo -e "\e[0Ksection_end:`date +%s`:my_first_section\r\e[0K"

문제 해결

스크립트에서 : 사용 시 Syntax is incorrect

스크립트에서 콜론(:)을 사용하는 경우, GitLab은 다음과 같은 출력을 생성할 수 있습니다:

  • Syntax is incorrect
  • script config should be a string or a nested array of strings up to 10 levels deep

예를 들어, cURL 명령의 일부로 "PRIVATE-TOKEN: ${PRIVATE_TOKEN}"을 사용하는 경우:

pages-job:
  stage: deploy
  script:
    - curl --header 'PRIVATE-TOKEN: ${PRIVATE_TOKEN}' "https://gitlab.example.com/api/v4/projects"
  environment: production

YAML 파서는 :가 YAML 키워드를 정의한다고 생각하고 Syntax is incorrect 오류를 출력합니다.

콜론이 포함된 명령을 사용하려면 전체 명령을 단일 인용부호로 감싸야 합니다. 기존의 단일 인용부호(')를 이중 인용부호(")로 변경해야 할 수도 있습니다:

pages-job:
  stage: deploy
  script:
    - 'curl --header "PRIVATE-TOKEN: ${PRIVATE_TOKEN}" "https://gitlab.example.com/api/v4/projects"'
  environment: production

스크립트에서 &&를 사용할 때 작업이 실패하지 않음

단일 스크립트 줄에서 두 개의 명령을 결합하기 위해 &&를 사용하면,
하나의 명령이 실패했음에도 불구하고 작업이 성공으로 반환될 수 있습니다.
예를 들어:

job-does-not-fail:
  script:
    - invalid-command xyz && invalid-command abc
    - echo $?
    - echo "작업은 이미 실패했어야 하지만, 예상치 못하게 이 내용이 실행됩니다."

&& 연산자는 두 개의 명령이 실패했음에도 불구하고 종료 코드 0을 반환하며,
작업은 계속 실행됩니다. 명령 중 하나가 실패할 때 스크립트가 종료되도록 하려면,
전체 줄을 괄호로 묶어야 합니다:

job-fails:
  script:
    - (invalid-command xyz && invalid-command abc)
    - echo "작업은 이미 실패했으며, 이 내용은 실행되지 않습니다."

멀티라인 명령이 접힌 YAML 멀티라인 블록 스칼라로 유지되지 않음

긴 명령을 분할하기 위해 - > 접힌 YAML 멀티라인 블록 스칼라를 사용할 경우,
추가된 들여쓰기로 인해 줄이 개별 명령으로 처리됩니다.

예를 들어:

script:
  - >
    RESULT=$(curl --silent
      --header
        "Authorization: Bearer $CI_JOB_TOKEN"
      "${CI_API_V4_URL}/job"
    )

이것은 들여쓰기로 인해 줄 바꿈이 유지되어 실패합니다:

$ RESULT=$(curl --silent # 접힌 멀티라인 명령
curl: no URL specified!
curl: try 'curl --help' or 'curl --manual' for more information
/bin/bash: line 149: --header: command not found
/bin/bash: line 150: https://gitlab.example.com/api/v4/job: No such file or directory

다음 방법으로 해결할 수 있습니다:

  • 추가된 들여쓰기를 제거하기:

    script:
  - >
    RESULT=$(curl --silent
    --header
    "Authorization: Bearer $CI_JOB_TOKEN"
    "${CI_API_V4_URL}/job"
    )

  • 스크립트를 수정하여 추가 줄 바꿈이 처리되도록 하기, 예를 들어 쉘 줄 연속성을 사용하는 방법:

    script:
  - >
    RESULT=$(curl --silent \
      --header \
        "Authorization: Bearer $CI_JOB_TOKEN" \
      "${CI_API_V4_URL}/job")

작업 로그 출력 형식이 예상과 다르거나 예상치 못한 문자가 포함됨

때때로 작업 로그의 형식이 잘못 표시되며, 이는 TERM 환경 변수를 사용하여 색상 또는 포맷을 적용하는 도구와 관련이 있습니다.
예를 들어, mypy 명령어와 함께:

예제 출력

GitLab Runner는 컨테이너의 셸을 비대화식 모드에서 실행하므로,
셸의 TERM 환경 변수는 dumb으로 설정됩니다. 이러한 도구에 대한 형식을 수정하려면, 다음과 같이 할 수 있습니다:

  • 명령을 실행하기 전에 셸의 환경에서 TERM=ansi를 설정하기 위해 추가 스크립트 줄을 추가합니다.

  • TERM CI/CD 변수와 값 ansi를 추가합니다.

after_script 섹션 실행이 조기에 중지되고 잘못된 $CI_JOB_STATUS 값이 설정됨

GitLab Runner 16.9.0에서 16.11.0까지: