# 워크플로우 시작

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

## 필수 조건

워크플로 및 워크플로 트리거에 대한 자세한 내용은 [워크플로](/ko/actions/concepts/workflows-and-actions/workflows)을(를) 참조하세요.

## 워크플로에서 워크플로 트리거

리포지 `GITHUB_TOKEN` 토리를 사용하여 작업을 수행하는 경우 트리거된 `GITHUB_TOKEN` 이벤트는 다음과 같은 예외를 제외하고 새 워크플로 실행을 만들지 않습니다.

* `workflow_dispatch` 및 `repository_dispatch` 이벤트는 항상 워크플로 실행을 생성합니다.
* `pull_request`
  `opened`, `synchronize` 또는 `reopened` 활동 유형의 이벤트: `GITHUB_TOKEN`를 사용하는 워크플로가 풀 리퀘스트를 생성하거나 업데이트하면, 그 결과로 생성된 `pull_request` 이벤트는 **approval-required** 상태의 워크플로 실행을 생성합니다. 끌어오기 요청에는 병합 상자에 배너가 표시되고, 리포지토리에 대한 쓰기 권한이 있는 사용자는 **실행할 워크플로 승인**을 선택하여 실행을 시작할 수 있습니다. 다른 `pull_request` 작업 형식(예: `labeled`, `edited`또는 `closed`)은 워크플로 실행을 만들지 않습니다. 이렇게 하면 자동화에서 만든 끌어오기 요청에서 CI 워크플로가 실행되도록 허용하면서 재귀 워크플로 실행을 방지할 수 있습니다. 워크플로 실행을 승인하는 방법에 대한 자세한 내용은 [포크에서 시작된 워크플로 실행을 승인하기](/ko/actions/how-tos/manage-workflow-runs/approve-runs-from-forks)을 참조하세요.

다른 모든 이벤트의 경우 이 동작은 실수로 재귀 워크플로 실행을 만들지 못하게 합니다. 예를 들어, 워크플로 실행이 리포지토리의 `GITHUB_TOKEN`을 사용하여 코드를 푸시하는 경우 리포지토리가 `push` 이벤트 발생 시 실행되도록 구성된 워크플로를 포함하고 있더라도 새 워크플로가 실행되지 않습니다. 자세한 내용은 [워크플로에서 인증에 GITHUB\_TOKEN 사용](/ko/actions/tutorials/authenticate-with-github_token)을 참조하세요.

워크플로 실행 내에서 워크플로를 트리거하려는 경우, 토큰이 필요한 이벤트를 트리거하기 위해 GitHub App 대신 personal access token 설치 액세스 토큰 또는 `GITHUB_TOKEN`을(를) 사용할 수 있습니다. 또한 `pull_request` 이러한 대안 중 하나를 사용하면 자동화에서 끌어오기 요청을 만들거나 업데이트할 때 워크플로를 자동으로 실행할 수 있습니다(위에서 설명한 승인 프롬프트 없이).

GitHub App를 사용하는 경우 GitHub App를 생성하고 앱 ID와 프라이빗 키를 시크릿으로 저장해야 합니다. 자세한 내용은 [GitHub Actions 워크플로에서 GitHub 앱을 사용하여 인증된 API 요청 만들기](/ko/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow)을(를) 참조하세요.
personal access token를 사용하는 경우 personal access token를 만들어 비밀로 저장해야 합니다. 자세한 내용은 personal access token 만들기에 대해 [개인용 액세스 토큰 관리](/ko/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)을 참조하세요. 비밀을 저장하는 방법에 대한 자세한 내용은 [GitHub Actions에서 비밀 사용](/ko/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)을(를) 참조하세요.

사용 비용을 최소화 GitHub Actions 하려면 재귀 또는 의도하지 않은 워크플로 실행을 만들지 않도록 합니다.

예를 들어, 다음 워크플로는 personal access token라는 비밀에 저장된 `MY_TOKEN`를 사용하여 GitHub CLI를 통해 이슈에 레이블을 추가합니다. 레이블이 추가되면 실행되는 모든 워크플로는 이 단계가 수행되면 실행됩니다.

