변수를 사용할 수 있는 위치

변수를 사용할 수 있는 위치

CI/CD 변수 문서에서 설명했듯이, GitLab에는 정의할 수 있는 변수가 아주 많아요. 어떤 변수는 모든 GitLab CI/CD 기능에서 쓸 수 있지만, 어떤 변수는 다소 제한돼요. 이 문서는 어떤 유형의 변수를 어디에서 어떻게 사용할 수 있는지 정리해 줘요.

출처: 문서

본문

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

변수 사용 위치

정의한 변수는 다음 파일에서 사용할 수 있어요.

  • GitLab에서, .gitlab-ci.yml 파일
  • GitLab Runner에서, config.toml 파일

.gitlab-ci.yml 파일

정의 확장 가능? 확장 위치 설명
after_script 예 스크립트 실행 셸 변수 확장은 실행 셸 환경에서 이뤄져요.
artifacts:name 예 Runner 변수 확장은 GitLab Runner의 내부 변수 확장 메커니즘으로 이뤄져요.
artifacts:paths 예 Runner 변수 확장은 GitLab Runner의 내부 변수 확장 메커니즘으로 이뤄져요.
artifacts:exclude 예 Runner 변수 확장은 GitLab Runner의 내부 변수 확장 메커니즘으로 이뤄져요.
before_script 예 스크립트 실행 셸 변수 확장은 실행 셸 환경에서 이뤄져요.
cache:key 예 Runner 변수 확장은 GitLab Runner의 내부 변수 확장 메커니즘으로 이뤄져요.
cache:paths 예 Runner 변수 확장은 GitLab Runner의 내부 변수 확장 메커니즘으로 이뤄져요.
cache:policy 예 Runner 변수 확장은 GitLab Runner의 내부 변수 확장 메커니즘으로 이뤄져요.
environment:name 예 GitLab environment:url과 비슷하지만, 변수 확장 시 다음은 지원하지 않아요. CI_ENVIRONMENT_* 변수, 지속 변수(Persisted variables).
environment:url 예 GitLab 변수 확장은 GitLab의 내부 변수 확장 메커니즘으로 이뤄져요. 잡에 정의된 모든 변수(프로젝트/그룹 변수, .gitlab-ci.yml의 변수, 트리거 변수, 파이프라인 스케줄 변수)가 지원돼요. GitLab Runner config.toml에 정의된 변수와 잡의 script에서 만든 변수는 지원되지 않아요.
environment:deployment_tier 예 GitLab environment:url과 비슷하지만, 변수 확장 시 다음은 지원하지 않아요. CI_ENVIRONMENT_* 변수, 지속 변수.
environment:auto_stop_in 예 GitLab 변수 확장은 GitLab의 내부 변수 확장 메커니즘으로 이뤄져요. 치환되는 변수의 값은 사람이 읽을 수 있는 자연어 형식의 시간 기간이어야 해요. 자세한 내용은 지원 값을 참고해요.
environment:kubernetes:agent 예 GitLab environment:url과 비슷하지만, 변수 확장 시 다음은 지원하지 않아요. CI_ENVIRONMENT_* 변수, 지속 변수.
environment:kubernetes:flux_resource_path 예 GitLab environment:url과 비슷하지만, 변수 확장 시 다음은 지원하지 않아요. CI_ENVIRONMENT_* 변수, 지속 변수.
environment:kubernetes:namespace 예 GitLab environment:url과 비슷하지만, 변수 확장 시 다음은 지원하지 않아요. CI_ENVIRONMENT_* 변수, 지속 변수.
id_tokens:aud 예 GitLab 변수 확장은 GitLab의 내부 변수 확장 메커니즘으로 이뤄져요.
image 예 Runner 변수 확장은 GitLab Runner의 내부 변수 확장 메커니즘으로 이뤄져요.
include 예 GitLab 변수 확장은 GitLab의 내부 변수 확장 메커니즘으로 이뤄져요. 지원되는 변수에 대한 자세한 내용은 include에서 변수 사용을 참고해요.
resource_group 예 GitLab environment:url과 비슷하지만, 변수 확장 시 다음은 지원하지 않아요. CI_ENVIRONMENT_URL, 지속 변수.
rules:changes 아니요 GitLab 변수 확장은 GitLab의 내부 변수 확장 메커니즘으로 이뤄져요.
rules:changes:compare_to 아니요 GitLab 변수 확장은 GitLab의 내부 변수 확장 메커니즘으로 이뤄져요.
rules:exists 아니요 GitLab 변수 확장은 GitLab의 내부 변수 확장 메커니즘으로 이뤄져요.
rules:if 아니요 해당 없음 변수는 $variable 형태여야 해요. 다음은 지원하지 않아요. CI_ENVIRONMENT_SLUG 변수, 지속 변수.
script 예 스크립트 실행 셸 변수 확장은 실행 셸 환경에서 이뤄져요.
services:name 예 Runner 변수 확장은 GitLab Runner의 내부 변수 확장 메커니즘으로 이뤄져요.
tags 예 GitLab 변수 확장은 GitLab의 내부 변수 확장 메커니즘으로 이뤄져요.
trigger 및 trigger:project 예 GitLab 변수 확장은 GitLab의 내부 변수 확장 메커니즘으로 이뤄져요.
variables 예 GitLab/Runner 변수 확장은 먼저 GitLab의 내부 변수 확장 메커니즘으로 이뤄지고, 그다음 인식되지 않거나 사용할 수 없는 변수는 GitLab Runner의 내부 변수 확장 메커니즘으로 확장돼요.
workflow:name 예 GitLab 변수 확장은 GitLab의 내부 변수 확장 메커니즘으로 이뤄져요. workflow에서 사용할 수 있는 모든 변수가 지원돼요. 프로젝트/그룹 변수. 전역 variables와 workflow:rules:variables(규칙이 일치할 때). 상위 파이프라인에서 상속받은 변수. 트리거에서 온 변수. 파이프라인 스케줄에서 온 변수. GitLab Runner config.toml에 정의된 변수, 잡에 정의된 변수, 지속 변수는 지원되지 않아요.

