GitHub Actions 기본 컨텍스트 완전 정리

GitHub Actions에서는 별도의 설정 없이 ${{ }} 문법만으로 다양한 컨텍스트 변수에 접근할 수 있다. 이 글에서는 실무에서 자주 사용하는 핵심 컨텍스트를 정리하고, 바로 활용 가능한 패턴까지 함께 정리한다.

---

1. github 컨텍스트

워크플로우를 트리거한 이벤트와 실행 환경 정보를 담고 있다. 가장 많이 사용하는 핵심 컨텍스트다.

주요 변수

변수설명예시

github.ref_name	브랜치 또는 태그 이름	main, dev
github.ref	전체 ref 경로	refs/heads/main
github.sha	커밋 해시 (전체)	abc1234ef...
github.event_name	트리거 이벤트	push, pull_request
github.actor	실행 유저	username
github.repository	리포지토리 이름	org/repo
github.repository_owner	리포지토리 소유자	org
github.run_id	실행 고유 ID	1234567890
github.run_number	실행 횟수	42
github.workflow	워크플로우 이름	Deploy
github.job	현재 job ID	build
github.workspace	코드 경로	/home/runner/work/...

사용 예시

- name: Print branch
  run: echo ${{ github.ref_name }}

브랜치에 따라 로직을 나눌 때 핵심적으로 사용한다.

environment: ${{ github.ref_name == 'main' && 'production' || 'development' }}

---

2. secrets 컨텍스트

리포지토리 Settings → Secrets에 저장된 값을 참조한다.
자동으로 마스킹되므로 로그에 노출되지 않는다.

env:
  MY_SECRET: ${{ secrets.MY_SECRET }}

주의 사항 (중요)

heredoc 내부에서 직접 ${{ secrets.X }}를 사용하는 것은 안전하지 않다.
특수문자 처리 문제가 발생할 수 있기 때문이다.

반드시 env로 먼저 전달한 후 사용한다.

- name: Create .env
  run: |
    cat > .env << EOF
    MY_SECRET=${MY_SECRET}
    EOF
  env:
    MY_SECRET: ${{ secrets.MY_SECRET }}

---

3. vars 컨텍스트

Settings → Variables에 저장된 값이다.
secrets와 달리 평문이므로 민감하지 않은 값에만 사용해야 한다.

- run: echo ${{ vars.APP_URL }}

---

4. env 컨텍스트

워크플로우 내부에서 정의한 환경변수다.

env:
  NODE_ENV: production

steps:
  - run: echo ${{ env.NODE_ENV }}

---

5. steps 컨텍스트

같은 job 내 이전 step의 output을 참조할 때 사용한다.

steps:
  - id: get-version
    run: echo "version=1.0.0" >> $GITHUB_OUTPUT

  - run: echo ${{ steps.get-version.outputs.version }}

---

6. needs 컨텍스트

다른 job의 output을 참조할 때 사용한다.

jobs:
  build:
    outputs:
      version: ${{ steps.get-version.outputs.version }}

  deploy:
    needs: build
    steps:
      - run: echo ${{ needs.build.outputs.version }}

---

7. runner 컨텍스트

현재 실행 중인 러너 환경 정보다.

변수설명예시

runner.os	OS	Linux, Windows, macOS
runner.arch	아키텍처	X64, ARM64
runner.name	러너 이름	custom-runner
runner.temp	임시 디렉토리	/home/runner/work/_temp

---

실무에서 자주 쓰는 패턴

1. 브랜치에 따라 environment 분기

environment: ${{ github.ref_name == 'main' && 'production' || 'development' }}

---

2. 브랜치에 따라 빌드 명령 분기

run: ${{ github.ref_name == 'main' && 'yarn build:prod' || 'yarn build:dev' }}

---

3. 브랜치에 따라 러너 분기

runs-on: ${{ github.ref_name == 'main'
  && fromJSON('["self-hosted", "prod-runner"]')
  || fromJSON('["self-hosted", "dev-runner"]') }}

---

정리

GitHub Actions에서 컨텍스트를 제대로 이해하면 조건 분기, 배포 전략, 환경 분리를 매우 단순하게 구성할 수 있다.

핵심은 세 가지다.

• github: 실행 상황 판단
• secrets / vars: 설정값 관리
• steps / needs: 데이터 흐름 제어

이 구조만 명확히 이해하면 대부분의 워크플로우는 복잡하지 않게 설계할 수 있다.