Skip to main content

Triggering a workflow

How to automatically trigger GitHub Actions workflows

ノート: GitHubホストランナーは、現在GitHub Enterprise Serverでサポートされていません。 GitHubパブリックロードマップで、計画されている将来のサポートに関する詳しい情報を見ることができます。

About workflow triggers

ワークフロートリガーは、ワークフローの実行を引き起こすイベントです。 それらのイベントには以下のようなものがあります。

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

たとえば、リポジトリのデフォルトブランチにプッシュが行われたときや、リリースが作成されたときや、Issueがオープンされたときにワークフローが実行されるように設定できます。

Workflow triggers are defined with the on key. 詳しい情報については、「GitHub Actions のワークフロー構文」を参照してください。

ワークフローの実行がトリガーされるには、以下のステップが生じます。

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

  2. GitHub Enterprise Server searches the .github/workflows directory in 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. ワークフローを実行すると、GitHub Enterprise Server はランナー環境において GITHUB_SHA (コミット SHA) および GITHUB_REF (Git ref) 環境変数を設定します。 詳しい情報については、「環境変数の利用」を参照してください。

Triggering a workflow from a workflow

タスクの実行にリポジトリのGITHUB_TOKENを使用する場合、GITHUB_TOKENによってトリガーされたイベントは、新しいワークフローの実行を発生させません。 これによって、予想外の再帰的なワークフローの実行が生じないようになります。 たとえば、ワークフローの実行によってリポジトリのGITHUB_TOKENを使ったコードのプッシュが行われた場合、そのリポジトリにpushイベントが生じた際に実行されるよう設定されたワークフローが含まれていても、新しいワークフローの実行は行われません。 For more information, see "Authenticating with the GITHUB_TOKEN."

If you do want to trigger a workflow from within a workflow run, you can use a personal access token instead of GITHUB_TOKEN to trigger events that require a token. 個人アクセストークンを作成し、それをシークレットとして保存する必要があります。 GitHub Actionsの利用コストを最小化するために、再帰的あるいは意図しないワークフローの実行が生じないようにしてください。 For more information about creating a personal access token, see "Creating a personal access token." For more information about storing a personal access token as a secret, see "Creating and storing encrypted secrets."

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:
          GITHUB_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:
          GITHUB_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 "Events that trigger workflows."

単一イベントの利用

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

on: push

複数イベントの利用

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

on: [push, fork]

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

複数のイベントでのアクティビティタイプとフィルタの利用

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イベントはcreatedediteddeletedというアクティビティタイプを持ちます。 ワークフローがlabelイベントでトリガーされるなら、それはラベルが作成、編集、削除されたときに実行されます。 labelイベントにcreatedアクティビティタイプを指定したなら、ワークフローはラベルが作成されたときに実行され、ラベルが編集あるいは削除されたときには実行されません。

on:
  label:
    types:
      - created

複数のアクティビティタイプを指定した場合、ワークフローのトリガーを引き起こすのに必要なのはそれらのイベントアクティビティタイプの1つだけです。 ワークフローに対するトリガーになるイベントアクティビティタイプが複数同時に発生した場合、複数のワークフローの実行がトリガーされます。 たとえば、以下のワークフローはIssueがオープンされるかラベル付けされたときにトリガーされます。 2つのラベルを付けたIssueがオープンされた場合、Issueのオープンイベントに対して1つ、そして2つのIssueのラベル付けのイベントに対して2つ、合計3つのワークフローの実行が開始されます。

on:
  issues:
    types:
      - opened
      - labeled

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

フィルタの利用

一部のイベントは、ワークフローを実行すべきときを詳細に制御できるようにしてくれるフィルタを持ちます。

たとえば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フィルタを使ってください。 branchesbranches-ignoreを1つのワークフロー内の同じイベントに使うことはできません。

branches/branches-ignorepathsの両方を定義した場合、ワークフローはどちらのフィルタも満たされた場合にのみ実行されます。

branches及びbranches-ignoreキーワードは、複数のブランチ名にマッチさせるために***+?!などの文字を使うglobパターンを受け付けます。 これらの文字のいずれかを含む名前に対してリテラルの一致をさせたい場合には、これらの特殊文字を\でエスケープしなければなりません。 globパターンに関する詳しい情報については「フィルタパターンのチートシート」を参照してください。

