워크플로 트리거하기

GitHub Actions 워크플로를 자동으로 트리거하는 방법을 알려드릴게요. on 키만 잘 이해하면 워크플로가 언제·어떻게 실행될지 완벽히 제어할 수 있어요.

출처: 문서

본문

GitHub Actions 워크플로를 자동으로 트리거하는 방법

사전 요구 사항

워크플로와 트리거 방법에 대해 더 자세히 알아보려면 Workflows를 참고하세요.

워크플로에서 워크플로 트리거하기

저장소의 GITHUB_TOKEN을 사용해서 작업을 수행하면, GITHUB_TOKEN으로 트리거된 이벤트는 다음 예외를 제외하고 새 워크플로 실행을 만들지 않습니다:

workflow_dispatch와 repository_dispatch 이벤트는 항상 워크플로 실행을 만듭니다.
opened, synchronize, reopened 활동 유형의 pull_request 이벤트: GITHUB_TOKEN을 사용하는 워크플로가 풀 리퀘스트를 만들거나 업데이트하면, 결과로 생성되는 pull_request 이벤트는 approval-required(승인 필요) 상태의 워크플로 실행을 만듭니다. 풀 리퀘스트의 머지 상자에 배너가 표시되고, 저장소에 write 권한이 있는 사용자가 Approve workflows to run을 선택해서 실행을 시작할 수 있습니다. 다른 pull_request 활동 유형(예: labeled, edited, closed)은 워크플로 실행을 만들지 않습니다. 이는 재귀적 워크플로 실행을 방지하면서도 자동화가 만든 풀 리퀘스트에서 CI 워크플로가 실행되도록 허용합니다. 워크플로 실행 승인에 대한 자세한 내용은 Approving workflow runs from forks를 참고하세요.

다른 모든 이벤트의 경우, 이 동작은 실수로 재귀적 워크플로 실행을 만드는 것을 방지합니다. 예를 들어 워크플로 실행이 저장소의 GITHUB_TOKEN으로 코드를 푸시하면, 저장소에 push 이벤트 발생 시 실행되도록 구성된 워크플로가 있어도 새 워크플로가 실행되지 않습니다. 자세한 내용은 Use GITHUB_TOKEN for authentication in workflows을 참고하세요.

워크플로 실행 안에서 워크플로를 트리거하고 싶다면, 토큰이 필요한 이벤트를 트리거할 때 GITHUB_TOKEN 대신 GitHub App 설치 접근 토큰이나 개인용 액세스 토큰(personal access token)을 사용할 수 있습니다. 이 대안 중 하나를 사용하면 자동화가 풀 리퀘스트를 만들거나 업데이트할 때 pull_request 워크플로가 위에서 설명한 승인 프롬프트 없이 자동으로 실행되게 할 수도 있습니다.

GitHub App을 사용한다면 GitHub App을 만들고 앱 ID와 비밀 키를 시크릿으로 저장해야 합니다. 자세한 내용은 Making authenticated API requests with a GitHub App in a GitHub Actions workflow를 참고하세요. 개인용 액세스 토큰을 사용한다면 개인용 액세스 토큰을 만들고 시크릿으로 저장해야 합니다. 개인용 액세스 토큰 만들기에 대한 자세한 내용은 Managing your personal access tokens를 참고하세요. 시크릿 저장에 대한 자세한 내용은 Using secrets in GitHub Actions를 참고하세요.

GitHub Actions 사용 비용을 최소화하려면 재귀적이거나 의도하지 않은 워크플로 실행을 만들지 않도록 주의하세요.

예를 들어 다음 워크플로는 GitHub CLI를 통해 이슈에 라벨을 추가하는 데 개인용 액세스 토큰(MY_TOKEN이라는 시크릿으로 저장됨)을 사용합니다. 라벨이 추가될 때 실행되는 워크플로는 이 스텝이 수행되면 실행됩니다.

on:
  issues:
    types:
      - opened

jobs:
  label_issue:
    runs-on: ubuntu-latest
    steps:
      - env:
          GH_TOKEN: ${{ secrets.MY_TOKEN }}
          ISSUE_URL: ${{ github.event.issue.html_url }}
        run: |
          gh issue edit $ISSUE_URL --add-label "triage"