config.toml 파일

정의 확장 가능? 설명
runners.environment 예 변수 확장은 GitLab Runner의 내부 변수 확장 메커니즘으로 이뤄져요.
runners.kubernetes.pod_labels 예 변수 확장은 GitLab Runner의 내부 변수 확장 메커니즘으로 이뤄져요.
runners.kubernetes.pod_annotations 예 변수 확장은 GitLab Runner의 내부 변수 확장 메커니즘으로 이뤄져요.

config.toml에 대한 자세한 내용은 고급 구성을 참고해요.

확장 메커니즘 (Expansion mechanisms)

변수는 다음 경로를 통해 확장될 수 있어요.

  • GitLab에서, 러너가 잡을 받기 전
  • GitLab Runner에서, 잡을 처리할 때
  • 실행 셸 환경에서, 스크립트 실행 중

GitLab 내부 변수 확장 메커니즘

확장되는 부분은 $variable, ${variable}, %variable% 형태여야 해요. 각 형태는 잡을 처리하는 OS/셸과 무관하게 같은 방식으로 처리돼요. 어떤 러너가 잡을 받기 전에 GitLab에서 확장이 이뤄지기 때문이에요.

중첩 변수 확장

GitLab은 잡 변수 값을 러너로 보내기 전에 재귀적으로 확장해요. 예를 들어 다음 시나리오에서:

- BUILD_ROOT_DIR: '${CI_BUILDS_DIR}'
- OUT_PATH: '${BUILD_ROOT_DIR}/out'
- PACKAGE_PATH: '${OUT_PATH}/pkg'

러너는 유효하고 완전한 형태의 경로를 받아요. 예를 들어 ${CI_BUILDS_DIR}가 /output이라면 PACKAGE_PATH는 /output/out/pkg가 돼요.

사용할 수 없는 변수에 대한 참조는 그대로 남아요. 이 경우 러너가 런타임에 변수 값을 확장하려고 시도해요. 예를 들어 CI_BUILDS_DIR 같은 변수는 러너만 런타임에 알 수 있어요.

GitLab Runner 내부 변수 확장 메커니즘

  • 지원: 프로젝트/그룹 변수, .gitlab-ci.yml 변수, config.toml 변수, 트리거·파이프라인 스케줄·수동 파이프라인에서 온 변수.
  • 지원하지 않음: 스크립트 안에서 정의한 변수(예: export MY_VARIABLE="test").

