스크립트 및 작업 로그

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

script 섹션에서 특별한 구문을 사용하여 다음을 수행할 수 있습니다:

script에서 특수 문자 사용

가끔, script 명령은 반드시 홑따옴표나 겹따옴표로 감싸져야 할 때가 있습니다.
예를 들어, 콜론(:)을 포함하는 명령은 반드시 홑따옴표(')로 감싸야 합니다.
YAML 파서는 “key: value” 쌍으로 해석하는 것이 아니라 문자열로 해석해야 합니다.

예를 들어, 다음 스크립트에는 콜론이 사용됩니다: yaml job: script: - curl --request POST --header 'Content-Type: application/json' "https://gitlab/api/v4/projects" 유효한 YAML로 간주되려면 전체 명령을 홑따옴표로 감싸야 합니다. 명령이 이미 홑따옴표를 사용하고 있다면 가능하다면 이를 겹따옴표(")로 변경해야 합니다: yaml job: script: - 'curl --request POST --header "Content-Type: application/json" "https://gitlab/api/v4/projects"' 이 CI Lint 도구를 사용하여 구문이 유효한지 확인할 수 있습니다.

또한, 다음과 같은 문자를 사용할 때 주의하세요:

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

0이 아닌 종료 코드 무시

스크립트 명령이 0이 아닌 종료 코드를 반환하면 작업이 실패하고 추가 명령이 실행되지 않습니다.
이 동작을 피하려면 종료 코드를 변수에 저장하세요: yaml job: script: - false || exit_code=$? - if [ $exit_code -ne 0 ]; then echo "이전 명령이 실패했습니다"; fi;

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

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

  • before_script을 default로 사용하여 모든 작업의 script 명령 이전에 실행될 기본 명령어 배열을 정의합니다.
  • after_script을 default로 사용하여 작업이 완료되거나 취소된 후에 실행될 기본 명령어 배열을 정의합니다.

작업에서 다른 값을 정의하여 기본값을 무시할 수 있습니다. 기본값을 무시하려면 before_script: [] 또는 after_script: []을 사용하세요: ```yaml 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 명령 건너뛰기

after_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

긴 명령어 분할

| (literal) 및 > (folded) YAML 여러 줄 블록 스칼라 지시자를 사용하여 긴 명령어를 여러 줄로 나눌 수 있습니다.
경고: 여러 명령어가 하나의 명령어 문자열로 결합되면 마지막 명령어의 실패 또는 성공만 보고됩니다.
이는 이전 명령의 실패가 버그로 인해 무시되기 때문입니다.
이를 해결하기 위해 각 명령을 별도의 script 항목으로 실행하거나 각 명령 문자열에 exit 1 명령을 추가하세요.

| (literal) YAML 여러 줄 블록 스칼라 지시자를 사용하여 작업 설명의 script 섹션에서 여러 줄에 걸쳐 명령을 작성할 수 있습니다.
각 줄은 별도의 명령으로 처리됩니다. 작업 로그에서 첫 번째 명령만 반복되지만 추가 명령은 여전히 실행됩니다: yaml job: script: - | echo "첫 번째 명령 행." echo "두 번째 명령 행." echo "세 번째 명령 행."

위의 예제는 작업 로그에서 다음과 같이 표시됩니다: 

$ echo 첫 번째 명령 행 # 줄바꿈된 명령문
첫 번째 명령 행
두 번째 명령 행.
세 번째 명령 행.

> (folded) YAML 여러 줄 블록 스칼라 지시자는 섹션 사이의 빈 줄을 새 명령의 시작으로 처리합니다: ```yaml job: script: - > echo “첫 번째 몸령 행 두 번째 줄로 나눠집니다.” 

  echo "두 번째 명령 행." ```

이것은 > 또는 | 블록 스칼라 지시자 없이 여러 줄 명령을 결합할 때의 동작과 유사합니다: ```yaml job: script: - echo “첫 번째 명령 행 두 번째 줄로 나눠집니다.” 

  echo "두 번째 몸령 행." ```

위의 두 가지 예제는 작업 로그에서 다음과 같이 표시됩니다: shell $ echo 첫 번째 명령 행 두 번째 줄로 나눠집니다 # 줄바꿈된 명령문 첫 번째 명령 행 두 번째 줄로 나눠집니다. 두 번째 몸령 행.

> 또는 | 블록 스칼라 지시자를 생략하면 GitLab은 비어 있지 않은 줄을 결합하여 명령을 형성합니다. 줄들이 연결될 수 있도록 확인하세요.

Shell here documents는 | 및 > 연산자와 함께 작동합니다. 아래 예제는 소문자 문자를 대문자로 변환합니다: yaml job: script: - | tr a-z A-Z << END_TEXT one two three four five six END_TEXT

결과는 다음과 같습니다: shell $ tr a-z A-Z << END_TEXT # 줄바꿈된 명령문 ONE TWO THREE FOUR FIVE SIX

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

스크립트 출력물은 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 16.5에서 GitLab Runner 기능 플래그, FF_SCRIPT_SECTIONS 뒤에 있는 여러 줄 명령 bash 셸 출력물 지원 잡 로그는 확장되거나 축소될 수 있는 섹션으로 나눠집니다. 각 섹션은 지속 시간을 표시합니다.

다음 예제에서:

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

축소 가능한 섹션

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

수동으로 GitLab이 축소 가능한 섹션을 제한하는 데 사용하는 특별한 코드를 출력하여 잡 로그의 축소 가능한 섹션을 만들 수 있습니다:

  • 섹션 시작 마커: \e[0Ksection_start:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K + TEXT_OF_SECTION_HEADER
  • 섹션 끝 마커: \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[0KHeader of the 1st collapsible section"
    - 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: 렌더링(색이 입힌)된 작업 로그에 섹션 표시를 표시하지 않도록 하는 이스케이프 시퀀스. 그들은 작업 로그의 완전한 원본을 보여주는 상단 오른쪽 코너의 전체 원본 표시 선택()으로 액세스할 때 표시됩니다.
    • \r: 캐리지 리턴(커서를 줄의 시작으로 되돌립니다).
    • \e[0K: 커서 위치부터 줄 끝까지의 라인을 지우는 ANSI 이스케이프 코드. (\e[K만으로는 작동하지 않으며, 0을 포함해야 합니다).

샘플 원시 작업 로그: 

\e[0Ksection_start:1560896352:my_first_section\r\e[0KHeader of the 1st collapsible section
이 줄은 축소됐을 때 숨겨져야 합니다
\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" "Header of the 1st collapsible 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 + TEXT_OF_SECTION_HEADER
  • 섹션 종료 표시기 (변경되지 않음): \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[0KHeader of the 1st collapsible section"
    - echo '작업 로그를 로드한 후에는 이 줄이 자동으로 숨겨질 것입니다'
    - echo -e "\e[0Ksection_end:`date +%s`:my_first_section\r\e[0K"

문제 해결

:을 사용하는 스크립트에서 구문이 잘못되었습니다

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

  • 구문이 잘못되었습니다
  • 스크립트 구성은 문자열이거나 최대 10단계 깊이의 중첩 배열이어야 합니다

예를 들어, 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 키워드로 정의한다고 생각하고 구문이 잘못되었습니다 오류가 발생합니다.

콜론을 포함하는 명령어를 사용하려면 전체 명령어를 하나의 따옴표로 감싸야 합니다. 이미 있는 단일 따옴표(')를 쌍 따옴표(")로 변경해야 할 수도 있습니다. 

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과 값이 ansi인 CI/CD 변수를 추가합니다.

after_script 섹션 실행이 일찍 중지되고 잘못된 $CI_JOB_STATUS 값

GitLab Runner 16.9.0에서 16.11.0까지: