Skip to main content
ドキュメントには頻繁に更新が加えられ、その都度公開されています。本ページの翻訳はまだ未完成な部分があることをご了承ください。最新の情報については、英語のドキュメンテーションをご参照ください。本ページの翻訳に問題がある場合はこちらまでご連絡ください。

GitHub Actionsのワークフロー構文

ここには以下の内容があります:

ワークフローは、1つ以上のジョブからなる設定可能な自動化プロセスです。 ワークフローの設定を定義するには、YAMLファイルを作成しなければなりません。

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

ワークフロー用のYAML構文について

ワークフローファイルはYAML構文を使用し、ファイル拡張子が.ymlまたは.yamlである必要があります。 YAMLについて詳しくなく、学んでいきたい場合は、「Learn YAML in five minutes (Y分で学ぶYAML)」をお読みください。

ワークフローファイルは、リポジトリの.github/workflowsディレクトリに保存する必要があります。

name

ワークフローの名前。 GitHubでは、リポジトリのアクションページにワークフローの名前が表示されます。 nameを省略すると、GitHubはリポジトリのルートに対するワークフローファイルの相対パスをその値に設定します。

on

To automatically trigger a workflow, use on to define which events can cause the workflow to run. 使用可能なイベントの一覧は、「ワークフローをトリガーするイベント」を参照してください。

You can define single or multiple events that can a trigger workflow, or set a time schedule. You can also restrict the execution of a workflow to only occur for specific files, tags, or branch changes. These options are described in the following sections.

Using a single event

For example, a workflow with the following on value will run when a push is made to any branch in the workflow's repository:

on: push

Using multiple events

You can specify a single event or multiple events. For example, a workflow with the following on value will run when a push is made to any branch in the repository or when someone forks the repository:

on: [push, fork]

If you specify multiple events, only one of those events needs to occur to trigger your workflow. If multiple triggering events for your workflow occur at the same time, multiple workflow runs will be triggered.

Using activity types

Some events have activity types that give you more control over when your workflow should run. Use on.<event_name>.types to define the type of event activity that will trigger a workflow run.

For example, the issue_comment event has the created, edited, and deleted activity types. If your workflow triggers on the label event, it will run whenever a label is created, edited, or deleted. If you specify the created activity type for the label event, your workflow will run when a label is created but not when a label is edited or deleted.

on:
  label:
    types:
      - created

If you specify multiple activity types, only one of those event activity types needs to occur to trigger your workflow. If multiple triggering event activity types for your workflow occur at the same time, multiple workflow runs will be triggered. For example, the following workflow triggers when an issue is opened or labeled. If an issue with two labels is opened, three workflow runs will start: one for the issue opened event and two for the two issue labeled events.

on:
  issues:
    types:
      - opened
      - labeled

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

Using filters

Some events have filters that give you more control over when your workflow should run.

For example, the push event has a branches filter that causes your workflow to run only when a push to a branch that matches the branches filter occurs, instead of when any push occurs.

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

Using activity types and filters with multiple events

If you specify activity types or filters for an event and your workflow triggers on multiple events, you must configure each event separately. 設定を持たないイベントも含め、すべてのイベントにはコロン (:)を追加しなければなりません。

For example, a workflow with the following on value will run when:

  • A label is created
  • A push is made to the main branch in the repository
  • A push is made to a GitHub Pages-enabled branch
on:
  label:
    types:
      - created
  push:
    branches:
      - main
  page_build:

on.<event_name>.types

Use on.<event_name>.types to define the type of activity that will trigger a workflow run. ほとんどの GitHub イベントは、2 つ以上のアクティビティタイプからトリガーされます。 For example, the label is triggered when a label is created, edited, or deleted. typesキーワードを使用すると、ワークフローを実行させるアクティブの範囲を狭くすることができます。 webhook イベントをトリガーするアクティビティタイプが1つだけの場合、typesキーワードは不要です。

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

on:
  label:
    types: [created, edited]

on.<pull_request|pull_request_target>.<branches|branches-ignore>

When using the pull_request and pull_request_target events, you can configure a workflow to run only for pull requests that target specific branches.

Use the branches filter when you want to include branch name patterns or when you want to both include and exclude branch names patterns. Use the branches-ignore filter when you only want to exclude branch name patterns. You cannot use both the branches and branches-ignore filters for the same event in a workflow.

If you define both branches/branches-ignore and paths, the workflow will only run when both filters are satisfied.

The branches and branches-ignore keywords accept glob patterns that use characters like *, **, +, ?, ! and others to match more than one branch name. If a name contains any of these characters and you want a literal match, you need to escape each of these special characters with \. For more information about glob patterns, see the "Filter pattern cheat sheet."

Example: Including branches

The patterns defined in branches are evaluated against the Git ref's name. For example, the following workflow would run whenever there is a pull_request event for a pull request targeting:

  • A branch named main (refs/heads/main)
  • A branch named mona/octocat (refs/heads/mona/octocat)
  • A branch whose name starts with releases/, like releases/10 (refs/heads/releases/10)
on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches:    
      - main
      - 'mona/octocat'
      - 'releases/**'

Example: Excluding branches

