작업 스크립트에서 CI/CD 변수 사용하기

모든 CI/CD 변수는 작업 환경의 환경 변수로 설정돼요. 실행기(runner executor)의 셸 형식에 맞춰 작업 스크립트에서 변수를 사용하는 방법을 설명하는 문서예요.

Bash, PowerShell, Windows Batch 등 셸별 접근 문법과, 파싱 오류 방지, 변수 간 참조, 문자열 내 사용 등 실무에서 자주 쓰는 패턴을 옆에서 설명해 주는 방식으로 정리했어요.

출처: 문서

본문

모든 CI/CD 변수는 작업 환경의 환경 변수로 설정돼요. 각 환경의 셸에 대한 표준 형식을 사용해 작업 스크립트에서 변수를 사용할 수 있어요.

환경 변수에 접근하려면 러너 실행기의 셸에 맞는 문법을 사용하세요.

Bash 및 `sh` 사용

Bash, sh 및 유사한 셸에서 환경 변수에 접근하려면 CI/CD 변수 앞에 $를 붙이세요.

job_name:
  script:
    - echo "$CI_JOB_ID"

PowerShell 사용

Windows PowerShell 환경에서 변수에 접근하려면(시스템이 설정한 환경 변수 포함) 변수 이름 앞에 $env: 또는 $를 붙이세요.

job_name:
  script:
    - echo $env:CI_JOB_ID
    - echo $CI_JOB_ID
    - echo $env:PATH

Windows Batch 사용

Windows Batch에서 CI/CD 변수에 접근하려면 변수를 %로 감싸세요.

job_name:
  script:
    - echo %CI_JOB_ID%

지연 확장(delayed expansion)을 위해 변수를 !로 감쌀 수도 있어요. 공백이나 줄바꿈이 포함된 변수에는 지연 확장이 필요할 수 있어요.

job_name:
  script:
    - echo !ERROR_MESSAGE!

서비스 컨테이너에서

서비스 컨테이너는 CI/CD 변수를 사용할 수 있지만, 기본적으로는 .gitlab-ci.yml 파일에 저장된 변수에만 접근할 수 있어요. GitLab UI에서 추가된 변수는 서비스 컨테이너가 기본적으로 신뢰되지 않으므로 사용할 수 없어요.

UI 정의 변수를 서비스 컨테이너에서 사용할 수 있게 하려면 .gitlab-ci.yml에서 다른 변수에 다시 할당할 수 있어요.

variables:
  SA_PASSWORD_YAML_FILE: $SA_PASSWORD_UI

재할당된 변수는 원래 변수와 같은 이름이 될 수 없어요. 그렇지 않으면 확장되지 않아요.

파싱 오류 방지

YAML 및 셸 파싱 오류를 방지하려면 스크립트 명령과 변수 값을 인용하세요.

콜론(:)이 포함된 명령은 YAML이 키-값 쌍으로 해석하지 않도록 전체 명령을 인용하세요.
```
job_name:
  script:
    - 'echo "Status: Complete"'  # Single quotes prevent YAML colon parsing
```

값에 공백이나 특수 문자가 포함될 수 있는 변수는 인용하세요.

job_name:
  script:
    - echo "$FILE_PATH"          # Quote if FILE_PATH might have spaces

변수를 별도의 셸 인수로 확장하려면 인용을 피하세요.

job_name:
  variables:
    COMPILE_FLAGS: "-Wall -Werror -O2"
  script:
    - gcc $COMPILE_FLAGS main.c  # Expands to: gcc -Wall -Werror -O2 main.c

`script` 섹션의 환경 변수를 `artifacts`나 `cache`로 전달

$GITLAB_ENV를 사용해 script 섹션에서 정의한 환경 변수를 artifacts나 cache 키워드에서 사용하세요. 예를 들어:

build-job:
  stage: build
  script:
    - echo "ARCH=$(arch)" >> $GITLAB_ENV
    - touch some-file-$(arch)
  artifacts:
    paths:
      - some-file-$ARCH

하나의 변수에 여러 값 저장하기

값의 배열인 CI/CD 변수는 만들 수 없지만, 셸 스크립팅 기법을 사용하면 비슷하게 동작하게 할 수 있어요.

예를 들어 공백으로 구분된 여러 값을 변수에 저장한 다음 스크립트로 값들을 반복할 수 있어요.

job1:
  variables:
    FOLDERS: src test docs
  script:
    - |
      for FOLDER in $FOLDERS
        do
          echo "The path is root/${FOLDER}"
        done

다른 변수 안에서 CI/CD 변수 사용하기

다른 변수 안에서 변수를 사용할 수 있어요.

job:
  variables:
    FLAGS: '-al'
    LS_CMD: 'ls "$FLAGS"'
  script:
    - 'eval "$LS_CMD"'  # Executes 'ls -al'

문자열의 일부로

문자열의 일부로 변수를 사용할 수 있어요. 변수를 중괄호({})로 감싸면 변수 이름과 주변 텍스트를 구분하는 데 도움이 돼요. 중괄호가 없으면 인접한 텍스트가 변수 이름의 일부로 해석돼요. 예를 들어:

job:
  variables:
    FLAGS: '-al'
    DIR: 'path/to/directory'
    LS_CMD: 'ls "$FLAGS"'
    CD_CMD: 'cd "${DIR}_files"'
  script:
    - 'eval "$LS_CMD"'  # Executes 'ls -al'
    - 'eval "$CD_CMD"'  # Executes 'cd path/to/directory_files'

CI/CD 변수에서 `$` 문자 사용하기

$ 문자가 다른 변수의 시작으로 해석되지 않게 하려면 $$를 대신 사용하세요.

job:
  variables:
    FLAGS: '-al'
    LS_CMD: 'ls "$FLAGS" $$TMP_DIR'
  script:
    - 'eval "$LS_CMD"'  # Executes 'ls -al $TMP_DIR'

이는 CI/CD 변수를 다운스트림 파이프라인으로 전달할 때는 동작하지 않아요.

더 알아보기

변수를 정의하는 다양한 방법과 우선순위를 이해하고 싶다면 CI/CD 변수 문서를 살펴보세요. 파이프라인 전체에 변수를 전달하는 dotenv 방식도 함께 익히면 복잡한 파이프라인을 다룰 때 유용해요.

작업 스크립트에서 CI/CD 변수 사용하기