---

dotenv 변수를 특정 job에 전달하기#

  - 
  Tier: Free, Premium, Ultimate

- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

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

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

dotenv 파일을 dotenv 보고서 아티팩트로 저장하면, 동일한 파이프라인의 다른 job, 다운스트림 파이프라인에 전달하거나 동적 환경 URL을 설정하는 데 사용할 수 있습니다.

dotenv 변수는 다음과 같은 방법으로 사용할 수 있습니다:

• 한 job에서 값을 생성하고 이후 job에서 사용합니다.

• 파이프라인 Stage 간에 계산된 값을 전달합니다.

• 배포 출력에 따라 동적 환경 URL을 설정합니다.

• 멀티 프로젝트 파이프라인 간에 변수를 공유합니다.

job script 섹션에서 또는 러너에서 변수 확장을 지원하는 키워드와 함께 dotenv 변수를 사용할 수 있습니다. rules 섹션에서는 dotenv 변수를 사용할 수 없습니다.

dotenv 변수는 job 변수 및 .gitlab-ci.yml에 정의된 기본 변수보다 우선순위가 높지만, 프로젝트, 그룹, 인스턴스 또는 파이프라인 변수보다는 낮습니다.

dotenv 보고서에서 동일한 변수 이름이 여러 번 나타나면 마지막 값이 사용됩니다.

이후 job에 변수 전달하기#

기본적으로 dotenv 변수는 이후 Stage의 모든 job에서 사용할 수 있습니다. job 간에 변수를 전달하려면:

• job에서 VARIABLE_NAME=value 형식으로 변수가 담긴 파일(예: build.env)을 생성합니다. 한 줄에 변수 하나씩 작성합니다.

• 파일을 dotenv 보고서 아티팩트로 출력합니다.

• 이후 job에서 스크립트에 해당 변수를 사용합니다.

예를 들어, 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를 사용하세요.

dotenv 변수를 받을 job 제어하기#

dotenv 변수를 받을 job을 제어하려면 dependencies 또는 needs 키워드를 사용하세요.

특정 job에서만 상속받기#

dependencies를 사용하여 특정 job에서만 상속받도록 제한합니다:

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 변수 제외하기#

특정 job으로부터 dotenv 변수를 받지 않으려면 needs와 artifacts: false를 함께 사용하세요. 이 방법은 dotenv 변수뿐만 아니라 해당 job의 모든 아티팩트 다운로드를 차단합니다:

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

이 예시의 needs는 build-job1이 완료되는 즉시 job을 시작하게 합니다.

또는 빈 dependencies 배열을 사용하여 모든 업스트림 job으로부터의 아티팩트 다운로드를 차단할 수 있습니다:

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

다운스트림 파이프라인에 변수 전달하기#

dotenv 변수 상속을 통해 다운스트림 파이프라인에 dotenv 변수를 전달할 수 있습니다. 멀티 프로젝트 파이프라인에서는 업스트림 job에 dotenv 아티팩트를 생성하고 다운스트림 job에서 needs를 사용하여 상속받습니다:

• 변수를 .env 파일에 저장합니다.

• .env 파일을 dotenv 보고서 아티팩트로 저장합니다.

• 다운스트림 파이프라인을 트리거합니다.

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

deploy:
  stage: deploy
  trigger: my/downstream_project

다운스트림 파이프라인에서 needs를 사용하여 업스트림 job의 아티팩트를 상속받도록 job을 설정합니다. job은 dotenv 변수를 전달받아 스크립트에서 BUILD_VERSION에 접근할 수 있습니다:

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

동적 환경 URL 설정하기#

배포 job이 완료된 후 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 파일을 처리하기 위해 dotenv gem을 사용하지만, 원래 dotenv 규칙과 gem의 구현을 넘어서는 추가적인 제한을 적용합니다.

형식 요구사항#

• UTF-8 인코딩만 지원됩니다.

• 파일에 빈 줄이나 주석(#으로 시작하는 줄)을 포함할 수 없습니다.

• 변수 이름에는 ASCII 문자(A-Za-z), 숫자(0-9), 밑줄(_)만 사용할 수 있습니다.

• dotenv 파일은 따옴표를 지원하지 않습니다. 작은따옴표 또는 큰따옴표는 있는 그대로 보존되며 이스케이프에 사용할 수 없습니다.

• 값에는 개행 문자 또는 이스케이프가 필요한 기타 특수 문자를 포함할 수 없습니다.

• 멀티라인 값은 지원되지 않습니다. GitLab은 업로드 시 파일을 거부합니다.

• 앞뒤 공백 또는 개행 문자(\n)는 제거됩니다.

크기 및 변수 제한#

GitLab.com 티어 제한에 대해서는 GitLab.com CI/CD 설정을 참조하세요.

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