注: GitHub ホステッド ランナーは、現在 GitHub Enterprise Server でサポートされていません。 GitHub public roadmap で、今後の計画的なサポートの詳細を確認できます。
ワークフロー トリガーについて
ワークフロー トリガーは、ワークフローの実行を引き起こすイベントです。 次のようなイベントがあります。
- ワークフローのリポジトリ内で発生するイベント
- GitHub Enterprise Server の外部で発生し、GitHub Enterprise Server で
repository_dispatch
イベントをトリガーするイベント - スケジュールされた時刻
- マニュアル
たとえば、リポジトリの既定のブランチに対してプッシュが行われたときや、リリースが作成されたとき、またはイシューが開かれたときに実行するようにワークフローを構成できます。
ワークフロー トリガーは、on
キーを使って定義されます。 詳しくは、「GitHub Actions のワークフロー構文」を参照してください。
ワークフローの実行がトリガーされるには、以下のステップが生じます。
-
リポジトリでイベントが発生します。 イベントには、コミット SHA と Git ref が関連付けられています。
-
GitHub Enterprise Server は、リポジトリのルートにある
.github/workflows
ディレクトリで、イベントの関連付けらたコミット SHA または Git リファレンスに存在するワークフロー ファイルを検索します。 -
トリガーするイベントと一致する
on:
値を持つすべてのワークフローに対して、ワークフロー実行がトリガーされます。 一部のイベントでは、実行のために、リポジトリの既定のブランチにワークフロー ファイルが存在している必要もあります。各ワークフロー実行では、そのイベントに関連付けられたコミット SHA または Git ref に存在するワークフローのバージョンが使用されます。 ワークフローが実行されると、GitHub Enterprise Server によってランナー環境の
GITHUB_SHA
(コミット SHA) とGITHUB_REF
(Git ref) の環境変数が設定されます。 詳しくは、「変数に情報を格納する」を参照してください。
ワークフローからワークフローをトリガーする
リポジトリGITHUB_TOKEN
を使用してタスクを実行する場合、 GITHUB_TOKEN
によってworkflow_dispatch
トリガーされるイベント (例外) と repository_dispatch
、 は新しいワークフロー実行を作成しません。 これによって、予想外の再帰的なワークフローの実行が生じないようになります。 たとえば、ワークフロー実行でリポジトリの GITHUB_TOKEN
を使用してコードがプッシュされた場合、push
イベントの発生時に実行するように構成されたワークフローがリポジトリに含まれている場合でも、新しいワークフローは実行されません。 詳しくは、「自動トークン認証」をご覧ください。
ワークフロー内からワークフローをトリガーする場合、トークンを必要とするイベントをトリガーする GITHUB_TOKEN
の代わりに、GitHub App インストール アクセス トークンまたは personal access token を使えます。
GitHub App を使う場合、GitHub App を作成し、シークレットとしてアプリ ID とプライベート キーを格納する必要があります。 詳しくは、「GitHub Actions ワークフローで GitHub App を使用して認証済み API 要求を作成する」を参照してください。 personal access token を使う場合、personal access token を作成し、それをシークレットとして格納する必要があります。 personal access tokenの作成について詳しくは、「個人用アクセス トークンを管理する」をご覧ください。 シークレットの保管の詳細については、「GitHub Actions でのシークレットの使用」を参照してください。
GitHub Actionsの利用コストを最小化するために、再帰的あるいは意図しないワークフローの実行が生じないようにしてください。
たとえば、次のワークフローでは、(MY_TOKEN
というシークレットとして格納された) personal access token を使い、GitHub CLI を介してイシューにラベルを追加します。 ラベルの追加時に実行されるすべてのワークフローは、このステップが実行されると実行されます。
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
キーを使って、ワークフローをトリガーするイベントを指定します。 使えるイベントについて詳しくは、「ワークフローをトリガーするイベント」をご覧ください。
単一のイベントを使用する
たとえば、次の on
の値を持つワークフローは、ワークフローのリポジトリ内の任意のブランチにプッシュが行われるときに実行されます。
on: push
複数のイベントを使用する
1 つのイベントまたは複数のイベントを指定できます。 たとえば、次の on
の値を持つワークフローは、ワークフローのリポジトリ内の任意のブランチにプッシュが行われるとき、または誰かがリポジトリをフォークしたときに実行されます。
on: [push, fork]
複数のイベントを指定する場合、ワークフローをトリガーするために必要なイベントは 1 つだけです。 ワークフローの複数のトリガー イベントが同時に発生した場合、複数のワークフロー実行がトリガーされます。
アクティビティの種類とフィルターを複数のイベントと共に使用する
アクティビティの種類とフィルターを使って、ワークフローを実行するタイミングをさらに細かく制御できます。 詳細については、「イベント アクティビティの種類を使用する」と「フィルターを使用する」を参照してください。 イベントにアクティビティの種類やフィルターを指定し、ワークフローが複数のイベントでトリガーされる場合、各イベントを個別に構成する必要があります。 構成しないイベントも含め、すべてのイベントにはコロン (:
) を追加する必要があります。
たとえば、以下の on
の値を持つワークフローは、次のような場合に実行されます。
- ラベルが作成されたとき
- リポジトリ内の
main
ブランチにプッシュされたとき - GitHub Pages 対応のブランチにプッシュされたとき
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
複数のアクティビティの種類を指定した場合、ワークフローをトリガーするために発生する必要があるのは、それらのイベント アクティビティの種類のうちの 1 つだけです。 ワークフローの複数のトリガー イベント アクティビティの種類が同時に発生した場合、複数のワークフロー実行がトリガーされます。 たとえば、次のワークフローは、Issue がオープンされた場合またはラベル付けされた場合にトリガーされます。 2 つのラベルを持つ Issue がオープンされると、3 つのワークフロー実行 (1 つは Issue がオープンされたイベント用、2 つは Issue のラベルが付いたイベント用) が開始されます。
on:
issues:
types:
- opened
- labeled
各イベントとそのアクティビティの種類の詳細については、「ワークフローをトリガーするイベント」を参照してください。
フィルターを使用する
一部のイベントには、ワークフローを実行するタイミングをより細かく制御できるフィルターがあります。
たとえば、push
イベントの branches
フィルターでは、プッシュが発生したときではなく、branches
フィルターと同じブランチに対してプッシュが発生したときのみ、ワークフローを実行できます。
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
の両方を定義すると、ワークフローは両方のフィルターが満たされた場合にのみ実行されます。
branches
と branches-ignore
のキーワードは、複数のブランチ名に一致する文字 (*
、**
、+
、?
、!
など) を使用する glob パターンを受け入れます。 名前にこれらの文字のいずれかが含まれており、リテラルの一致が必要な場合は、\
でこれらの各特殊文字をエスケープする必要があります。 glob パターンの詳細については、「GitHub Actions のワークフロー構文」を参照してください。
例: ブランチの包含
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/**'
ワークフローが必要な場合は、パスまたはブランチ フィルターを使用してワークフローの実行をスキップしないでください。 詳細については、「ワークフロー実行をスキップする」と「必要なワークフロー」を参照してください。
ブランチ フィルター、パス フィルター、または コミット メッセージのためにワークフローがスキップされる場合、そのワークフローに関連付けられているチェックは "保留中" 状態のままになります。 これらのチェックを成功させる必要がある pull request は、マージが禁止されます。
例: ブランチの除外
パターンが 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'
例: パスの包含および除外
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'
フィルターを使用してプッシュ イベントに対して特定のブランチまたはタグをターゲットにする
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 のワークフロー構文」を参照してください。
ブランチとタグを含める例
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
イベントがない限り、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.*
ブランチやタグを含めたり除外したりする例
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'
フィルターを使用して 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 のワークフロー構文」をご覧ください。
例: パスの包含
paths
フィルターにパターンにマッチするパスが 1 つでもあれば、ワークフローは実行されます。 たとえば、次のワークフローは、JavaScript ファイル (.js
) をプッシュするたびに実行されます。
on:
push:
paths:
- '**.js'
ワークフローが必要な場合は、パスまたはブランチ フィルターを使用してワークフローの実行をスキップしないでください。 詳細については、「ワークフロー実行をスキップする」と「必要なワークフロー」を参照してください。
パス フィルター、ブランチ フィルター、またはコミット メッセージのためにワークフローがスキップされる場合、そのワークフローに関連付けられているチェックは "保留中" 状態のままになります。 これらのチェックを成功させる必要がある pull request は、マージが禁止されます。
例: パスの除外
すべてのパス名が paths-ignore
のパターンと一致する場合、ワークフローは実行されません。 パス名が paths-ignore
のパターンと一致しない場合は、一部のパス名がパターンと一致する場合でも、ワークフローが実行されます。
以下のパスのフィルターを持つワークフローは、リポジトリのルートにある docs
ディレクトリ外のファイルを少なくとも 1 つ含む push
イベントでのみ実行されます。
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
のみを変更するプッシュはワークフローの実行をトリガーしません。
on:
push:
paths:
- 'sub-project/**'
- '!sub-project/docs/**'
Git diffの比較
Note
1,000 以上のコミットをプッシュする場合、あるいは GitHub がタイムアウトのために diff を生成できない場合、そのワークフローは常に実行されます。
フィルターは、変更されたファイルを評価し、paths-ignore
または paths
のリストに対してファイルを実行することで、ワークフローを実行すべきか判断します。 ファイルが変更されていない場合、ワークフローは実行されません。
GitHubはプッシュに対してはツードットdiff、Pull Requestに対してはスリードットdiffを使って変更されたファイルのリストを生成します。
- pull request: スリードット diff は、トピック ブランチの最新バージョンとトピック ブランチがベース ブランチと最後に同期されたコミットとの比較です。
- 既存のブランチへのプッシュ: ツードット diff は、ヘッド SHA とベース SHA を互いに直接比較します。
- 新しいブランチへのプッシュ: プッシュされた最も深いコミットの先祖の親に対するツードット diff です。
diff は 300 個のファイルに制限されます。 フィルターによって返された最初の 300 個のファイルに一致しないファイルが変更された場合、ワークフローは実行されません。 ワークフローが自動的に実行されるように、より具体的なフィルターを作成する必要がある場合があります。
詳しくは、「プルリクエスト中でのブランチの比較について」を参照してください。
フィルターを使用してワークフロー実行イベントに対して特定のブランチをターゲットにする
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'
手動でトリガーされるワークフローの入力を定義する
workflow_dispatch
イベントを使用すると、必要に応じてワークフローに渡される入力を指定できます。
このトリガーは、ワークフロー ファイルが既定のブランチにある場合に限りイベントを受信します。
トリガーされたワークフローは、inputs
コンテキストの入力を受け取ります。 詳細については、「コンテキスト」を参照してください。
注:
- ワークフローは、
github.event.inputs
コンテキスト内の入力も受け取ります。inputs
コンテキストとgithub.event.inputs
コンテキストの情報ですが、inputs
コンテキストではブール値が文字列に変換されず、ブール値として保持されます。choice
型は文字列に解決され、1 つの選択可能なオプションです。 inputs
の最上位レベルのプロパティの最大数は 10 です。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 }}
再利用可能なワークフローの入力、出力、シークレットを定義する
再利用可能なワークフローが呼び出し元のワークフローから受け取る入力とシークレットを定義できます。 また、再利用可能なワークフローが呼び出し元のワークフローで使用できるようにする出力を指定することもできます。 詳しくは、「ワークフローの再利用」を参照してください。
イベント情報を使用する
ワークフロー実行をトリガーしたイベントに関する情報は、github.event
コンテキストで使用できます。 github.event
コンテキストのプロパティは、ワークフローをトリガーしたイベントの種類によって異なります。 たとえば、イシューがラベル付けされたときにトリガーされるワークフローでは、そのイシューとラベルに関する情報が含まれます。
イベントのすべてのプロパティを表示する
一般的なプロパティとペイロードの例については、webhook イベントのドキュメントを参照してください。 詳しくは、「Webhook のイベントとペイロード」を参照してください。
また、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/**
を変更する pull request が開かれると実行されます。 pull request の作成者 (github.event.pull_request.user.login
) が octobot
でも dependabot[bot]
でもない場合、ワークフローでは GitHub CLI を使用して 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.'
コンテキストについて詳しくは、「ワークフロー実行に関するコンテキスト情報へのアクセス」をご覧ください。 イベント ペイロードについて詳しくは、「Webhook のイベントとペイロード」をご覧ください。
ワークフローの実行方法をさらに細かく制御する
イベント、イベント アクティビティの種類、またはイベント フィルターによる制御よりもさらに細かい制御が必要な場合は、条件と環境を使って、ワークフロー内の個々のジョブまたはステップを実行するかどうかを制御できます。
条件の使用
条件を使って、ワークフロー内のジョブまたはステップを実行するかどうかをさらに細かく制御できます。
イベント ペイロードの値を使用する例
たとえば、イシューに特定のラベルが追加されたときにワークフローを実行したい場合は、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'
イベントの種類を使用する例
たとえば、ワークフローをトリガーしたイベントに応じて異なるジョブまたはステップを実行したい場合は、条件を使って、イベント コンテキストに特定のイベントの種類が存在するかどうかをチェックできます。 次のワークフローは、イシューまたは pull request がクローズされるたびに実行されます。 イシューがクローズされたためにワークフローが実行された場合、github.event
コンテキストには issue
の値が含まれますが、pull_request
の値は含まれません。 したがって、if_issue
ステップは実行されますが、if_pr
ステップは実行されません。 逆に、pull request がクローズされたためにワークフローが実行された場合、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
イベント コンテキストで使用できる情報について詳しくは、「イベント情報を使用する」を参照してください。 条件を使う方法について詳しくは、「ワークフローとアクションで式を評価する」をご覧ください。
環境を使用してワークフロー ジョブを手動でトリガーする
ワークフロー内の特定のジョブを手動でトリガーしたい場合は、特定のチームまたはユーザーからの承認を必要とする環境を使用できます。 まず、必要なレビュー担当者を使用して環境を構成します。 詳しくは、「デプロイに環境の使用」を参照してください。 次に、environment:
キーを使って、ワークフロー内のジョブで環境名を参照します。 環境を参照するジョブは、少なくとも 1 人のレビュー担当者がそのジョブを承認するまで実行されません。
たとえば、次のワークフローは、main へのプッシュが発生するたびに実行されます。 build
ジョブは常に実行されます。 publish
ジョブは、build
ジョブが正常に完了し (needs: [build]
による)、production
という環境のすべてのルール (必要なレビュー担当者を含む) に合格した (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'
環境、環境シークレット、およびデプロイ保護ルールは、現在のすべての GitHub プランのパブリック リポジトリで使用できます。 ブロンズ、シルバー、ゴールドなどの従来のプランでは使用できません。 プライベートまたは内部リポジトリ内の環境、環境のシークレット、デプロイ ブランチにアクセスするには、GitHub Pro、GitHub Team または GitHub Enterprise を使う必要があります。
使用できるイベント
使えるすべてのイベントの一覧については、「ワークフローをトリガーするイベント」をご覧ください。