When a pattern matches the branches-ignore pattern, the workflow will not run. The patterns defined in branches are evaluated against the Git ref's name. For example, the following workflow would run whenever there is a pull_request event unless the pull request is targeting:

  • A branch named mona/octocat (refs/heads/mona/octocat)
  • A branch whose name matches releases/**-alpha, like releases/beta/3-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

You cannot use branches and branches-ignore to filter the same event in a single workflow. If you want to both include and exclude branch patterns for a single event, use the branches filter along with the ! character to indicate which branches should be excluded.

If you define a branch with the ! character, you must also define at least one branch without the ! character. If you only want to exclude branches, use branches-ignore instead.

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

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

The following workflow will run on pull_request events for pull requests that target releases/10 or releases/beta/mona, but not for pull requests that target releases/10-alpha or releases/beta/3-alpha because the negative pattern !releases/**-alpha follows the positive pattern.

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

on.push.<branches|tags|branches-ignore|tags-ignore>

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の名前と照らし合わせて評価されます。 For example, the following workflow would run whenever there is a push event, unless the push event is to:

  • A branch named mona/octocat (refs/heads/mona/octocat)
  • A branch whose name matches releases/**-alpha, like beta/3-alpha (refs/releases/beta/3-alpha)
  • v2という名前のタグ(refs/tags/v2)
  • A tag whose name starts with v1., like v1.9 (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

You can't use branches and branches-ignore to filter the same event in a single workflow. Similarly, you can't use tags and tags-ignore to filter the same event in a single workflow. If you want to both include and exclude branch or tag patterns for a single event, use the branches or tags filter along with the ! character to indicate which branches or tags should be excluded.

If you define a branch with the ! character, you must also define at least one branch without the ! character. If you only want to exclude branches, use branches-ignore instead. Similarly, if you define a tag with the ! character, you must also define at least one tag without the ! character. If you only want to exclude tags, use tags-ignore instead.

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

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

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

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

on.<push|pull_request|pull_request_target>.<paths|paths-ignore>

When using the push and pull_request events, you can configure a workflow to run based on what file paths are changed. Path filters are not evaluated for pushes of tags.

Use the paths filter when you want to include file path patterns or when you want to both include and exclude file path patterns. Use the paths-ignore filter when you only want to exclude file path patterns. You cannot use both the paths and paths-ignore filters for the same event in a workflow.

If you define both branches/branches-ignore and paths, the workflow will only run when both filters are satisfied.

The paths and paths-ignore keywords accept glob patterns that use the * and ** wildcard characters to match more than one path name. 詳しい情報については、「フィルタパターンのチートシート」を参照してください。

Example: Including paths

pathsフィルタのパターンにマッチするパスが1つでもあれば、ワークフローは実行されます。 For example, the following workflow would run anytime you push a JavaScript file (.js).

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

Note: If a workflow is skipped due to path filtering, branch filtering or a commit message, then checks associated with that workflow will remain in a "Pending" state. A pull request that requires those checks to be successful will be blocked from merging. For more information, see "Handling skipped but required checks."

Example: Excluding paths

すべてのパス名が paths-ignore のパターンと一致する場合、ワークフローは実行されません。 If any path names do not match patterns in paths-ignore, even if some path names match the patterns, the workflow will run.

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

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

Example: Including and excluding paths

You can not use paths and paths-ignore to filter the same event in a single workflow. If you want to both include and exclude path patterns for a single event, use the paths filter along with the ! character to indicate which paths should be excluded.

If you define a path with the ! character, you must also define at least one path without the ! character. If you only want to exclude paths, use paths-ignore instead.

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

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

この例は、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の比較

Note: If you push more than 1,000 commits, or if GitHub does not generate the diff due to a timeout, the workflow will always run.

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

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

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

Diffs are limited to 300 files. If there are files changed that aren't matched in the first 300 files returned by the filter, the workflow will not run. You may need to create more specific filters so that the workflow will run automatically.

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

on.schedule

You can use on.schedule to define a time schedule for your workflows. POSIX クーロン構文を使用して、特定の UTC 時間にワークフローを実行できるようスケジュール設定できます。 スケジュールしたワークフローは、デフォルトまたはベースブランチの直近のコミットで実行されます。 スケジュールされたワークフローを実行できる最短の間隔は、5 分ごとに 1 回です。

この例では、ワークフローは毎日UTCの5:30と17:30にトリガーされます。

on:
  schedule:
    # *はYAMLにおける特殊文字なので、この文字列はクオートしなければならない
    - cron:  '30 5,17 * * *'

A single workflow can be triggered by multiple schedule events. You can access the schedule event that triggered the workflow through the github.event.schedule context. This example triggers the workflow to run at 5:30 UTC every Monday-Thursday, but skips the Not on Monday or Wednesday step on Monday and Wednesday.

on:
  schedule:
    - cron: '30 5 * * 1,3'
    - cron: '30 5 * * 2,4'

jobs:
  test_schedule:
    runs-on: ubuntu-latest
    steps:
      - name: Not on Monday or Wednesday
        if: github.event.schedule != '30 5 * * 1,3'
        run: echo "This step will be skipped on Monday and Wednesday"
      - name: Every time
        run: echo "This step will always run"

cron構文に関する詳しい情報については、「ワークフローをトリガーするイベント」を参照してください。

on.workflow_run.<branches|branches-ignore>

When using the workflow_run event, you can specify what branches the triggering workflow must run on in order to trigger your workflow.

The branches and branches-ignore filters accept glob patterns that use characters like *, **, +, ?, ! and others to match more than one branch name. If a name contains any of these characters and you want a literal match, you need to escape each of these special characters with \. For more information about glob patterns, see the "Filter pattern cheat sheet."

For example, a workflow with the following trigger will only run when the workflow named Build runs on a branch whose name starts with releases/:

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

A workflow with the following trigger will only run when the workflow named Build runs on a branch that is not named canary:

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

You cannot use both the branches and branches-ignore filters for the same event in a workflow. If you want to both include and exclude branch patterns for a single event, use the branches filter along with the ! character to indicate which branches should be excluded.

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

  • A matching negative pattern (prefixed with !) after a positive match will exclude the branch.
  • A matching positive pattern after a negative match will include the branch again.

For example, a workflow with the following trigger will run when the workflow named Build runs on a branch that is named releases/10 or releases/beta/mona but will not releases/10-alpha, releases/beta/3-alpha, or main.

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

on.workflow_dispatch.inputs

When using the workflow_dispatch event, you can optionally specify inputs that are passed to the workflow.

The triggered workflow receives the inputs in the github.event.inputs context. For more information, see "Contexts."

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning' 
      print_tags:
        description: 'True to print to STDOUT'
        required: true 
      tags:
        description: 'Test scenario tags'
        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 }} 

permissions

permissionsを使ってGITHUB_TOKEN に付与されているデフォルトの権限を変更し、必要に応じてアクセスを追加または削除して、必要最小限のアクセスのみを許可することができます。 詳しい情報については、「ワークフローでの認証」を参照してください。

permissions は、最上位キーとしてワークフロー内のすべてのジョブに適用するために、または特定のジョブ内で使用できます。 特定のジョブ内に permissions キーを追加すると、GITHUB_TOKEN を使用するそのジョブ内のすべてのアクションと実行コマンドが、指定したアクセス権を取得します。 詳しい情報については、jobs.<job_id>.permissions を参照してください。

Available scopes and access values:

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

If you specify the access for any of these scopes, all of those that are not specified are set to none.

You can use the following syntax to define read or write access for all of the available scopes:

permissions: read-all|write-all

You can use the following syntax to disable permissions for all of the available scopes:

permissions: {}

permissionsキーを使って、フォークされたリポジトリの読み取り権限の付与や削除ができますが、通常は書き込みアクセス権を付与することはできません。 この動作の例外としては、管理ユーザがGitHub Actionsの設定でSend write tokens to workflows from pull requests(Pull Requestからワークフローに書き込みトークンを送る)を選択している場合があります。 詳しい情報については、「リポジトリの GitHub Actions 設定の管理」を参照してください。

例: GITHUB_TOKENへの権限の割り当て

この例は、ワークフロー内のすべてのジョブに適用される GITHUB_TOKEN に設定されている権限を示しています。 すべての権限に読み取りアクセスが付与されます。

name: "My workflow"

on: [ push ]

permissions: read-all

jobs:
  ...

env

ワークフロー中のすべてのジョブのステップから利用できる環境変数のmapです。 1つのジョブのステップ、あるいは1つのステップからだけ利用できる環境変数を設定することもできます。 詳しい情報については「jobs.<job_id>.env」及び「jobs.<job_id>.steps[*].envを参照してください。

Variables in the env map cannot be defined in terms of other variables in the map.

同じ名前で複数の環境変数が定義されている場合、GitHubは最も具体的な環境変数を使用します。 たとえば、ステップ中で定義された環境変数は、ジョブやワークフローの同じ名前の変数をステップの実行の間オーバーライドします。 ジョブで定義された変数は、そのジョブの実行の間はワークフローで定義された同じ名前の変数をオーバーライドします。

サンプル

env:
  SERVER: production

defaults

defaultsを使って、ワークフロー中のすべてのジョブに適用されるデフォルト設定のmapを作成してください。 1つのジョブだけで利用できるデフォルト設定を設定することもできます。 詳しい情報についてはjobs.<job_id>.defaultsを参照してください。

同じ名前で複数のデフォルトの設定が定義されている場合、GitHubは最も具体的なデフォルト設定を使用します。 たとえば、ジョブで定義されたデフォルト設定は、同じ名前を持つワークフローで定義されたデフォルト設定をオーバーライドします。

defaults.run

defaults.runを使って、ワークフロー中のすべてのrunステップにデフォルトのshell及びworking-directoryオプションを指定できます。 1つのジョブだけで利用できるrunのデフォルト設定を設定することもできます。 詳しい情報についてはjobs.<job_id>.defaults.runを参照してください。 このキーワード中では、コンテキストや式を使うことはできません。

同じ名前で複数のデフォルトの設定が定義されている場合、GitHubは最も具体的なデフォルト設定を使用します。 たとえば、ジョブで定義されたデフォルト設定は、同じ名前を持つワークフローで定義されたデフォルト設定をオーバーライドします。

例: デフォルトのシェルとワーキングディレクトリの設定

defaults:
  run:
    shell: bash
    working-directory: scripts

concurrency

concurrencyを使って、同じ並行処理グループを使うジョブもしくはワークフローが一度に1つだけ実行されることを保証できます。 並行処理グループには、任意の文字列または式を使用できます。 この式はgithub contextだけを使用します。 式に関する詳しい情報については「」を参照してください。

ジョブレベルで concurrency を指定することもできます。 詳しい情報については、jobs.<job_id>.concurrency を参照してください。

並行ジョブもしくはワークフローがキューに入っている場合、リポジトリ内の同じ並行グループを使う他のジョブもしくはワークフローが進行中だと、キューイングされたジョブもしくはワークフローは保留中になります。 この並行グループ内の以前の保留中のジョブもしくはワークフローは、キャンセルされます。 同じ並行グループ内にある実行中のジョブもしくはワークフローもキャンセルするには、cancel-in-progress: trueを指定してください。

並行性とデフォルトの動作の使用例

concurrency: staging_environment
concurrency: ci-${{ github.ref }}

並行性を使って進行中のジョブもしくは実行をキャンセルする例

concurrency: 
  group: ${{ github.ref }}
  cancel-in-progress: true

Example: Using a fallback value

If you build the group name with a property that is only defined for specific events, you can use a fallback value. For example, github.head_ref is only defined on pull_request events. If your workflow responds to other events in addition to pull_request events, you will need to provide a fallback to avoid a syntax error. The following concurrency group cancels in-progress jobs or runs on pull_request events only; if github.head_ref is undefined, the concurrency group will fallback to the run ID, which is guaranteed to be both unique and defined for the run.

concurrency: 
  group: ${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

Example: Only cancel in-progress jobs or runs for the current workflow

If you have multiple workflows in the same repository, concurrency group names must be unique across workflows to avoid canceling in-progress jobs or runs from other workflows. Otherwise, any previously in-progress or pending job will be canceled, regardless of the workflow.

To only cancel in-progress runs of the same workflow, you can use the github.workflow property to build the concurrency group:

concurrency: 
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs

ワークフローの実行は、1つ以上のジョブで構成されており、それらのジョブはデフォルトでは並列に実行されます。 ジョブを逐次的に実行するには、jobs.<job_id>.needsキーワードを使用して他のジョブに対する依存関係を定義します。

それぞれのジョブは、runs-onで指定されたランナー環境で実行されます。

ワークフローの利用限度内であれば、実行するジョブ数に限度はありません。 詳しい情報についてはGitHubホストランナーの「使用制限と支払い」及びセルフホストランナーの使用制限に関する「セルフホストランナーについて」を参照してください。

ワークフローの実行中で動作しているジョブの一意の識別子を知る必要がある場合は、GitHub Enterprise Server APIが利用できます。 詳しい情報については、「ワークフロージョブ」を参照してください。

jobs.<job_id>

jobs.<job_id>を使い、ジョブに一意の識別子を与えてください。 job_idキーは文字列型で、その値はジョブの設定データのマップとなるものです。 <job_id>は、jobsオブジェクトごとに一意の文字列に置き換える必要があります。 <job_id>は、英字または_で始める必要があり、英数字と-_しか使用できません。

例: ジョブの作成

この例では2つのジョブが作成されており、そのjob_idの値はmy_first_jobmy_second_jobです。

jobs:
  my_first_job:
    name: My first job
  my_second_job:
    name: My second job

jobs.<job_id>.name

jobs.<job_id>.nameを使ってジョブの名前を設定してください。この名前はGitHubのUIに表示されます。

jobs.<job_id>.permissions

特定のジョブについて、jobs.<job_id>.permissionsを使ってGITHUB_TOKENに付与されたデフォルトの権限を変更し、必要に応じてアクセスを付与したり削除したりして、必要最小限のアクセスだけを許可できます。 詳しい情報については、「ワークフローでの認証」を参照してください。

ジョブ定義内で権限を指定することで、必要に応じて、ジョブごとに GITHUB_TOKEN に異なる権限のセットを設定できます。 または、ワークフロー内のすべてのジョブの権限を指定することもできます。 ワークフローレベルでの権限の定義については、 permissions を参照してください。

Available scopes and access values:

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

If you specify the access for any of these scopes, all of those that are not specified are set to none.

You can use the following syntax to define read or write access for all of the available scopes:

permissions: read-all|write-all

You can use the following syntax to disable permissions for all of the available scopes:

permissions: {}

permissionsキーを使って、フォークされたリポジトリの読み取り権限の付与や削除ができますが、通常は書き込みアクセス権を付与することはできません。 この動作の例外としては、管理ユーザがGitHub Actionsの設定でSend write tokens to workflows from pull requests(Pull Requestからワークフローに書き込みトークンを送る)を選択している場合があります。 詳しい情報については、「リポジトリの GitHub Actions 設定の管理」を参照してください。

例: 特定のジョブに対する権限の設定

この例では、stale という名前のジョブにのみ適用される GITHUB_TOKEN に設定されている権限を示しています。 issues および pull-requests のスコープに対して書き込みアクセスが許可されます。 他のすべてのスコープにはアクセスできません。

jobs:
  stale:
    runs-on: ubuntu-latest

    permissions:
      issues: write
      pull-requests: write

    steps:
      - uses: actions/stale@v4

jobs.<job_id>.needs

jobs.<job_id>.needsを使って、このジョブを実行する前に成功して完了していなければならないジョブを特定してください。 これは文字列型または文字列の配列です。 1つのジョブが失敗した場合、失敗したジョブを続行するような条件式を使用していない限り、そのジョブを必要としている他のジョブはすべてスキップされます。 1つの実行にお互いを必要とする一連のジョブが含まれていた場合、失敗時点以降の依存関係チェーン中のすべてのジョブに失敗が適用されます。

例: 依存対象のジョブの成功を必要とする

jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]

この例では、job1が正常に完了してからjob2が始まり、job3job1job2が完了するまで待機します。

つまり、この例のジョブは逐次実行されるということです。

  1. job1
  2. job2
  3. job3

例: 依存対象のジョブの成功を必要としない

jobs:
  job1:
  job2:
    needs: job1
  job3:
    if: ${{ always() }}
    needs: [job1, job2]

この例では、job3は条件式のalways() を使っているので、job1job2が成功したかどうかにかかわらず、それらのジョブが完了したら常に実行されます。 詳しい情報については「」を参照してください。

jobs.<job_id>.if

jobs.<job_id>.if条件文を使って、条件が満たされていなければジョブを実行しないようにすることができます。 条件文を作成するには、サポートされている任意のコンテキストや式が使えます。

if 条件の中で式を使用する際には、式構文 (${{ }})を省略できます。これは、GitHub が if 条件を式として自動的に評価するためです。 詳しい情報については「」を参照してください。

例: 特定のリポジトリのジョブだけを実行する

この例はifを使っていつproduction-deployジョブが実行できるかを制御しています。 このジョブは、リポジトリの名前がocto-repo-prodで、octo-orgというOrganization内にあるときだけ実行されます。 そうでない場合、このジョブはskippedとマークされます。

YAML
name: example-workflow
on: [push]
jobs:
  production-deploy:
    if: github.repository == 'octo-org/octo-repo-prod'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '14'
      - run: npm install -g bats

jobs.<job_id>.runs-on

jobs.<job_id>.runs-onを使って、ジョブを実行するマシンのタイプを定義してください。 runs-onは単一の文字列として、あるいは文字列の配列として渡せます。 文字列の配列を指定した場合、ワークフローは指定されたすべてのruns-onの値にラベルがマッチしたセルフホストランナーが利用可能であれば、そのランナーで実行されます。 複数のマシン上でワークフローを実行したいのであれば、jobs.<job_id>.strategyを使ってください。

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

GitHubホストランナーの選択

GitHubホストランナーを使う場合、それぞれのジョブはruns-onで指定された仮想環境の新しいインスタンスで実行されます。

利用可能なGitHubホストランナーの種類は以下のとおりです。

仮想環境 YAMLのワークフローラベル 注釈
Windows Server 2022 windows-latestもしくはwindows-2022 The windows-latest label currently uses the Windows Server 2022 runner image.
Windows Server 2019 windows-2019
Ubuntu 22.04 ubuntu-22.04 Ubuntu 22.04 is currently in public beta.
Ubuntu 20.04 ubuntu-latestまたはubuntu-20.04
Ubuntu 18.04 ubuntu-18.04
macOS Monterey 12 macos-12
macOS Big Sur 11 macos-latestもしくはmacos-11 The macos-latest label currently uses the macOS 11 runner image.
macOS Catalina 10.15 macos-10.15

Note: The -latest virtual environments are the latest stable images that GitHub provides, and might not be the most recent version of the operating system available from the operating system vendor.

Note: Beta and Deprecated Images are provided "as-is", "with all faults" and "as available" and are excluded from the service level agreement and warranty. Beta Images may not be covered by customer support.

例: オペレーティングシステムの指定

runs-on: ubuntu-latest

詳しい情報については「GitHubホストランナーの仮想環境」を参照してください。

セルフホストランナーの選択

ジョブでセルフホストランナーを指定するには、ワークフローファイル中でセルフホストランナーのラベルでruns-onを設定してください。

All self-hosted runners have the self-hosted label. Using only this label will select any self-hosted runner. To select runners that meet certain criteria, such as operating system or architecture, we recommend providing an array of labels that begins with self-hosted (this must be listed first) and then includes additional labels as needed. When you specify an array of labels, jobs will be queued on runners that have all the labels that you specify.

Although the self-hosted label is not required, we strongly recommend specifying it when using self-hosted runners to ensure that your job does not unintentionally specify any current or future GitHub-hosted runners.

例: ランナーの選択にラベルを使用

runs-on: [self-hosted, linux]

詳しい情報については「セルフホストランナーについて」及び「ワークフロー内でのセルフホストランナーの利用」を参照してください。

jobs.<job_id>.environment

jobs.<job_id>.environmentを使って、ジョブが参照する環境を定義してください。 環境を参照するジョブがランナーに送られる前に、その環境のすべての保護ルールはパスしなければなりません。 詳しい情報については「デプロイメントの環境の利用」を参照してください。

環境は、環境のnameだけで、あるいはname and urlを持つenvironmentオブジェクトとして渡すことができます。 デプロイメントAPIでは、このURLはenvironment_urlにマップされます。 デプロイメントAPIに関する詳しい情報については「デプロイメント」を参照してください。

例: 単一の環境名の使用

environment: staging_environment

例: 環境名とURLの使用

environment:
  name: production_environment
  url: https://github.com

URLには式を指定でき、secrets context以外の任意のコンテキストを利用できます。 式に関する詳しい情報については「」を参照してください。

例: URLとしての出力の使用

environment:
  name: production_environment
  url: ${{ steps.step_id.outputs.url_output }}

jobs.<job_id>.concurrency

注釈: ジョブレベルで並行処理が指定されている場合、ジョブの順序は保証されないか、互いに 5 分以内にそのキューを実行します。

jobs.<job_id>.concurrencyを使って、同じ並行処理グループを使う1つのジョブもしくはワークフローだけが実行されることを保証できます。 並行処理グループには、任意の文字列または式を使用できます。 式は、secrets コンテキストを除く任意のコンテキストを使用できます。 式に関する詳しい情報については「」を参照してください。

ワークフローレベルで concurrency を指定することもできます。 詳しい情報については、concurrency を参照してください。

並行ジョブもしくはワークフローがキューに入っている場合、リポジトリ内の同じ並行グループを使う他のジョブもしくはワークフローが進行中だと、キューイングされたジョブもしくはワークフローは保留中になります。 この並行グループ内の以前の保留中のジョブもしくはワークフローは、キャンセルされます。 同じ並行グループ内にある実行中のジョブもしくはワークフローもキャンセルするには、cancel-in-progress: trueを指定してください。

並行性とデフォルトの動作の使用例

concurrency: staging_environment
concurrency: ci-${{ github.ref }}

並行性を使って進行中のジョブもしくは実行をキャンセルする例

concurrency: 
  group: ${{ github.ref }}
  cancel-in-progress: true

Example: Using a fallback value

If you build the group name with a property that is only defined for specific events, you can use a fallback value. For example, github.head_ref is only defined on pull_request events. If your workflow responds to other events in addition to pull_request events, you will need to provide a fallback to avoid a syntax error. The following concurrency group cancels in-progress jobs or runs on pull_request events only; if github.head_ref is undefined, the concurrency group will fallback to the run ID, which is guaranteed to be both unique and defined for the run.

concurrency: 
  group: ${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

Example: Only cancel in-progress jobs or runs for the current workflow

If you have multiple workflows in the same repository, concurrency group names must be unique across workflows to avoid canceling in-progress jobs or runs from other workflows. Otherwise, any previously in-progress or pending job will be canceled, regardless of the workflow.

To only cancel in-progress runs of the same workflow, you can use the github.workflow property to build the concurrency group:

concurrency: 
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs.<job_id>.outputs

jobs.<job_id>.outputsを使って、ジョブの出力のmapを作成できます。 ジョブの出力は、そのジョブに依存しているすべての下流のジョブから利用できます。 ジョブの依存関係の定義に関する詳しい情報についてはjobs.<job_id>.needsを参照してください。

Outputs are Unicode strings, and can be a maximum of 1 MB. The total of all outputs in a workflow run can be a maximum of 50 MB.

式を含むジョブの出力は、それぞれのジョブの終わりにランナー上で評価されます。 シークレットを含む出力はランナー上で編集され、GitHub Actionsには送られません。

依存するジョブでジョブの出力を使いたい場合には、needsコンテキストが利用できます。 詳細については、「コンテキスト」を参照してください。

例: ジョブの出力の定義

jobs:
  job1:
    runs-on: ubuntu-latest
    # ステップの出力をジョブの出力にマップする
    outputs:
      output1: ${{ steps.step1.outputs.test }}
      output2: ${{ steps.step2.outputs.test }}
    steps:
      - id: step1
        run: echo "::set-output name=test::hello"
      - id: step2
        run: echo "::set-output name=test::world"
  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - run: echo ${{needs.job1.outputs.output1}} ${{needs.job1.outputs.output2}}

jobs.<job_id>.env

ジョブ中のすべてのステップから利用できる環境変数のmapです。 ワークフロー全体あるいは個別のステップのための環境変数を設定することもできます。 詳しい情報についてはenv及びjobs.<job_id>.steps[*].envを参照してください。

同じ名前で複数の環境変数が定義されている場合、GitHubは最も具体的な環境変数を使用します。 たとえば、ステップ中で定義された環境変数は、ジョブやワークフローの同じ名前の変数をステップの実行の間オーバーライドします。 ジョブで定義された変数は、そのジョブの実行の間はワークフローで定義された同じ名前の変数をオーバーライドします。

サンプル

jobs:
  job1:
    env:
      FIRST_NAME: Mona

jobs.<job_id>.defaults

jobs.<job_id>.defaultsを使って、ジョブ中のすべてのステップに適用されるデフォルト設定のmapを作成してください。 ワークフロー全体に対してデフォルト設定を設定することもできます。 詳しい情報についてはdefaultsを参照してください。

同じ名前で複数のデフォルトの設定が定義されている場合、GitHubは最も具体的なデフォルト設定を使用します。 たとえば、ジョブで定義されたデフォルト設定は、同じ名前を持つワークフローで定義されたデフォルト設定をオーバーライドします。

jobs.<job_id>.defaults.run

jobs.<job_id>.defaults.runを使ってジョブ中のすべてのrunステップにデフォルトのshellworking-directoryを指定してください。 このセクションではコンテキストと式は許されていません。

ジョブ中のすべてのrunステップにデフォルトのshell及びworking-directoryを提供できます。 ワークフロー全体についてrunのためのデフォルト設定を設定することもできます。 詳しい情報についてはjobs.defaults.runを参照してください。 このキーワード中では、コンテキストや式を使うことはできません。

同じ名前で複数のデフォルトの設定が定義されている場合、GitHubは最も具体的なデフォルト設定を使用します。 たとえば、ジョブで定義されたデフォルト設定は、同じ名前を持つワークフローで定義されたデフォルト設定をオーバーライドします。

例: ジョブのrunステップにデフォルトのオプションを設定

jobs:
  job1:
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
        working-directory: scripts

jobs.<job_id>.steps

1つのジョブには、steps (ステップ) と呼ばれる一連のタスクがあります。 ステップでは、コマンドを実行する、設定タスクを実行する、あるいはリポジトリやパブリックリポジトリ、Dockerレジストリで公開されたアクションを実行することができます。 すべてのステップでアクションを実行するとは限りませんが、すべてのアクションはステップとして実行されます。 各ステップは、ランナー環境のそれ自体のプロセスで実行され、ワークスペースとファイルシステムにアクセスします。 ステップはそれ自体のプロセスで実行されるため、環境変数を変更しても、ステップ間では反映されません。 GitHubには、ジョブを設定して完了するステップが組み込まれています。

ワークフローの利用限度内であれば、実行するステップ数に限度はありません。 詳しい情報についてはGitHubホストランナーの「使用制限と支払い」及びセルフホストランナーの使用制限に関する「セルフホストランナーについて」を参照してください。

サンプル

name: Greeting from Mona

on: push

jobs:
  my-job:
    name: My Job
    runs-on: ubuntu-latest
    steps:
      - name: Print a greeting
        env:
          MY_VAR: Hi there! My name is
          FIRST_NAME: Mona
          MIDDLE_NAME: The
          LAST_NAME: Octocat
        run: |
          echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME.

jobs.<job_id>.steps[*].id

ステップの一意の識別子。 idを使って、コンテキストのステップを参照することができます。 詳細については、「コンテキスト」を参照してください。

jobs.<job_id>.steps[*].if

条件文のifを使って、条件が満たされなければステップを実行しないようにできます。 条件文を作成するには、サポートされている任意のコンテキストや式が使えます。

if 条件の中で式を使用する際には、式構文 (${{ }})を省略できます。これは、GitHub が if 条件を式として自動的に評価するためです。 詳しい情報については「」を参照してください。

Example: Using contexts

このステップは、イベントの種類がpull_requestでイベントアクションがunassignedの場合にのみ実行されます。

steps:
 - name: My first step
   if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}
   run: echo This event is a pull request that had an assignee removed.

Example: Using status check functions

my backup stepは、ジョブの前のステップが失敗した場合にのみ実行されます。 詳しい情報については「」を参照してください。

steps:
  - name: My first step
    uses: octo-org/action-name@main
  - name: My backup step
    if: ${{ failure() }}
    uses: actions/heroku@1.0.0

Example: Using secrets

Secrets cannot be directly referenced in if: conditionals. Instead, consider setting secrets as job-level environment variables, then referencing the environment variables to conditionally run steps in the job.

If a secret has not been set, the return value of an expression referencing the secret (such as ${{ secrets.SuperSecret }} in the example) will be an empty string.

name: Run a step if a secret has been set
on: push
jobs:
  my-jobname:
    runs-on: ubuntu-latest
    env:
      super_secret: ${{ secrets.SuperSecret }}
    steps:
      - if: ${{ env.super_secret != '' }}
        run: echo 'This step will only run if the secret has a value set.'
      - if: ${{ env.super_secret == '' }}
        run: echo 'This step will only run if the secret does not have a value set.'

For more information, see "Context availability" and "Encrypted secrets."

jobs.<job_id>.steps[*].name

GitHubで表示されるステップの名前。

jobs.<job_id>.steps[*].uses

ジョブでステップの一部として実行されるアクションを選択します。 アクションとは、再利用可能なコードの単位です。 ワークフロー、パブリックリポジトリ、または公開されているDockerコンテナイメージと同じリポジトリで定義されているアクションを使用できます。

Git ref、SHA、またはDockerタグ番号を指定して、使用しているアクションのバージョンを含めることを強く推奨します。 バージョンを指定しないと、アクションのオーナーがアップデートを公開したときに、ワークフローが中断したり、予期せぬ動作をしたりすることがあります。

  • リリースされたアクションバージョンのコミットSHAを使用するのが、安定性とセキュリティのうえで最も安全です。
  • 特定のメジャーアクションバージョンを使用すると、互換性を維持したまま重要な修正とセキュリティパッチを受け取ることができます。 ワークフローが引き続き動作することも保証できます。
  • アクションのデフォルトブランチを使用すると便利なこともありますが、別のユーザが破壊的変更を加えた新しいメジャーバージョンをリリースすると、ワークフローが動作しなくなる場合があります。

入力が必要なアクションもあり、入力をwithキーワードを使って設定する必要があります。 必要な入力を判断するには、アクションのREADMEファイルをお読みください。

アクションは、JavaScriptのファイルもしくはDockerコンテナです。 使用するアクションがDockerコンテナの場合は、Linux環境で実行する必要があります。 詳細についてはruns-onを参照してください。

Example: Using versioned actions

steps:
  # Reference a specific commit
  - uses: actions/checkout@a81bbbf8298c0fa03ea29cdc473d45769f953675
  # Reference the major version of a release
  - uses: actions/checkout@v2
  # Reference a specific version
  - uses: actions/checkout@v2.2.0
  # Reference a branch
  - uses: actions/checkout@main

Example: Using a public action

{owner}/{repo}@{ref}

You can specify a branch, ref, or SHA in a public GitHub repository.

jobs:
  my_first_job:
    steps:
      - name: My first step
        # Uses the default branch of a public repository
        uses: actions/heroku@main
      - name: My second step
        # Uses a specific version tag of a public repository
        uses: actions/aws@v2.0.1

Example: Using a public action in a subdirectory

{owner}/{repo}/{path}@{ref}

パブリックGitHubリポジトリで特定のブランチ、ref、SHAにあるサブディレクトリ。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/aws/ec2@main

Example: Using an action in the same repository as the workflow

./path/to/dir

ワークフローのリポジトリにあるアクションを含むディレクトリのパス。 アクションを使用する前にリポジトリをチェックアウトする必要があります。

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v2
      - name: Use local my-action
        uses: ./.github/actions/my-action

Example: Using a Docker Hub action

docker://{image}:{tag}

Docker Hubで公開されているDockerイメージ。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://alpine:3.8

Example: Using a Docker public registry action

docker://{host}/{image}:{tag}

パブリックレジストリのDockerイメージ。 この例では、gcr.io にある Google Container Registry を使用しています。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://gcr.io/cloud-builders/gradle

Example: Using an action inside a different private repository than the workflow

ワークフローはプライベートリポジトリをチェックアウトし、アクションをローカルで参照する必要があります。 個人アクセストークンを生成し、暗号化されたシークレットとしてトークンを追加します。 詳しい情報については、「個人アクセストークンを作成する」および「暗号化されたシークレット」を参照してください。

例にある PERSONAL_ACCESS_TOKEN をシークレットの名前に置き換えます。

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v2
        with:
          repository: octocat/my-private-repo
          ref: v1.0
          token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          path: ./.github/actions/my-private-repo
      - name: Run my action
        uses: ./.github/actions/my-private-repo/my-action

jobs.<job_id>.steps[*].run

オペレーティングシステムのシェルを使用してコマンドラインプログラムを実行します。 nameを指定しない場合、ステップ名はデフォルトでrunコマンドで指定された文字列になります。

コマンドは、デフォルトでは非ログインシェルを使用して実行されます。 別のシェルを選択して、コマンドを実行するシェルをカスタマイズできます。 For more information, see jobs.<job_id>.steps[*].shell.

runキーワードは、それぞれがランナー環境での新しいプロセスとシェルです。 複数行のコマンドを指定すると、各行が同じシェルで実行されます。 例:

  • 1行のコマンド:

    - name: Install Dependencies
      run: npm install
    
  • 複数行のコマンド:

    - name: Clean install dependencies and build
      run: |
        npm ci
        npm run build
    

working-directoryキーワードを使えば、コマンドが実行されるワーキングディレクトリを指定できます。

- name: Clean temp directory
  run: rm -rf *
  working-directory: ./temp

jobs.<job_id>.steps[*].shell

shellキーワードを使用して、ランナーのオペレーティングシステムのデフォルトシェルを上書きできます。 組み込みのshellキーワードを使用するか、カスタムセットのシェルオプションを定義することができます。 The shell command that is run internally executes a temporary file that contains the commands specified in the run keyword.

サポートされているプラットフォームshell パラメータ説明内部で実行されるコマンド
すべてbash非Windowsプラットフォームのデフォルトシェルで、shへのフォールバックがあります。 Windowsでbashシェルを指定すると、Windows用Gitに含まれるbashシェルが使用されます。bash --noprofile --norc -eo pipefail {0}
すべてpwshPowerShell Coreです。 GitHubはスクリプト名に拡張子.ps1を追加します。pwsh -command ". '{0}'"
すべてpythonPythonのコマンドを実行します。python {0}
Linux / macOSsh非Windowsプラットフォームにおいてシェルが提供されておらず、パス上でbashが見つからなかった場合のフォールバック動作です。sh -e {0}
WindowscmdGitHubはスクリプト名に拡張子.cmdを追加し、{0}を置き換えます。%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}"".
WindowspwshこれはWindowsで使われるデフォルトのシェルです。 PowerShell Coreです。 GitHubはスクリプト名に拡張子.ps1を追加します。 セルフホストのWindowsランナーにPowerShell Coreがインストールされていない場合、その代わりにPowerShell Desktopが使われます。pwsh -command ". '{0}'".
WindowspowershellPowerShell Desktop. GitHubはスクリプト名に拡張子.ps1を追加します。powershell -command ". '{0}'".

Example: Running a script using bash

steps:
  - name: Display the path
    run: echo $PATH
    shell: bash

Example: Running a script using Windows cmd

steps:
  - name: Display the path
    run: echo %PATH%
    shell: cmd

Example: Running a script using PowerShell Core

steps:
  - name: Display the path
    run: echo ${env:PATH}
    shell: pwsh

PowerShell Desktopを使用してスクリプトを実行する例

steps:
  - name: Display the path
    run: echo ${env:PATH}
    shell: powershell

Example: Running a python script

steps:
  - name: Display the path
    run: |
      import os
      print(os.environ['PATH'])
    shell: python

カスタムシェル

command […options] {0} [..more_options]を使用すると、テンプレート文字列にshell値を設定できます。 GitHubは、空白区切りで最初の文字列をコマンドとして解釈し、{0}にある一時的なスクリプトのファイル名を挿入します。

例:

steps:
  - name: Display the environment variables and their values
    run: |
      print %ENV
    shell: perl {0}

使われるコマンドは(この例ではperl)は、ランナーにインストールされていなければなりません。

終了コードとエラーアクションの環境設定

組み込みのshellキーワードについては、GitHubがホストする実行環境で以下のデフォルトが提供されます。 シェルスクリプトを実行する際には、以下のガイドラインを使ってください。

  • bash/sh:

    • set -eo pipefailを使用したフェイルファースト動作 : bash及び組み込みのshellのデフォルト。 Windows以外のプラットフォームでオプションを指定しない場合のデフォルトでもあります。
    • フェイルファーストをオプトアウトし、シェルのオプションにテンプレート文字列を指定して完全に制御することもできます。 たとえば、bash {0}とします。
    • shライクのシェルは、スクリプトで実行された最後のコマンドの終了コードで終了します。これが、アクションのデフォルトの動作でもあります。 runnerは、この終了コードに基づいてステップのステータスを失敗/成功としてレポートします。
  • powershell/pwsh

    • 可能な場合のフェイルファースト動作。 pwshおよびpowershellの組み込みシェルの場合は、スクリプトの内容の前に$ErrorActionPreference = 'stop' が付加されます。
    • ここでは、アクションステータスがスクリプトの最後の終了コードを反映するように、PowerShellスクリプトにif ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE }を付加しています。
    • 必要な場合には、組み込みシェルを使用せずに、pwsh -File {0}powershell -Command "& '{0}'"などのカスタムシェルを指定すれば、いつでもオプトアウトすることができます。
  • cmd

    • 各エラーコードをチェックしてそれぞれに対応するスクリプトを書く以外、フェイルファースト動作を完全にオプトインする方法はないようです。 デフォルトでその動作を指定することはできないため、この動作はスクリプトに記述する必要があります。
    • cmd.exeは、実行した最後のプログラムのエラーレベルで終了し、runnerにそのエラーコードを返します。 この動作は、これ以前のshおよびpwshのデフォルト動作と内部的に一貫しており、cmd.exeのデフォルトなので、この動作には影響しません。

jobs.<job_id>.steps[*].with

アクションによって定義される入力パラメータのmap。 各入力パラメータはキー/値ペアです。 入力パラメータは環境変数として設定されます。 変数の前にはINPUT_が付けられ、大文字に変換されます。

サンプル

hello_worldアクションで定義される3つの入力パラメータ (first_namemiddle_namelast_name) を定義します。 hello-worldアクションからは、これらの入力変数はINPUT_FIRST_NAMEINPUT_MIDDLE_NAMEINPUT_LAST_NAMEという環境変数としてアクセスできます。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/hello_world@main
        with:
          first_name: Mona
          middle_name: The
          last_name: Octocat

jobs.<job_id>.steps[*].with.args

Dockerコンテナへの入力を定義する文字列。 GitHubは、コンテナの起動時にargsをコンテナのENTRYPOINTに渡します。 このパラメータは、文字列の配列をサポートしません。

サンプル

steps:
  - name: Explain why this job ran
    uses: octo-org/action-name@main
    with:
      entrypoint: /bin/echo
      args: The ${{ github.event_name }} event triggered this step.

argsは、Dockerfile中のCMD命令の場所で使われます。 Dockerfile中でCMDを使うなら、以下の優先順位順のガイドラインを利用してください。

  1. 必須の引数をアクションのREADME中でドキュメント化し、CMD命令から除外してください。
  2. argsを指定せずにアクションを利用できるよう、デフォルトを使ってください。
  3. アクションが--helpフラグやそれに類するものを備えているなら、アクションを自己ドキュメント化するためのデフォルトとして利用してください。

jobs.<job_id>.steps[*].with.entrypoint

Dockerfile中のDockerのENTRYPOINTをオーバーライドします。あるいは、もしそれが指定されていなかった場合に設定します。 shellやexec形式を持つDockerのENTRYPOINT命令とは異なり、entrypointキーワードは実行する実行可能ファイルを定義する単一の文字列だけを受け付けます。

サンプル

steps:
  - name: Run a custom command
    uses: octo-org/action-name@main
    with:
      entrypoint: /a/different/executable

entrypointキーワードはDockerコンテナアクションで使われることを意図したものですが、入力を定義しないJavaScriptのアクションでも使うことができます。

jobs.<job_id>.steps[*].env

ランナー環境でステップが使う環境変数を設定します。 ワークフロー全体あるいはジョブのための環境変数を設定することもできます。 詳しい情報については「env」及び「jobs.<job_id>.env」を参照してください。

同じ名前で複数の環境変数が定義されている場合、GitHubは最も具体的な環境変数を使用します。 たとえば、ステップ中で定義された環境変数は、ジョブやワークフローの同じ名前の変数をステップの実行の間オーバーライドします。 ジョブで定義された変数は、そのジョブの実行の間はワークフローで定義された同じ名前の変数をオーバーライドします。

パブリックなアクションは、READMEファイル中で期待する環境変数を指定できます。 環境変数に秘密情報を設定しようとしている場合、秘密情報はsecretsコンテキストを使って設定しなければなりません。 For more information, see "Using environment variables" and "Contexts."

サンプル

steps:
  - name: My first action
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      FIRST_NAME: Mona
      LAST_NAME: Octocat

jobs.<job_id>.steps[*].continue-on-error

ステップが失敗してもジョブが失敗にならないようにします。 trueに設定すれば、このステップが失敗した場合にジョブが次へ進めるようになります。

jobs.<job_id>.steps[*].timeout-minutes

プロセスがkillされるまでにステップが実行できる最大の分数。

jobs.<job_id>.timeout-minutes

GitHubで自動的にキャンセルされるまでジョブを実行する最長時間 (分)。 デフォルト: 360

If the timeout exceeds the job execution time limit for the runner, the job will be canceled when the execution time limit is met instead. For more information about job execution time limits, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.

Note: The GITHUB_TOKEN expires when a job finishes or after a maximum of 24 hours. For self-hosted runners, the token may be the limiting factor if the job timeout is greater than 24 hours. For more information on the GITHUB_TOKEN, see "About the GITHUB_TOKEN secret."

jobs.<job_id>.strategy

Use jobs.<job_id>.strategy to use a matrix strategy for your jobs. マトリックス戦略を使うと、単一のジョブ定義中で変数を使って、変数の組み合わせに基づく複数のジョブの実行を自動的に生成できます。 たとえばマトリックス戦略を使って、コードを言語の複数のバージョンや、複数のオペレーティングシステムでテストできます。 For more information, see "Using a matrix for your jobs."

jobs.<job_id>.strategy.matrix

jobs.<job_id>.strategy.matrixを使って、様々なジョブ設定のマトリックスを定義してください。 マトリックス内では、1つ以上の変数のあとに値の配列を続けて定義してください。 たとえば、以下のマトリックスは[10, 12, 14]という値のversionという変数を、そして[ubuntu-latest, windows-latest]という値のosという変数を持っています。

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]

取り得る変数のそれぞれの組み合わせに対して、ジョブが実行されます。 この例では、ワークフローはos及びversion変数のそれぞれの組み合わせに対応する6つのジョブを実行します。

デフォルトでは、GitHub Enterprise Serverは利用可能なランナーに応じて並列に実行されるジョブ数を最大化します。 マトリックス内の変数の順序によって、ジョブが生成される順序が決まります。 定義された最初の変数が、ワークフロー中で生成される最初のジョブになります。 たとえば、上のマトリックスはジョブを以下の順序で生成します。

  • {version: 10, os: ubuntu-latest}
  • {version: 10, os: windows-latest}
  • {version: 12, os: ubuntu-latest}
  • {version: 12, os: windows-latest}
  • {version: 14, os: ubuntu-latest}
  • {version: 14, os: windows-latest}

1つのマトリックスはワークフローの実行ごとに最大で256のジョブを生成します。 この制限は、GitHub Enterprise Serverホスト及びセルフホストの両方のランナーに適用されます。

定義した変数はmatrixコンテキストのプロパティとなり、このプロパティはワークフローファイルの他の領域から参照できます。 この例では、matrix.versionmatrix.osを使ってジョブが使用している現在のversionosの値にアクセスできます。 詳細については、「コンテキスト」を参照してください。

Example: Using a single-dimension matrix

1つの変数を指定して、1次元のマトリックスを作成できます。

たとえば、以下のワークフローは変数version[10, 12, 14]という値を定義しています。 このワークフローは、変数中のそれぞれの値に対して1つずつ、3つのジョブを実行します。 それぞれのジョブはversionの値にmatrix.versionコンテキストを通じてアクセスし、その値をnode-versionとしてactions/setup-nodeアクションに渡します。

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
    steps:
      - uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.version }}

Example: Using a multi-dimension matrix

複数の変数を指定して、多次元マトリックスを作成できます。 変数の取り得るそれぞれの組み合わせに対してジョブが実行されます。

たとえば、以下のワークフローは2つの変数を指定しています。

  • os変数では2つのオペレーティングシステムが指定されています
  • version変数では、3つのNode.jsのバージョンが指定されています

このワークフローは、os及びversion変数のそれぞれの組み合わせに応じた6のジョブを実行します。 各ジョブは、runs-onの値を現在のosの値に設定し、現在のversionの値をactions/setup-nodeアクションに渡します。

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [ubuntu-18.04, ubuntu-20.04]
        version: [10, 12, 14]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.version }}

Example: Using contexts to create matrices

コンテキストを使ってマトリックスを作成できます。 コンテキストに関する詳しい情報については「コンテキスト」を参照してください。

たとえば、以下のワークフローはrepository_dispatchイベントでトリガーされ、マトリックスの構築にイベントのペイロードからの情報を使います。 リポジトリのディスパッチイベントが以下のようなペイロードで作成されると、マトリックスのversion変数は[12, 14, 16]という値を持ちます。 repository_dispatchに関する詳しい情報については「ワークフローをトリガーするイベント」を参照してください。

{
  "event_type": "test",
  "client_payload": {
    "versions": [12, 14, 16]
  }
}
on:
  repository_dispatch:
    types:
      - test

jobs:
  example_matrix:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        version: ${{ github.event.client_payload.versions }}
    steps:
      - uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.version }}

jobs.<job_id>.strategy.matrix.include

jobs.<job_id>.strategy.matrix.includeを使って、既存のマトリックス設定を拡張したり、新しい設定を追加したりしてください。 includeの値は、オブジェクトのリストです。

includeリスト中の各オブジェクトについて、オブジェクト中のkey:valueペアがいずれもオリジナルのマトリックスの値を上書きしない場合、それらのkey:valueペアはそれぞれのマトリックスの組み合わせに追加されます。 オブジェクトがマトリックスの組み合わせのいずれにも追加できない場合、代わりに新しいマトリックスの組み合わせが作成されます。 オリジナルのマトリックスの値は上書きされませんが、追加されたマトリックスの値は上書きできることに注意してください。

たとえば、以下のマトリックス

strategy:
  matrix:
    fruit: [apple, pear]
    animal: [cat, dog]
    include:
      - color: green
      - color: pink
        animal: cat
      - fruit: apple
        shape: circle
      - fruit: banana
      - fruit: banana
        animal: cat

は、以下のマトリックスの組み合わせを持つ6つのジョブを生成します。

  • {fruit: apple, animal: cat, color: pink, shape: circle}
  • {fruit: apple, animal: dog, color: green, shape: circle}
  • {fruit: pear, animal: cat, color: pink}
  • {fruit: pear, animal: dog, color: green}
  • {fruit: banana}
  • {fruit: banana, animal: cat}

以下のようなロジックに従っています。

  • {color: green}は、オリジナルの組み合わせのどの部分も上書きすることなく追加できるので、すべてのオリジナルのマトリックスの組み合わせに追加されます。
  • {color: pink, animal: cat}は、animal: catを含むオリジナルのマトリックスの組み合わせに対してcolor:pinkだけを追加します。 これは、先のincludeエントリで追加されたcolor: greenを上書きします。
  • {fruit: apple, shape: circle}fruit: appleを含むオリジナルのマトリックスの組み合わせにshape: circleだけを追加します。
  • {fruit: banana}は、値を上書きせずにオリジナルのマトリックスの組み合わせに追加することができないので、追加のマトリックスの組み合わせとして追加されます。
  • {fruit: banana, animal: cat}は、値を上書きせずにオリジナルのマトリックスの組み合わせに追加することができないので、追加のマトリックスの組み合わせとして追加されます。 これは{fruit: banana}のマトリックスの組み合わせには追加されませんが、それはこの組み合わせがオリジナルのマトリックスの組み合わせの1つではないからです。

Example: Expanding configurations

たとえば、以下のワークフローはosnodeの組み合わせに対応する6つのジョブを実行します。 osの値がwindows-latestnodeの値が16に対するジョブが実行されると、そのジョブにはnpmという追加の変数が6を値として含まれます。

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [windows-latest, ubuntu-latest]
        node: [12, 14, 16]
        include:
          - os: windows-latest
            node: 16
            npm: 6
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.node }}
      - if: ${{ matrix.npm }}
        run: npm install -g npm@${{ matrix.npm }}
      - run: npm --version

Example: Adding configurations

たとえばこのマトリックスは、マトリックス内のos及びversionの各組み合わせに、osの値がwindows-latestversionの値が17の場合を加えて、10個のジョブを実行します。

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]
        version: [12, 14, 16]
        include:
          - os: windows-latest
            version: 17

マトリックス変数を指定しなければ、include以下のすべての設定が実行されます。 たとえば、以下のワークフローはincludeの各エントリに対応して2つのジョブを実行します。 これによって、完全にマトリックスを展開することなく、マトリックス戦略を活用できます。

jobs:
  includes_only:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - site: "production"
            datacenter: "site-a"
          - site: "staging"
            datacenter: "site-b"

jobs.<job_id>.strategy.matrix.exclude

マトリックスで定義されている特定の設定を除外したい場合には、jobs.<job_id>.strategy.matrix.excludeを使ってください。 除外する設定は、部分一致だけでかまいません。 たとえば、以下のワークフローは9つのジョブを実行します。12個の各設定に対応するジョブから、{os: macos-latest, version: 12, environment: production}にマッチする1つのジョブと{os: windows-latest, version: 16}にマッチする2つのジョブが除外されます。

strategy:
  matrix:
    os: [macos-latest, windows-latest]
    version: [12, 14, 16]
    environment: [staging, production]
    exclude:
      - os: macos-latest
        version: 12
        environment: production
      - os: windows-latest
        version: 16
runs-on: ${{ matrix.os }}

ノート: すべてのincludeの組み合わせは、excludeの後に処理されます。 このため、includeを使って以前に除外された組み合わせを追加し直すことができます。

jobs.<job_id>.strategy.fail-fast

jobs.<job_id>.strategy.fail-fast and jobs.<job_id>.continue-on-errorで、ジョブの失敗をどのように扱うかを制御できます。

jobs.<job_id>.strategy.fail-fastはマトリックス全体に適用されます。 jobs.<job_id>.strategy.fail-fasttrueに設定されていると、GitHub Enterprise Serverはマトリックス内のいずれかのジョブが失敗した場合、マトリックスの進行中及びキューイングされたすべてのジョブをキャンセルします。 この属性のデフォルトはtrueです。

jobs.<job_id>.continue-on-errorは単一のジョブに適用されます。 jobs.<job_id>.continue-on-errortrueの場合、jobs.<job_id>.continue-on-error: trueを指定されたジョブが失敗したとしても、マトリックス内の他のジョブは実行を継続します。

jobs.<job_id>.strategy.fail-fastjobs.<job_id>.continue-on-errorは合わせて利用できます。 たとえば、以下のワークフローは4つのジョブを開始します。 それぞれのジョブにおいて、continue-on-errormatrix.experimentalの値によって決定されます。 continue-on-error: falseを指定されたいずれかのジョブが失敗すると、進行中もしくはキューイングされたすべてのジョブはキャンセルされます。 continue-on-error: trueを指定されたジョブが失敗しても、他のジョブは影響を受けません。

jobs:
  test:
    runs-on: ubuntu-latest
    continue-on-error: ${{ matrix.experimental }}
    strategy:
      fail-fast: true
      matrix:
        version: [6, 7, 8]
        experimental: [false]
        include:
          - version: 9
            experimental: true

jobs.<job_id>.strategy.max-parallel

デフォルトでは、GitHub Enterprise Serverは利用できるランナーに応じて並列に実行するジョブ数を最大化します。 matrixジョブ戦略を使用する際に同時に実行できるジョブの最大数を設定するには、jobs.<job_id>.strategy.max-parallelを使ってください。

たとえば以下のワークフローは、仮に6つのジョブすべてを一度に実行できるランナーが利用できるとしても、同時に最大で2つのジョブしか実行しません。

jobs:
  example_matrix:
    strategy:
      max-parallel: 2
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]

jobs.<job_id>.continue-on-error

ジョブが失敗した時に、ワークフローの実行が失敗にならないようにします。 trueに設定すれば、ジョブが失敗した時にワークフローの実行が次へ進めるようになります。

Example: Preventing a specific failing matrix job from failing a workflow run

ジョブマトリックス中の特定のジョブが失敗しても、ワークフローの実行が失敗にならないようにすることができます。 For example, if you wanted to only allow an experimental job with node set to 15 to fail without failing the workflow run.

runs-on: ${{ matrix.os }}
continue-on-error: ${{ matrix.experimental }}
strategy:
  fail-fast: false
  matrix:
    node: [13, 14]
    os: [macos-latest, ubuntu-18.04]
    experimental: [false]
    include:
      - node: 15
        os: ubuntu-18.04
        experimental: true

jobs.<job_id>.container

Note: If your workflows use Docker container actions, job containers, or service containers, then you must use a Linux runner:

  • GitHubホストランナーを使うなら、Ubuntuランナーを使わなければなりません。
  • セルフホストランナーを使っているなら、ランナーとしてLinuxマシンを使い、Dockerをインストールしておかなければなりません。

jobs.<job_id>.containerを使って、コンテナをまだ指定していないジョブ内の任意のステップを実行するためのコンテナを作成してください。 スクリプトアクションとコンテナアクションの両方を使うステップがある場合、コンテナアクションは同じボリュームマウントを使用して、同じネットワーク上にある兄弟コンテナとして実行されます。

containerを設定しない場合は、コンテナで実行されるよう設定されているアクションを参照しているステップを除くすべてのステップが、runs-onで指定したホストで直接実行されます。

例: コンテナ内でのジョブの実行

YAML
name: CI
on:
  push:
    branches: [ main ]
jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container:
      image: node:14.16
      env:
        NODE_ENV: development
      ports:
        - 80
      volumes:
        - my_docker_volume:/volume_mount
      options: --cpus 1
    steps:
      - name: Check for dockerenv file
        run: (ls /.dockerenv && echo Found dockerenv) || (echo No dockerenv)

コンテナイメージのみを指定する場合、imageは省略できます。

jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container: node:14.16

jobs.<job_id>.container.image

jobs.<job_id>.container.imageを使って、アクションを実行させるコンテナとして使うDockerイメージを定義してください。 この値は、Docker Hubのイメージ名か、レジストリ名にすることができます。

jobs.<job_id>.container.credentials

If the image's container registry requires authentication to pull the image, you can use jobs.<job_id>.container.credentials to set a map of the username and password. この認証情報は、docker loginコマンドに渡すものと同じ値です。

例: コンテナレジストリの認証情報の定義

container:
  image: ghcr.io/owner/image
  credentials:
     username: ${{ github.actor }}
     password: ${{ secrets.github_token }}

jobs.<job_id>.container.env

jobs.<job_id>.container.envを使って、コンテナ内の環境変数のmapを設定してください。

jobs.<job_id>.container.ports

jobs.<job_id>.container.portsを使って、コンテナで公開するポートの配列を設定してください。

jobs.<job_id>.container.volumes

jobs.<job_id>.container.volumesを使って、コンテナが使用するボリュームの配列を設定してください。 volumes (ボリューム) を使用すると、サービス間で、または1つのジョブのステップ間でデータを共有できます。 指定できるのは、名前付きDockerボリューム、匿名Dockerボリューム、またはホスト上のバインドマウントです。

ボリュームを指定するには、ソースパスとターゲットパスを指定してください。

<source>:<destinationPath>.

<source>は、ホストマシン上のボリューム名または絶対パス、<destinationPath>はコンテナでの絶対パスです。

例: コンテナでのボリュームのマウント

volumes:
  - my_docker_volume:/volume_mount
  - /data/my_data
  - /source/directory:/destination/directory

jobs.<job_id>.container.options

jobs.<job_id>.container.optionsを使って、追加のDockerコンテナのリソースオプションを設定してください。 オプションの一覧は、「docker createのオプション」を参照してください。

警告: --network オプションはサポートされていません。

jobs.<job_id>.services

Note: If your workflows use Docker container actions, job containers, or service containers, then you must use a Linux runner:

  • GitHubホストランナーを使うなら、Ubuntuランナーを使わなければなりません。
  • セルフホストランナーを使っているなら、ランナーとしてLinuxマシンを使い、Dockerをインストールしておかなければなりません。

ワークフロー中のジョブのためのサービスコンテナをホストするために使われます。 サービスコンテナは、データベースやRedisのようなキャッシュサービスの作成に役立ちます。 ランナーは自動的にDockerネットワークを作成し、サービスコンテナのライフサイクルを管理します。

コンテナを実行するようにジョブを設定した場合、あるいはステップがコンテナアクションを使う場合は、サービスもしくはアクションにアクセスするためにポートをマップする必要はありません。 Dockerは自動的に、同じDockerのユーザ定義ブリッジネットワーク上のコンテナ間のすべてのポートを公開します。 サービスコンテナは、ホスト名で直接参照できます。 ホスト名は自動的に、ワークフロー中のサービスに設定したラベル名にマップされます。

ランナーマシン上で直接実行されるようにジョブを設定し、ステップがコンテナアクションを使わないのであれば、必要なDockerサービスコンテナのポートはDockerホスト(ランナーマシン)にマップしなければなりません サービスコンテナには、localhostとマップされたポートを使ってアクセスできます。

ネットワーキングサービスコンテナ間の差異に関する詳しい情報については「サービスコンテナについて」を参照してください。

Example: Using localhost

この例では、nginxとredisという2つのサービスを作成します。 Dockerホストのポートを指定して、コンテナのポートを指定しなかった場合、コンテナのポートは空いているポートにランダムに割り当てられます。 GitHubは、割り当てられたコンテナポートを${{job.services.<service_name>.ports}}コンテキストに設定します。 以下の例では、サービスコンテナのポートへは${{ job.services.nginx.ports['8080'] }} 及び${{ job.services.redis.ports['6379'] }} コンテキストでアクセスできます。

services:
  nginx:
    image: nginx
    # Dockerホストのポート8080をnginxコンテナのポート80にマップする
    ports:
      - 8080:80
  redis:
    image: redis
    # Dockerホストのポート6379をRedisコンテナのランダムな空きポートにマップする
    ports:
      - 6379/tcp

jobs.<job_id>.services.<service_id>.image

アクションを実行するサービスコンテナとして使用するDockerイメージ。 The value can be the Docker Hub image name or a registry name.

jobs.<job_id>.services.<service_id>.credentials

If the image's container registry requires authentication to pull the image, you can use jobs.<job_id>.container.credentials to set a map of the username and password. この認証情報は、docker loginコマンドに渡すものと同じ値です。

サンプル

services:
  myservice1:
    image: ghcr.io/owner/myservice1
    credentials:
      username: ${{ github.actor }}
      password: ${{ secrets.github_token }}
  myservice2:
    image: dockerhub_org/myservice2
    credentials:
      username: ${{ secrets.DOCKER_USER }}
      password: ${{ secrets.DOCKER_PASSWORD }}

jobs.<job_id>.services.<service_id>.env

サービスコンテナ中の環境変数のmapを設定します。

jobs.<job_id>.services.<service_id>.ports

サービスコンテナで公開するポートのarrayを設定します。

jobs.<job_id>.services.<service_id>.volumes

使用するサービスコンテナにボリュームのarrayを設定します。 volumes (ボリューム) を使用すると、サービス間で、または1つのジョブのステップ間でデータを共有できます。 指定できるのは、名前付きDockerボリューム、匿名Dockerボリューム、またはホスト上のバインドマウントです。

ボリュームを指定するには、ソースパスとターゲットパスを指定してください。

<source>:<destinationPath>.

<source>は、ホストマシン上のボリューム名または絶対パス、<destinationPath>はコンテナでの絶対パスです。

サンプル

volumes:
  - my_docker_volume:/volume_mount
  - /data/my_data
  - /source/directory:/destination/directory

jobs.<job_id>.services.<service_id>.options

追加のDockerコンテナリソースのオプション。 オプションの一覧は、「docker createのオプション」を参照してください。

警告: --network オプションはサポートされていません。

フィルタパターンのチートシート

特別なキャラクタをパス、ブランチ、タグフィルタで利用できます。

  • *ゼロ個以上のキャラクタにマッチしますが、/にはマッチしません。 たとえばOcto*Octocatにマッチします。
  • **ゼロ個以上の任意のキャラクタにマッチします。
  • ?: Matches zero or one of the preceding character.
  • +: 直前の文字の 1 つ以上に一致します。
  • [] 括弧内にリストされた、あるいは範囲に含まれる1つのキャラクタにマッチします。 範囲に含めることができるのはa-zA-Z0-9のみです。 たとえば、[0-9a-z]という範囲は任意の数字もしくは小文字にマッチします。 たとえば[CB]atCatあるいはBatにマッチし、[1-2]00100200にマッチします。
  • !: パターンの先頭に置くと、肯定のパターンを否定にします。 先頭のキャラクタではない場合は、特別な意味を持ちません。

YAMLにおいては、*[!は特別なキャラクタです。 パターンを*[!で始める場合、そのパターンをクオートで囲まなければなりません。

# 有効
- '**/README.md'