例: ブランチを含める

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/**'

例: ブランチの除外

パターンがtags-ignoreとマッチする場合、ワークフローは実行されません。 branchesで定義されているパターンは、Git refの名前と照らし合わせて評価されます。 たとえば、次のワークフローは以下をターゲットとしないPull Requestに対するpull_requestイベントがあった場合に実行されます。

  • mona/octocatという名前のブランチ(refs/heads/mona/octocat)
  • releases/beta/3-alphaのように、releases/**-alphaにマッチする名前のブランチ(refs/releases/beta/3-alpha)
on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches-ignore:    
      - 'mona/octocat'
      - 'releases/**-alpha'

例: ブランチを含めるとともに除外

branches及びbranches-ignoreフィルタを1つのワークフロー中の同じイベントをフィルタリングするために使うことはできません。 1つのイベントに対して含めるブランチパターンと除外するブランチパターンをどちらも使いたい場合には、branchesフィルタを!文字と合わせて使い、除外するブランチを示してください。

!文字を使ってブランチを定義する場合、!文字なしで少なくとも1つのブランチを定義する必要もあります。 ブランチの除外だけをしたい場合には、代わりにbranches-ignoreを使ってください。

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

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

以下のワークフローは、releases/10releases/beta/mona へのpull_requestイベントで実行されますが、releases/10-alphareleases/beta/3-alphaに対するPull Requstでは実行されません。肯定のマッチングパターンの後に、否定のマッチングパターン !releases/**-alpha が続いているからです。

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フィルタを1つのワークフロー中の同じイベントでどちらも使用することはできません。

タグ名のパターンを含めたい場合、あるいはタグ名のパターンを含めるとともに除外もしたい場合に、tagsフィルターを使ってください。 タグ名のパターンを除外のみしたい場合には、tags-ignoreフィルターを使ってください。 tags及びtags-ignoreフィルタを1つのワークフロー中の同じイベントでどちらも使用することはできません。

tags/tags-ignoreのみ、もしくはbranches/branches-ignoreだけを定義した場合、ワークフローは未定義のGit refに影響するイベントに対しては実行されません。 tags/tags-ignoreあるいはbranches/branches-ignoreのどちらも定義しなかった場合、ブランチもしくはタグに影響するイベントに対して実行されます。 branches/branches-ignore及びpathsをどちらも定義した場合、ワークフローは双方のフィルタを満たす場合にのみ実行されます。

branchesbranches-ignoretagstags-ignoreのキーワードは、1つ以上ののブランチもしくはタグ名にマッチする***+?!といった文字を使うglobパターンを受け付けます。 これらの文字のいずれかを含む名前に対してリテラルの一致をさせたい場合には、これらの特殊文字を\エスケープしなければなりません。 globパターンに関する詳しい情報については「フィルタパターンのチートシート」を参照してください。

例: ブランチ及びタグ名を含める

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:
    # refs/headsに対してマッチするパターンのシーケンス
    branches:    
      - main
      - 'mona/octocat'
      - 'releases/**'
    # refs/tagsに対してマッチするパターンのシーケンス
    tags:        
      - v2
      - v1.*

例: ブランチ及びタグの除外

パターンがbranches-ignoreまたはtags-ignoreとマッチする場合、ワークフローは実行されません。 branchesおよびtagsで定義されているパターンは、Git refの名前と照らし合わせて評価されます。 たとえば、次のワークフローはpushイベントがあり、そのpushイベントが以下に対するものでない場合に実行されます。

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

例: ブランチとタグを含めるとともに除外

branches及びbranches-ignoreフィルタを1つのワークフロー中の同じイベントをフィルタリングするために使うことはできません。 同様に、tags及びtags-ignoreを1つのワークフロー中の同じイベントをフィルタリングするために使うことはできません。 1つのイベントに対してブランチもしくはタグパターンを含めるとともに除外したい場合には、branchesもしくはtagsフィルタを!文字とともに使って、除外すべきブランチもしくはタグを示してください。

!文字を使ってブランチを定義する場合、!文字なしで少なくとも1つのブランチを定義する必要もあります。 ブランチの除外だけをしたい場合には、代わりにbranches-ignoreを使ってください。 同様に、!文字でタグを定義する場合には、!なしで少なくとも1つのタグを定義する必要があります。 タグの除外だけをしたい場合には、代わりにtags-ignoreを使ってください。

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

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

以下のワークフローは、releases/10releases/beta/mona へのプッシュで実行されますが、releases/10-alphareleases/beta/3-alpha へのプッシュでは実行されません。肯定のマッチングパターンの後に、否定のマッチングパターン !releases/**-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つのワークフロー中の同じイベントでどちらも使用することはできません。

branches/branches-ignorepathsの両方を定義した場合、ワークフローはどちらのフィルタも満たされた場合にのみ実行されます。

paths および paths-ignore キーワードは、*** のワイルドカード文字を使って複数のパス名と一致させる glob パターンを受け付けます。 詳しい情報については、「フィルタパターンのチートシート」を参照してください。

例: パスを含める

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

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

ノート: path filteringbranch filteringcommit messageによってワークフローがスキップされた場合、そのワークフローに関連づけられたチェックは、"Pending"状態のままになります。 それらのチェックの成功を必要とするPull Requestのマージはブロックされます。 詳しい情報については「スキップされた必須のチェックの処理」を参照してください。

例: パスの除外

すべてのパス名が paths-ignore のパターンと一致する場合、ワークフローは実行されません。 paths-ignore内のパターンにマッチしないパス名があった場合、場合、パターンにマッチするパスがあったとしても、ワークフローは実行されます。

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

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

例: パスを含めるとともに除外

paths及びpaths-ignoreを1つのワークフロー中の同じイベントをフィルタリングするために使うことはできません。 1つのイベントに対して含めるパスパターンと除外するパスパターンをどちらも使いたい場合には、pathsフィルタを!文字と合わせて使い、除外するパスを示してください。

!文字を使ってパスを定義する場合、!文字なしで少なくとも1つのパスを定義する必要もあります。 パスの除外だけをしたい場合には、代わりにpaths-ignoreを使ってください。

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

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

この例は、pushイベントにsub-projectディレクトリあるいはそのサブディレクトリ内のファイルが含まれ、そのファイルがsub-project/docsディレクトリ内にはない場合に実行されます。 たとえばsub-project/index.jsもしくはsub-project/src/index.jsを変更するプッシュはワークフローを実行させますが、sub-project/docs/readme.mdだけを変更するプッシュは実行させません。

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

Git diffの比較

ノート: 1,000以上のコミットをプッシュする場合、あるいはGitHubがタイムアウトのためにdiffを生成できない場合、そのワークフローは常に実行されます。

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

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

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

Diffは300ファイルに制限されています。 フィルタが返す先頭の300ファイル内にマッチしない変更されたファイルがある場合、ワークフローは実行されません。 ワークフローが自動的に実行されるよう、さらに具体的なフィルタを作成する必要があるかもしれません。

詳しい情報については「Pull Request中のブランチの比較について」を参照してください。

Using filters to target specific branches for workflow run events

workflow_runを使う場合、ワークフローがトリガーされるためには、どのブランチでトリガーされたワークフローが実行されなければならないかを指定できます。

branches及びbranches-ignoreフィルタは、複数のブランチ名にマッチさせるために***+?!などの文字を使うglobパターンを受け付けます。 これらの文字のいずれかを含む名前に対してリテラルの一致をさせたい場合には、これらの特殊文字を\エスケープしなければなりません。 globパターンに関する詳しい情報については「フィルタパターンのチートシート」を参照してください。

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

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

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

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

branchesbranches-ignoreを1つのワークフロー内の同じイベントに使うことはできません。 1つのイベントに対して含めるブランチパターンと除外するブランチパターンをどちらも使いたい場合には、branchesフィルタを!文字と合わせて使い、除外するブランチを示してください。

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

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

たとえば、以下のトリガーを持つワークフローは、Buildというナメのワークフローがreleases/10もしくはreleases/beta/monaという名前のブランチ上で実行されている場合に実行されますが、releases/10-alphareleases/beta/3-alphamainといった名前のブランチ上で実行されている場合には実行されません。

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

Defining inputs for manually triggered workflows

workflow_dispatchイベントを使う場合、ワークフローに渡す入力を指定することもできます。

トリガーされたワークフローは、入力をgithub.event.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:  ${{ github.event.inputs.print_tags == 'true' }} 
    steps:
      - name: Print the input tag to STDOUT
        run: echo  The tags are ${{ github.event.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 events and payloads."

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:
          GITHUB_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 "Contexts." For more information about event payloads, see "Webhook events and payloads."

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 "Expressions."

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 "Using 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
        echo 'building'

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

Environments, environment protection rules, and environment secrets are available in public repositories for all products. For access to environments in private repositories, you must use GitHub Enterprise.

Available events

For a full list of available events, see "Events that trigger workflows."