러너는 변수 확장에 Go의 os.Expand() 메서드를 사용해요. 즉 $variable과 ${variable}로 정의된 변수만 처리해요. 또한 확장은 한 번만 이뤄지므로, 중첩 변수는 정의 순서와 GitLab에서 중첩 변수 확장이 활성화되어 있는지에 따라 동작할 수도, 안 할 수도 있어요.

아티팩트와 캐시 업로드의 경우 러너는 Go의 os.Expand() 대신 mvdan.cc/sh/v3/expand를 변수 확장에 사용해요. mvdan.cc/sh/v3/expand가 파라미터 확장을 지원하기 때문이에요.

실행 셸 환경 (Execution shell environment)

실행 셸 환경은 script 실행 중에 일어나는 확장 단계예요. 동작은 사용되는 셸(bash, sh, cmd, PowerShell)에 따라 달라져요. 예를 들어 잡의 script에 echo $MY_VARIABLE-${MY_VARIABLE_2} 줄이 있으면 bash/sh에서는 제대로 처리되지만(변수 정의 여부에 따라 빈 문자열이나 값을 남김), Windows의 cmd나 PowerShell에서는 동작하지 않아요. 이 셸들은 다른 변수 문법을 사용하기 때문이에요.

지원:

  • script는 셸의 기본 변수(예: 모든 bash/sh 셸에 존재해야 하는 $PATH)와 GitLab CI/CD가 정의한 모든 변수(프로젝트/그룹 변수, .gitlab-ci.yml 변수, config.toml 변수, 트리거·파이프라인 스케줄 변수)를 사용할 수 있어요.
  • script는 앞 줄에서 정의한 모든 변수도 사용할 수 있어요. 예를 들어 export MY_VARIABLE="test"로 변수를 정의하면: before_script에서 정의하면 before_script의 이후 줄과 관련 script의 모든 줄에서 동작해요. script에서 정의하면 script의 이후 줄에서 동작해요. after_script에서 정의하면 after_script의 이후 줄에서 동작해요.

after_script 스크립트의 경우 다음만 가능해요.

  • 같은 after_script 섹션에서 스크립트보다 먼저 정의된 변수만 사용할 수 있어요.
  • before_script와 script에서 정의한 변수는 사용할 수 없어요.

이런 제한은 after_script 스크립트가 분리된 셸 컨텍스트에서 실행되기 때문이에요.

지속 변수 (Persisted variables)

일부 사전 정의 변수는 지속(persisted) 변수라고 불러요. 지속 변수는:

파이프라인 트리거 잡은 잡 수준의 지속 변수를 사용할 수 없지만, 파이프라인 수준의 지속 변수는 사용할 수 있어요.

일부 지속 변수는 토큰을 포함하고 있어서 보안상 이유로 일부 정의에서 사용할 수 없어요.

파이프라인 수준 지속 변수:

  • CI_PIPELINE_ID
  • CI_PIPELINE_URL

잡 수준 지속 변수:

  • CI_DEPLOY_PASSWORD
  • CI_DEPLOY_USER
  • CI_JOB_ID
  • CI_JOB_STARTED_AT
  • CI_JOB_TOKEN
  • CI_JOB_URL
  • CI_PIPELINE_CREATED_AT
  • CI_REGISTRY_PASSWORD
  • CI_REGISTRY_USER
  • CI_REPOSITORY_URL

환경 범위를 가진 변수

환경 범위(environment scope)로 정의된 변수는 지원돼요. review/staging/* 범위에 $STAGING_SECRET 변수가 정의되어 있다면, 다음 잡은 일치하는 변수 표현식을 기반으로 동적 환경을 사용해 만들어져요.

my-job:
  stage: staging
  environment:
    name: review/$CI_JOB_STAGE/deploy
  script:
    - 'deploy staging'
  rules:
    - if: $STAGING_SECRET == 'something'

더 알아보기

변수의 종류와 정의 방법은 CI/CD 변수 문서에서, 각 키워드의 세부 문법은 YAML 문법 문서에서 확인할 수 있어요. rules의 변수 표현식과 함께 사용하면 환경별로 동작을 세밀하게 나눌 수 있어요.