# 無効 - ワークフローの実行を妨げる
# 解析エラーを作成する
- **/README.md

For more information about branch, tag, and path filter syntax, see "on.<push>.<branches|tags>", "on.<pull_request>.<branches|tags>", and "on.<push|pull_request>.paths."

ブランチやタグにマッチするパターン

パターン説明マッチの例
feature/*ワイルドカードの*は任意のキャラクタにマッチしますが、スラッシュ(/)にはマッチしません。feature/my-branch

feature/your-branch
feature/**ワイルドカードの**は、ブランチ及びタグ名のスラッシュ(/)を含む任意のキャラクタにマッチします。feature/beta-a/my-branch

feature/your-branch

feature/mona/the/octocat
main

releases/mona-the-octocat
ブランチあるいはタグ名に完全に一致したときにマッチします。main

releases/mona-the-octocat
'*'スラッシュ(/)を含まないすべてのブランチ及びタグ名にマッチします。 *はYAMLにおける特別なキャラクタです。 パターンを*で始める場合は、クオートを使わなければなりません。main

releases
'**'すべてのブランチ及びタグ名にマッチします。 これは branchesあるいはtagsフィルタを使わない場合のデフォルトの動作です。all/the/branches

every/tag
'*feature'*はYAMLにおける特別なキャラクタです。 パターンを*で始める場合は、クオートを使わなければなりません。mona-feature

feature

ver-10-feature
v2*v2で始めるブランチ及びタグ名にマッチします。v2

v2.0

v2.9
v[12].[0-9]+.[0-9]+Matches all semantic versioning branches and tags with major version 1 or 2.v1.10.1

v2.0.0

ファイルパスにマッチするパターン

パスパターンはパス全体にマッチしなければならず、リポジトリのルートを出発点とします。

パターンマッチの説明マッチの例
'*'ワイルドカードの*は任意のキャラクタにマッチしますが、スラッシュ(/)にはマッチしません。 *はYAMLにおける特別なキャラクタです。 パターンを*で始める場合は、クオートを使わなければなりません。README.md

server.rb
'*.jsx?'?はゼロ個以上の先行するキャラクタにマッチします。page.js

page.jsx
'**'ワイルドカードの**は、スラッシュ(/)を含む任意のキャラクタにマッチします。 これは pathフィルタを使わない場合のデフォルトの動作です。all/the/files.md
'*.js'ワイルドカードの*は任意のキャラクタにマッチしますが、スラッシュ(/)にはマッチしません。 リポジトリのルートにあるすべての.jsファイルにマッチします。app.js

index.js
'**.js'リポジトリ内のすべての.jsファイルにマッチします。index.js

js/index.js

src/js/app.js
docs/*リポジトリのルートのdocsのルートにあるすべてのファイルにマッチします。docs/README.md

docs/file.txt
docs/**リポジトリのルートのdocs内にあるすべてのファイルにマッチします。docs/README.md

docs/mona/octocat.txt
docs/**/*.mddocsディレクトリ内にある.mdというサフィックスを持つファイルにマッチします。docs/README.md

