dotenv 변수를 특정 잡에 전달하기

dotenv 변수를 특정 잡에 전달하기

환경 변수를 다른 잡에 전달하려면 dotenv 파일을 사용해요. dotenv 파일은 .env 확장자를 가진 파일로, 환경 변수 키와 값의 목록을 저장해요. 예를 들어 sample.env 파일에서:

REVIEW_URL=review.example.com/123456
BUILD_VERSION=v1.0.0

dotenv 파일을 dotenv 리포트 아티팩트로 저장하면, 같은 파이프라인의 다른 잡이나 하위 파이프라인에 전달하거나 동적 환경 URL을 설정하는 데 사용할 수 있어요.

출처: 문서

본문

dotenv 변수는 다음과 같은 방식으로 사용할 수 있어요.

• 한 잡에서 값을 생성해 후속 잡에서 사용.
• 파이프라인 스테이지 간 계산된 값 전달.
• 배포 출력을 기반으로 동적 환경 URL 설정.
• 멀티 프로젝트 파이프라인 간 변수 공유.

dotenv 변수는 잡 script 섹션이나 러너에서 변수 확장을 지원하는 키워드에서 사용할 수 있어요. rules 섹션에서는 dotenv 변수를 사용할 수 없어요.

dotenv 변수는 .gitlab-ci.yml에 정의된 잡 변수와 기본 변수보다 우선순위가 높지만, 프로젝트, 그룹, 인스턴스 또는 파이프라인 변수보다는 높지 않아요.

dotenv 리포트에 같은 변수 이름이 여러 번 나타나면 마지막 값이 사용돼요.

이후 잡에 변수 전달하기

기본적으로 dotenv 변수는 이후 스테이지의 모든 잡에서 사용할 수 있어요. 잡 사이에 변수를 전달하려면:

1. 잡에서 VARIABLE_NAME=value 형식으로 변수가 들어 있는 파일(예: build.env)을 만들어요. 줄마다 변수 하나씩이에요.
2. 이 파일을 dotenv 리포트 아티팩트로 출력해요.
3. 이후 잡에서 스크립트에 변수를 사용해요.

예를 들어 build-job이 BUILD_VERSION=v1.0.0이 들어 있는 build.env를 만들면, test-job이 자동으로 환경 변수로 받아요.

build-job:
  stage: build
  script:
    - echo "BUILD_VERSION=v1.0.0" >> build.env
  artifacts:
    reports:
      dotenv: build.env

test-job:
  stage: test
  script:
    - echo "Testing version $BUILD_VERSION"  # Output: 'Testing version v1.0.0'

