변수에 정보 저장하기

GitHub는 각 GitHub Actions 워크플로 실행에 기본 변수를 설정해요. 또한 단일 워크플로나 여러 워크플로에서 사용할 사용자 지정 변수를 직접 설정할 수도 있어요.

출처: 문서

본문

GitHub는 각 GitHub Actions 워크플로 실행을 위한 기본 변수를 설정합니다. 단일 워크플로나 여러 워크플로에서 사용할 사용자 지정 변수도 설정할 수 있습니다.

단일 워크플로를 위한 환경 변수 정의하기

단일 워크플로를 위한 사용자 지정 환경 변수를 설정하려면 워크플로 파일에서 env 키를 사용해서 정의할 수 있습니다. 이 방법으로 설정한 사용자 지정 변수의 스코프는 변수가 정의된 요소로 제한됩니다. 다음 범위로 변수를 정의할 수 있습니다:

워크플로 전체: 워크플로 파일 최상위 레벨에서 env를 사용합니다.
워크플로 내 잡의 내용: jobs.<job_id>.env를 사용합니다.
잡 내의 특정 스텝: jobs.<job_id>.steps[*].env를 사용합니다.

name: Greeting on variable day

on:
  workflow_dispatch

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

러너 환경 변수나 컨텍스트를 사용해서 env 변수 값에 접근할 수 있습니다. 위 예시는 echo 명령에서 러너 환경 변수로 사용되는 세 개의 사용자 지정 변수 $DAY_OF_WEEK, $Greeting, $First_Name을 보여줍니다. 이 변수들의 값은 각각 워크플로, 잡, 스텝 레벨에서 설정되고 스코프가 지정됩니다. 이 변수들의 보간(interpolation)은 러너에서 발생합니다.

워크플로의 run 스텝 또는 참조된 액션의 명령은 러너에서 사용 중인 셸이 처리합니다. 워크플로의 다른 부분에 있는 지침은 GitHub Actions가 처리하며 러너로 전송되지 않습니다. run 스텝에서는 러너 환경 변수나 컨텍스트를 모두 사용할 수 있지만, 러너로 전송되지 않는 워크플로 부분에서는 변수 값에 접근하기 위해 컨텍스트를 사용해야 합니다. 자세한 내용은 Using contexts to access variable values를 참고하세요.

러너 환경 변수 보간은 워크플로 잡이 러너 머신으로 전송된 후에 이루어지므로, 러너에서 사용되는 셸에 맞는 적절한 구문을 사용해야 합니다. 이 예시에서 워크플로는 ubuntu-latest를 지정합니다. 기본적으로 Linux 러너는 bash 셸을 사용하므로 $NAME 구문을 사용해야 합니다. 기본적으로 Windows 러너는 PowerShell을 사용하므로 $env:NAME 구문을 사용해야 합니다. 셸에 대한 자세한 내용은 Workflow syntax for GitHub Actions을 참고하세요.

여러 워크플로를 위한 구성 변수 정의하기

여러 워크플로에서 사용할 구성 변수(configuration variable)를 만들 수 있으며, 조직, 저장소, 환경 레벨 중 하나에서 정의할 수 있습니다.

예를 들어, 조직 레벨에서 빌드 도구에 전달되는 파라미터의 기본값을 구성 변수로 설정한 다음, 저장소 소유자가 경우에 따라 이 파라미터를 덮어쓸 수 있게 할 수 있습니다.

구성 변수를 정의하면 vars 컨텍스트에서 자동으로 사용할 수 있습니다. 자세한 내용은 Using the vars context to access configuration variable values를 참고하세요.

저장소용 구성 변수 만들기

GitHub에서 조직 저장소에 시크릿이나 변수를 만들려면 write 권한이 있어야 합니다. 개인 계정 저장소라면 저장소 협업자여야 합니다.

GitHub에서 저장소의 메인 페이지로 이동합니다.
저장소 이름 아래에서 Settings를 클릭합니다.
사이드바의 "Security" 섹션에서 Secrets and variables를 선택한 다음 Actions를 클릭합니다.
Variables 탭을 클릭합니다.
New repository variable을 클릭합니다.
Name 필드에 변수 이름을 입력합니다.
Value 필드에 변수 값을 입력합니다.
Add variable을 클릭합니다.

환경용 구성 변수 만들기

개인 계정 저장소의 환경에 시크릿이나 변수를 만들려면 저장소 소유자여야 합니다. 조직 저장소의 환경에 시크릿이나 변수를 만들려면 admin 권한이 있어야 합니다. 환경에 대한 자세한 내용은 Managing environments for deployment를 참고하세요.

GitHub에서 저장소의 메인 페이지로 이동합니다.
저장소 이름 아래에서 Settings를 클릭합니다.
왼쪽 사이드바에서 Environments를 클릭합니다.
변수를 추가할 환경을 클릭합니다.
Environment variables 아래에서 Add variable을 클릭합니다.
Name 필드에 변수 이름을 입력합니다.
Value 필드에 변수 값을 입력합니다.
Add variable을 클릭합니다.

