# ワークフローをトリガーする

GitHub Actions ワークフローを自動的にトリガーする方法

## 前提条件

ワークフローとトリガー ワークフローの詳細については、「[ワークフロー](/ja/actions/concepts/workflows-and-actions/workflows)」を参照してください。

## ワークフローからワークフローをトリガーする

リポジトリの `GITHUB_TOKEN` を使用してタスクを実行する場合、 `GITHUB_TOKEN` によってトリガーされるイベントは新しいワークフロー実行を作成しません。ただし、次の例外があります。

* `workflow_dispatch` と `repository_dispatch` イベントでは、常にワークフロー実行が作成されます。
* `pull_request`
  `opened`、`synchronize`、または`reopened`アクティビティの種類を含むイベント: `GITHUB_TOKEN`を使用するワークフローがプル要求を作成または更新すると、結果として得られる`pull_request` イベントによって、**承認が必要な**状態でワークフロー実行が作成されます。 プル要求にはマージ ボックスにバナーが表示され、リポジトリへの書き込みアクセス権を持つユーザーは、\[実行するワークフローの承認] を選択して **実行を**開始できます。 その他の `pull_request` アクティビティの種類 ( `labeled`、 `edited`、 `closed`など) では、ワークフロー実行は作成されません。 これにより、自動化によって作成されたプル要求に対する CI ワークフローの実行を引き続き許可しながら、再帰ワークフローを実行できなくなります。 ワークフロー実行の承認の詳細については、「 [フォークからのワークフロー実行の承認](/ja/actions/how-tos/manage-workflow-runs/approve-runs-from-forks)」を参照してください。

その他のすべてのイベントでは、この動作により、再帰的なワークフロー実行が誤って作成されるのを防ぐことができます。 たとえば、ワークフロー実行でリポジトリの `GITHUB_TOKEN` を使用してコードがプッシュされた場合、`push` イベントの発生時に実行するように構成されたワークフローがリポジトリに含まれている場合でも、新しいワークフローは実行されません。 詳細については、 [AUTOTITLE を](/ja/actions/tutorials/authenticate-with-github_token)参照してください。

ワークフロー実行内からワークフローをトリガーする場合は、GitHub Appではなく、personal access token インストール アクセス トークンまたは`GITHUB_TOKEN`を使用して、トークンを必要とするイベントをトリガーできます。 これらの代替手段のいずれかを使用すると、プル要求が自動化によって作成または更新されたときに、(前述の承認プロンプトなしで) `pull_request` ワークフローを自動的に実行することもできます。

