GitHub Actions 트리거 이벤트 완벽 가이드

GitHub Actions 워크플로우를 실행시키는 다양한 트리거 이벤트를 알아봅니다. push, pull_request부터 schedule, workflow_dispatch까지 실무에서 자주 사용하는 이벤트들을 초급자도 쉽게 이해할 수 있도록 설명합니다.

---

목차

1. push_이벤트와_브랜치_필터
2. pull_request_이벤트_종류
3. schedule로_크론_작업
4. workflow_dispatch_수동_실행
5. repository_dispatch_외부_트리거
6. 이벤트_필터링_paths와_branches

---

1. push 이벤트와 브랜치 필터

김개발 씨는 오늘 처음으로 GitHub Actions를 설정하게 되었습니다. "코드를 푸시할 때마다 자동으로 테스트가 돌아가면 좋겠는데..." 하고 생각하던 중, 선배가 다가와 말했습니다.

"push 이벤트를 사용하면 돼요. 근데 모든 브랜치에서 실행되면 곤란하니까 필터도 걸어야 해요."

push 이벤트는 GitHub Actions에서 가장 기본이 되는 트리거입니다. 누군가 저장소에 코드를 push할 때마다 워크플로우가 자동으로 실행됩니다.

마치 현관문에 설치된 센서가 누군가 들어올 때마다 조명을 켜는 것과 같습니다. 브랜치 필터를 사용하면 특정 브랜치에서만 워크플로우가 실행되도록 제한할 수 있습니다.

다음 코드를 살펴봅시다.

# .github/workflows/ci.yml
name: CI Pipeline

on:
  push:
    # main과 develop 브랜치에서만 실행
    branches:
      - main
      - develop
    # feature로 시작하는 브랜치도 포함
    branches-ignore:
      - 'release/**'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: npm test

김개발 씨는 입사 3개월 차 주니어 개발자입니다. 팀에서 새로운 프로젝트를 시작하면서 CI/CD 파이프라인을 구축하는 임무를 맡게 되었습니다.

"자동화라... 어디서부터 시작해야 하지?" 막막한 마음으로 검색을 시작했습니다.

선배 개발자 박시니어 씨가 다가와 화면을 살펴봅니다. "GitHub Actions 쓰려고요?

그럼 먼저 push 이벤트부터 이해해야 해요. 모든 자동화의 시작점이거든요." 그렇다면 push 이벤트란 정확히 무엇일까요?

쉽게 비유하자면, push 이벤트는 마치 집 현관에 설치된 동작 감지 센서와 같습니다. 누군가 현관문을 열고 들어오면 센서가 이를 감지하고 자동으로 조명을 켭니다.

마찬가지로 개발자가 코드를 저장소에 push하면, GitHub Actions가 이를 감지하고 설정된 워크플로우를 자동으로 실행합니다. push 이벤트가 없던 시절에는 어땠을까요?

개발자들은 코드를 푸시한 후 직접 터미널을 열어 테스트를 실행해야 했습니다. "npm test 돌렸어요?" "아, 깜빡했네요." 이런 대화가 오가기 일쑤였습니다.

사람이 하는 일이니 실수도 잦았고, 테스트 없이 배포되는 코드도 종종 있었습니다. 바로 이런 문제를 해결하기 위해 push 이벤트 기반 자동화가 등장했습니다.

코드를 push하는 순간 자동으로 테스트가 실행되니 깜빡할 일이 없습니다. 테스트가 실패하면 즉시 알림이 오고, 문제가 있는 코드가 배포되는 것을 막을 수 있습니다.

위의 코드를 한 줄씩 살펴보겠습니다. 먼저 on: push 부분이 핵심입니다.

이 설정이 "push가 발생하면 이 워크플로우를 실행하라"고 GitHub에게 알려줍니다. 그 아래 branches 배열에는 main과 develop이 명시되어 있습니다.

이는 오직 이 두 브랜치에 push될 때만 워크플로우가 실행된다는 의미입니다. branches-ignore는 반대 개념입니다.

여기에 명시된 패턴과 일치하는 브랜치에서는 워크플로우가 실행되지 않습니다. 예제에서는 release로 시작하는 모든 브랜치를 제외했습니다.

실제 현업에서는 어떻게 활용할까요? 대부분의 팀에서는 main 브랜치에 push될 때 전체 테스트와 빌드를 실행합니다.