조직용 구성 변수 만들기

[!NOTE] 조직 레벨의 시크릿과 변수는 GitHub Free에서 비공개 저장소가 접근할 수 없습니다. GitHub 구독을 업그레이드하는 방법에 대한 자세한 내용은 Upgrading your account's plan을 참고하세요.

조직에서 시크릿이나 변수를 만들 때 정책을 사용해서 저장소별 접근을 제한할 수 있습니다. 예를 들어 모든 저장소에 접근을 허용하거나, 비공개 저장소만, 또는 지정된 저장소 목록으로만 제한할 수 있습니다.

조직 소유자는 조직 레벨에서 시크릿이나 변수를 만들 수 있습니다.

GitHub에서 조직의 메인 페이지로 이동합니다.
조직 이름 아래에서 Settings를 클릭합니다.
사이드바의 "Security" 섹션에서 Secrets and variables를 선택한 다음 Actions를 클릭합니다.
Variables 탭을 클릭합니다.
New organization variable을 클릭합니다.
Name 필드에 변수 이름을 입력합니다.
Value 필드에 변수 값을 입력합니다.
Repository access 드롭다운 목록에서 접근 정책을 선택합니다.
Add variable을 클릭합니다.

컨텍스트를 사용해서 변수 값에 접근하기

컨텍스트는 워크플로 실행, 변수, 러너 환경, 잡, 스텝에 대한 정보에 접근하는 방법입니다. 자세한 내용은 Contexts reference를 참고하세요. 워크플로에서 다양한 목적으로 사용할 수 있는 컨텍스트가 많이 있습니다. 워크플로 내에서 특정 컨텍스트를 어디에 사용할 수 있는지에 대한 자세한 내용은 Contexts reference를 참고하세요.

환경 변수 값에는 env 컨텍스트로, 구성 변수 값에는 vars 컨텍스트로 접근할 수 있습니다.

`env` 컨텍스트를 사용해서 환경 변수 값에 접근하기

러너 환경 변수 외에도 GitHub Actions는 컨텍스트를 사용해서 env 키 값을 설정하고 읽을 수 있게 해줍니다. 환경 변수와 컨텍스트는 워크플로의 서로 다른 지점에서 사용하기 위한 것입니다.

워크플로 또는 참조된 액션의 run 스텝은 러너가 처리합니다. 따라서 러너에서 사용 중인 셸에 맞는 적절한 구문(예: Linux 러너의 bash 셸에서는 $NAME, Windows 러너의 PowerShell에서는 $env:NAME)을 사용해서 러너 환경 변수를 사용할 수 있습니다. 대부분의 경우 ${{ CONTEXT.PROPERTY }} 구문의 컨텍스트를 사용해서 같은 값에 접근할 수도 있습니다. 차이점은 컨텍스트는 잡이 러너로 전송되기 전에 문자열로 보간되고 대체된다는 점입니다.

그러나 GitHub Actions가 처리하고 러너로 전송되지 않는 워크플로 부분에서는 러너 환경 변수를 사용할 수 없습니다. 대신 컨텍스트를 사용해야 합니다. 예를 들어, 잡이나 스텝을 러너로 보낼지 결정하는 if 조건은 항상 GitHub Actions가 처리합니다. 따라서 if 조건문에서 변수 값에 접근하려면 컨텍스트를 사용해야 합니다.

name: Conditional env variable

on: workflow_dispatch

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        if: ${{ env.DAY_OF_WEEK == 'Monday' }}
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

앞선 예시를 수정해 if 조건을 도입했습니다. 이제 워크플로 스텝은 DAY_OF_WEEK가 "Monday"로 설정된 경우에만 실행됩니다. if 조건문에서 env 컨텍스트를 사용해서 이 값에 접근합니다. run 명령 안에서 참조되는 변수에는 env 컨텍스트가 필요하지 않습니다. 그 변수들은 러너 환경 변수로 참조되며 잡이 러너에 도착한 후 보간됩니다. 다만 컨텍스트를 사용해서 잡을 러너로 보내기 전에 그 변수들을 보간하도록 선택할 수도 있습니다. 결과 출력은 동일합니다.

run: echo "${{ env.Greeting }} ${{ env.First_Name }}. Today is ${{ env.DAY_OF_WEEK }}!"

[!NOTE] 컨텍스트는 일반적으로 ${{ context.property }}처럼 달러 기호와 중괄호로 표시됩니다. if 조건에서 ${{와 }}는 선택 사항이지만, 사용한다면 위와 같이 전체 비교문을 감싸야 합니다.

