Triggering a workflow

About workflow triggers

ワークフロー トリガーは、ワークフローの実行を引き起こすイベントです。 次のようなイベントがあります。

• ワークフローのリポジトリ内で発生するイベント
• GitHub の外部で発生し、GitHub 上で repository_dispatch イベントをトリガーするイベント
• スケジュールされた時刻
• マニュアル

たとえば、リポジトリの既定のブランチに対してプッシュが行われたときや、リリースが作成されたとき、またはイシューが開かれたときに実行するようにワークフローを構成できます。

Workflow triggers are defined with the on key. For more information, see GitHub Actions　のワークフロー構文.

The following steps occur to trigger a workflow run:

1. An event occurs on your repository. The event has an associated commit SHA and Git ref.

2. GitHub searches the .github/workflows directory in the root of your repository for workflow files that are present in the associated commit SHA or Git ref of the event.

3. A workflow run is triggered for any workflows that have on: values that match the triggering event. Some events also require the workflow file to be present on the default branch of the repository in order to run.

   Each workflow run will use the version of the workflow that is present in the associated commit SHA or Git ref of the event. When a workflow runs, GitHub sets the GITHUB_SHA (commit SHA) and GITHUB_REF (Git ref) environment variables in the runner environment. For more information, see Store information in variables.

Triggering a workflow from a workflow

リポジトリの GITHUB_TOKEN を使ってタスクを実行した場合、GITHUB_TOKEN によってトリガーされたイベントでは (workflow_dispatch と repository_dispatch を除きます)、新しいワークフロー実行は作成されません。 これによって、予想外の再帰的なワークフローの実行が生じないようになります。 たとえば、ワークフロー実行でリポジトリの GITHUB_TOKEN を使用してコードがプッシュされた場合、push イベントの発生時に実行するように構成されたワークフローがリポジトリに含まれている場合でも、新しいワークフローは実行されません。 For more information, see Automatic token authentication.

If you do want to trigger a workflow from within a workflow run, you can use a GitHub App installation access token or a personal access token instead of GITHUB_TOKEN to trigger events that require a token.

If you use a GitHub App, you'll need to create a GitHub App and store the app ID and private key as secrets. For more information, see GitHub Actions ワークフローで GitHub App を使用して認証済み API 要求を作成する. If you use a personal access token, you'll need to create a personal access token and store it as a secret. For more information about creating a personal access token, see 個人用アクセス トークンを管理する. For more information about storing secrets, see Using secrets in GitHub Actions.

To minimize your GitHub Actions usage costs, ensure that you don't create recursive or unintended workflow runs.

For example, the following workflow uses a personal access token (stored as a secret called MY_TOKEN) to add a label to an issue via GitHub CLI. Any workflows that run when a label is added will run once this step is performed.

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"

Conversely, the following workflow uses GITHUB_TOKEN to add a label to an issue. It will not trigger any workflows that run when a label is added.

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"

Using events to trigger workflows

Use the on key to specify what events trigger your workflow. For more information about events you can use, see ワークフローをトリガーするイベント.

Using a single event

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

on: push

Using multiple events

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

on: [push, fork]

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

Using activity types and filters with multiple events

You can use activity types and filters to further control when your workflow will run. For more information, see Using event activity types and Using filters. イベントにアクティビティの種類やフィルターを指定し、ワークフローが複数のイベントでトリガーされる場合、各イベントを個別に構成する必要があります。 構成しないイベントも含め、すべてのイベントにはコロン (:) を追加する必要があります。

たとえば、以下の on の値を持つワークフローは、次のような場合に実行されます。

• ラベルが作成されたとき
• リポジトリ内の main ブランチにプッシュされたとき
• GitHub Pages 対応のブランチにプッシュされたとき

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

Using event activity types

一部のイベントには、ワークフローを実行するタイミングをより細かく制御できるアクティビティの種類があります。 on.<event_name>.types を使用して、ワークフロー実行をトリガーするイベント アクティビティの種類を定義します。

たとえば、issue_comment イベントには、created、edited、deleted のアクティビティの種類があります。 label イベントでワークフローがトリガーされる場合、ラベルが作成、編集、または削除されるたびにワークフローが実行されます。 label イベントに created アクティビティの種類を指定すると、ワークフローはラベルの作成時に実行されますが、ラベルの編集または削除時には実行されません。

on:
  label:
    types:
      - created

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

on:
  issues:
    types:
      - opened
      - labeled

各イベントとそのアクティビティの種類の詳細については、「ワークフローをトリガーするイベント」を参照してください。