GitHub Appを使用する場合は、GitHub Appを作成し、アプリ ID と秘密キーをシークレットとして格納する必要があります。 詳しくは、「[GitHub Actions ワークフローでGitHub アプリを使用して認証済み API 要求を作成する](/ja/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の作成の詳細については、「[個人用アクセス トークンを管理する](/ja/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)」を参照してください。 シークレットの保管の詳細については、「[GitHub Actions でのシークレットの使用](/ja/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` キーを使って、ワークフローをトリガーするイベントを指定します。 使用できるイベントについて詳しくは、「[ワークフローをトリガーするイベント](/ja/actions/reference/workflows-and-actions/events-that-trigger-workflows)」をご覧ください。

### 単一のイベントを使用する

たとえば、次の `on` の値を持つワークフローは、ワークフローのリポジトリ内の任意のブランチにプッシュが行われるときに実行されます。

```yaml
on: push
```

### 複数のイベントを使用する

1 つのイベントまたは複数のイベントを指定できます。 たとえば、次の `on` の値を持つワークフローは、ワークフローのリポジトリ内の任意のブランチにプッシュが行われるとき、または誰かがリポジトリをフォークしたときに実行されます。

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

複数のイベントを指定する場合、ワークフローをトリガーするために必要なイベントは 1 つだけです。 ワークフローの複数のトリガー イベントが同時に発生した場合、複数のワークフロー実行がトリガーされます。

### アクティビティの種類とフィルターを複数のイベントと共に使用する

アクティビティの種類とフィルターを使って、ワークフローを実行するタイミングをさらに細かく制御できます。 詳細については、「[イベント アクティビティの種類を使用する](#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
```

複数のアクティビティの種類を指定した場合、ワークフローをトリガーするために発生する必要があるのは、それらのイベント アクティビティの種類のうちの 1 つだけです。 ワークフローの複数のトリガー イベント アクティビティの種類が同時に発生した場合、複数のワークフロー実行がトリガーされます。 たとえば、次のワークフローは、issue が開かれたとき、またはラベルが付けられたときに実行されます。 2 つのラベルを持つ Issue がオープンされると、3 つのワークフロー実行 (1 つは Issue がオープンされたイベント用、2 つは Issue のラベルが付いたイベント用) が開始されます。

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

各イベントとそのアクティビティの種類の詳細については、「[ワークフローをトリガーするイベント](/ja/actions/reference/workflows-and-actions/events-that-trigger-workflows)」を参照してください。

## フィルターを使用する

一部のイベントには、ワークフローを実行するタイミングをより細かく制御できるフィルターがあります。

たとえば、`push` イベントの `branches` フィルターでは、プッシュが発生したときではなく、`branches` フィルターと同じブランチに対してプッシュが発生したときのみ、ワークフローを実行できます。

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

### フィルターを使用して pull request イベントに対して特定のブランチをターゲットにする

`pull_request` イベントと `pull_request_target` イベントを使用する場合は、特定のブランチを対象とする pull request に対してのみ実行するようにワークフローを構成できます。

ブランチ名パターンを包含する場合、またはブランチ名パターンの包含と除外の両方を行う場合は、`branches` フィルターを使用します。 ブランチ名パターンの除外のみを行う場合は、`branches-ignore` フィルターを使用します。
`branches` と `branches-ignore` のフィルターの両方をワークフロー内の同じイベントで使うことはできません。

`branches`
/
`branches-ignore` と [`paths`/`paths-ignore`](/ja/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore) の両方を定義すると、ワークフローは両方のフィルターが満たされた場合にのみ実行されます。

`branches` と `branches-ignore` のキーワードは、複数のブランチ名に一致する文字 (`*`、`**`、`+`、`?`、`!` など) を使用する glob パターンを受け入れます。 名前にこれらの文字のいずれかが含まれていて、文字どおりに一致させたい場合は、これらの特殊文字をそれぞれ `\` でエスケープする必要があります。 glob パターンの詳細については、[GitHub Actions　のワークフロー構文](/ja/actions/reference/workflows-and-actions/workflow-syntax#filter-pattern-cheat-sheet) を参照してください。

#### 例: ブランチの包含

`branches` で定義されているパターンは、Git ref の名前に対して評価されます。 たとえば、次のワークフローは、pull request の対象となる `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/**'
```

ブランチ フィルター、[パス フィルター](/ja/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore)、または [コミット メッセージ](/ja/actions/how-tos/manage-workflow-runs/skip-workflow-runs)のためにワークフローがスキップされる場合、そのワークフローに関連付けられているチェックは "保留中" 状態のままになります。 これらのチェックを成功させる必要がある pull request は、マージが禁止されます。

#### 例: ブランチの除外

パターンが `branches-ignore` パターンと一致する場合、ワークフローは実行されません。
`branches-ignore` で定義されているパターンは、Git ref の名前に対して評価されます。 たとえば、次のワークフローは、pull request の対象とならない限り、`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'
```

#### 例: ブランチの包含および除外

1 つのワークフローで同じイベントのフィルター処理をするために `branches` と `branches-ignore` を使用することはできません。 1 つのイベントに対して分岐パターンの適用と除外の両方を行う場合は、`branches` フィルターと `!` 文字を使用して、除外する分岐を指定します。

`!` 文字を含むブランチを定義する場合は、`!` 文字を含まないブランチも 1 つ以上定義する必要があります。 ブランチの除外のみを行いたい場合は、代わりに `branches-ignore` を使用します。

パターンを定義する順序により、結果に違いが生じます。

* 肯定のマッチング パターンの後に否定のマッチング パターン (`!` のプレフィックスが付く) を定義すると、Git ref が除外されます。
* 否定のマッチングパターンの後に肯定のマッチングパターンを定義すると、Git ref を再び含めます。

次のワークフローは、否定のパターン `pull_request` が肯定のパターンの後に続くため、`releases/10` または `releases/beta/mona` を対象とする pull request の `releases/10-alpha` イベントで実行されますが、`releases/beta/3-alpha` または `!releases/**-alpha` を対象とする pull request では実行されません。 <!-- 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`](/ja/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore) の両方を定義すると、ワークフローは両方のフィルターが満たされた場合にのみ実行されます。

`branches`、`branches-ignore`、`tags`、および `tags-ignore` のキーワードは、複数のブランチまたはタグ名に一致する文字 (`*`、`**`、`+`、`?`、`!` など) を使用する glob パターンを許容します。 名前にこれらの文字のいずれかが含まれており、リテラルの一致が必要な場合は、\_\_ でこれらの各特殊文字を`\`する必要があります。 glob パターンの詳細については、[GitHub Actions　のワークフロー構文](/ja/actions/reference/workflows-and-actions/workflow-syntax#filter-pattern-cheat-sheet) を参照してください。

#### ブランチとタグを含める例

`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`)

```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 ref の名前に対して評価されます。 たとえば、次のワークフローは、`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.*
```

#### ブランチやタグを含めたり除外したりする例

1 つのワークフローで同じイベントをフィルターするために `branches` と `branches-ignore` を使用することはできません。 同様に、1 つのワークフローで同じイベントをフィルターするために `tags` と `tags-ignore` を使用することはできません。 1 つのイベントに対してブランチまたはタグ パターンを含める/除外の両方を行う場合は、`branches` または `tags` フィルターと `!` 文字を使用して、除外するブランチまたはタグを指定します。

`!` 文字を含むブランチを定義する場合は、`!` 文字を含まないブランチも 1 つ以上定義する必要があります。 ブランチの除外のみを行いたい場合は、代わりに `branches-ignore` を使用します。 同様に、`!` 文字を含むタグを定義する場合は、`!` 文字を含まないタグも 1 つ以上定義する必要があります。 タグの除外のみを行いたい場合は、代わりに `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'
```

### フィルターを使用して pull request またはプッシュ イベントに対して特定のパスをターゲットにする

`push` と `pull_request` のイベントを使用すると、変更されるファイル パスに基づいて実行するワークフローを構成できます。 タグのプッシュでは、パス フィルターは評価されません。

ファイル パス パターンを包含する場合、またはファイル パス パターンの包含と除外の両方を行う場合は、`paths` フィルターを使用します。 ファイル パス パターンの除外のみを行う場合は、`paths-ignore` フィルターを使用します。
`paths` と `paths-ignore` のフィルターの両方をワークフロー内の同じイベントで使うことはできません。 1 つのイベントに対してパス パターンの包含と除外の両方を行う場合は、除外するパスを示すために`paths` 文字を接頭辞にした`!`フィルタを使用します。

> \[!NOTE]
> `paths`パターンを定義する順序により、結果に違いが生じます:
>
> * 正のパターンに一致した後に、`!` が先頭に付いた負のパターンに一致すると、そのパスは除外されます。
> * 否定のマッチングパターンの後に肯定のマッチングパターンを定義すると、パスを再び含めます。

`branches`
/
`branches-ignore` と `paths`/`paths-ignore` の両方を定義すると、ワークフローは両方のフィルターが満たされた場合にのみ実行されます。

`paths` と `paths-ignore` のキーワードは、複数のパス名と一致するために `*` と `**` のワイルドカード文字を使用する glob パターンを受け入れます。 詳細については、「[GitHub Actions　のワークフロー構文](/ja/actions/reference/workflows-and-actions/workflow-syntax#filter-pattern-cheat-sheet)」を参照してください。

#### 例: パスの包含

`paths` フィルターにパターンにマッチするパスが 1 つでもあれば、ワークフローは実行されます。 たとえば、次のワークフローは、JavaScript ファイル (`.js`) をプッシュするたびに実行されます。

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

パス フィルター、[ブランチ フィルター](/ja/actions/reference/workflows-and-actions/workflow-syntax#onpull_requestpull_request_targetbranchesbranches-ignore)、または[コミット メッセージ](/ja/actions/how-tos/manage-workflow-runs/skip-workflow-runs)のためにワークフローがスキップされる場合、そのワークフローに関連付けられているチェックは "保留中" 状態のままになります。 これらのチェックを成功させる必要がある pull request は、マージが禁止されます。

#### 例: パスの除外

すべてのパス名が `paths-ignore` のパターンと一致する場合、ワークフローは実行されません。 パス名が `paths-ignore` のパターンと一致しない場合は、一部のパス名がパターンと一致する場合でも、ワークフローが実行されます。

以下のパスのフィルターを持つワークフローは、リポジトリのルートにある `docs` ディレクトリ外のファイルを少なくとも 1 つ含む `push` イベントでのみ実行されます。

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

#### 例: パスの包含および除外

1 つのワークフローで同じイベントのフィルター処理をするために `paths` と `paths-ignore` を使用することはできません。 1 つのイベントに対してパス パターンの包含と除外の両方を行う場合は、除外するパスを示すために`!` 文字を接頭辞にした`paths`フィルタを使用します。

`!` 文字を含むパスを定義する場合は、`!` 文字を含まないパスも 1 つ以上定義する必要があります。 パスの除外のみを行いたい場合は、代わりに `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 diffの比較

フィルターは、変更されたファイルを評価し、`paths-ignore` または `paths` のリストに対してファイルを実行することで、ワークフローを実行すべきか判断します。 ファイルが変更されていない場合、ワークフローは実行されません。

GitHub では、プッシュの場合は 2 ドットの差分を使用し、pull requestは 3 ドットの差分を使用して、変更されたファイルの一覧が生成されます。

* **プル リクエスト:** 3 点差分は、トピック ブランチの最新バージョンと、トピック ブランチが最後にベース ブランチと同期された時点のコミットを比較したものです。
* **既存のブランチへのプッシュ:** ツードット diff は、ヘッド SHA とベース SHA を互いに直接比較します。
* **新しいブランチへのプッシュ:** プッシュされた最も古い祖先コミットの親を基準にした 2 ドット差分です。

状況によっては、フィルター処理されたワークフローの実行方法を変更する制限 GitHub Actions 適用されます。

* プッシュに 1,000 を超えるコミットが含まれている場合、ワークフローは **常に** 実行されます。
* 差分の生成がタイムアウトすると、ワークフローは **常に** 実行されます。
* 生成された差分に 3,000 を超えるファイルが含まれており、ワークフロー フィルターが一致するファイルがフィルターによって返された最初の 3,000 に **含まれていない** 場合、ワークフローは実行されません。

これらの動作を観察する場合は、フィルターをより具体的にするか、プッシュ要求とプル要求の操作方法を変更して、より簡単な相違を生成することが必要になる場合があります。

詳しくは、「[支店](/ja/pull-requests/reference/branches)」をご覧ください。

### フィルターを使用してワークフロー実行イベントに対して特定のブランチをターゲットにする

`workflow_run` イベントを使用する場合は、ワークフローをトリガーするためにトリガーするワークフローが稼働する必要があるブランチを指定できます。

`branches` フィルターと `branches-ignore` フィルターは、複数のブランチ名に一致する文字 (`*`、`**`、`+`、`?` など) を使用する glob パターンを受け入れます。`!` 名前にこれらの文字のいずれかが含まれていて、文字どおりに一致させたい場合は、これらの各特殊文字を\_\_ で`\`する必要があります。 glob パターンの詳細については、[GitHub Actions　のワークフロー構文](/ja/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` のフィルターの両方をワークフロー内の同じイベントで使うことはできません。 1 つのイベントに対して分岐パターンの適用と除外の両方を行う場合は、`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` コンテキスト内の入力を受け取ります。 詳細については、「[コンテキスト](/ja/actions/reference/workflows-and-actions/contexts#inputs-context)」を参照してください。

> \[!NOTE]
>
> * ワークフローは、`github.event.inputs` コンテキスト内の入力も受け取ります。
>   `inputs` コンテキストと `github.event.inputs` コンテキストの情報ですが、`inputs` コンテキストではブール値が文字列に変換されず、ブール値として保持されます。
>   `choice` 型は文字列に解決され、1 つの選択可能なオプションです。
> *

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

## 再利用可能なワークフローの入力、出力、シークレットを定義する

再利用可能なワークフローが呼び出し元のワークフローから受け取る入力とシークレットを定義できます。 また、再利用可能なワークフローが呼び出し元のワークフローで使用できるようにする出力を指定することもできます。 詳しくは、「[ワークフローを再利用する](/ja/actions/how-tos/reuse-automations/reuse-workflows)」をご覧ください。

## イベント情報を使用する

ワークフロー実行をトリガーしたイベントに関する情報は、`github.event` コンテキストで使用できます。
`github.event` コンテキストのプロパティは、ワークフローをトリガーしたイベントの種類によって異なります。 たとえば、イシューがラベル付けされたときにトリガーされるワークフローでは、そのイシューとラベルに関する情報が含まれます。

### イベントのすべてのプロパティを表示する

一般的なプロパティとペイロードの例については、webhook イベントのドキュメントを参照してください。 詳しくは、「[Webhook のイベントとペイロード](/ja/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/**` を変更する pull request が開かれると実行されます。 pull request 作成者 (`github.event.pull_request.user.login`) が `octobot` または `dependabot[bot]`されていない場合、ワークフローは GitHub CLI を使用して pull request (`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.'
```

コンテキストについて詳しくは、「[コンテキスト リファレンス](/ja/actions/reference/workflows-and-actions/contexts)」をご覧ください。 イベント ペイロードについて詳しくは、「[Webhook のイベントとペイロード](/ja/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'
```

#### イベントの種類を使用する例

たとえば、ワークフローをトリガーしたイベントに応じて異なるジョブまたはステップを実行したい場合は、条件を使って、イベント コンテキストに特定のイベントの種類が存在するかどうかをチェックできます。 次のワークフローは、イシューまたは pull request がクローズされるたびに実行されます。 イシューがクローズされたためにワークフローが実行された場合、`github.event` コンテキストには `issue` の値が含まれますが、`pull_request` の値は含まれません。 したがって、`if_issue` ステップは実行されますが、`if_pr` ステップは実行されません。 逆に、pull request がクローズされたためにワークフローが実行された場合、`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)」をご覧ください。 条件を使う方法について詳しくは、「[ワークフロー内とアクション内で式を評価する](/ja/actions/reference/workflows-and-actions/expressions)」をご覧ください。

### 環境を使用してワークフロー ジョブを手動でトリガーする

ワークフロー内の特定のジョブを手動でトリガーしたい場合は、特定のチームまたはユーザーからの承認を必要とする環境を使用できます。 まず、必要なレビュー担当者を使用して環境を構成します。 詳しくは、「[デプロイメント用の環境管理](/ja/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments)」をご覧ください。 次に、`environment:` キーを使って、ワークフロー内のジョブで環境名を参照します。 環境を参照するジョブは、少なくとも 1 人のレビュー担当者がそのジョブを承認するまで実行されません。

たとえば、次のワークフローは、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 Pro、 GitHub Team、または GitHub Enterpriseを使用する必要があります。
>
> GitHub Free、GitHub Pro、またはGitHub Teamプランを使用している場合、待機タイマーや必要なレビュー担当者などの他のデプロイ保護規則は、パブリック リポジトリでのみ使用できます。

## 使用できるイベント

使用できるすべてのイベントの一覧については、「[ワークフローをトリガーするイベント](/ja/actions/reference/workflows-and-actions/events-that-trigger-workflows)」をご覧ください。