```yaml
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`을 사용하여 이슈에 레이블을 추가합니다. 레이블이 추가될 때 실행되는 워크플로는 트리거되지 않습니다.

```yaml
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` 키를 사용하여 워크플로를 트리거하는 이벤트를 지정합니다. 이러한 이벤트에 대한 자세한 내용은 [워크플로를 트리거하는 이벤트](/ko/actions/reference/workflows-and-actions/events-that-trigger-workflows)을(를) 참고하세요.

### 단일 이벤트 사용

예를 들어 다음 `on` 값이 있는 워크플로는 워크플로 리포지토리의 분기로 푸시될 때 실행됩니다.

```yaml
on: push
```

### 여러 이벤트 사용

단일 이벤트 또는 여러 이벤트를 지정할 수 있습니다. 예를 들어 다음 `on` 값이 있는 워크플로는 워크플로 리포지토리의 분기로 푸시될 때 실행됩니다.

```yaml
on: [push, fork]
```

여러 이벤트를 지정하는 경우 워크플로를 트리거하려면 이러한 이벤트 중 하나만 발생해야 합니다. 워크플로에 대한 트리거 이벤트가 여러 개 동시에 발생하는 경우 워크플로 실행 여러 개가 트리거됩니다.

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

작업 유형 및 필터를 사용하여 워크플로가 실행되는 시기를 추가로 제어할 수 있습니다. 자세한 내용은 [이벤트 작업 유형 사용](#using-event-activity-types) 및 [필터 사용](#using-filters)을 참조하세요. 이벤트에 대해 작업 유형 또는 필터를 지정하고 여러 이벤트에서 워크플로가 트리거되는 경우 각 이벤트를 별도로 구성해야 합니다. 구성이 없는 이벤트를 포함하여 모든 이벤트에 콜론(`:`)을 추가해야 합니다.

예를 들어 다음 `on` 값이 있는 워크플로는 다음과 같은 경우에 실행됩니다.

* 레이블이 생성되는 경우
* 리포지토리의 `main` 분기에 푸시되는 경우
* GitHub Pages 사용 분기에 푸시되는 경우

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

## 이벤트 작업 유형 사용

일부 이벤트에는 워크플로가 실행되어야 하는 시기를 보다 정확하게 제어할 수 있는 활동 유형이 있습니다.
`on.<event_name>.types`를 사용하여 워크플로 실행을 트리거할 이벤트 활동 유형을 정의합니다.

예를 들어 `issue_comment` 이벤트에는 `created`, `edited` 및 `deleted` 활동 유형이 있습니다.
`label` 이벤트에 대해 워크플로가 트리거되면 레이블을 만들거나 편집하거나 삭제할 때마다 이 워크플로가 실행됩니다.
`created` 이벤트에 대해 `label` 활동 유형을 지정하면 레이블을 편집하거나 삭제할 때가 아니라 레이블을 만들 때 워크플로가 실행됩니다.

```yaml
on:
  label:
    types:
      - created
```

활동 유형을 여러 개 지정한 경우 워크플로를 트리거하려면 이러한 이벤트 활동 유형 중 하나만 발생해야 합니다. 워크플로에 대한 트리거 이벤트 활동 유형 여러 개가 동시에 발생하는 경우 워크플로 실행 여러 개가 트리거됩니다. 예를 들어 다음 워크플로는 이슈가 시작되거나 레이블이 지정될 때 트리거됩니다. 레이블이 두 개 달린 이슈가 열리면 워크플로 실행이 세 번 시작됩니다. 하나는 이슈 열림 이벤트에 대한 실행이고, 나머지 두 개는 이슈 레이블 지정 이벤트 두 건에 대한 실행입니다.

```yaml
on:
  issues:
    types:
      - opened
      - labeled
```

각 이벤트 및 해당 활동 유형에 대한 자세한 내용은 [워크플로를 트리거하는 이벤트](/ko/actions/reference/workflows-and-actions/events-that-trigger-workflows)을(를) 참조하세요.

## 필터 사용

일부 이벤트에는 워크플로가 실행되어야 하는 시기를 더 자세히 제어할 수 있는 필터가 있습니다.

예를 들어 `push` 이벤트에는 푸시가 발생하는 경우 대신 `branches` 필터와 일치하는 분기로 푸시가 발생하는 경우에만 워크플로가 실행되도록 하는 `branches` 필터가 있습니다.

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

### 필터를 사용하여 끌어오기 요청 이벤트에 특정 분기를 대상으로 지정

`pull_request` 및 `pull_request_target` 이벤트를 사용하는 경우 특정 분기를 대상으로 하는 끌어오기 요청에 대해서만 실행되도록 워크플로를 구성할 수 있습니다.

분기 이름 패턴을 포함하려는 경우 또는 분기 이름 패턴을 포함하거나 제외하려는 경우 `branches` 필터를 사용합니다. 분기 이름 패턴만 제외하려는 경우 `branches-ignore` 필터를 사용합니다. 워크플로의 동일한 이벤트에 대해 `branches` 필터와 `branches-ignore` 필터 둘 다는 사용할 수 없습니다.

`branches`
/
`branches-ignore` 및 [`paths`/`paths-ignore`](/ko/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore)를 둘 다 정의하는 경우 워크플로는 두 필터가 모두 충족될 때만 실행됩니다.

`branches` 및 `branches-ignore` 키워드는 `*`, `**`, `+`, `?`, `!` 같은 문자를 사용하여 둘 이상의 분기 이름과 일치시키는 glob 패턴을 지원합니다. 이름에 이러한 문자 중 하나라도 포함되어 있고 문자 그대로 일치시키려는 경우, 이러한 각 특수 문자를 `\`로 각각 이스케이프해야 합니다. glob 패턴에 대한 자세한 내용은 [GitHub Actions에 대한 워크플로 구문](/ko/actions/reference/workflows-and-actions/workflow-syntax#filter-pattern-cheat-sheet)을(를) 참조하세요.

#### 예: 분기 포함

`branches`에 정의된 패턴은 Git ref의 이름에 따라 평가됩니다. 예를 들어 끌어오기 요청 대상 지정을 위한 `pull_request` 이벤트가 있을 때마다 다음 워크플로가 실행됩니다.

* `main`으로 명명된 분기(`refs/heads/main`)
* `mona/octocat`으로 명명된 분기(`refs/heads/mona/octocat`)
* `releases/`과 같이 이름이 `releases/10`로 시작하는 분기(`refs/heads/releases/10`)

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

분기 필터링, [경로 필터링](/ko/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore) 또는 [커밋 메시지](/ko/actions/how-tos/manage-workflow-runs/skip-workflow-runs)로 인해 워크플로를 건너뛰는 경우 해당 워크플로와 연결된 검사는 “보류 중” 상태로 유지됩니다. 이러한 검사가 성공해야 하는 끌어오기 요청은 병합에서 차단됩니다.

#### 예: 분기 제외

패턴이 `branches-ignore` 패턴과 일치하면 워크플로가 실행되지 않습니다.
`branches-ignore`에 정의된 패턴은 Git ref의 이름에 따라 평가됩니다. 예를 들어 끌어오기 요청의 대상을 지정하지 않는 한 `pull_request` 이벤트가 있을 때마다 다음 워크플로가 실행됩니다.

* `mona/octocat`으로 명명된 분기(`refs/heads/mona/octocat`)
* `releases/**-alpha`와 같이 이름이 `releases/beta/3-alpha`와 일치하는 분기(`refs/heads/releases/beta/3-alpha`) <!-- markdownlint-disable-line outdated-release-phase-terminology -->

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

#### 예: 브랜치 포함 및 제외

`branches` 및 `branches-ignore`를 사용하여 단일 워크플로의 동일한 이벤트를 필터링할 수 없습니다. 단일 이벤트에 대한 분기 패턴을 포함 및 제외하려면 `branches` 문자와 함께 `!` 필터를 사용하여 제외해야 하는 분기를 나타냅니다.

`!` 문자를 사용하여 분기를 정의하는 경우 `!` 문자 없이 하나 이상의 분기도 정의해야 합니다. 분기만 제외하려면 `branches-ignore`를 대신 사용합니다.

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

* 긍정 일치 후 일치하는 부정 패턴(접두사 `!`)은 Git ref를 제외합니다.
* 부정 일치 후 일치하는 긍정 패턴은 Git ref를 다시 포함합니다.

다음 워크플로는 `pull_request` 또는 `releases/10`를 대상으로 하는 끌어오기 요청에 대한 `releases/beta/mona` 이벤트에서 실행되지만 `releases/10-alpha` 부정 패턴이 긍정 패턴 이후에 나오므로 `releases/beta/3-alpha` 또는 `!releases/**-alpha`를 대상으로 하는 끌어오기 요청에 대해서는 그러지 않습니다. <!-- markdownlint-disable-line outdated-release-phase-terminology -->

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

### 필터를 사용하여 푸시 이벤트에 특정 분기 또는 태그를 대상으로 지정

`push` 이벤트를 사용하는 경우 특정 분기 또는 태그에서 실행되도록 워크플로를 구성할 수 있습니다.

분기 이름 패턴을 포함하려는 경우 또는 분기 이름 패턴을 포함하거나 제외하려는 경우 `branches` 필터를 사용합니다. 분기 이름 패턴만 제외하려는 경우 `branches-ignore` 필터를 사용합니다. 워크플로의 동일한 이벤트에 대해 `branches` 필터와 `branches-ignore` 필터 둘 다는 사용할 수 없습니다.

태그 이름 패턴을 포함하려는 경우 또는 태그 이름 패턴을 포함하거나 제외하려는 경우 `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`](/ko/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore)를 둘 다 정의하는 경우 워크플로는 두 필터가 모두 충족될 때만 실행됩니다.

`branches`, `branches-ignore`, `tags` 및 `tags-ignore` 키워드는 두 개 이상의 분기 또는 태그 이름과 일치하도록 `*`, `**`, `+`, `?`, `!` 등의 문자를 사용하는 GLOB 패턴을 허용합니다. 이름에 해당 문자가 포함되어 있고 리터럴 일치를 원하는 경우 각 특수 문자를 \_\_ 로 `\`해야 합니다. glob 패턴에 대한 자세한 내용은 [GitHub Actions에 대한 워크플로 구문](/ko/actions/reference/workflows-and-actions/workflow-syntax#filter-pattern-cheat-sheet)을(를) 참조하세요.

#### 예: 브랜치 및 태그 포함

`branches` 및 `tags`에 정의된 패턴은 Git 참조의 이름을 기준으로 평가됩니다. 예를 들어, 다음 워크플로는 `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`)

```yaml
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 참조의 이름을 기준으로 평가됩니다. 예를 들어, `push` 이벤트가 다음을 대상으로 하지 않는 한 `push` 이벤트가 있을 때마다 다음 워크플로가 실행됩니다.

* `mona/octocat`으로 명명된 분기(`refs/heads/mona/octocat`)
* `releases/**-alpha`와 같이 이름이 `releases/beta/3-alpha`와 일치하는 분기(`refs/heads/releases/beta/3-alpha`) <!-- markdownlint-disable-line outdated-release-phase-terminology -->
* `v2` 태그(`refs/tags/v2`)
* `v1.`처럼 이름이 `v1.9`으로 시작하는 태그(`refs/tags/v1.9`)

```yaml
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` 또는 `releases/10-alpha`에 대한 푸시에서 실행되지만 `releases/beta/3-alpha` 또는 `!releases/**-alpha`에서는 실행되지 않습니다. <!-- markdownlint-disable-line outdated-release-phase-terminology -->

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

### 필터를 사용하여 끌어오기 요청 또는 푸시 이벤트에 특정 경로를 대상으로 지정

`push` 및 `pull_request` 이벤트를 사용하는 경우 변경된 파일 경로에 따라 실행되도록 워크플로를 구성할 수 있습니다. 경로 필터는 태그 푸시에 대해 평가되지 않습니다.

파일 경로 패턴을 포함하려는 경우 또는 파일 경로 패턴을 포함 및 제외하려는 경우 `paths` 필터를 사용합니다. 파일 경로 패턴만 제외하려는 경우 `paths-ignore` 필터를 사용합니다. 워크플로의 동일한 이벤트에 대해 `paths` 필터와 `paths-ignore` 필터 둘 다는 사용할 수 없습니다. 단일 이벤트에 대한 경로 패턴을 포함 및 제외하려면 접두어 `paths` 문자와 함께 `!` 필터를 사용하여 제외해야 하는 경로를 나타냅니다.

> \[!NOTE]
> `paths` 패턴을 정의하는 순서가 중요합니다.
>
> * 긍정 일치 후 일치하는 부정 패턴(접두사 `!`)은 경로를 제외합니다.
> * 부정 일치 후 일치하는 긍정 패턴은 경로를 다시 포함합니다.

`branches`
/
`branches-ignore` 및 `paths`/`paths-ignore`를 둘 다 정의하는 경우 워크플로는 두 필터가 모두 충족될 때만 실행됩니다.

`paths` 및 `paths-ignore` 키워드는 둘 이상의 경로 이름에 대한 일치 판정을 위해 `*` 및 `**` 와일드카드 문자를 사용하는 GLOB 패턴을 허용합니다. 자세한 내용은 [GitHub Actions에 대한 워크플로 구문](/ko/actions/reference/workflows-and-actions/workflow-syntax#filter-pattern-cheat-sheet)을(를) 참조하세요.

#### 예: 경로 포함

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

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

경로 필터링, [분기 필터링](/ko/actions/reference/workflows-and-actions/workflow-syntax#onpull_requestpull_request_targetbranchesbranches-ignore) 또는 [커밋 메시지](/ko/actions/how-tos/manage-workflow-runs/skip-workflow-runs)로 인해 워크플로를 건너뛰는 경우 해당 워크플로와 연결된 검사는 “보류 중” 상태로 유지됩니다. 이러한 검사가 성공해야 하는 끌어오기 요청은 병합에서 차단됩니다.

#### 예: 경로 제외

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

다음 경로 필터가 있는 워크플로는 리포지토리의 루트에 있는 `docs` 디렉터리 외부에 하나 이상의 파일이 포함된 `push` 이벤트에서만 실행됩니다.

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

#### 예: 경로 포함 및 제외

`paths` 및 `paths-ignore`를 사용하여 단일 워크플로의 동일한 이벤트를 필터링할 수 없습니다. 단일 이벤트에 대한 경로 패턴을 포함 및 제외하려면 접두어 `!` 문자와 함께 `paths` 필터를 사용하여 제외해야 하는 경로를 나타냅니다.

`!` 문자를 사용하여 경로를 정의하는 경우 `!` 문자 없이 하나 이상의 경로도 정의해야 합니다. 경로만 제외하려면 `paths-ignore`를 대신 사용합니다.

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

* 긍정 일치 후 일치하는 부정 패턴(접두사 `!`)은 경로를 제외합니다.
* 부정 일치 후 일치하는 긍정 패턴은 경로를 다시 포함합니다.

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

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

#### Git 다른점 확인

필터는 변경된 파일을 평가하고 `paths-ignore` 또는 `paths` 목록에 따라 이를 실행하여 워크플로 실행 여부를 결정합니다. 변경된 파일이 없으면 워크플로가 실행되지 않습니다.

GitHub는 푸시의 경우 2점 diff를, 풀 요청의 경우 3점 diff를 사용하여 변경된 파일 목록을 생성합니다.

* **끌어오기 요청:** 세 개의 점 차이는 토픽 분기의 최신 버전과 토픽 분기가 기본 분기와 마지막으로 동기화된 커밋을 비교한 것입니다.
* **기존 분기로 푸시:** 두 개의 점 차이는 헤드와 기본 SHA를 서로 직접 비교합니다.
* **새 분기로 푸시:** 푸시된 가장 깊은 커밋의 상위 부모에 대한 두 개의 점 차이입니다.

경우에 따라 GitHub Actions 필터링된 워크플로 실행 방법을 변경하는 제한이 적용됩니다.

* 푸시에 1,000개 이상의 커밋이 포함된 경우 워크플로는 **항상** 실행됩니다.
* diff 생성이 시간 초과되면 워크플로가 **항상** 실행됩니다.
* 생성된 diff에 3,000개 이상의 파일이 포함되어 있고 워크플로 필터가 일치하는 파일이 필터에서 반환된 처음 3,000개에 있지 않으면 워크플로가 실행 **되지 않습니다** .

이러한 동작이 나타난다면, 필터를 더 구체적으로 지정하거나 푸시와 풀 리퀘스트를 처리하는 방식을 바꿔 더 단순한 diff를 생성해야 할 수 있습니다.

자세한 내용은 [지점](/ko/pull-requests/reference/branches)을(를) 참조하세요.

### 필터를 사용하여 워크플로 실행 이벤트에 특정 분기를 대상으로 지정

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

`branches` 및 `branches-ignore` 필터는 `*`, `**`, `+`, `?`, `!` 등의 문자를 사용하는 glob 패턴을 허용하며, 이를 통해 둘 이상의 분기 이름과 일치시킬 수 있습니다. 이름에 이러한 문자 중 하나라도 포함되어 있고 문자 그대로 일치시키려는 경우, 이러한 각 특수 문자 앞에 \_\_ 를 붙여 각각 `\`해야 합니다. glob 패턴에 대한 자세한 내용은 [GitHub Actions에 대한 워크플로 구문](/ko/actions/reference/workflows-and-actions/workflow-syntax#filter-pattern-cheat-sheet)을(를) 참조하세요.

예를 들어 다음 트리거가 있는 워크플로는 이름이 `Build`로 시작하는 분기에서 `releases/`라는 워크플로가 실행되는 경우에만 실행됩니다.

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

다음 트리거가 있는 워크플로는 이름이 `Build`가 아닌 분기에서 `canary`라는 워크플로가 실행되는 경우에만 실행됩니다.

```yaml
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`인 경우에는 그러지 않습니다. <!-- markdownlint-disable-line outdated-release-phase-terminology -->

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

## 수동으로 트리거된 워크플로에 대한 입력 정의

`workflow_dispatch` 이벤트를 사용할 때 필요에 따라 워크플로에 전달되는 입력을 지정할 수 있습니다.

이 트리거는 워크플로 파일이 기본 브랜치에 있을 때만 이벤트를 수신합니다.
트리거된 워크플로는 `inputs` 컨텍스트에서 입력을 받습니다. 자세한 내용은 [컨텍스트](/ko/actions/reference/workflows-and-actions/contexts#inputs-context)를 참조하세요.

> \[!NOTE]
>
> * 워크플로는 `github.event.inputs` 컨텍스트의 입력도 수신합니다.
>   `inputs` 컨텍스트와 `github.event.inputs` 컨텍스트의 정보는 `inputs` 컨텍스트가 부울 값을 문자열로 변환하는 대신 부울 값으로 유지한다는 점을 제외하고 동일합니다. 이 `choice` 형식은 문자열로 확인되며 단일 선택 가능한 옵션입니다.
> * 최상위 속성 `inputs` 의 최대 수는 25 입니다.
> * 최대 페이로드 `inputs`는 65,535자입니다.

```yaml
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 }} 
```

## 재사용 가능한 워크플로에 대한 입력, 출력, 비밀 정의

재사용 가능한 워크플로가 호출 워크플로에서 받아야 하는 입력 및 비밀을 정의할 수 있습니다. 재사용 가능한 워크플로가 호출 워크플로에 사용할 수 있도록 하는 출력을 지정할 수도 있습니다. 자세한 내용은 [워크플로 재사용](/ko/actions/how-tos/reuse-automations/reuse-workflows)을(를) 참조하세요.

## 이벤트 정보 사용

워크플로 실행을 트리거한 이벤트에 대한 정보는 `github.event` 컨텍스트를 참조하세요.
`github.event` 컨텍스트의 속성은 워크플로를 트리거한 이벤트 유형에 따라 달라집니다. 예를 들어 이슈에 레이블이 지정되면 트리거되는 워크플로에는 이슈 및 레이블에 대한 정보가 있습니다.

### 이벤트의 모든 속성 보기

일반적인 속성 및 예제 페이로드에 대한 웹후크 이벤트 설명서를 참조하세요. 자세한 내용은 [웹후크 이벤트 및 페이로드](/ko/webhooks/webhook-events-and-payloads)을(를) 참조하세요.

전체 `github.event` 컨텍스트를 인쇄하여 워크플로를 트리거한 이벤트에 사용할 수 있는 속성을 확인할 수도 있습니다.

```yaml
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`.

```yaml
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.'
```

컨텍스트에 대한 자세한 내용은 [문맥 참조](/ko/actions/reference/workflows-and-actions/contexts)을(를) 참조하세요. 이벤트 페이로드에 관한 자세한 내용은 [웹후크 이벤트 및 페이로드](/ko/webhooks/webhook-events-and-payloads)을(를) 참조하세요.

## 워크플로 실행 방법 추가 제어

이벤트, 이벤트 작업 유형 또는 이벤트 필터가 제공하는 것보다 더 세부적인 제어를 원하는 경우 조건부 및 환경을 사용하여 워크플로의 개별 작업 또는 단계가 실행될지 여부를 제어할 수 있습니다.

### 조건부 사용

조건부를 사용하여 워크플로의 작업 또는 단계 실행 여부를 추가로 제어할 수 있습니다.

#### 이벤트 페이로드에서 값을 사용하는 예제

예를 들어 이슈에 특정 레이블이 추가될 때 워크플로를 실행하려면 `issues labeled` 이벤트 작업 유형에서 트리거하고 조건부를 사용하여 워크플로를 트리거한 레이블을 확인할 수 있습니다. 다음 워크플로는 워크플로 리포지토리의 이슈에 레이블이 추가될 때 실행되지만 레이블에 `run_if_label_matches`라는 이름이 지정된 경우에만 `bug` 작업이 실행됩니다.

```yaml
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` 단계가 실행되지 않습니다.

```yaml
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)을 참조하세요. 조건부를 사용하는 방법에 대한 자세한 내용은 [워크플로 및 작업에서 식 평가](/ko/actions/reference/workflows-and-actions/expressions)을(를) 참조하세요.

### 환경을 사용하여 워크플로 작업을 수동으로 트리거

워크플로에서 특정 작업을 수동으로 트리거하려는 경우 특정 팀 또는 사용자의 승인이 필요한 환경을 사용할 수 있습니다. 먼저 필요한 검토자를 사용하여 환경을 구성합니다. 자세한 내용은 [배포 환경 관리](/ko/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments)을(를) 참조하세요. 그런 다음, `environment:` 키를 사용하여 워크플로 작업에서 환경 이름을 참조합니다. 환경을 참조하는 모든 작업은 하나 이상의 검토자가 작업을 승인할 때까지 실행되지 않습니다.

예를 들어 다음 워크플로는 main에 대한 푸시가 있을 때마다 실행됩니다.
`build` 작업은 항상 실행됩니다.
`publish` 작업은 `build` 작업이 성공적으로 완료된 후(원인: `needs: [build]`) 및 `production` 환경의 모든 규칙(필수 검토자 포함)이 통과된 후(원인: `environment: production`)에만 실행됩니다.

```yaml
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 계획에 대한 공용 리포지토리에서 사용할 수 있습니다. 브론즈, 실버 또는 골드와 같은 레거시 플랜에서는 사용할 수 없습니다. 프라이빗 또는 내부 리포지토리에서 환경, 환경 비밀 및 배포 분기에 액세스하려면 GitHub ProGitHub Team 또는 GitHub Enterprise를 사용해야 합니다.
>
> GitHub Free, GitHub Pro, 또는 GitHub Team 요금제에 가입된 경우, 대기 타이머나 필수 검토자와 같은 기타 배포 보호 규칙은 공용 리포지토리에서만 사용할 수 있습니다.

## 사용 가능한 이벤트

사용 가능한 이벤트의 전체 목록은 [워크플로를 트리거하는 이벤트](/ko/actions/reference/workflows-and-actions/events-that-trigger-workflows)을(를) 참조하세요.