환경 변수

환경 변수(env)는 Workflow, Job, Step 3단계에서 정의할 수 있습니다. 하위 레벨에서 동일한 키를 선언하면 상위 레벨의 값을 덮어씁니다.

시크릿과 변수의 등록 방법은 시크릿과 변수 가이드를 참조하세요.

아래는 변수 관리 UI 예시입니다.

Override Priority

하위 레벨에서 동일한 키를 선언하면 상위 레벨의 값을 덮어씁니다. 우선순위: Step env > Job env > Workflow env

Step env  >  Job env  >  Workflow env
(최우선)                    (최하위)

3단계 환경 변수 예제

# 1단계: Workflow 레벨 (모든 Job/Step에서 사용 가능)
env:
  APP_NAME: my-app
  LOG_LEVEL: info

jobs:
  build:
    # 2단계: Job 레벨 (이 Job의 모든 Step에서 사용 가능)
    env:
      LOG_LEVEL: debug    # Workflow의 info를 debug로 덮어씀
      BUILD_TARGET: dist

    steps:
      - name: build
        run: |
          echo $APP_NAME      # "my-app"    (Workflow에서 상속)
          echo $LOG_LEVEL     # "debug"     (Job에서 덮어씀)
          echo $BUILD_TARGET  # "dist"      (Job에서 정의)
          echo $EXTRA         # "step-only" (Step에서 정의)
        # 3단계: Step 레벨 (이 Step에서만 사용 가능)
        env:
          EXTRA: step-only
          LOG_LEVEL: trace  # Job의 debug를 trace로 덮어씀

Secrets 사용

민감한 값은 secrets 컨텍스트로 참조합니다. 환경 변수의 value에서 Expression을 사용합니다.

env:
  # ✅ 올바른 사용 — value에 Expression 사용
  API_KEY: "${{ secrets.API_KEY }}"
  DB_PASSWORD: "${{ secrets.DB_PASSWORD }}"

jobs:
  deploy:
    env:
      DEPLOY_TOKEN: "${{ secrets.DEPLOY_TOKEN }}"
    steps:
      - name: deploy
        run: ./deploy.sh
        env:
          # Step에서도 secrets 참조 가능
          AWS_ACCESS_KEY: "${{ secrets.AWS_ACCESS_KEY_ID }}"

Variables 사용

조직/저장소 레벨에서 설정한 변수는 vars 컨텍스트로 참조합니다.

env:
  DEPLOY_ENV: "${{ vars.DEPLOY_ENV }}"
  REGION: "${{ vars.AWS_REGION }}"

jobs:
  deploy:
    steps:
      - name: deploy
        run: |
          echo "Deploying to $DEPLOY_ENV in $REGION"
          ./deploy.sh

env key와 Expression

env의 key에는 Expression을 사용할 수 없습니다. key는 반드시 리터럴 문자열이어야 하며, Expression은 value에서만 사용 가능합니다.

# ❌ 잘못된 사용 — key에 Expression 사용 불가
env:
  ${{ secrets.KEY_NAME }}: some-value

# ✅ 올바른 사용 — key는 리터럴 문자열, value에서 Expression 사용
env:
  API_KEY: "${{ secrets.API_KEY }}"
  APP_VERSION: "${{ vars.APP_VERSION }}"
  COMMIT_SHA: "${{ collabops.sha }}"

Rules

env의 key는 반드시 리터럴 문자열이어야 합니다.

Expression은 value에서만 사용 가능합니다.

하위 레벨(Step > Job > Workflow)에서 동일한 key를 선언하면 상위 값을 덮어씁니다.

환경 변수 이름은 대문자와 _를 사용하는 것이 관례입니다.