GitHub Actions — 워크플로·잡·스텝·시크릿·OIDC

GitHub Actions 는 GitHub 저장소 안에 CI/CD 를 두는 자리입니다. 2018 년 베타로 공개됐고 2019 년에 GA 로 옮겨갔습니다.

1. GitHub Actions 에 대한 이야기

GitHub 가 운영하는 CI/CD 플랫폼입니다. 워크플로 정의가 저장소 안의 .github/workflows/*.yml 에 산다는 점, 마켓플레이스의 액션을 그대로 써서 시작 비용이 낮다는 점이 특징으로 거론됩니다. 가격은 공개 저장소 무료 + 사설 저장소의 무료 한도 + 추가 사용량 과금. Enterprise 는 별도입니다.

용어	의미
Workflow	한 YAML 파일이 정의하는 자동화 (`on:` + `jobs:`)
Event	트리거 (push · pull_request · schedule · workflow_dispatch 등)
Job	같은 runner 위에서 직렬·병렬로 도는 스텝 묶음
Step	명령(`run:`) 또는 액션(`uses:`) 한 줄
Runner	잡을 실제로 굴리는 컴퓨터 (호스티드 또는 셀프호스티드)
Action	재사용 단위 (`uses: actions/checkout@v4`)

name: ci
on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npm test

2. Runner

호스티드 (GitHub-hosted) — GitHub 가 제공하는 임시 VM. Ubuntu · Windows · macOS. 잡마다 새 VM.
셀프호스티드 — 자기 서버·VM 에 runner 에이전트를 띄움. 라벨로 워크플로가 붙도록 매칭.
Larger runner — 더 강한 사양의 호스티드 옵션 (과금).

호스티드는 동일 환경의 깔끔함이 강점, 셀프호스티드는 비용·환경 통제 (예: GPU·내부망 접근) 가 강점입니다.

3. Matrix

같은 잡을 여러 매개변수로 동시에 굴립니다.

strategy:
  matrix:
    node: [18, 20, 22]
    os: [ubuntu-latest, windows-latest]

조합 수가 많아지면 비용·시간이 빠르게 자라므로 include · exclude 로 좁히는 모양이 흔합니다.

4. Reusable workflow · Composite action

Reusable workflow — 다른 워크플로에서 uses: 로 호출. 입력·시크릿을 명시.
Composite action — 여러 스텝을 한 액션으로 묶기. 작은 단위의 재사용.

큰 조직의 CI 표준화 자리에서 둘이 함께 쓰입니다.

5. 캐시·아티팩트

actions/cache — 의존성·빌드 결과를 키 기반으로 저장·복원. 키가 일치하면 적중.
actions/upload-artifact / download-artifact — 잡 사이·워크플로 사이의 산출물 전달.
다수 setup 액션 (setup-node · setup-go · setup-python 등) 이 내부에 캐시를 포함합니다.

캐시 키는 보통 lock 파일 (package-lock.json · pnpm-lock.yaml 등) 의 해시로 만듭니다. 키가 너무 짧으면 캐시 적중이 자주 어긋납니다.

6. 시크릿과 환경

Repository secrets — 저장소 단위.
Environment secrets — 환경 (staging · production) 단위. 승인·웨이트 가능.
Organization secrets — 조직 단위.

시크릿은 로그에서 자동 마스킹되지만 echo · 외부 서비스 전달 자리에서 새는 사례가 보고됩니다.

7. OIDC

GitHub Actions 가 발행하는 OIDC 토큰을 클라우드 (예: AWS · GCP · Azure) 가 검증해 임시 자격증명을 발급하는 모양입니다. 정적 키를 시크릿에 두지 않고도 클라우드 권한을 받을 수 있어 보안·운영에서 강점이 거론됩니다.

permissions:
  id-token: write
  contents: read

steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123:role/GitHubActions
      aws-region: ap-northeast-2

GCP 의 Workload Identity Federation, Azure 의 OIDC 통합이 같은 결로 다뤄집니다.

8. 다른 CI 도구

도구	출시	결
GitHub Actions	2018 베타 / 2019 GA	저장소 결합 · 마켓플레이스
GitLab CI	2015~	GitLab 결합 · 셀프호스팅 익숙
CircleCI	2011	워크플로 DSL 의 결이 빠른 시작
Jenkins	2011 (원형은 Hudson 2005)	자체 호스팅의 표준 자리 · 플러그인 풍부
Buildkite	2014	셀프호스팅 에이전트 + SaaS UI 결합
Travis CI	2011	오픈소스 측에 한 시기 표준이었으나 점유 변동
Drone CI	2014	컨테이너 네이티브
Bitbucket Pipelines	2016	Bitbucket 결합

선택의 결:

저장소 호스팅과의 결합 — GitHub → Actions, GitLab → GitLab CI, Bitbucket → Pipelines.
셀프호스팅 우선 — Jenkins · Drone · 자체 GitLab Runner.
마켓플레이스·생태계 — Actions 가 가장 풍부하다는 평이 다수.
비용 예측 — 사용량 단가·동시 잡 한도 차이.

9. PR 가드와 배포의 결

PR 가드:

빌드·단위 테스트.
lint · 타입 체크.
통합 테스트 (필요 시 service container · Testcontainers).
코드 커버리지 리포트.
보안 스캔 (CodeQL · Dependabot · SCA).

배포:

main 머지 시 staging 자동 배포.
프로덕션은 environment 승인 게이트.
OIDC 로 클라우드 권한 받기.
카나리·롤링 배포는 클라우드 측 도구와 결합.

10. 컨벤션 감사 게이트

PR 가드는 빌드·테스트·lint 에서 멈출 이유가 없습니다. 자동 감사 (automated audit) — 프로젝트 규약이나 불변식을 기계적으로 점검하는 스텝 — 을 머지 차단 항목으로 더 얹을 수 있습니다. 평범한 워크플로 스텝일 뿐이라, 종료 코드가 0 이 아니면 잡이 실패하고, 브랜치 보호에서 그 체크를 필수로 걸어 두면 머지가 막힙니다.

흔한 감사 대상:

diff 안의 금지 패턴 — 디버그용 console.log, 하드코딩된 시크릿, 남겨진 TODO·FIXME 마커.
커밋 메시지 규약 위반.
프로젝트 불변식 — 로케일 파일 사이의 i18n 키 정합, 깨진 내부 링크 없음, lock 파일과 매니페스트의 일치.

작은 예 — 변경된 파일을 grep 으로 훑어 금지 패턴이 보이면 1 로 빠지는 셸 스크립트:

- name: convention audit
  run: |
    if git diff --name-only origin/main... \
       | xargs -r grep -nE 'console\.log|TODO' 2>/dev/null; then
      echo "forbidden pattern found"; exit 1
    fi

값어치는 분명합니다 — 리뷰어의 기억에 기대던 규약이 기계적으로 강제됩니다. 모든 PR 에서, 예외 없이. 다만 감사 스크립트는 빠르고 결정적 (deterministic) 이어야 합니다. 어쩌다 실패하는 감사는 게이트 전체의 신뢰를 깎습니다.

11. 스케줄·매트릭스 비용

on: schedule 의 cron 으로 정기 작업을 돌립니다. 데이터 파이프라인·문서 생성·정합성 점검 같은 자리에 자주 쓰입니다. 매 분 단위 실행은 한도·비용 주의입니다.

매트릭스의 OS · 언어 버전 조합이 폭주하지 않도록 제한하고, fail-fast: true 와 continue-on-error: false 의 의미를 인식합니다.

12. 자주 걸리는 자리

시크릿 누출 — echo $SECRET 또는 외부 서비스로 전달 시 마스킹이 깨질 수 있습니다. 명시적 add-mask 또는 권한 최소화로 막습니다.

OIDC 권한 폭 — assume 가능한 role 의 권한이 너무 넓으면 의미가 약해집니다.

fork PR 의 시크릿 — fork 에서 온 PR 은 기본적으로 시크릿이 노출되지 않습니다 (보안). 필요한 경우 pull_request_target 을 쓰지만 보안 함정이 따라옵니다.

무한 트리거 — 워크플로가 자기 변경을 push 해 다시 트리거되는 자리. paths · if 로 차단합니다.

runner 환경 차이 — ubuntu-latest 의 기본 도구·버전이 시간에 따라 바뀝니다. 핀 고정이 안전합니다.

캐시 적중 실패 — 키가 너무 길면 거의 항상 미스, 너무 짧으면 잘못된 캐시 사용입니다.

셀프호스티드의 격리 — 셀프호스티드 runner 가 fork PR 을 받는 설정은 위험합니다. 기본 비활성입니다.

Concurrency — 같은 브랜치에 빠른 푸시가 들어오면 동시에 잡이 돌아 충돌합니다. concurrency: 그룹·취소.

action 출처 — 신뢰되지 않은 action 을 uses: 하면 코드 실행 권한을 그대로 줍니다. 핀 고정 (@sha) 권장합니다.

하고픈 말

CI/CD 는 도입한 양만큼 운영 부담이 함께 자랍니다. 처음에는 PR 가드 한 줄로 시작해 충분히 자리잡으면 배포·스케줄로 확장하는 흐름이 안전합니다. 마켓플레이스 action 을 가져다 쓸 때는 출처와 핀 고정을 한 번 더 봅니다.

vitest-pytest-infra

GitHub Actions 문서 · Workflow syntax · Reusable workflows · OIDC 통합 · actions/cache · GitLab CI 를 참고합니다.

GitHub Actions