GitHub Actions 트리거 완전 정복

GitHub Actions 트리거 완전 정복

(pull_request, schedule, workflow_dispatch로 실전 자동화하기)

GitHub Actions는 깃허브 저장소 안에서 코드의 테스트, 빌드, 배포, 문서화 같은 작업을 자동으로 실행해주는 강력한 자동화 도구입니다.이 자동화의 핵심은 바로 트리거(trigger)입니다. 트리거는 **"언제 워크플로우를 실행할 것인가"**를 정의하는 이벤트 조건이죠. 이 글에서는 가장 많이 사용되는 세 가지 트리거인 👉 pull_request, schedule, workflow_dispatch 를 중심으로 개념, 사용법, 예제를 알려드립니다.

---

✅ 트리거란?

GitHub Actions 워크플로우를 언제, 어떤 상황에서 실행할지 정하는 규칙입니다.

on:
  push:         # push 트리거 (기본)
  pull_request: # PR 생성/수정 시
  schedule:     # 정해진 시간마다
  workflow_dispatch:  # 수동 실행

---

🟦 1. pull_request 트리거

📘 개념

PR(Pull Request)이 생성되거나 수정될 때 자동 실행됩니다.

📌 예시

on:
  pull_request:
    branches: [ main ]

✅ 언제 사용하나요?

사용 상황	설명
PR 코드 테스트	병합 전에 자동 테스트
Lint 체크	코드 스타일 확인
문서 미리 보기	mkdocs/Storybook 자동 빌드
팀 코드 리뷰 자동화	PR에 코멘트 자동 추가 등

🔧 워크플로우 예시

name: Test on PR

on:
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
      - name: Run Tests
        run: pytest

---

🕒 2. schedule 트리거

📘 개념

정해진 시간마다 자동 실행되는 CRON 기반 타이머 트리거입니다.

📌 예시

on:
  schedule:
    - cron: '0 0 * * *'  # 매일 자정 (UTC 기준)

🧮 유용한 CRON 예시

CRON	실행 시점 (UTC 기준)
0 0 * * *	매일 자정
0 6 * * 1	매주 월요일 오전 6시
*/15 * * * *	15분마다

한국 시간(KST)은 UTC + 9시간을 기억하세요!

✅ 언제 사용하나요?

• 매일/매주 API 문서 자동 빌드
• 보안 스캔 / 취약점 확인
• 의존성 버전 체크
• Stale PR/Issue 자동 닫기

🔧 워크플로우 예시

name: Nightly Build

on:
  schedule:
    - cron: '0 0 * * *'

jobs:
  docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
      - name: Generate Docs
        run: pdoc my_module --html --output-dir docs

반응형

---

🟩 3. workflow_dispatch 트리거

📘 개념

수동 실행이 가능하도록 만들어주는 트리거입니다.
워크플로우 탭에서 "Run workflow" 버튼을 통해 실행할 수 있습니다.

📌 예시

on:
  workflow_dispatch:

✅ 언제 사용하나요?

• 팀원이 직접 수동으로 문서 생성/배포할 때
• 테스트 버전을 수동 배포하고 싶을 때
• 버튼 하나로 파이프라인 실행하고 싶을 때

🎛 옵션 추가 가능

on:
  workflow_dispatch:
    inputs:
      env:
        description: '실행 환경 선택'
        required: true
        default: 'dev'

 

→ 버튼을 누르면 실행 전 옵션을 선택할 수 있어요.

🔧 워크플로우 예시

name: Manual Deployment

on:
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
      - name: Manual Trigger Deploy
        run: echo "🎯 수동 배포 완료!"

---

🔁 비교 요약

트리거	실행 시점	대표 활용 예
push	커밋 푸시 시	테스트, 배포
pull_request	PR 생성/수정 시	코드 리뷰 자동화, PR 테스트
schedule	정해진 시간마다	야간 빌드, 주간 문서화
workflow_dispatch	수동 실행	직접 트리거, 테스트 환경용

---

🏁 추천 조합 예시

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  schedule:
    - cron: '0 0 * * *'
  workflow_dispatch:

하나의 워크플로우 파일에서 여러 트리거를 동시에 등록할 수 있어요!