Github Actions - Context

Context

Context란 workflow 실행 중에 github, run , job, step, 환경, secret 등의 상태 및 값을 담은 읽기 전용 객체이다.

Context를 쓰기 위해서는 표현식 구문 ${{}}의 내부에 작성해서 사용한다.

${{github.sha}}
${{runner.os}}
${{matrix.node}}

 

대표적인 Context

1) github

repo, branch, commit, event의 정보를 담고 있다

# 현재 워크플로우를 실행하는 저장소 명
github.repository

# 워크플로우를 트리거한 Git 참조(Reference) 
# 또는 branch(refs/heads/main) 또는 태그(ref/tags/v1.0.0)경로
github.ref

# 워크플로우를 트리거한 최신 커밋의 SHA 해시값
github.sha

# 워크플로우를 시작하게 만든 이벤트의 종류
github.event_name

# 현재 워크플로우가 실패 후 재시도된 횟수(첫시도는 1)
github.run_attempt

...

 

2) runner

실행 머신(러너) 정보를 담고 있다.

# 실행 머신의 운영체제 이름
runner.os

# 실행 머신의 CPU 아키텍쳐(CPU 종류로 x64(64비트 인텔), ARM64등이 있다)
runner.arch

# 실행 중인 러너의 이름
runner.name

# 러너가 사용할 수 있는 임시 디렉터리의 경로 
runner.temp

# 러너의 도구 캐시 디렉토리 경로
runner.tool.cache

 

3) env

env 블록에서 설정한 환경 변수 접근(읽기)

env.MY_VAR

 

4) vars

Github Actions에서 미리 저장소/환경에 등록한 Repository/Environment 변수들

vars.API_BASE_URL

 

5) secrets

secrets은 Github Actions가 자동으로 알 수 없는 비밀 정보(API key, password, token 등)를 안전하게 사용하도록 하기 위해서 사용자가 직접 Github 저장소 혹은 조직 설정에 등록해 높은 값으로 이 비밀값(자동 마스킹)을 사용하기 위한 컨텍스트이다.

secrets.GITHUB_TOKEN
secrets.MY_API_KEY

 

6) job

현재 잡 관련 상태

job.status

 

7) steps

steps 컨텍스트는 Github Actions 워크플로우 내에서 이전 단계(step)들의 실행 결과 또는 출력값(Outputs)을 참조할 때 사용된다.

steps.[Step ID].outputs.[Output Name]

- steps: 컨텍스트의 시작점
- build: 데이터를 출력한 이전 단계의 id (고유 이름)
- outputs: 이전 단계가 명시적으로 내보낸 출력값들을 담는 컨테이너
- tag: 이전 단계에서 정의한 출력 변수의 이름

 

8) matrix

matrix는 주로 소프트웨어의 호환성 테스트나 다양한 플랫폼 배포를 위해서 사용된다.

워크 플로우를 정의할 때 strategy 블록내에서 사용되며 

jobs:
  test:
    runs-on: ${{ matrix.os }} # 실행 환경은 matrix.os 값 사용
    strategy:
      matrix:
        # matrix.os 변수는 'ubuntu-latest'와 'windows-latest'를 가짐
        os: [ubuntu-latest, windows-latest] 
        # matrix.node 변수는 '18'과 '20'을 가짐
        node: [18, 20]

 

위와 같이 선언했을때 모든 조합으로 잡을 만들어 병렬로 실행된다

이에 대한 정보를 matrix라는 컨텍스트를 사용해서 확인할 수 있다.

# 현재 Job이 실행되고 있는 os의 이름(ubuntu-latest, windows-latest 등..)
matrix.os

# 현재 Job이 사용해야 하는 Node.js의 버전(18, 20)
matrix.node

 

 

9) needs

이전(의존) 잡의 출력/상태로 output과 result로 확인이 가능하다.

needs 컨텍스트를 호출하는 job의 경우는 다른 job에 의존관계를 명시했을때만 사용이 가능하다.

 

needs에서 출력하고자 하는 값을 확인하는 방법으로는 output이 있는데 이는 의존하는 job의 id와 의존하는 job에서 output으로 내보내는 특정 값의 명칭을 사용해서 값을 확인할 수 있다.

# needs.Dependency_job_id.output.var_name

jobs:
  # Job ID: artifact_creator
  artifact_creator:
    runs-on: ubuntu-latest
    outputs:
      # 외부에 공개할 변수명: my_version
      my_version: ${{ steps.set_version.outputs.VERSION_STR }} 
    steps:
      - id: set_version
        # GITHUB_OUTPUT을 통해 값을 steps.set_version.outputs.VERSION_STR에 설정
        run: echo "VERSION_STR=1.0.2" >> $GITHUB_OUTPUT

 deployment:
    runs-on: ubuntu-latest
    needs: artifact_creator # artifact_creator Job에 의존
    steps:
      - name: Use the version tag
        run: |
          # needs.artifact_creator.outputs.my_version 경로로 값 '1.0.2'를 가져옴
          VERSION=${{ needs.artifact_creator.outputs.my_version }} 
          echo "배포 버전은 $VERSION 입니다."

 

의존 job의 과를 확인하는 result는 의존하는 job의 id를 이용해서 그 결과를 확인할 수 있다.

# needs.dependency_job_id.result

jobs:
  # 1. 테스트 Job
  test:
    id: run_tests
    runs-on: ubuntu-latest
    # ... 테스트 실행 ...
    
  # 2. 알림 Job (테스트 Job 결과에 따라 실행)
  notify_failure:
    runs-on: ubuntu-latest
    needs: test # test Job에 의존
    if: ${{needs.test.result == 'failure'}} # 오직 test Job이 실패했을 때만 실행
    steps:
      - name: Send Slack Alert
        run: echo "테스트가 실패했습니다! 즉시 확인 요망."

 

10) inputs

workflow_dispatch / workflow_call에서 사용자가 입력한 입력값에 대한 매개변수의 값을 출력한다.

입력값의 확인은 아래의 형태로 확인이 가능하다.

input.param

 

11) strategy

매트릭스 전략 정보인데 이건 많이 사용을 안한다고 한다

 

마지막으로 위 context에 대한 문법에 대한 내용을 아래 홈페이지에서 확인이 가능하니 여기서 좀 더 구체적으로 확인하면서 사용하자

https://docs.github.com/en/actions/reference/workflows-and-actions/contexts

Contexts reference - GitHub Docs

 

 

왜 Context를 사용하는가?

이 컨텍스트를 사용하는 이유는 워크플로우가 실행되는 그 순간에 생기는 사실들, 상황들은 안전하고 일관되게 참조할 수 있게 하기 위해서이다.

예를 들어 지금 어떤 커밋이고 몇번째 시도이도 어떤 브랜치, 러너, 입력 값인지는 항상 상황마다 달라지게 되어 있는데 이를 고정적으로 값으로는 사용할 수 없기에 컨텍스트를 사용해서 실제 실시간으로 정보들을 참조해서 가져올수 있게 하기 위해서 사용된다.

또한 추가로 if 와 같은 조건절에도 사용이 가능하여 분기를 쳐서 더 유연한 workflow를 만들 수 있다는 점과 보안값을 분리해서 사용하며 스탭에서 스탭으로 잡에서 잡으로 원하는 값을 넘겨 사용할 수 있도록 도와주기 위해서 사용된다.

 

종합하자면 유동적인 데이터를 정확하게 받고 안정적이고, 유연한 workflow를 위해 사용되는 것이 Context라고 보면 된다.