[!WARNING] 워크플로와 액션을 만들 때 코드가 공격자의 신뢰할 수 없는 입력을 실행할 수 있는지 항상 고려해야 합니다. 특정 컨텍스트는 공격자가 자신의 악성 콘텐츠를 삽입할 수 있으므로 신뢰할 수 없는 입력으로 취급해야 합니다. 자세한 내용은 Secure use reference를 참고하세요.

`vars` 컨텍스트를 사용해서 구성 변수 값에 접근하기

vars 컨텍스트를 사용해서 워크플로 전반에서 구성 변수에 접근할 수 있습니다. 자세한 내용은 Contexts reference를 참고하세요.

구성 변수가 설정되어 있지 않으면 해당 변수를 참조하는 컨텍스트의 반환값은 빈 문자열이 됩니다.

다음 예시는 워크플로 전반에서 vars 컨텍스트로 구성 변수를 사용하는 모습을 보여줍니다. 다음 구성 변수들은 각각 저장소, 조직 또는 환경 레벨에서 정의되었습니다.

on:
  workflow_dispatch:
env:
  # Setting an environment variable with the value of a configuration variable
  env_var: ${{ vars.ENV_CONTEXT_VAR }}

jobs:
  display-variables:
    name: ${{ vars.JOB_NAME }}
    # You can use configuration variables with the `vars` context for dynamic jobs
    if: ${{ vars.USE_VARIABLES == 'true' }}
    runs-on: ${{ vars.RUNNER }}
    environment: ${{ vars.ENVIRONMENT_STAGE }}
    steps:
    - name: Use variables
      run: |
        echo "repository variable : $REPOSITORY_VAR"
        echo "organization variable : $ORGANIZATION_VAR"
        echo "overridden variable : $OVERRIDE_VAR"
        echo "variable from shell environment : $env_var"
      env:
        REPOSITORY_VAR: ${{ vars.REPOSITORY_VAR }}
        ORGANIZATION_VAR: ${{ vars.ORGANIZATION_VAR }}
        OVERRIDE_VAR: ${{ vars.OVERRIDE_VAR }}
        
    - name: ${{ vars.HELLO_WORLD_STEP }}
      if: ${{ vars.HELLO_WORLD_ENABLED == 'true' }}
      uses: actions/hello-world-javascript-action@main
      with:
        who-to-greet: ${{ vars.GREET_NAME }}

운영 체제 감지하기

RUNNER_OS 기본 환경 변수와 해당 컨텍스트 속성 ${{ runner.os }}를 사용하면 서로 다른 운영 체제에서 사용할 수 있는 단일 워크플로 파일을 작성할 수 있습니다. 예를 들어 다음 워크플로는 러너가 사용하는 셸에 따라 달라지는 환경 변수 구문을 수정하지 않고도 운영 체제를 macos-latest에서 windows-latest로 바꿔도 성공적으로 실행될 수 있습니다.

on: workflow_dispatch

jobs:
  if-Windows-else:
    runs-on: macos-latest
    steps:
      - name: condition 1
        if: runner.os == 'Windows'
        run: echo "The operating system on the runner is $env:RUNNER_OS."
      - name: condition 2
        if: runner.os != 'Windows'
        run: echo "The operating system on the runner is not Windows, it's $RUNNER_OS."

이 예시에서 두 if문은 runner 컨텍스트의 os 속성을 확인해서 러너의 운영 체제를 결정합니다. if 조건은 GitHub Actions가 처리하며, 체크가 true로 판정된 스텝만 러너로 전송됩니다. 여기서 두 체크 중 하나는 항상 true이고 다른 하나는 항상 false이므로 두 스텝 중 하나만 러너로 전송됩니다. 잡이 러너로 전송되면 스텝이 실행되고 echo 명령의 환경 변수가 적절한 구문(Windows의 PowerShell에서는 $env:NAME, Linux와 macOS의 bash와 sh에서는 $NAME)으로 보간됩니다. 이 예시에서 runs-on: macos-latest 문은 두 번째 스텝이 실행된다는 뜻입니다.

워크플로에서 스텝과 잡 사이에 값 전달하기

잡의 한 스텝에서 값을 생성하면, 해당 값을 기존 또는 새 환경 변수에 할당한 다음 GITHUB_ENV 환경 파일에 기록해서 같은 잡의 이후 스텝에서 사용할 수 있습니다. 환경 파일은 액션이 직접 사용하거나, 워크플로 파일에서 run 키워드를 사용한 셸 명령으로 사용할 수 있습니다. 자세한 내용은 Workflow commands for GitHub Actions를 참고하세요.

워크플로의 한 잡에 있는 스텝에서 같은 워크플로의 다른 잡에 있는 스텝으로 값을 전달하려면 그 값을 잡 출력(job output)으로 정의할 수 있습니다. 그다음 다른 잡의 스텝에서 이 잡 출력을 참조할 수 있습니다. 자세한 내용은 Workflow syntax for GitHub Actions를 참고하세요.

다음 단계

참고 자료는 Variables reference를 참고하세요.

변수에 정보 저장하기