반대로 다음 워크플로는 GITHUB_TOKEN을 사용해서 이슈에 라벨을 추가합니다. 이 워크플로는 라벨이 추가될 때 실행되는 워크플로를 트리거하지 않습니다.

on:
  issues:
    types:
      - opened

jobs:
  label_issue:
    runs-on: ubuntu-latest
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ISSUE_URL: ${{ github.event.issue.html_url }}
        run: |
          gh issue edit $ISSUE_URL --add-label "triage"

이벤트를 사용해서 워크플로 트리거하기

on 키를 사용해서 워크플로를 트리거할 이벤트를 지정합니다. 사용할 수 있는 이벤트에 대한 자세한 내용은 Events that trigger workflows를 참고하세요.

단일 이벤트 사용하기

예를 들어 다음 on 값을 가진 워크플로는 워크플로 저장소의 어떤 브랜치에든 push가 발생하면 실행됩니다:

on: push

여러 이벤트 사용하기

단일 이벤트나 여러 이벤트를 지정할 수 있습니다. 예를 들어 다음 on 값을 가진 워크플로는 저장소의 어떤 브랜치에 push가 발생하거나 누군가가 저장소를 포크하면 실행됩니다:

on: [push, fork]

여러 이벤트를 지정하면 이벤트 중 하나만 발생해도 워크플로가 트리거됩니다. 워크플로의 트리거 이벤트 여러 개가 동시에 발생하면 여러 워크플로 실행이 트리거됩니다.

여러 이벤트와 함께 활동 유형 및 필터 사용하기

활동 유형과 필터를 사용해서 워크플로가 실행될 시점을 더 세밀하게 제어할 수 있습니다. 자세한 내용은 Using event activity types와 Using filters를 참고하세요. 이벤트에 활동 유형이나 필터를 지정하고 워크플로가 여러 이벤트에서 트리거되는 경우, 각 이벤트를 개별적으로 구성해야 합니다. 구성이 없는 이벤트를 포함한 모든 이벤트에 콜론(:)을 추가해야 합니다.

예를 들어 다음 on 값을 가진 워크플로는 다음과 같은 경우에 실행됩니다:

라벨이 생성될 때
저장소의 main 브랜치에 push가 발생할 때
GitHub Pages가 활성화된 브랜치에 push가 발생할 때

on:
  label:
    types:
      - created
  push:
    branches:
      - main
  page_build:

이벤트 활동 유형 사용하기

일부 이벤트는 워크플로가 실행될 시점을 더 세밀하게 제어할 수 있는 활동 유형을 가집니다. on.<event_name>.types를 사용해서 워크플로 실행을 트리거할 이벤트 활동 유형을 정의합니다.

예를 들어 issue_comment 이벤트에는 created, edited, deleted 활동 유형이 있습니다. 워크플로가 label 이벤트에서 트리거되면 라벨이 생성, 수정, 삭제될 때마다 실행됩니다. label 이벤트에 created 활동 유형을 지정하면 라벨이 생성될 때만 실행되고 수정이나 삭제 시에는 실행되지 않습니다.

on:
  label:
    types:
      - created

여러 활동 유형을 지정하면 이벤트 활동 유형 중 하나만 발생해도 워크플로가 트리거됩니다. 워크플로의 트리거 이벤트 활동 유형 여러 개가 동시에 발생하면 여러 워크플로 실행이 트리거됩니다. 예를 들어 다음 워크플로는 이슈가 열리거나 라벨이 지정될 때 트리거됩니다. 라벨이 두 개인 이슈가 열리면 세 개의 워크플로 실행이 시작됩니다: 이슈 열림 이벤트 하나와 이슈 라벨 지정 이벤트 두 개입니다.

on:
  issues:
    types:
      - opened
      - labeled

각 이벤트와 활동 유형에 대한 자세한 내용은 Events that trigger workflows를 참고하세요.

필터 사용하기

일부 이벤트는 워크플로가 실행될 시점을 더 세밀하게 제어할 수 있는 필터를 가집니다.

예를 들어 push 이벤트에는 branches 필터가 있어서, 아무 push에서나 실행되는 대신 branches 필터와 일치하는 브랜치에 push가 발생할 때만 워크플로가 실행되게 합니다.

on:
  push:
    branches:
      - main
      - 'releases/**'

필터를 사용해서 풀 리퀘스트 이벤트의 특정 브랜치 대상 지정하기

