워크플로를 트리거하는 이벤트

워크플로를 트리거하는 이벤트

워크플로는 스스로 실행되지 않고, 저장소에서 벌어지는 **이벤트(Event)**에 반응해서 실행돼요. on: 키워드로 어떤 이벤트에 이 워크플로가 돌아갈지를 선언하죠. 이 페이지에서는 push·pull_request를 넘어, CI/CD에서 자주 쓰는 다양한 이벤트와 그 안에서 잡을 세밀하게 거르는 if: 조건법을 소개해요.

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

출처: https://docs.github.com/actions/using-workflows/events-that-trigger-workflows

대표 트리거

push — 브랜치나 태그에 커밋이 푸시될 때 실행돼요. branches:·tags:·paths: 필터로 특정 변경에만 좁힐 수 있어요.

pull_request — PR이 열리거나 갱신될 때 실행돼요. types:로 어떤 PR 활동(열림·재오픈·리뷰 요청 등)에 반응할지 고를 수 있어요. PR 이벤트는 **머지 대상 브랜치(베이스)**를 기준으로 실행되므로, 조건을 쓸 때 github.head_ref(PR의 헤드 브랜치)와 비교하는 게 일반적이에요.

on:
  pull_request:
    types: [opened, reopened]

pull_request_target — PR 관련 이벤트지만 베이스 브랜치의 코드(머지 대상 브랜치의 워크플로·시크릿)로 실행돼요. PR에서 온 불신 코드로 실행되지 않기 때문에, PR의 라벨 변경처럼 안전한 자동화에 쓰여요. 단, 신중하게 다뤄야 해요.

release — 릴리즈가 발행(published)됐을 때 실행돼요. 배포 워크플로의 시작점으로 자주 쓰여요.

workflow_dispatch — Actions 탭에서 버튼을 눌러 수동으로 실행할 수 있게 해주는 이벤트예요. inputs:로 사용자가 넘길 입력값도 정의할 수 있어요.

schedule — cron 문법으로 정해진 시간에 주기적으로 실행돼요.

on:
  schedule:
    - cron: '30 5 * * 1,3'

workflow_run — 다른 워크플로가 끝났을 때 이 워크플로를 실행해요. 앞 워크플로의 결과는 github.event.workflow_run.conclusion로 확인할 수 있어요. 워크플로를 단계로 연결하고 싶을 때 유용해요.

repository_dispatch — GitHub API로 외부에서 이벤트를 보내 실행하는 방식이에요. 외부 도구(ChatOps 등)가 CI를 트리거할 때 쓰여요.

create / watch / status 등 저장소 활동 기반 트리거도 있어요. 예를 들어 status 이벤트는 커밋 상태가 바뀌었을 때 반응해요.

이벤트 세부 조건 — if:

이벤트가 발생했다고 해서 모든 잡이 돌 필요는 없어요. if: 조건과 이벤트 컨텍스트를 조합하면 특정 잡만 골라 실행할 수 있어요.

예를 들어 issue_comment 이벤트에서 PR 댓글과 일반 이슈 댓글을 나눠 처리해요.

on: issue_comment
jobs:
  pr_commented:
    name: PR comment
    if: ${{ github.event.issue.pull_request }}
    runs-on: ubuntu-latest
    steps:
      - run: echo A comment on PR $NUMBER
        env:
          NUMBER: ${{ github.event.issue.number }}
  issue_commented:
    name: Issue comment
    if: ${{ !github.event.issue.pull_request }}
    runs-on: ubuntu-latest
    steps:
      - run: echo A comment on issue $NUMBER

PR이 머지됐을 때만 돌리고 싶다면 github.event.pull_request.merged == true를, 특정 팀의 리뷰 요청일 때만 돌리고 싶다면 github.event.requested_team.name == 'octo-team'을 if:에 넣으면 돼요.

schedule 이벤트와 workflow_run 이벤트에도 같은 조건법을 적용할 수 있어요. 예를 들어 if: github.event.schedule != '30 5 * * 1,3'처럼 특정 크론에서만 뺄 수도 있어요.

주의할 점

  • pull_request는 베이스 브랜치 기준으로 시크릿과 컨텍스트를 계산해요. PR의 실제 코드는 머지 전까지 베이스 기준이라, PR 검증 워크플로를 설계할 때 이 차이를 꼭 감안하세요. (PR의 코드로 실행해야 할 때 고려하는 게 pull_request_target이에요.)
  • schedule은 저장소가 오랫동안 활동이 없으면 간헐적으로 지연·비활성화될 수 있어요.
  • 어떤 이벤트가 정확히 언제 발생하는지, 어떤 컨텍스트 필드가 있는지는 공식 레퍼런스를 꼭 확인하세요. 이벤트마다 github.event.*에 담기는 내용이 달라요.

더 알아보기