develop 브랜치에서는 개발용 테스트만 돌리고, feature 브랜치에서는 간단한 린트 검사만 수행하는 식으로 브랜치별로 다른 워크플로우를 설정합니다. 하지만 주의할 점도 있습니다.

초보 개발자들이 흔히 하는 실수 중 하나는 브랜치 필터 없이 push 이벤트를 설정하는 것입니다. 이렇게 하면 모든 브랜치의 모든 push마다 워크플로우가 실행되어 GitHub Actions 사용량이 급증합니다.

무료 플랜의 경우 월 사용량 제한이 있으니 반드시 필요한 브랜치만 필터링해야 합니다. 다시 김개발 씨의 이야기로 돌아가 봅시다.

박시니어 씨의 설명을 들은 김개발 씨는 고개를 끄덕였습니다. "아, 그래서 main 브랜치만 설정하라고 하셨군요!" push 이벤트와 브랜치 필터를 제대로 이해하면 효율적인 CI 파이프라인의 첫 발을 내딛게 됩니다.

실전 팁

💡 - branches와 branches-ignore를 동시에 사용할 경우 branches가 우선 적용됩니다

• 와일드카드 패턴을 활용하면 feature/** 처럼 하위 브랜치 전체를 한 번에 지정할 수 있습니다
• tags 필터를 추가하면 태그 push 시에도 워크플로우를 실행할 수 있습니다

---

2. pull request 이벤트 종류

김개발 씨가 첫 번째 PR을 올렸습니다. 그런데 신기하게도 PR을 열자마자 자동으로 테스트가 돌아갔습니다.

"어? 저는 push만 설정했는데요?" 박시니어 씨가 웃으며 답했습니다.

"그건 pull_request 이벤트예요. PR의 상태 변화를 감지하는 거죠."

pull_request 이벤트는 PR이 열리거나, 수정되거나, 닫힐 때 워크플로우를 실행합니다. 마치 서류 결재 시스템에서 새 결재 요청이 들어오면 자동으로 검토 프로세스가 시작되는 것과 같습니다.

types 옵션을 사용하면 어떤 상태 변화에 반응할지 세밀하게 제어할 수 있습니다.

다음 코드를 살펴봅시다.

# .github/workflows/pr-check.yml
name: PR Validation

on:
  pull_request:
    # 특정 이벤트 타입만 지정
    types:
      - opened      # PR이 처음 열릴 때
      - synchronize # 새 커밋이 push될 때
      - reopened    # 닫힌 PR이 다시 열릴 때
    branches:
      - main

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint check
        run: npm run lint
      - name: Unit tests
        run: npm test

김개발 씨는 열심히 작업한 코드를 PR로 올렸습니다. 그런데 PR 페이지 하단에 노란색 원이 빙글빙글 돌고 있었습니다.

"Checks in progress"라는 문구가 보입니다. 잠시 후 초록색 체크마크로 바뀌었습니다.

"오, 자동으로 테스트가 통과됐네!" 박시니어 씨가 설명을 시작합니다. "그게 바로 pull_request 이벤트예요.

PR이 열리면 자동으로 코드 검증이 시작되는 거죠." pull_request 이벤트는 마치 회사의 결재 시스템과 같습니다. 직원이 휴가 신청서를 제출하면 자동으로 팀장에게 알림이 가고, 검토 프로세스가 시작됩니다.

PR도 마찬가지입니다. 개발자가 PR을 열면 GitHub Actions가 자동으로 코드 검증을 시작합니다.

pull_request 이벤트에서 가장 중요한 것은 types 옵션입니다. PR에는 다양한 상태 변화가 있습니다.

처음 열릴 때(opened), 새 커밋이 추가될 때(synchronize), 닫힐 때(closed), 다시 열릴 때(reopened), 리뷰어가 할당될 때(review_requested) 등 수많은 상태가 존재합니다. 기본적으로 pull_request 이벤트는 opened, synchronize, reopened 세 가지 타입에만 반응합니다.

하지만 types 옵션을 명시적으로 지정하면 원하는 타입만 선택할 수 있습니다. 위의 코드를 자세히 살펴보겠습니다.

types 배열에 opened, synchronize, reopened가 명시되어 있습니다. 이는 PR이 처음 열리거나, 새 커밋이 추가되거나, 닫힌 PR이 다시 열릴 때 워크플로우가 실행된다는 의미입니다.

반면 PR이 닫히거나 라벨이 추가될 때는 실행되지 않습니다. branches: main은 main 브랜치를 대상으로 하는 PR에서만 워크플로우가 실행됨을 의미합니다.

실무에서 pull_request 이벤트가 중요한 이유는 코드 리뷰 전 자동 검증 때문입니다. PR이 열리면 자동으로 린트 검사, 단위 테스트, 빌드 테스트가 실행됩니다.

리뷰어는 이 결과를 보고 코드를 리뷰할지 결정할 수 있습니다. 테스트가 실패한 PR은 리뷰할 필요도 없이 수정을 요청하면 됩니다.

또한 브랜치 보호 규칙과 함께 사용하면 더욱 강력해집니다. GitHub 저장소 설정에서 "Require status checks to pass before merging" 옵션을 활성화하면, 워크플로우가 성공해야만 PR을 머지할 수 있습니다.

테스트가 실패한 코드는 물리적으로 머지가 불가능해집니다. 주의할 점이 있습니다.

pull_request_target이라는 비슷한 이벤트가 있는데, 이는 포크된 저장소에서 오는 PR을 처리할 때 사용합니다. 보안상의 이유로 일반 pull_request와 다르게 동작하니 문서를 꼭 확인해야 합니다.

김개발 씨는 이제 PR을 올릴 때마다 자동으로 테스트가 돌아가는 이유를 이해했습니다. "코드 품질을 자동으로 검증해주니 정말 편하네요!"

실전 팁

💡 - labeled 타입을 사용하면 특정 라벨이 붙은 PR에서만 워크플로우를 실행할 수 있습니다

• pull_request와 push를 동시에 사용할 때는 중복 실행에 주의해야 합니다
• draft PR에서는 ready_for_review 타입을 활용하면 유용합니다

---

3. schedule로 크론 작업

어느 날 김개발 씨가 출근해보니 대시보드에 빨간 경고등이 켜져 있었습니다. "어제 밤에 외부 API가 변경됐대요.

우리 시스템이 영향을 받았어요." 박시니어 씨가 말했습니다. "매일 새벽에 헬스체크를 돌리면 이런 걸 미리 발견할 수 있어요.

schedule 이벤트를 써보세요."

schedule 이벤트는 크론(cron) 표현식을 사용하여 정해진 시간에 워크플로우를 자동 실행합니다. 마치 매일 아침 7시에 울리도록 설정한 알람 시계처럼, 특정 시간이 되면 자동으로 작업이 시작됩니다.

정기적인 테스트, 리포트 생성, 데이터 백업 등에 유용하게 활용됩니다.

다음 코드를 살펴봅시다.

# .github/workflows/scheduled-tasks.yml
name: Scheduled Health Check

on:
  schedule:
    # 매일 UTC 기준 새벽 3시 (한국 시간 정오)
    - cron: '0 3 * * *'
    # 매주 월요일 오전 9시 (UTC)
    - cron: '0 9 * * 1'

jobs:
  health-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check external APIs
        run: |
          curl -f https://api.example.com/health
          echo "API is healthy"
      - name: Run integration tests
        run: npm run test:integration

김개발 씨의 팀은 여러 외부 API에 의존하는 서비스를 운영하고 있습니다. 어느 날 고객으로부터 "결제가 안 돼요"라는 문의가 폭주했습니다.

원인을 파악해보니 결제 API 제공사가 밤새 엔드포인트를 변경한 것이었습니다. "이런 일을 미리 감지할 수는 없을까요?" 김개발 씨가 물었습니다.

박시니어 씨가 답했습니다. "schedule 이벤트를 사용하면 돼요.

매일 새벽에 자동으로 API 상태를 체크하고, 문제가 있으면 슬랙으로 알림을 보내는 거죠." schedule 이벤트는 마치 자동 알람 시계와 같습니다. 한 번 설정해두면 매일 같은 시간에 알람이 울립니다.

우리가 자는 동안에도 말이죠. GitHub Actions도 마찬가지입니다.

설정된 시간이 되면 우리가 자는 새벽에도 자동으로 워크플로우가 실행됩니다. 크론 표현식은 5개의 필드로 구성됩니다.

분(0-59), 시(0-23), 일(1-31), 월(1-12), 요일(0-6)입니다. **'0 3 * * *'**는 "매일 3시 0분에"라는 의미입니다.

별표(*)는 "모든 값"을 의미합니다. 따라서 모든 일, 모든 월, 모든 요일에 실행됩니다.

위 코드에는 두 개의 크론 스케줄이 설정되어 있습니다. 첫 번째 **'0 3 * * *'**는 매일 UTC 기준 새벽 3시에 실행됩니다.

한국 시간으로는 정오 12시입니다. 두 번째 **'0 9 * * 1'**은 매주 월요일 오전 9시(UTC)에 실행됩니다.

마지막 필드의 1은 월요일을 의미합니다. 중요한 점은 시간대가 UTC라는 것입니다.

한국은 UTC+9이므로, 한국 시간 기준으로 새벽 3시에 실행하려면 UTC 기준 전날 오후 6시로 설정해야 합니다. 이 부분을 헷갈리면 예상과 다른 시간에 워크플로우가 실행될 수 있습니다.

실무에서 schedule 이벤트는 다양하게 활용됩니다. 매일 새벽 의존성 취약점 검사를 실행하는 팀도 있고, 매주 월요일 아침에 주간 테스트 리포트를 생성하는 팀도 있습니다.

데이터베이스 백업, 로그 정리, 캐시 갱신 등 정기적으로 수행해야 하는 작업에 안성맞춤입니다. 한 가지 주의사항이 있습니다.

GitHub Actions의 schedule은 정확한 실행 시간을 보장하지 않습니다. 서버 부하에 따라 최대 1시간까지 지연될 수 있습니다.

따라서 정확한 시간에 실행되어야 하는 중요한 작업에는 적합하지 않을 수 있습니다. 또한 저장소에 60일 이상 활동이 없으면 스케줄된 워크플로우가 자동으로 비활성화됩니다.

이 점도 기억해두세요. 김개발 씨는 그날 바로 매일 새벽 3시에 실행되는 헬스체크 워크플로우를 설정했습니다.

이제 외부 API 변경을 미리 감지할 수 있게 되었습니다.

실전 팁

💡 - crontab.guru 사이트에서 크론 표현식을 쉽게 만들고 테스트할 수 있습니다

• schedule은 기본 브랜치(main/master)에서만 동작하므로 설정 변경 후 반드시 머지해야 합니다
• 여러 크론 스케줄을 배열로 지정하면 여러 시간대에 실행할 수 있습니다

---

4. workflow dispatch 수동 실행

"급해요! 지금 바로 배포해야 해요!" 김개발 씨가 다급하게 외쳤습니다.

하지만 배포 파이프라인은 main 브랜치에 push해야만 실행되도록 설정되어 있었습니다. 박시니어 씨가 말했습니다.

"workflow_dispatch를 추가해두면 버튼 하나로 언제든 수동 실행할 수 있어요."

workflow_dispatch 이벤트는 GitHub 웹 UI나 API를 통해 워크플로우를 수동으로 실행할 수 있게 해줍니다. 마치 자동 세차기에 수동 버튼이 있는 것처럼, 평소에는 자동으로 돌아가지만 필요할 때는 직접 실행할 수 있습니다.

입력 파라미터를 받아 동적으로 워크플로우를 제어할 수도 있습니다.

다음 코드를 살펴봅시다.

# .github/workflows/deploy.yml
name: Manual Deploy

on:
  workflow_dispatch:
    inputs:
      environment:
        description: '배포 환경 선택'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production
      debug_mode:
        description: '디버그 모드 활성화'
        required: false
        type: boolean
        default: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to ${{ inputs.environment }}
        run: |
          echo "Deploying to ${{ inputs.environment }}"
          if [ "${{ inputs.debug_mode }}" = "true" ]; then
            echo "Debug mode is ON"
          fi

금요일 오후 5시, 김개발 씨의 팀에 긴급 상황이 발생했습니다. 프로덕션에서 크리티컬한 버그가 발견된 것입니다.

핫픽스 코드는 이미 준비되었지만, 배포 파이프라인은 main 브랜치에 push될 때만 실행되도록 설정되어 있었습니다. "지금 PR 올리고 리뷰 받고 머지하려면 시간이 너무 걸려요." 김개발 씨가 안절부절못합니다.

박시니어 씨가 침착하게 말했습니다. "그래서 workflow_dispatch를 미리 설정해뒀어요.

Actions 탭에서 버튼만 누르면 바로 배포할 수 있어요." workflow_dispatch는 마치 비상 버튼과 같습니다. 평소에는 자동으로 돌아가는 시스템이지만, 긴급한 상황에서는 사람이 직접 버튼을 눌러 즉시 실행할 수 있습니다.

이 유연성이 workflow_dispatch의 핵심입니다. 더 강력한 기능은 inputs 옵션입니다.

inputs을 사용하면 워크플로우 실행 시 사용자로부터 값을 입력받을 수 있습니다. 위 코드에서는 배포 환경(staging 또는 production)을 선택하고, 디버그 모드를 켜거나 끌 수 있습니다.

type: choice는 드롭다운 메뉴로 미리 정의된 옵션 중에서 선택하게 합니다. type: boolean은 체크박스로 표시됩니다.

이 외에도 string, number 타입을 사용할 수 있습니다. 코드에서 입력값은 ${{ inputs.environment }} 형태로 접근합니다.

GitHub 웹 UI에서 워크플로우를 실행하면 이 값들이 폼으로 표시됩니다. 사용자가 값을 입력하거나 선택하면 그 값이 워크플로우로 전달됩니다.

실무에서 workflow_dispatch는 정말 다양하게 활용됩니다. 긴급 배포뿐만 아니라, 특정 버전으로 롤백하기, 캐시 강제 초기화하기, 테스트 환경 재구성하기 등 필요할 때만 수동으로 실행해야 하는 작업에 적합합니다.

gh CLI를 사용하면 터미널에서도 실행할 수 있습니다. gh workflow run deploy.yml -f environment=production -f debug_mode=true 이렇게 하면 웹 UI에 접속하지 않고도 바로 워크플로우를 트리거할 수 있습니다.

CI/CD 파이프라인 내에서 다른 워크플로우를 호출할 때도 유용합니다. 한 가지 주의할 점이 있습니다.

workflow_dispatch는 기본 브랜치에 워크플로우 파일이 존재해야만 UI에 나타납니다. 새 브랜치에서 워크플로우를 작성하고 있다면 먼저 main에 머지해야 합니다.

김개발 씨는 그 금요일 오후, workflow_dispatch 덕분에 5분 만에 핫픽스를 배포할 수 있었습니다. "이제 긴급 상황에도 당황하지 않아도 되겠어요!"

실전 팁

💡 - required: true로 설정하면 해당 입력값 없이는 워크플로우를 실행할 수 없습니다

• gh workflow run 명령으로 CLI에서도 수동 실행이 가능합니다
• 브랜치를 선택하여 특정 브랜치의 워크플로우를 실행할 수도 있습니다

---

5. repository dispatch 외부 트리거

김개발 씨 팀의 서비스는 여러 개의 마이크로서비스로 구성되어 있습니다. "API 서버가 배포되면 자동으로 프론트엔드 테스트가 돌아가면 좋겠는데..." 박시니어 씨가 말했습니다.

"repository_dispatch를 쓰면 한 저장소에서 다른 저장소의 워크플로우를 트리거할 수 있어요."

repository_dispatch 이벤트는 외부 시스템이나 다른 저장소에서 API 호출을 통해 워크플로우를 실행합니다. 마치 도미노처럼 한 곳에서 시작된 이벤트가 연쇄적으로 다른 시스템을 깨우는 것과 같습니다.

마이크로서비스 아키텍처에서 저장소 간 연동에 특히 유용합니다.

다음 코드를 살펴봅시다.

# 트리거 받는 쪽: .github/workflows/on-api-deploy.yml
name: On API Deploy

on:
  repository_dispatch:
    types: [api-deployed, config-updated]

jobs:
  run-e2e-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Show event info
        run: |
          echo "Event type: ${{ github.event.action }}"
          echo "API version: ${{ github.event.client_payload.version }}"
      - name: Run E2E tests
        run: npm run test:e2e

# 트리거 보내는 쪽 (curl 예시)
# curl -X POST \
#   -H "Authorization: token $GITHUB_TOKEN" \
#   -H "Accept: application/vnd.github.v3+json" \
#   https://api.github.com/repos/owner/repo/dispatches \
#   -d '{"event_type":"api-deployed","client_payload":{"version":"1.2.3"}}'

김개발 씨의 팀은 백엔드 API 서버와 프론트엔드 앱을 별도의 저장소에서 관리하고 있습니다. 문제는 API 서버가 배포될 때마다 프론트엔드 팀이 수동으로 E2E 테스트를 실행해야 한다는 것이었습니다.

"API 서버 배포됐어요?" "네, 방금요." "그럼 테스트 돌릴게요." 이런 대화가 매번 반복되었습니다. 박시니어 씨가 해결책을 제시했습니다.

"repository_dispatch를 쓰면 API 서버가 배포될 때 자동으로 프론트엔드 저장소의 테스트가 실행되게 할 수 있어요." repository_dispatch는 마치 도미노와 같습니다. 첫 번째 도미노가 쓰러지면 그 충격이 다음 도미노로 전달되고, 연쇄적으로 모든 도미노가 쓰러집니다.

마찬가지로 API 저장소에서 배포가 완료되면 그 신호가 프론트엔드 저장소로 전달되어 테스트가 자동으로 시작됩니다. 위 코드의 구조를 살펴보겠습니다.

**types: [api-deployed, config-updated]**는 이 워크플로우가 반응할 이벤트 타입을 정의합니다. 외부에서 "api-deployed" 또는 "config-updated" 타입으로 dispatch 요청을 보내면 워크플로우가 실행됩니다.

client_payload는 이벤트와 함께 전달되는 데이터입니다. 위 예시에서는 API 버전 정보를 전달하고 있습니다.

워크플로우에서는 **${{ github.event.client_payload.version }}**으로 이 값에 접근할 수 있습니다. 트리거를 보내는 쪽은 GitHub API를 호출합니다.

curl 명령이나 다른 워크플로우에서 GitHub API의 dispatches 엔드포인트에 POST 요청을 보내면 됩니다. 이때 반드시 repo 권한이 있는 토큰이 필요합니다.

실무에서 repository_dispatch는 다양한 시나리오에서 활용됩니다. 마이크로서비스 아키텍처에서 서비스 간 연동이 대표적입니다.

인프라 저장소가 업데이트되면 애플리케이션 저장소의 재배포가 트리거되기도 합니다. 외부 CI 시스템(Jenkins, CircleCI 등)에서 GitHub Actions 워크플로우를 실행하는 데에도 사용됩니다.

주의할 점이 있습니다. repository_dispatch를 사용하려면 적절한 권한 설정이 필수입니다.

Personal Access Token이나 GitHub App 토큰에 repo 권한이 있어야 합니다. 또한 이 이벤트는 기본 브랜치에서만 동작합니다.

보안 측면에서도 주의가 필요합니다. 누구나 API를 호출할 수 있다면 악의적인 워크플로우 실행이 가능해집니다.

토큰 관리를 철저히 하고, 필요하다면 client_payload에 검증용 시크릿을 포함시키는 것도 좋은 방법입니다. 김개발 씨는 API 저장소의 배포 워크플로우 마지막에 repository_dispatch를 추가했습니다.

이제 API가 배포되면 자동으로 프론트엔드 E2E 테스트가 실행됩니다. "완전 자동화됐네요!"

실전 팁

💡 - client_payload에 필요한 데이터를 담아 워크플로우에 전달할 수 있습니다

• types 필드로 여러 종류의 이벤트를 구분하여 처리할 수 있습니다
• 보안을 위해 dispatch 호출에 사용하는 토큰은 최소 권한 원칙을 따르세요

---

6. 이벤트 필터링 paths와 branches

김개발 씨가 문서만 수정했는데 전체 빌드가 돌아갔습니다. 30분이나 걸리는 빌드를요.

"README만 고쳤는데 왜 빌드가 도는 거예요?" 박시니어 씨가 답했습니다. "paths 필터를 설정하지 않아서 그래요.

특정 파일이 변경됐을 때만 실행되게 할 수 있어요."

paths와 branches 필터는 워크플로우가 실행되는 조건을 세밀하게 제어합니다. 마치 보안 검색대에서 특정 물품만 검사하는 것처럼, 특정 경로나 브랜치의 변경에만 반응하도록 설정할 수 있습니다.

불필요한 워크플로우 실행을 줄여 비용과 시간을 절약합니다.

다음 코드를 살펴봅시다.

# .github/workflows/smart-ci.yml
name: Smart CI

on:
  push:
    branches:
      - main
      - 'release/**'
    paths:
      - 'src/**'
      - 'package.json'
      - '!src/**/*.test.ts'  # 테스트 파일 제외
    paths-ignore:
      - 'docs/**'
      - '*.md'
      - '.github/**'

  pull_request:
    branches:
      - main
    paths:
      - 'src/**'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: npm run build
      - name: Test
        run: npm test

