워크플로 문법 (Workflow Syntax)

.github/workflows/ 아래의 YAML 파일은 GitHub Actions의 공식 **워크플로 문법(Workflow Syntax)**을 따라야 해요. on:·jobs:·steps: 같은 가장 큰 키부터 strategy.matrix·services·container 같은 세부 키까지, 워크플로가 이해하는 모든 키의 구조와 규칙을 이 페이지에서 정리해요.

상위 문서: GitHub Actions · 워크플로와 이벤트 · 잡

출처: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions

파일과 기본 구조

워크플로 파일은 YAML 문법을 쓰고 확장자는 .yml 또는 .yaml이에요. 반드시 저장소의 .github/workflows/ 디렉터리에 두어야 해요. 파일의 최상위 키는 대략 다음과 같아요.

name — 워크플로 이름(선택)
on — 어떤 이벤트에서 실행할지 (필수)
permissions — 워크플로가 요청할 GITHUB_TOKEN 권한
env — 모든 잡에 적용되는 환경변수
defaults — 모든 잡의 기본 run 설정(shell, working-directory)
concurrency — 동시 실행 제어(그룹·취소 정책)
jobs — 실행할 잡들의 정의

jobs — 워크플로의 몸통

jobs 아래에 각 잡을 jobs.<job_id>로 선언해요. 잡은 기본적으로 병렬로 실행되고, needs:로 순서를 정하면 직렬로도 돌릴 수 있어요. 각 잡은 runs-on으로 지정한 러너 환경에서 실행돼요.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - run: npm ci
      - run: npm run build

jobs.<job_id>.if — 매트릭스가 적용되기 전에 평가되는 조건이에요. jobs.<job_id>.runs-on — 잡을 실행할 머신 타입을 정해요. 최신 러너 그룹 문법은 runs-on: group: 로도 지정할 수 있어요.

jobs:
  check-bats-version:
    runs-on: group: ubuntu-runners
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v4
        with:
          node-version: '14'
      - run: bats -v

jobs.<job_id>.needs — 먼저 성공해야 할 잡을 지정해 실행 순서를 만들어요. jobs.<job_id>.outputs — 잡의 결과를 산출물로 내보내 다른 잡이 참조하게 해요. jobs.<job_id>.environment — 배포 환경 이름을 지정해, 환경 보호 규칙(reviewer 등)을 적용할 수 있어요.

steps — 잡 안의 단계들

jobs.<job_id>.steps는 배열로, 각 스텝은 name, id, if, uses, run, with, env 등으로 구성돼요.

uses: — 액션을 불러 써요 (actions/checkout@v5 등).
run: — 러너 셸에서 직접 명령을 실행해요.
with: — 액션에 넘길 입력값(예: node-version).
if: — 이 스텝을 실행할지 조건.
continue-on-error: true — 이 스텝이 실패해도 워크플로를 실패로 만들지 않아요.
timeout-minutes: — 스텝 단위 실행 제한 시간.
working-directory: / shell: — run:이 실행될 디렉터리와 셸.

동시 실행 제어 — concurrency

concurrency:로 워크플로나 잡을 그룹으로 묶어, 같은 그룹은 한 번에 하나만 실행되게 해요. cancel-in-progress: true면 새 실행이 들어올 때 이전 실행을 취소해요.

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

브랜치별로 그룹을 나누면, 같은 브랜치에 푸시가 연달아 들어올 때 이전 실행을 취소해 리소스를 아낄 수 있어요.

매트릭스와 실패 정책 — strategy

jobs.<job_id>.strategy 로 매트릭스 전략을 선언해요. strategy.matrix로 변수 조합을 만들고, strategy.fail-fast로 매트릭스 전체 실패 정책을, strategy.max-parallel로 동시 실행 개수를 정해요. 상세는 매트릭스 전략을 참고해요.

jobs:
  test:
    strategy:
      fail-fast: true
      matrix:
        os: [ubuntu-latest, macos-latest]

매트릭스 한 워크플로 실행당 최대 256개 잡(호스팅·셀프 호스팅 공통) 상한이 있어요.

컨테이너·서비스 — container · services

jobs.<job_id>.container로 잡 자체를 컨테이너 안에서 실행할 수 있고(이미지·자격증명·볼륨·포트 지정), jobs.<job_id>.services로 잡이 사용할 보조 서비스 컨테이너(DB 등)를 띄울 수 있어요.

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: secret
        ports:
          - 5432:5432

재사용 가능한 워크플로 — uses (job 수준)

jobs.<job_id>.uses에 다른 워크플로 파일 경로를 지정해 재사용 가능한 워크플로를 호출할 수 있어요. with:로 입력을, secrets:로 시크릿을 넘겨요.

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/reusable.yml@v1
    with:
      environment: production
    secrets:
      inherit: true

권한 — permissions

permissions: 키로 이 워크플로가 자동 생성되는 GITHUB_TOKEN에 부여할 권한을 최소화할 수 있어요. 보안 기본 원칙은"가능한 한 적게"예요. 잡 단위로도 jobs.<job_id>.permissions를 지정할 수 있어요.

permissions:
  contents: read
  packages: write

워크플로 문법 (Workflow Syntax)