Using filters

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

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

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

Using filters to target specific branches for pull request events

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

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

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

branches と branches-ignore のキーワードは、複数のブランチ名に一致する文字 (*、**、+、?、! など) を使用する glob パターンを受け入れます。 名前にこれらの文字のいずれかが含まれており、リテラルの一致が必要な場合は、\ でこれらの各特殊文字をエスケープする必要があります。 glob パターンの詳細については、GitHub Actions　のワークフロー構文 を参照してください。

Example: Including branches

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

マージ前にパスするためにワークフローが必要な場合は、パスまたはブランチ フィルターを使用してワークフローの実行をスキップしないでください。 詳細については、「Skipping workflow runs」および「ルールセットで使用できるルール」を参照してください。

ブランチ フィルター、パス フィルター、または コミット メッセージのためにワークフローがスキップされる場合、そのワークフローに関連付けられているチェックは "保留中" 状態のままになります。 これらのチェックを成功させる必要がある pull request は、マージが禁止されます。

Example: Excluding branches

パターンが branches-ignore パターンと一致する場合、ワークフローは実行されません。 branches-ignore で定義されているパターンは、Git ref の名前に対して評価されます。 たとえば、次のワークフローは、pull request の対象とならない限り、pull_request イベントが発生するたびに実行されます。