자격 증명, API 키, 토큰 같은 민감한 데이터는 dotenv 파일에 포함하지 마세요. 파이프라인 사용자가 dotenv 파일 내용에 접근할 수 있어요. 접근을 제한하려면 [artifacts:access](/ci/yaml/#artifactsaccess)를 사용해요.

어떤 잡이 dotenv 변수를 받을지 제어하기

어떤 잡이 dotenv 변수를 받을지 제어하려면 [dependencies](/ci/yaml/#dependencies) 또는 [needs](/ci/yaml/#needs) 키워드를 사용해요.

특정 잡에서 상속하기

dependencies를 사용해 특정 잡에게만 상속을 제한해요.

build-job1:
  stage: build
  script:
    - echo "BUILD_VERSION=v1.0.0" >> build.env
  artifacts:
    reports:
      dotenv: build.env

build-job2:
  stage: build
  script:
    - echo "This job has no dotenv artifacts"

test-job:
  stage: test
  script:
    - echo "$BUILD_VERSION"  # Output: 'v1.0.0'
  dependencies:
    - build-job1
    # build-job2 is not listed, so its artifacts are not inherited

dotenv 변수 제외하기

이름이 지정된 잡에서 dotenv 변수를 받지 않도록 하려면 artifacts: false와 함께 needs를 사용해요. 이렇게 하면 dotenv 변수뿐 아니라 해당 잡의 모든 아티팩트 다운로드가 차단돼요.

test-job:
  stage: test
  script:
    - echo "$BUILD_VERSION"  # Output: '' (empty)
  needs:
    - job: build-job1
      artifacts: false

이 예시의 [needs](/ci/yaml/#needs)는 잡이 build-job1이 완료되는 즉시 시작하게도 만들어요.

또는 빈 [dependencies](/ci/yaml/) 배열을 사용해 모든 업스트림 잡의 아티팩트 다운로드를 차단해요.

test-job:
  stage: test
  script:
    - echo "$BUILD_VERSION"  # Output: '' (empty)
  dependencies: []

하위 파이프라인에 변수 전달하기

dotenv 변수 상속으로 하위 파이프라인에 dotenv 변수를 전달할 수 있어요. 멀티 프로젝트 파이프라인에서 업스트림 잡에 dotenv 아티팩트를 만들고, 하위 잡에서 needs를 사용해 상속해요.

1. 변수를 .env 파일에 저장해요.
2. .env 파일을 dotenv 리포트 아티팩트로 저장해요.
3. 하위 파이프라인을 트리거해요.

build_vars:
  stage: build
  script:
    - echo "BUILD_VERSION=hello" >> build.env
  artifacts:
    reports:
      dotenv: build.env

deploy:
  stage: deploy
  trigger: my/downstream_project

하위 파이프라인에서 needs로 업스트림 잡의 아티팩트를 상속하도록 잡을 설정해요. 잡이 dotenv 변수를 받고 스크립트에서 BUILD_VERSION에 접근할 수 있게 돼요.

test:
  stage: test
  script:
    - echo $BUILD_VERSION
  needs:
    - project: my/upstream_project
      job: build_vars
      ref: master
      artifacts: true

동적 환경 URL 설정하기

외부 호스팅 플랫폼이 배포마다 URL을 동적으로 생성한다면, dotenv 변수를 사용해 배포 잡이 끝난 후 그 URL을 환경 URL로 설정할 수 있어요.

자세한 내용은 동적 환경 URL 설정을 참고해요.

복잡한 값 저장하기

dotenv 파일에는 다중 줄 값 제한, 이스케이프가 필요한 특수 문자 등 특정 형식 제한이 있어요. 값에 JSON이 포함되거나, 여러 줄에 걸치거나, 이스케이프가 필요한 문자가 포함된다면 dotenv 변수를 피하고 별도의 파일 아티팩트를 사용해요. 값 제약의 전체 목록은 형식 요구 사항을 참고해요.

대신에:

# Not supported
- echo 'CONFIG={"key": "value"}' >> build.env

별도의 아티팩트를 사용해요.

build-job:
  stage: build
  script:
    - echo '{"key": "value"}' > config.json
  artifacts:
    paths:
      - config.json

dotenv 파일 요구 사항

dotenv 파일은 다음 형식, 크기 및 변수 요구 사항을 충족해야 해요.

GitLab은 dotenv gem으로 dotenv 파일을 처리하지만, 원래 dotenv 규칙과 gem의 구현보다 추가적인 제한을 적용해요.

형식 요구 사항

• UTF-8 인코딩만 지원돼요.
• 파일에는 빈 줄이나 주석(#로 시작하는 줄)이 있을 수 없어요.
• 변수 이름은 ASCII 문자(A-Za-z), 숫자(0-9), 밑줄(_)만 포함할 수 있어요.
• dotenv 파일은 따옴표를 지원하지 않아요. 작은따옴표와 큰따옴표는 그대로 보존되며 이스케이프에 사용할 수 없어요.
• 값에는 줄바꿈이나 이스케이프가 필요한 다른 특수 문자를 포함할 수 없어요.
• 다중 줄 값은 지원되지 않아요. GitLab이 업로드 시 파일을 거부해요.
• 앞뒤 공백이나 줄바꿈 문자(\n)는 제거돼요.

크기와 변수 제한

제한	값
최대 파일 크기	5 KB
GitLab Self-Managed의 기본 최대 상속 변수 수	20

GitLab.com 티어 제한은 GitLab.com CI/CD 설정을 참고해요.

GitLab Self-Managed에서 이 제한을 변경하려면 CI/CD 제한을 참고해요.

더 알아보기

dotenv 아티팩트의 상세 설정은 artifacts:reports:dotenv 문서에서, 변수 간 우선순위 규칙은 CI/CD 변수 문서에서 확인할 수 있어요. 하위 파이프라인에 값을 넘기는 흐름이라면 하위 파이프라인 문서도 함께 보면 좋아요.