[12-2] GitHub Actions 워크플로우에서의 다양한 트리거 유형

✔️ 들어가며

CI/CD 파이프라인은 코드 품질을 지키고, 빠른 배포와 장애 감지를 위해 필수적인 요소이다. GitHub Actions는 이를 위한 강력한 플랫폼으로, 단순한 테스트 자동화부터 멀티 환경 배포 오케스트레이션까지 다양한 시나리오를 코드 한 파일로 표현할 수 있다.

 

그리고 그 중심에는 트리거(Trigger)가 있다. 트리거는 워크플로우가 언제, 어떤 조건에서 실행될지 결정한다. 아무리 정교하게 설계된 파이프라인이라도 트리거가 잘못 설계되면 불필요한 실행으로 비용이 낭비되거나, 반대로 중요한 순간에 워크플로우가 실행되지 않는 상황이 발생한다.

 

GitHub Actions는 코드 push/PR과 같은 개발 이벤트, 정기 실행을 위한 스케줄, 사람이 직접 실행하는 수동 트리거, 외부 시스템과 연결되는 API 트리거, 그리고 레포지토리 활동 기반의 이벤트 트리거까지 다양한 유형을 제공한다. 각 트리거는 고유한 목적과 적합한 시나리오가 있으며, 이를 올바르게 조합하는 것이 중요하다.

---

✔️ 유형 1. 코드 이벤트

1-1. push

• 설명
  • 코드가 브랜치 또는 태그에 푸시될 때 워크플로우를 실행한다. 가장 기본적이고 많이 쓰이는 트리거로, branches, tags, paths 필터로 정밀하게 제어 가능하다.
• 적합한 시나리오
  • 스테이징 배포
  • 특정 파일 변경 감지

1-2. pull_request

• 설명
  • PR이 열리거나, 동기화되거나, 재오픈될 때 실행된다.
• 적합한 시나리오
  • PR 검증 게이트
  • Preview 환경 배포
  • 자동 리뷰 코멘트

✔️ 유형 2. 스케줄

2-1. schedule

• 설명
  • 특정 시간에 워크플로우를 주기적으로 실행한다. GitHub 서버 시간(UTC) 기준으로 동작하며, 최소 실행 간격은 5분이다.
• 적합한 시나리오
  • 야간 E2E 테스트 (매일 새벽 전체 end-to-end 테스트를 실행해 릴리즈 전 회귀 조기 감지)
  • 의존성 취약점 스캔
  • 데이터 파이프라인

✔️ 유형 3. 수동/외부 트리거

3-1. workflow_dispatch

• 설명
  • GitHub UI 또는 API를 통해 수동으로 워크플로우를 실행한다. inputs로 실행 시 파라미터를 전달할 수 있어 운영 작업에 유용하다.
• 적합한 시나리오
  • 프로덕션 배포
  • 긴급 롤백
  • 일회성 마이그레이션

3-2. workflow_call

• 설명
  • 다른 워크플로우에서 현재 워크플로우를 실행할 수 있게 한다. 즉, 재사용 가능한 워크플로우를 만드는 핵심 트리거로, inputs와 outputs를 정의해 모듈처럼 사용할 수 있다.
• 적합한 시나리오
  • 공통 CI 모듈화
  • 조직 표준 배포 파이프라인
  • 단계별 파이프라인 구성

3-3. repository_dispatch

• 설명
  • 외부 시스템이 GitHub API를 통해 POST 요청으로 워크플로우를 트러거한다. event-type을 지정해 여러 워크플로우를 선택적으로 실행할 수 있어 외부 통합에 강력하다는 특징이 있다.
• 적합한 시나리오
  • 외부 시스템 연동(Jira 이슈 상태 변경, 외부 CI 시스템이셔 GitHub 워크플로우 원격 실행)
  • 모노레포 선택적 트리거(특정 서비스 변경에만 관련 서브 파이프라인을 API로 실행)

3-4. workflow_run

• 설명
  • 다른 워크플로우의 완료 상태(성공/실패/완료)를 감지해 실행된다.
• 적합한 시나리오
  • 실패 알림 & 자동 복구
  • 파이프라이닝 체이닝

✔️ 유형 4. 레포지토리 이벤트

4-1. release

• 설명
  • GitHub Release가 생성, 편집, 게시, 삭제될 때 실행된다.
• 적합한 시나리오
  • 프로덕션 자동 배포
  • 패키지 퍼블리시
  • 릴리즈 자산 생성

4-2. issue & issue_comment

• 설명
  • 이슈 생성/수정/라벨링/PR 및 코멘트 작성 시 실행된다.
• 적합한 시나리오
  • 이슈 자동 분류
  • 이슈 기반 환경 생성

---

✔️ 정리

실무에서는 하나의 트리거만으로 충분한 경우는 드물다. push + workflow_dispatch를 조합해 자동 실행과 수동 실행을 모두 지원하거나, pull_request + workflow_run으로 포크 PR의 보안 배포 문제를 해결하는 등 여러 트리거를 전략적으로 조합하는 것이 일반적이다.

 

좋은 트리거 설계는 불필요한 실행을 최소화하면서, 필요한 순간에는 반드시 실행되는 트리거이다. GitHub Actions를 잘 활용하기 위해서는, 이러한 트리거를 이해하고 목적에 맞게 설계하는 역량을 길러야 한다.