김개발 씨의 팀에서는 한 가지 불만이 있었습니다. README.md 파일을 한 줄 수정해도 전체 CI 파이프라인이 돌아가는 것이었습니다.

빌드에 30분, 테스트에 20분. 문서 수정 하나에 50분을 낭비하고 있었습니다.

"GitHub Actions 무료 사용량도 금방 바닥나요." 팀원들이 하소연했습니다. 박시니어 씨가 해결책을 제시했습니다.

"paths 필터를 쓰면 돼요. 소스 코드가 변경됐을 때만 빌드가 실행되게 할 수 있어요." paths 필터는 마치 선별적 보안 검색과 같습니다.

공항에서 모든 승객을 검사하지 않고, 특정 조건에 해당하는 승객만 추가 검사를 받는 것처럼요. 워크플로우도 마찬가지입니다.

모든 파일 변경에 반응하는 대신, 중요한 파일이 변경됐을 때만 실행됩니다. 위 코드에서 paths 필터를 살펴보겠습니다.

paths: ['src/', 'package.json']**은 src 디렉토리 내의 모든 파일 또는 package.json이 변경됐을 때만 워크플로우가 실행됨을 의미합니다. 다른 파일만 변경되면 워크플로우는 실행되지 않습니다.

!src//*.test.ts**는 부정 패턴입니다. 느낌표로 시작하는 패턴은 해당 파일을 제외합니다.