docs/mona/hello-world.md

docs/a/markdown/file.md
'**/docs/**'リポジトリ内にあるdocsディレクトリ内のすべてのファイルにマッチします、docs/hello.md

dir/docs/my-file.txt

space/docs/plan/space.doc
'**/README.md'リポジトリ内にあるREADME.mdファイルにマッチします。README.md

js/README.md
'**/*src/**'リポジトリ内にあるsrcというサフィックスを持つフォルダ内のすべてのファイルにマッチします。a/src/app.js

my-src/code/js/app.js
'**/*-post.md'リポジトリ内にある-post.mdというサフィックスを持つファイルにマッチします。my-post.md

path/their-post.md
'**/migrate-*.sql'リポジトリ内のmigrate-というプレフィックスと.sqlというサフィックスを持つファイルにマッチします。migrate-10909.sql

db/migrate-v1.0.sql

db/sept/migrate-v1.sql
*.md

!README.md
感嘆符(!)をパターンの前に置くと、そのパターンの否定になります。 あるファイルがあるパターンにマッチし、ファイル中でその後に定義されている否定パターンにマッチした場合、そのファイルは含まれません。hello.md

Does not match

README.md

docs/hello.md
*.md

!README.md

README*
パターンは順番にチェックされます。 先行するパターンを否定するパターンで、ファイルパスが再度含まれるようになります。hello.md

README.md

README.doc