• mona/octocat という名前のブランチ (refs/heads/mona/octocat)
• 名前が releases/beta/3-alpha のように releases/**-alpha と一致する ブランチ (refs/heads/releases/beta/3-alpha)

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

Example: Including and excluding branches

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

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

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

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

次のワークフローは、否定のパターン !releases/**-alpha が肯定のパターンの後に続くため、releases/10 または releases/beta/mona を対象とする pull request の pull_request イベントで実行されますが、releases/10-alpha または releases/beta/3-alpha を対象とする pull request では実行されません。

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

Using filters to target specific branches or tags for push events

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 の両方を定義すると、ワークフローは両方のフィルターが満たされた場合にのみ実行されます。

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

Example: Including branches and tags

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.*

Example: Excluding branches and tags

パターンが branches-ignore または tags-ignore パターンと一致する場合、ワークフローは実行されません。 branches と tags で定義されているパターンは、Git ref の名前に対して評価されます。 たとえば、次のワークフローは、push イベントがない限り、push イベントが発生するたびに実行されます。

• mona/octocat という名前のブランチ (refs/heads/mona/octocat)
• releases/beta/3-alpha のように名前が releases/**-alpha と一致する ブランチ (refs/heads/releases/beta/3-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.*

Example: Including and excluding branches and tags

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

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

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

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

次のワークフローは、否定パターン !releases/**-alpha が肯定パターンに従うため、releases/10 または releases/beta/mona へのプッシュで実行され、releases/10-alpha または releases/beta/3-alpha では実行されません。

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

Using filters to target specific paths for pull request or push events

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

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

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

paths と paths-ignore のキーワードは、複数のパス名と一致するために * と ** のワイルドカード文字を使用する glob パターンを受け入れます。 詳細については、「GitHub Actions　のワークフロー構文」を参照してください。

Example: Including paths

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

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

マージ前にパスするためにワークフローが必要な場合は、パスまたはブランチ フィルターを使用してワークフローの実行をスキップしないでください。 詳細については、「Skipping workflow runs」および「ルールセットで使用できるルール」を参照してください。

パス フィルター、ブランチ フィルター、またはコミット メッセージのためにワークフローがスキップされる場合、そのワークフローに関連付けられているチェックは "保留中" 状態のままになります。 これらのチェックを成功させる必要がある pull request は、マージが禁止されます。

Example: Excluding paths

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

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

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

Example: Including and excluding paths

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 のみを変更するプッシュはワークフローの実行をトリガーしません。

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

Git diff comparisons

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

GitHubはプッシュに対してはツードットdiff、Pull Requestに対してはスリードットdiffを使って変更されたファイルのリストを生成します。

• pull request: スリードット diff は、トピック ブランチの最新バージョンとトピック ブランチがベース ブランチと最後に同期されたコミットとの比較です。
• 既存のブランチへのプッシュ: ツードット diff は、ヘッド SHA とベース SHA を互いに直接比較します。
• 新しいブランチへのプッシュ: プッシュされた最も深いコミットの先祖の親に対するツードット diff です。

詳しくは、「プルリクエスト中でのブランチの比較について」をご覧ください。

Using filters to target specific branches for workflow run events

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

branches フィルターと branches-ignore フィルターは、複数のブランチ名に一致する文字 (*、**、+、? など) を使用する glob パターンを受け入れます。! 名前にこれらの文字のいずれかが含まれており、リテラルの一致が必要な場合は、\ でこれらの各特殊文字を_エスケープ_する必要があります。 glob パターンの詳細については、GitHub Actions　のワークフロー構文 を参照してください。

たとえば、次のトリガーを持つワークフローは、名前が releases/ で始まるブランチで Build という名前のワークフローが稼働している場合にのみ実行されます。

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

次のトリガーを持つワークフローは、名前が canary でないブランチで Build という名前のワークフローが稼働している場合にのみ実行されます。

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

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

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

• 肯定のマッチング パターンの後に否定のマッチング パターン（! のプレフィックスが付く） を定義すると、ブランチを除外します。
• 否定のマッチング パターンの後に肯定のマッチング パターンを定義すると、ブランチを再び含めます。

たとえば、次のトリガーを持つワークフローは、名前が releases/10 または releases/beta/mona で始まるブランチで Build という名前のワークフローが稼働している場合にのみ実行されますが、releases/10-alpha、releases/beta/3-alpha または main という名前のブランチでは実行されません。

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

Defining inputs for manually triggered workflows

workflow_dispatch イベントを使用すると、必要に応じてワークフローに渡される入力を指定できます。

このトリガーは、ワークフロー ファイルが既定のブランチにある場合に限りイベントを受信します。 トリガーされたワークフローは、inputs コンテキスト内の入力を受け取ります。 詳細については、「コンテキスト」を参照してください。

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

Defining inputs, outputs, and secrets for reusable workflows

You can define inputs and secrets that a reusable workflow should receive from a calling workflow. You can also specify outputs that a reusable workflow will make available to a calling workflow. For more information, see Reusing workflows.

Using event information

Information about the event that triggered a workflow run is available in the github.event context. The properties in the github.event context depend on the type of event that triggered the workflow. For example, a workflow triggered when an issue is labeled would have information about the issue and label.

Viewing all properties of an event

Reference the webhook event documentation for common properties and example payloads. For more information, see Webhook のイベントとペイロード.

You can also print the entire github.event context to see what properties are available for the event that triggered your workflow:

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

Accessing and using event properties

You can use the github.event context in your workflow. For example, the following workflow runs when a pull request that changes package*.json, .github/CODEOWNERS, or .github/workflows/** is opened. If the pull request author (github.event.pull_request.user.login) is not octobot or dependabot[bot], then the workflow uses the GitHub CLI to label and comment on the pull request (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.'

For more information about contexts, see ワークフロー実行に関するコンテキスト情報へのアクセス. For more information about event payloads, see Webhook のイベントとペイロード.

Further controlling how your workflow will run

If you want more granular control than events, event activity types, or event filters provide, you can use conditionals and environments to control whether individual jobs or steps in your workflow will run.

Using conditionals

You can use conditionals to further control whether jobs or steps in your workflow will run.

Example using a value in the event payload

For example, if you want the workflow to run when a specific label is added to an issue, you can trigger on the issues labeled event activity type and use a conditional to check what label triggered the workflow. The following workflow will run when any label is added to an issue in the workflow's repository, but the run_if_label_matches job will only execute if the label is named 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'

Example using event type

For example, if you want to run different jobs or steps depending on what event triggered the workflow, you can use a conditional to check whether a specific event type exists in the event context. The following workflow will run whenever an issue or pull request is closed. If the workflow ran because an issue was closed, the github.event context will contain a value for issue but not for pull_request. Therefore, the if_issue step will run but the if_pr step will not run. Conversely, if the workflow ran because a pull request was closed, the if_pr step will run but the if_issue step will not run.

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

For more information about what information is available in the event context, see Using event information. For more information about how to use conditionals, see ワークフローとアクションで式を評価する.

Using environments to manually trigger workflow jobs

If you want to manually trigger a specific job in a workflow, you can use an environment that requires approval from a specific team or user. First, configure an environment with required reviewers. For more information, see Managing environments for deployment. Then, reference the environment name in a job in your workflow using the environment: key. Any job referencing the environment will not run until at least one reviewer approves the job.

For example, the following workflow will run whenever there is a push to main. The build job will always run. The publish job will only run after the build job successfully completes (due to needs: [build]) and after all of the rules (including required reviewers) for the environment called production pass (due to 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'

Available events

For a full list of available events, see ワークフローをトリガーするイベント.