pull_request와 pull_request_target 이벤트를 사용할 때 특정 브랜치를 대상으로 하는 풀 리퀘스트에서만 워크플로가 실행되도록 구성할 수 있습니다.

브랜치 이름 패턴을 포함하려 하거나 포함·제외를 모두 하려면 branches 필터를 사용합니다. 브랜치 이름 패턴만 제외하려면 branches-ignore 필터를 사용합니다. 워크플로에서 한 이벤트에 branches와 branches-ignore 필터를 둘 다 사용할 수 없습니다.

branches/branches-ignore와 paths/paths-ignore를 모두 정의하면 두 필터가 모두 충족될 때만 워크플로가 실행됩니다.

branches와 branches-ignore 키워드는 *, **, +, ?, ! 등의 문자를 사용해서 둘 이상의 브랜치 이름을 매칭하는 glob 패턴을 받습니다. 이름에 이러한 문자 중 하나가 포함되어 있고 리터럴 매칭을 원한다면, 각 특수 문자를 \\로 이스케이프해야 합니다. glob 패턴에 대한 자세한 내용은 Workflow syntax for GitHub Actions를 참고하세요.

예시: 브랜치 포함하기

branches에 정의된 패턴은 Git ref의 이름에 대해 평가됩니다. 예를 들어 다음 워크플로는 다음과 같은 대상을 가진 풀 리퀘스트에 대한 pull_request 이벤트가 있을 때마다 실행됩니다:

main이라는 이름의 브랜치(refs/heads/main)
mona/octocat이라는 이름의 브랜치(refs/heads/mona/octocat)
releases/10처럼 releases/로 시작하는 이름의 브랜치(refs/heads/releases/10)

on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches:
      - main
      - 'mona/octocat'
      - 'releases/**'

브랜치 필터링, 경로 필터링, 또는 커밋 메시지로 인해 워크플로가 건너뛰어지면 해당 워크플로와 연결된 검사(checks)는 "Pending" 상태로 유지됩니다. 해당 검사들의 성공을 요구하는 풀 리퀘스트는 머지가 차단됩니다.

예시: 브랜치 제외하기

패턴이 branches-ignore 패턴과 일치하면 워크플로가 실행되지 않습니다. branches-ignore에 정의된 패턴은 Git ref의 이름에 대해 평가됩니다. 예를 들어 다음 워크플로는 풀 리퀘스트가 다음을 대상으로 하지 않는 한 pull_request 이벤트가 있을 때마다 실행됩니다:

mona/octocat이라는 이름의 브랜치(refs/heads/mona/octocat)
releases/beta/3-alpha(refs/heads/releases/beta/3-alpha)처럼 releases/**-alpha와 일치하는 이름의 브랜치

on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches-ignore:
      - 'mona/octocat'
      - 'releases/**-alpha'

예시: 브랜치 포함 및 제외하기

단일 워크플로에서 branches와 branches-ignore를 사용해서 같은 이벤트를 필터링할 수 없습니다. 단일 이벤트에 브랜치 패턴을 포함·제외 모두 하려면 ! 문자와 함께 branches 필터를 사용해서 제외할 브랜치를 지정합니다.

! 문자로 브랜치를 정의했다면 ! 문자 없이도 브랜치를 최소 하나 이상 정의해야 합니다. 브랜치만 제외하려면 branches-ignore를 사용하세요.

패턴을 정의하는 순서가 중요합니다.

양수 매칭(positive match) 뒤에 나오는 일치하는 음수 패턴(!가 붙은)은 Git ref를 제외합니다.
음수 매칭 뒤에 나오는 일치하는 양수 패턴은 Git ref를 다시 포함합니다.

다음 워크플로는 releases/10이나 releases/beta/mona를 대상으로 하는 풀 리퀘스트의 pull_request 이벤트에서 실행되지만, !releases/**-alpha 음수 패턴이 양수 패턴 뒤에 오기 때문에 releases/10-alpha나 releases/beta/3-alpha를 대상으로 하는 풀 리퀘스트에서는 실행되지 않습니다.

on:
  pull_request:
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

필터를 사용해서 push 이벤트의 특정 브랜치 또는 태그 대상 지정하기

push 이벤트를 사용할 때 특정 브랜치나 태그에서 워크플로가 실행되도록 구성할 수 있습니다.

태그 이름 패턴을 포함하려 하거나 포함·제외를 모두 하려면 tags 필터를 사용합니다. 태그 이름 패턴만 제외하려면 tags-ignore 필터를 사용합니다. 워크플로에서 한 이벤트에 tags와 tags-ignore 필터를 둘 다 사용할 수 없습니다.

tags/tags-ignore만 정의하거나 branches/branches-ignore만 정의하면 정의되지 않은 Git ref에 영향을 주는 이벤트에는 워크플로가 실행되지 않습니다. tags/tags-ignore나 branches/branches-ignore를 모두 정의하지 않으면 브랜치나 태그에 영향을 주는 이벤트에 대해 워크플로가 실행됩니다. branches/branches-ignore와 paths/paths-ignore를 모두 정의하면 두 필터가 모두 충족될 때만 워크플로가 실행됩니다.

branches, branches-ignore, tags, tags-ignore 키워드는 *, **, +, ?, ! 등의 문자를 사용해서 둘 이상의 브랜치나 태그 이름을 매칭하는 glob 패턴을 받습니다. 이름에 이러한 문자 중 하나가 포함되어 있고 리터럴 매칭을 원한다면 각 특수 문자를 \\로 이스케이프해야 합니다. glob 패턴에 대한 자세한 내용은 Workflow syntax for GitHub Actions를 참고하세요.

예시: 브랜치와 태그 포함하기

branches와 tags에 정의된 패턴은 Git ref의 이름에 대해 평가됩니다. 예를 들어 다음 워크플로는 다음에 대한 push 이벤트가 있을 때마다 실행됩니다:

main이라는 이름의 브랜치(refs/heads/main)
mona/octocat이라는 이름의 브랜치(refs/heads/mona/octocat)
releases/10처럼 releases/로 시작하는 이름의 브랜치(refs/heads/releases/10)
v2라는 이름의 태그(refs/tags/v2)
v1.9.1처럼 v1.로 시작하는 이름의 태그(refs/tags/v1.9.1)

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches:
      - main
      - 'mona/octocat'
      - 'releases/**'
    # Sequence of patterns matched against refs/tags
    tags:
      - v2
      - v1.*

예시: 브랜치와 태그 제외하기

패턴이 branches-ignore나 tags-ignore 패턴과 일치하면 워크플로가 실행되지 않습니다. branches와 tags에 정의된 패턴은 Git ref의 이름에 대해 평가됩니다. 예를 들어 다음 워크플로는 push 이벤트가 다음이 아닌 한 실행됩니다:

mona/octocat이라는 이름의 브랜치(refs/heads/mona/octocat)
releases/beta/3-alpha(refs/heads/releases/beta/3-alpha)처럼 releases/**-alpha와 일치하는 이름의 브랜치
v2라는 이름의 태그(refs/tags/v2)
v1.9처럼 v1.로 시작하는 이름의 태그(refs/tags/v1.9)

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches-ignore:
      - 'mona/octocat'
      - 'releases/**-alpha'
    # Sequence of patterns matched against refs/tags
    tags-ignore:
      - v2
      - v1.*

예시: 브랜치와 태그 포함 및 제외하기

단일 워크플로에서 branches와 branches-ignore를 사용해서 같은 이벤트를 필터링할 수 없습니다. 마찬가지로 단일 워크플로에서 tags와 tags-ignore를 사용해서 같은 이벤트를 필터링할 수 없습니다. 단일 이벤트에 브랜치나 태그 패턴을 포함·제외 모두 하려면 ! 문자와 함께 branches 또는 tags 필터를 사용해서 제외할 브랜치나 태그를 지정합니다.

! 문자로 브랜치를 정의했다면 ! 문자 없이도 브랜치를 최소 하나 이상 정의해야 합니다. 브랜치만 제외하려면 branches-ignore를 사용하세요. 마찬가지로 ! 문자로 태그를 정의했다면 ! 문자 없이도 태그를 최소 하나 이상 정의해야 합니다. 태그만 제외하려면 tags-ignore를 사용하세요.

패턴을 정의하는 순서가 중요합니다.

양수 매칭 뒤에 나오는 일치하는 음수 패턴(!가 붙은)은 Git ref를 제외합니다.
음수 매칭 뒤에 나오는 일치하는 양수 패턴은 Git ref를 다시 포함합니다.

다음 워크플로는 releases/10이나 releases/beta/mona에 대한 push에서 실행되지만, !releases/**-alpha 음수 패턴이 양수 패턴 뒤에 오기 때문에 releases/10-alpha나 releases/beta/3-alpha에서는 실행되지 않습니다.

on:
  push:
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

필터를 사용해서 풀 리퀘스트 또는 push 이벤트의 특정 경로 대상 지정하기

push와 pull_request 이벤트를 사용할 때 변경된 파일 경로를 기준으로 워크플로가 실행되도록 구성할 수 있습니다. 경로 필터는 태그 push에는 평가되지 않습니다.

파일 경로 패턴을 포함하려 하거나 포함·제외를 모두 하려면 paths 필터를 사용합니다. 파일 경로 패턴만 제외하려면 paths-ignore 필터를 사용합니다. 워크플로에서 한 이벤트에 paths와 paths-ignore 필터를 둘 다 사용할 수 없습니다. 단일 이벤트에 경로 패턴을 포함·제외 모두 하려면 ! 문자를 붙인 paths 필터를 사용해서 제외할 경로를 지정합니다.

[!NOTE] paths 패턴을 정의하는 순서가 중요합니다:

양수 매칭 뒤에 나오는 일치하는 음수 패턴(!가 붙은)은 경로를 제외합니다.

음수 매칭 뒤에 나오는 일치하는 양수 패턴은 경로를 다시 포함합니다.

branches/branches-ignore와 paths/paths-ignore를 모두 정의하면 두 필터가 모두 충족될 때만 워크플로가 실행됩니다.

paths와 paths-ignore 키워드는 *와 ** 와일드카드 문자를 사용해서 둘 이상의 경로 이름을 매칭하는 glob 패턴을 받습니다. 자세한 내용은 Workflow syntax for GitHub Actions를 참고하세요.

예시: 경로 포함하기

paths 필터의 패턴과 일치하는 경로가 하나 이상 있으면 워크플로가 실행됩니다. 예를 들어 다음 워크플로는 JavaScript 파일(.js)을 push할 때마다 실행됩니다.

on:
  push:
    paths:
      - '**.js'

경로 필터링, 브랜치 필터링, 또는 커밋 메시지로 인해 워크플로가 건너뛰어지면 해당 워크플로와 연결된 검사는 "Pending" 상태로 유지됩니다. 해당 검사들의 성공을 요구하는 풀 리퀘스트는 머지가 차단됩니다.

예시: 경로 제외하기

모든 경로 이름이 paths-ignore의 패턴과 일치하면 워크플로가 실행되지 않습니다. 일부 경로 이름이 패턴과 일치하더라도 paths-ignore의 패턴과 일치하지 않는 경로 이름이 하나라도 있으면 워크플로가 실행됩니다.

다음 경로 필터를 가진 워크플로는 저장소 루트의 docs 디렉터리 밖에 있는 파일을 하나 이상 포함하는 push 이벤트에서만 실행됩니다.

on:
  push:
    paths-ignore:
      - 'docs/**'

예시: 경로 포함 및 제외하기

단일 워크플로에서 paths와 paths-ignore를 사용해서 같은 이벤트를 필터링할 수 없습니다. 단일 이벤트에 경로 패턴을 포함·제외 모두 하려면 ! 문자를 붙인 paths 필터를 사용해서 제외할 경로를 지정합니다.

! 문자로 경로를 정의했다면 ! 문자 없이도 경로를 최소 하나 이상 정의해야 합니다. 경로만 제외하려면 paths-ignore를 사용하세요.

paths 패턴을 정의하는 순서가 중요합니다:

양수 매칭 뒤에 나오는 일치하는 음수 패턴(!가 붙은)은 경로를 제외합니다.
음수 매칭 뒤에 나오는 일치하는 양수 패턴은 경로를 다시 포함합니다.

이 예시는 push 이벤트가 파일이 sub-project/docs 디렉터리에 있지 않은 한 sub-project 디렉터리나 그 하위 디렉터리에 파일을 포함할 때마다 실행됩니다. 예를 들어 sub-project/index.js나 sub-project/src/index.js를 변경하는 push는 워크플로 실행을 트리거하지만, sub-project/docs/readme.md만 변경하는 push는 트리거하지 않습니다.

on:
  push:
    paths:
      - 'sub-project/**'
      - '!sub-project/docs/**'

Git diff 비교

필터는 변경된 파일을 평가하고 paths-ignore나 paths 목록과 비교해서 워크플로가 실행되어야 하는지 결정합니다. 변경된 파일이 없으면 워크플로가 실행되지 않습니다.

GitHub는 push에 대해서는 2점(two-dot) diff를, 풀 리퀘스트에 대해서는 3점(three-dot) diff를 사용해서 변경된 파일 목록을 생성합니다:

풀 리퀘스트: 3점 diff는 토픽 브랜치의 가장 최근 버전과 토픽 브랜치가 베이스 브랜치와 마지막으로 동기화된 커밋을 비교합니다.
기존 브랜치로의 push: 2점 diff는 head와 base SHA를 직접 비교합니다.
새 브랜치로의 push: 푸시된 가장 깊은 커밋의 조상의 부모에 대한 2점 diff입니다.

일부 상황에서 GitHub Actions는 필터링된 워크플로가 실행되는 방식을 바꾸는 제한을 적용합니다:

push에 1,000개가 넘는 커밋이 포함되면 워크플로는 항상 실행됩니다.
diff 생성이 타임아웃되면 워크플로는 항상 실행됩니다.
생성된 diff에 3,000개가 넘는 파일이 있고 워크플로 필터가 일치하는 파일이 필터가 반환하는 처음 3,000개 안에 없으면 워크플로는 실행되지 않습니다.

이런 동작이 관찰되면 필터를 더 구체적으로 만들거나, 더 단순한 diff를 만들도록 push와 풀 리퀘스트 방식을 바꿔야 할 수 있습니다.

자세한 내용은 Branches를 참고하세요.

필터를 사용해서 워크플로 실행 이벤트의 특정 브랜치 대상 지정하기

workflow_run 이벤트를 사용할 때, 트리거 워크플로가 어떤 브랜치에서 실행되어야 워크플로를 트리거하는지 지정할 수 있습니다.

branches와 branches-ignore 필터는 *, **, +, ?, ! 등의 문자를 사용해서 둘 이상의 브랜치 이름을 매칭하는 glob 패턴을 받습니다. 이름에 이러한 문자 중 하나가 포함되어 있고 리터럴 매칭을 원한다면 각 특수 문자를 \\로 이스케이프해야 합니다. glob 패턴에 대한 자세한 내용은 Workflow syntax for GitHub Actions를 참고하세요.

예를 들어 다음 트리거를 가진 워크플로는 Build라는 워크플로가 releases/로 시작하는 이름의 브랜치에서 실행될 때만 실행됩니다:

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'

다음 트리거를 가진 워크플로는 Build라는 워크플로가 canary가 아닌 이름의 브랜치에서 실행될 때만 실행됩니다:

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches-ignore:
      - "canary"

워크플로에서 한 이벤트에 branches와 branches-ignore 필터를 둘 다 사용할 수 없습니다. 단일 이벤트에 브랜치 패턴을 포함·제외 모두 하려면 ! 문자와 함께 branches 필터를 사용해서 제외할 브랜치를 지정합니다.

패턴을 정의하는 순서가 중요합니다.

양수 매칭 뒤에 나오는 일치하는 음수 패턴(!가 붙은)은 브랜치를 제외합니다.
음수 매칭 뒤에 나오는 일치하는 양수 패턴은 브랜치를 다시 포함합니다.

예를 들어 다음 트리거를 가진 워크플로는 Build라는 워크플로가 releases/10이나 releases/beta/mona라는 이름의 브랜치에서 실행될 때 실행되지만 releases/10-alpha, releases/beta/3-alpha, main에서는 실행되지 않습니다.

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

수동으로 트리거되는 워크플로를 위한 입력 정의하기

workflow_dispatch 이벤트를 사용할 때 워크플로에 전달되는 입력을 선택적으로 지정할 수 있습니다.

이 트리거는 워크플로 파일이 기본 브랜치에 있을 때만 이벤트를 받습니다. 트리거된 워크플로는 inputs 컨텍스트에서 입력을 받습니다. 자세한 내용은 Contexts를 참고하세요.

[!NOTE]

워크플로는 github.event.inputs 컨텍스트에서도 입력을 받습니다. inputs 컨텍스트와 github.event.inputs 컨텍스트의 정보는 동일하지만, inputs 컨텍스트는 Boolean 값을 문자열로 변환하지 않고 Boolean으로 유지한다는 차이가 있습니다. choice 타입은 문자열로 해석되며 단일 선택 가능한 옵션입니다.

inputs의 최상위 속성 최대 개수는 25개입니다.

inputs의 최대 페이로드는 65,535자입니다.

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning'
        type: choice
        options:
          - info
          - warning
          - debug
      print_tags:
        description: 'True to print to STDOUT'
        required: true
        type: boolean
      tags:
        description: 'Test scenario tags'
        required: true
        type: string
      environment:
        description: 'Environment to run tests against'
        type: environment
        required: true

jobs:
  print-tag:
    runs-on: ubuntu-latest
    if: ${{ inputs.print_tags }} 
    steps:
      - name: Print the input tag to STDOUT
        run: echo  The tags are ${{ inputs.tags }}

재사용 가능한 워크플로를 위한 입력, 출력, 시크릿 정의하기

재사용 가능한 워크플로(reusable workflow)가 호출 워크플로로부터 받아야 하는 입력과 시크릿을 정의할 수 있습니다. 또한 재사용 가능한 워크플로가 호출 워크플로에 제공할 출력을 지정할 수도 있습니다. 자세한 내용은 Reuse workflows를 참고하세요.

이벤트 정보 사용하기

워크플로 실행을 트리거한 이벤트에 대한 정보는 github.event 컨텍스트에서 사용할 수 있습니다. github.event 컨텍스트의 속성은 워크플로를 트리거한 이벤트 유형에 따라 다릅니다. 예를 들어 이슈에 라벨이 지정될 때 트리거된 워크플로는 이슈와 라벨에 대한 정보를 가집니다.

이벤트의 모든 속성 보기

일반적인 속성과 예시 페이로드에 대한 웹훅 이벤트 문서를 참고하세요. 자세한 내용은 Webhook events and payloads를 참고하세요.

또한 전체 github.event 컨텍스트를 출력해서 워크플로를 트리거한 이벤트에서 사용할 수 있는 속성을 확인할 수 있습니다:

jobs:
  print_context:
    runs-on: ubuntu-latest
    steps:
      - env:
          EVENT_CONTEXT: ${{ toJSON(github.event) }}
        run: |
          echo $EVENT_CONTEXT

이벤트 속성 접근 및 사용하기

워크플로에서 github.event 컨텍스트를 사용할 수 있습니다. 예를 들어 다음 워크플로는 package*.json, .github/CODEOWNERS, 또는 .github/workflows/**를 변경하는 풀 리퀘스트가 열릴 때 실행됩니다. 풀 리퀘스트 작성자(github.event.pull_request.user.login)가 octobot이나 dependabot[bot]이 아니면, 워크플로는 GitHub CLI를 사용해서 풀 리퀘스트에 라벨을 지정하고 댓글을 답니다(github.event.pull_request.number).

on:
  pull_request:
    types:
      - opened
    paths:
      - '.github/workflows/**'
      - '.github/CODEOWNERS'
      - 'package*.json'

jobs:
  triage:
    if: >-
      github.event.pull_request.user.login != 'octobot' &&
      github.event.pull_request.user.login != 'dependabot[bot]'
    runs-on: ubuntu-latest
    steps:
      - name: "Comment about changes we can't accept"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR: ${{ github.event.pull_request.html_url }}
        run: |
          gh pr edit $PR --add-label 'invalid'
          gh pr comment $PR --body 'It looks like you edited `package*.json`, `.github/CODEOWNERS`, or `.github/workflows/**`. We do not allow contributions to these files. Please review our [contributing guidelines](https://github.com/octo-org/octo-repo/blob/main/CONTRIBUTING.md) for what contributions are accepted.'

컨텍스트에 대한 자세한 내용은 Contexts reference를 참고하세요. 이벤트 페이로드에 대한 자세한 내용은 Webhook events and payloads를 참고하세요.

워크플로 실행 방식을 더 제어하기

이벤트, 이벤트 활동 유형, 이벤트 필터가 제공하는 것보다 더 세밀한 제어가 필요하면 조건(conditional)과 환경(environment)을 사용해서 워크플로의 개별 잡이나 스텝이 실행될지 제어할 수 있습니다.

조건 사용하기

조건을 사용해서 워크플로의 잡이나 스텝이 실행될지 더 제어할 수 있습니다.

이벤트 페이로드의 값 사용 예시

예를 들어 특정 라벨이 이슈에 추가될 때 워크플로가 실행되길 원한다면, issues labeled 이벤트 활동 유형에서 트리거하고 조건을 사용해서 어떤 라벨이 워크플로를 트리거했는지 확인할 수 있습니다. 다음 워크플로는 워크플로 저장소의 이슈에 어떤 라벨이 추가되어도 실행되지만, run_if_label_matches 잡은 라벨 이름이 bug일 때만 실행됩니다.

on:
  issues:
    types:
      - labeled

jobs:
  run_if_label_matches:
    if: github.event.label.name == 'bug'
    runs-on: ubuntu-latest
    steps:
      - run: echo 'The label was bug'

이벤트 유형 사용 예시

예를 들어 어떤 이벤트가 워크플로를 트리거했느냐에 따라 다른 잡이나 스텝을 실행하려면, 조건을 사용해서 이벤트 컨텍스트에 특정 이벤트 유형이 존재하는지 확인할 수 있습니다. 다음 워크플로는 이슈나 풀 리퀘스트가 닫힐 때마다 실행됩니다. 이슈가 닫혀서 워크플로가 실행되었다면 github.event 컨텍스트에 issue 값은 있지만 pull_request는 없습니다. 따라서 if_issue 스텝은 실행되지만 if_pr 스텝은 실행되지 않습니다. 반대로 풀 리퀘스트가 닫혀서 실행되었다면 if_pr 스텝은 실행되지만 if_issue 스텝은 실행되지 않습니다.

on:
  issues:
    types:
      - closed
  pull_request:
    types:
      - closed

jobs:
  state_event_type:
    runs-on: ubuntu-latest
    steps:
    - name: if_issue
      if: github.event.issue
      run: |
        echo An issue was closed
    - name: if_pr
      if: github.event.pull_request
      run: |
        echo A pull request was closed

이벤트 컨텍스트에서 사용할 수 있는 정보에 대한 자세한 내용은 Using event information을 참고하세요. 조건 사용 방법에 대한 자세한 내용은 Evaluate expressions in workflows and actions을 참고하세요.

환경을 사용해서 워크플로 잡을 수동으로 트리거하기

워크플로의 특정 잡을 수동으로 트리거하려면 특정 팀이나 사용자의 승인을 요구하는 환경을 사용할 수 있습니다. 먼저 필수 리뷰어가 있는 환경을 구성합니다. 자세한 내용은 Managing environments for deployment를 참고하세요. 그다음 워크플로의 잡에서 environment: 키로 환경 이름을 참조합니다. 환경을 참조하는 모든 잡은 최소 한 명의 리뷰어가 잡을 승인할 때까지 실행되지 않습니다.

예를 들어 다음 워크플로는 main에 push가 있을 때마다 실행됩니다. build 잡은 항상 실행됩니다. publish 잡은 build 잡이 성공적으로 완료된 후(needs: [build] 덕분에) 그리고 production이라는 환경의 모든 규칙(필수 리뷰어 포함)을 통과한 후(environment: production 덕분에)에만 실행됩니다.

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: build
        run: |
          echo 'building'

  publish:
    needs: [build]
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: publish
        run: |
          echo 'publishing'

[!NOTE] 환경, 환경 시크릿, 배포 보호 규칙은 모든 현재 GitHub 플랜의 공개 저장소에서 사용할 수 있습니다. Bronze, Silver, Gold 같은 레거시 플랜에서는 사용할 수 없습니다. 비공개 또는 내부 저장소에서 환경, 환경 시크릿, 배포 브랜치에 접근하려면 GitHub Pro, GitHub Team, GitHub Enterprise를 사용해야 합니다. GitHub Free, GitHub Pro, GitHub Team 플랜에서는 대기 타이머(wait timer)나 필수 리뷰어 같은 다른 배포 보호 규칙이 공개 저장소에서만 사용할 수 있습니다.

사용 가능한 이벤트

사용 가능한 전체 이벤트 목록은 Events that trigger workflows를 참고하세요.

워크플로 트리거하기