..

모던 GitHub Actions CI Flow: Workflow Quick Started

TOC

  1. Overview
  2. Workflow 기본 구조
  3. Event별 Workflow 작성
    1. pull_request
    2. push
    3. workflow_dispatch
  4. Step 작성
    1. run과 uses
  5. 최소 Workflow 이벤트별 예시
  6. 실습 저장소
  7. Conclusion

Overview

이 글은 GitHub Actions CI 시리즈의 2편이다. 1편 모던 GitHub Actions CI Flow에서 설명한 흐름을 Workflow YAML로 작성한다. Jenkins의 Pipeline이 실행할 작업을 정의하듯, GitHub Actions Workflow는 Event, Job, Step을 저장소 안에 선언한다.

이 글에서는 pull_request, push, workflow_dispatch를 기준으로 실행 조건을 작성하고, Step에서 run과 uses를 사용하는 방법을 설명한다.

Workflow 기본 구조

Workflow 파일은 저장소의 .github/workflows 디렉터리에 둔다. 기본 구조는 name, on, jobs로 구성한다.

name: CI

######
## 이벤트 선언
######
on:
  pull_request:
  # or
  push:
  # or
  workflow_dispatch:

######
## 작업 선언
######
jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - run: npm test
  • name: GitHub Actions 화면에 표시할 Workflow 이름
  • on: Workflow를 실행할 Event 필터
  • jobs: Runner에서 실행할 Job과 실행 순서
  • steps: Job 안에서 순서대로 실행할 작업

Event별 Workflow 작성

Event는 Jenkins의 Trigger와 비슷한 역할을 한다. 하나의 Workflow에 여러 Event를 선언하면 선언된 Event 중 하나가 발생할 때 Workflow가 실행된다. GitHub Actions Event 문서

pull_request

PR 생성, 새 commit Push, 재오픈을 대상으로 CI를 실행

on:
  pull_request:
    types: [opened, synchronize, reopened]
  • opened: PR 생성될 때
  • synchronize: PR source branch에 새 커밋이 반영될때
  • reopened: 닫힌 PR 재오픈될 때

push

지정한 브랜치에 commit이 반영될 때 실행 PR Merge 후 develop의 상태를 검증 or 개발 환경에 배포할 때 사용할 수 있다.

on:
  push:
    branches: [develop]

branches를 생략하면 모든 브랜치의 Push가 대상이 됨. 운영 배포처럼 영향 범위가 큰 작업은 대상 브랜치를 명시

workflow_dispatch

GitHub UI나 API에서 Workflow를 수동 실행 특정 Ref나 입력값을 받아 배포와 운영 작업을 실행할 수 있다. 이때inputs 하위의 custom 인자를 함께 받아 사용할 수 있다.

on:
  workflow_dispatch:
    inputs:

Step 작성

Step은 Runner에서 직접 명령을 구성하거나, 이미 정의된 자동화 단위를 호출

run과 uses

run은 Runner의 셸에서 명령을 실행하고, uses는 Action 또는 재사용 Workflow를 호출

uses는 미리 정의된 동작을 가져와 사용하는 방식이다. 직접 실행 명령을 작성하는 대신, 반복해서 사용할 수 있는 Action을 조합한다는 점에서 동작 템플릿처럼 이해할 수 있다.

Step 수준의 uses는 Action을 호출한다. 재사용 Workflow는 Job 수준에서 별도의 uses 문법으로 호출한다.

예시: uses

... 

steps:
  - uses: actions/setup-node@v7
    with:
      node-version: 24
  • actions/setup-node: 지정한 Node.js 실행 환경을 준비한다.
  • with: Action에 입력값을 전달한다.
  • @v6, @v7: Action의 Ref다. Tag, Branch, Commit SHA를 사용할 수 있다.

예시: run

steps:
  - run: npm test

최소 Workflow 이벤트별 예시

pr

name: pr test

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  pr-test: 
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

push

name: push test

on:
  push:
    branches: [develop]

jobs:
  push-test: 
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

workflow_dispatch

name: manual test

on:
  workflow_dispatch:
    inputs:
      msg:
        description: 메세지
        required: false
        type: string

jobs:
  manual-test: 
    runs-on: ubuntu-latest
    steps:
      - run: echo $

실습 저장소

이 글에서 설명한 Workflow 작성 방법은 다음 저장소에서 직접 테스트할 수 있다.

현재 Workflow는 workflow_dispatch를 사용해 수동으로 실행할 수 있다.

Actions 탭
  → manual test 선택
      → Run workflow
          → msg 입력
              → ubuntu-latest Runner에서 메시지 출력

저장소의 Workflow 파일에서 workflow_dispatch, inputs, jobs, runs-on, steps가 어떻게 연결되는지 확인하면서 본문의 흐름을 따라가면 된다.

Conclusion

GitHub Actions Workflow는 Event로 실행 시점을 정의하고, Job과 Step으로 실행할 작업을 구성한다.