즉, 테스트 파일만 수정했을 때는 빌드가 실행되지 않습니다. paths-ignore는 paths의 반대 개념입니다.

여기에 명시된 경로의 파일이 변경되면 워크플로우가 실행되지 않습니다. 위 예시에서는 docs 디렉토리, 마크다운 파일, .github 디렉토리가 제외되어 있습니다.

문서나 워크플로우 설정 파일만 수정했을 때는 빌드가 돌아가지 않습니다. paths와 paths-ignore를 동시에 사용하면 어떻게 될까요?

paths가 우선합니다. paths로 지정된 파일 중에서 paths-ignore에 해당하지 않는 파일이 변경됐을 때만 워크플로우가 실행됩니다.

하지만 복잡성을 피하기 위해 둘 중 하나만 사용하는 것이 권장됩니다. branches 필터도 비슷한 원리로 동작합니다.

branches: [main, 'release/']**는 main 브랜치와 release로 시작하는 모든 브랜치에서만 워크플로우가 실행됨을 의미합니다. 개인 feature 브랜치에서는 실행되지 않습니다.

branches-ignore를 사용하면 특정 브랜치를 제외할 수 있습니다. 실험적인 브랜치나 WIP 브랜치를 제외할 때 유용합니다.

와일드카드 패턴도 강력합니다. 'feature/'**는 feature로 시작하는 모든 하위 브랜치를 의미합니다.

'/test-*'**처럼 중간에 와일드카드를 사용할 수도 있습니다. 실무에서는 이런 필터링이 정말 중요합니다.

대형 프로젝트에서는 워크플로우가 하루에 수백 번 실행될 수 있습니다. 불필요한 실행을 줄이면 GitHub Actions 비용을 크게 절감할 수 있습니다.

또한 피드백 속도도 빨라집니다. 관련 없는 빌드를 기다릴 필요가 없으니까요.

김개발 씨는 paths 필터를 추가한 후 팀의 월간 Actions 사용량이 40%나 줄어든 것을 확인했습니다. "이제 문서 수정할 때 마음이 편해졌어요!"

실전 팁

💡 - paths와 branches 필터는 AND 조건으로 동작합니다. 둘 다 만족해야 워크플로우가 실행됩니다

• 경로 패턴에서 **는 디렉토리를 재귀적으로 매칭하고, *는 파일명만 매칭합니다
• 필터를 너무 좁게 설정하면 필요한 빌드가 누락될 수 있으니 주의하세요

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!