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

GitHub Actionsのワークフロー構文

リポジトリにワークフローファイルを追加すると、ソフトウェア開発のライフサイクルを自動化するカスタムの自動プロセスを作成することができます。

GitHub Actions is available with GitHub Free, GitHub Pro, GitHub Team, and GitHub Enterprise Cloud. GitHub Actions is unavailable for per-repository plans, which are legacy billing plans. For more information, see "GitHub's products."

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

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

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

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

使用制限

使用制限を超えると、ジョブがキューに入れられる、実行に失敗する、または完了に失敗する場合があります。 使用制限は変更される可能性があります。

  • You can execute up to 20 workflows concurrently per repository.

  • 1時間に実行できるAPIリクエストは、1つのリポジトリの全アクションで最大1000までです。

  • ワークフローの各ジョブは、最大で6時間まで実行できます。

  • The number of jobs you can run concurrently across all repositories in your account depends on your GitHub plan.

    GitHub plan Total concurrent jobs Maximum concurrent macOS jobs
    無料 20 5
    Pro 40 5
    Team 60 5
    Enterprise 180 15

name

ワークフローの名前。 GitHubでは、リポジトリのアクションページにワークフローの名前が表示されます。 このフィールドを省略した場合、GitHubはnameをワークフローのファイル名に設定します。

on

必須 ワークフローをトリガーするGitHubイベントの名前。 指定できるのは、1つのイベントstring、複数イベントのarray、イベントtypesarrayです。あるいは、ワークフローをスケジュールする、またはワークフロー実行を特定のファイルやタグ、ブランチ変更に限定するイベント設定mapも指定できます。 使用可能なイベントの一覧は、「ワークフローをトリガーするイベント」を参照してください。

1つのイベントを使用する例

# プッシュでトリガー
on: push

イベントのリストを使用する例

# プッシュあるいはプルリクエストでワークフローをトリガー
on: [push, pull_request]

on.<event_name>.types

ワークフローの実行をトリガーする特定のアクティビティ。 ほとんどの GitHub イベントは、2 つ以上のアクティビティタイプからトリガーされます。 たとえば、releaseリソースに対するイベントは、release が publishedunpublishedcreatedediteddeleted、または prereleased の場合にトリガーされます。 typesキーワードを使用すると、ワークフローを実行させるアクティブの範囲を狭くすることができます。 webhook イベントをトリガーするアクティビティタイプが1つだけの場合、typesキーワードは不要です。

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

# Trigger the workflow on pull request activity
on:
  release:
    # Only use the types keyword to narrow down the activity types that will trigger your workflow.
    types: [published, created, edited]

on.<push|pull_request>.<branches|tags>

pushおよびpull_requestイベントを使用する場合、特定のブランチまたはタグで実行するワークフローを設定できます。 tagsbranchesのうちの1つのみを定義すると、定義されていないGit refに影響するイベントに対して、ワークフローが実行されません。

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

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

branchesおよびtagsで定義されているパターンは、Git refの名前と照らし合わせて評価されます。 たとえば、branchesmona/octocatとパターンを定義すると、refs/heads/mona/octocatというGit refにマッチします。 releases/**というパターンは、refs/heads/releases/10というGit refにマッチします。

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches:    
      - master         # Push events on master branch
      - 'mona/octocat' # Push events to branches matching refs/heads/mona/octocat
      - 'releases/**'  # Push events to branches matching refs/heads/releases/10
    # Sequence of patterns matched against refs/tags
    tags:        
      - v1             # Push events to v1 tag
      - v1.*           # Push events to v1.0, v1.1, and v1.9 tags

ブランチとタグを無視する例

パターンがbranches-ignoreまたはtags-ignoreとマッチする場合は常に、ワークフローは実行されません。 branches-ignoreおよびtags-ignoreで定義されているパターンは、Git refの名前と照らし合わせて評価されます。 たとえば、branchesmona/octocatとパターンを定義すると、refs/heads/mona/octocatというGit refにマッチします。 branchesのパターンreleases/**-alphaは、refs/releases/beta/3-alphaというGit refにマッチします。

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches-ignore:
      - 'mona/octocat'      # Push events to branches matching refs/heads/mona/octocat
      - 'releases/**-alpha' # Push events to branches matching refs/heads/releases/beta/3-alpha
    # Sequence of patterns matched against refs/tags
    tags-ignore:
      - v1.*           # Push events to tags v1.0, v1.1, and v1.9

ブランチとタグを除外する

タグやブランチへのプッシュおよびプルリクエストでワークフローが実行されることを防ぐために、2 種類のフィルタを使うことができます。

  • branches または branches-ignore - ワークフロー内の同じイベントに対して、branchesbranches-ignore のフィルタを両方使うことはできません。 肯定のマッチに対してブランチをフィルタし、ブランチを除外する必要がある場合は、branches フィルタを使います。 ブランチ名のみを除外する必要がある場合は、branches-ignore フィルタを使います。
  • tags または tags-ignore - ワークフロー内の同じイベントに対して、tagstags-ignore のフィルタを両方使うことはできません。 肯定のマッチに対してタグをフィルタし、タグを除外する必要がある場合は、tags フィルタを使います。 タグ名のみを除外する必要がある場合は、tags-ignore フィルタを使います。

肯定と否定のパターンを使用する例

"!" の文字を使うことで、tagsbranches を除外できます。 パターンを定義する順序により、結果に違いが生じます。

  • 肯定のマッチングパターンの後に否定のマッチングパターン ("!" のプレフィクス) を定義すると、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>.paths

push および pull_request イベントを使用する場合、1 つ以上の変更されたファイルが paths-ignore にマッチしない場合や、1 つ以上の変更されたファイルが、設定された paths にマッチする場合にワークフローを実行するように設定できます。 タグへのプッシュに対して、パスのフィルタは評価されません。

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

バスを無視する例

パス名が paths-ignore のパターンとマッチする場合は常に、ワークフローは実行されません。 GitHub は、paths-ignore に定義されているパターンを、パス名に対して評価します。 以下のパスフィルタを持つワークフローは、リポジトリのルートにある docsディレクトリ外のファイルを少なくとも1つ含むpushイベントでのみ実行されます。

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

パスを含む例

pathsフィルタのパターンにマッチするパスが1つでもあれば、ワークフローは実行されます。 JavaScriptファイルをプッシュしたときにビルドを走らせるには、ワイルドカードパターンが使えます。

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

パスの除外

パスは、2種類のフィルタで除外できます。 これらのフィルタをワークフロー内の同じイベントで両方使うことはできません。

  • paths-ignore - パス名を除外する必要だけがある場合にはpaths-ignoreフィルタを使ってください。
  • paths - 肯定のマッチのパスとパスの除外のフィルタが必要な場合はpathsフィルタを使ってください。

肯定と否定のパターンを使用する例

!文字を使って、pathsを除外できます。 パターンを定義する順序により、結果に違いが生じます:

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

この例は、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を生成できない(あまりにdiffが大きい)場合、そのワークフローは常に実行されます。

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

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

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

詳しい情報については「プルリクエスト中のブランチの比較について」を参照してください。

on.schedule

POSIX クーロン構文を使用して、特定の UTC 時間にワークフローを実行できるようスケジュール設定できます。 スケジュールしたワークフローは、デフォルトまたはベースブランチの直近のコミットで実行されます。 スケジュールされたワークフローを実行できる最短のインターバルは5分ごとです。

This example triggers the workflow every 15 minutes:

on:
  schedule:
    # * is a special character in YAML so you have to quote this string
    - cron:  '*/15 * * * *'

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

env

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

When more than one environment variable is defined with the same name, GitHub uses the most specific environment variable. For example, an environment variable defined in a step will override job and workflow variables with the same name, while the step executes. A variable defined for a job will override a workflow variable with the same name, while the job executes.

jobs

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

各ジョブは、runs-onで指定した仮想環境の新しいインスタンスで実行されます。

You can run an unlimited number of jobs as long as you are within the workflow usage limits. 詳細については「利用限度」を参照してください。

jobs.<job_id>

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

サンプル

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

jobs.<job_id>.name

GitHubに表示されるジョブの名前。

jobs.<job_id>.needs

このジョブの実行前に正常に完了する必要があるジョブを示します。 文字列型または文字列の配列です。 1つのジョブが失敗した場合、失敗したジョブを続行するような条件文を使用していない限り、そのジョブを必要としている他のジョブはすべてスキップされます。

サンプル

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

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

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

  1. job1
  2. job2
  3. job3

jobs.<job_id>.runs-on

必須 ジョブを実行するマシンの種類。 マシンはGitHubホストランナーあるいは自己ホストランナーのいずれかです。

GitHubホストランナー

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

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

仮想環境 YAMLのワークフローラベル
Windows Server 2019 windows-latest
Ubuntu 18.04 ubuntu-latestまたはubuntu-18.04
Ubuntu 16.04 ubuntu-16.04
macOS Catalina 10.15 macos-latest
サンプル
runs-on: ubuntu-latest

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

自己ホストランナー

To specify a self-hosted runner for your job, configure runs-on in your workflow file with self-hosted runner labels.

All self-hosted runners have the self-hosted label, and you can select any self-hosted runner by providing only the self-hosted label. Alternatively, you can use self-hosted in an array with additional labels, such as labels for a specific operating system or system architecture, to select only the runner types you specify.

サンプル
runs-on: [self-hosted, linux]

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

jobs.<job_id>.env

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

When more than one environment variable is defined with the same name, GitHub uses the most specific environment variable. For example, an environment variable defined in a step will override job and workflow variables with the same name, while the step executes. A variable defined for a job will override a workflow variable with the same name, while the job executes.

サンプル

jobs:
  job1:
    env:
      FIRST_NAME: Mona

jobs.<job_id>.if

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

条件文のif内の式には、${{ }}構文は不要です。 詳しい情報については、「GitHub Actions のコンテキストと式構文」を参照してください。

jobs.<job_id>.steps

1つのジョブには、steps (ステップ) と呼ばれる一連のタスクがあります。 ステップでは、コマンドを実行する、設定タスクを実行する、あるいはリポジトリやパブリックリポジトリ、Dockerレジストリで公開されたアクションを実行することができます。 すべてのステップでアクションを実行するとは限りませんが、すべてのアクションはステップとして実行されます。 各ステップは、仮想環境のそれ自体のプロセスで実行され、ワークスペースとファイルシステムにアクセスします。 ステップはそれ自体のプロセスで実行されるため、環境変数を変更しても、ステップ間では反映されません。 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を使って、コンテキストのステップを参照することができます。 詳しい情報については、「GitHub Actions のコンテキストと式構文」を参照してください。

jobs.<job_id>.steps.if

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

条件文のif内の式には、${{ }}構文は不要です。 詳しい情報については、「GitHub Actions のコンテキストと式構文」を参照してください。

コンテキストの使用例

このステップは、イベントの種類が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.
ステータスチェック関数の使用例

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

steps:
  - name: My first step
    # Use an action (`my-action`) in your repository
    uses: ./.github/actions/my-action
  - name: My backup step
    if: failure()
    uses: actions/heroku@master

jobs.<job_id>.steps.name

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

jobs.<job_id>.steps.uses

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

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

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

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

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

バージョンされたアクションを使用する例
steps:    
  - uses: actions/setup-node@74bc508 # Reference a specific commit
  - uses: actions/setup-node@v1      # Reference the major version of a release   
  - uses: actions/setup-node@v1.2    # Reference a minor version of a release  
  - uses: actions/setup-node@master  # Reference a branch
パブリックアクションを使用する例

{owner}/{repo}@{ref}

パブリックGitHubリポジトリのブランチ、ref、SHAを指定できます。

jobs:
  my_first_job:
    steps:
      - name: My first step
      # Uses the master branch of a public repository
        uses: actions/heroku@master
      # use a specific version tag of a public repository
      - name: My second step
        uses: actions/aws@v2.0.1
サブディレクトリのパブリックアクションを使用する例

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

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

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/aws/ec2@master
ワークフローと同じリポジトリにあるアクションを使用する例

./path/to/dir

ワークフローのリポジトリにあるアクションを含むディレクトリのパス。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: ./.github/actions/my-action
Docker Hubアクションを使用する例

docker://{image}:{tag}

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

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://alpine:3.8
Dockerパブリックレジストリアクションを使用する例

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

パブリックレジストリのDockerイメージ。

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

jobs.<job_id>.steps.run

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

コマンドは、デフォルトでは非ログインシェルを使用して実行されます。 別のシェルを選択して、コマンドを実行するシェルをカスタマイズできます。 詳しい情報については「特定のシェルの利用」を参照してください。

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
特定のシェルを使用する

shellキーワードを使用して、仮想環境のオペレーティングシステムのデフォルトシェルを上書きできます。 組み込みのshellキーワードを使用するか、カスタムセットのシェルオプションを定義することができます。

サポートされているプラットフォーム shell パラメータ 説明 内部で実行されるコマンド
すべて bash 非Windowsプラットフォームのデフォルトシェルで、shへのフォールバックがあります。 Windowsでbashシェルを指定すると、Windows用Gitに含まれるbashシェルが使用されます。 bash --noprofile --norc -eo pipefail {0}
すべて pwsh PowerShell Coreです。 GitHubはスクリプト名に拡張子.ps1を追加します。 pwsh -command "& '{0}'"
すべて python Pythonのコマンドを実行します。 python {0}
Linux / macOS sh 非Windowsプラットフォームにおいてシェルが提供されておらず、パス上でbashが見つからなかった場合のフォールバック動作です。 sh -e {0}
Windows cmd GitHubはスクリプト名に拡張子.cmdを追加し、{0}を置き換えます。 %ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}"".
Windows powershell これはWindowsで使われるデフォルトのシェルです。 デスクトップPowerShellです。 GitHubはスクリプト名に拡張子.ps1を追加します。 powershell -command "& '{0}'".
bashを使用してスクリプトを実行する例
steps:
  - name: Display the path
    run: echo $PATH
    shell: bash
Windowsのcmdを使用してスクリプトを実行する例
steps:
  - name: Display the path
    run: echo %PATH%
    shell: cmd
PowerShell Coreを使用してスクリプトを実行する例
steps:
  - name: Display the path
    run: echo ${env:PATH}
    shell: pwsh
Python scriptを実行する例
steps:
  - name: Display the path
    run: |
      import os
      print(os.environ['PATH'])
    shell: python
カスタムシェル

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

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

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

  • bash/sh:

    • set -e o 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@master
        with:
          first_name: Mona
          middle_name: The
          last_name: Octocat      

jobs.<job_id>.steps.with.args

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

サンプル
steps:
  - name: Explain why this job ran
    uses: monacorp/action-name@master
    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: monacorp/action-name@master
    with:
      entrypoint: /a/different/executable

このentrypointキーワードはDockerコンテナのアクションを使おうとしていますが、これは入力を定義しないJavaScriptのアクションにも使えます。

jobs.<job_id>.steps.env

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

When more than one environment variable is defined with the same name, GitHub uses the most specific environment variable. For example, an environment variable defined in a step will override job and workflow variables with the same name, while the step executes. A variable defined for a job will override a workflow variable with the same name, while the job executes.

パブリックなアクションは、READMEファイル中で期待する環境変数を指定できます。 環境変数に秘密情報を設定しようとしている場合、秘密情報はsecretsコンテキストを使って設定しなければなりません。 詳しい情報については「GitHub Actionsの仮想環境」及び「GitHub Actionsのコンテキストと式構文」を参照してください。

サンプル
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

The maximum number of minutes to let a job run before GitHub automatically cancels it. デフォルト: 360

jobs.<job_id>.strategy

Strategy (戦略) によって、ジョブのビルドマトリクスが作成されます。 各ジョブを実行する環境のバリエーションを定義できます。

jobs.<job_id>.strategy.matrix

1つのビルドマトリクスが、仮想環境の異なる設定のセットです。 たとえば、サポート対象の複数の言語、オペレーティングシステム、ツールに対してジョブを実行することもできます。 それぞれの設定は、実行されてステータスをレポートするジョブのコピーです。

設定オプションに配列を指定すると、マトリクスを指定できます。 たとえば、GitHubの仮想環境がNode.jsのバージョン6、8、10をサポートしている場合、これらのバージョンの配列をmatrixで指定できます。

When you define a matrix of operating systems, you must set the required runs-on keyword to the operating system of the current job, rather than hard-coding the operating system name. To access the operating system name, you can use the matrix.os context parameter to set runs-on. 詳しい情報については、「GitHub Actions のコンテキストと式構文」を参照してください。

You can run an unlimited number of jobs as long as you are within the workflow usage limits. 詳細については「利用限度」を参照してください。

サンプル

この例は3つのジョブのマトリクスを生成し、それぞれに異なる値を変数のnodeに設定し、この変数をsetup-nodeアクションへの入力として使っています。 その結果、それぞれのジョブは異なるnodeのバージョンを使うことになります。

strategy:
  matrix:
    node: [6, 8, 10]
steps:
  - uses: actions/setup-node@v1
    with:
      node-version: ${{ matrix.node }}

これらのジョブは、matrixの変数をruns-onの指定子への入力として使い、2つの異なるバージョンのLinuxで実行させ、合計で6つのジョブ(3つのnodeのバージョン×2つのLinuxのバージョン)を生成できます。

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    os: [ubuntu-16.04, ubuntu-18.04]
    node: [6, 8, 10]
steps:
  - uses: actions/setup-node@v1
    with:
      node-version: ${{ matrix.node }}

GitHubの仮想環境でサポートされている設定オプションについては、「GitHub Actionsの仮想環境」を参照してください。

マトリクスビルドに設定を含める例

既存のビルドマトリクスジョブに、設定オプションを追加できます。 include を使ってビルドマトリクスに新しいジョブを追加することはできません。 たとえば、windows-latest を使うジョブでnode のバージョン 4 を実行しているときに、npm の特定のバージョンを使いたい場合は、include を使って追加のオプションを指定できます。

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    os: [macos-latest, windows-latest, ubuntu-18.04]
    node: [4, 6, 8, 10]
    include:
      # includes a new variable of npm with a value of 2 for the matrix leg matching the os and version
      - os: windows-latest
        node: 4
        npm: 2
マトリクスから設定を除外する例

exclude オプションを使って、ビルドマトリクスに定義されている特定の設定を削除できます。 exclude を使うと、ビルドマトリクスにより定義されたジョブが削除されます。 ジョブの数は、指定する配列に含まれるオペレーティングシステム (os) の外積から、任意の減算 (exclude) で引いたものです。

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    os: [macos-latest, windows-latest, ubuntu-18.04]
    node: [4, 6, 8, 10]
    exclude:
      # excludes node 4 on macOS
      - os: macos-latest
        node: 4

jobs.<job_id>.strategy.fail-fast

trueに設定すると、いずれかのmatrixジョブが失敗した場合にGitHubは進行中のジョブをすべてキャンセルします。 デフォルト: true

jobs.<job_id>.strategy.max-parallel

matrixジョブ戦略を使用するとき、同時に実行できるジョブの最大数。 デフォルトでは、GitHubはGitHubがホストしている仮想マシン上で利用できるrunnerに応じてできるかぎりの数のジョブを並列に実行します。

strategy:
  max-parallel: 2

jobs.<job_id>.container

ジョブの中で、まだコンテナを指定していない手順を実行するコンテナ。 スクリプトアクションとコンテナアクションの両方を使うステップがある場合、コンテナアクションは同じボリュームマウントを使用して、同じネットワーク上にある兄弟コンテナとして実行されます。

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

サンプル

jobs:
  my_job:
    container:
      image: node:10.16-jessie
      env:
        NODE_ENV: development
      ports:
        - 80
      volumes:
        - my_docker_volume:/volume_mount
      options: --cpus 1

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

jobs:
  my_job:
    container: node:10.16-jessie

jobs.<job_id>.container.image

アクションを実行するコンテナとして使用するDockerイメージ。 値はDocker Hubイメージ名か、パブリックDockerレジストリ名です。

jobs.<job_id>.container.env

コンテナで環境変数のarrayを設定します。

jobs.<job_id>.container.ports

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

jobs.<job_id>.container.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>.container.options

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

jobs.<job_id>.services

ワークフローでジョブのサービスをホストする追加のコンテナ。 データベースや、Redisなどのキャッシュサービスを作成するときに便利です。 仮想マシン上のrunnerが自動的にネットワークを作成し、サービスコンテナのライフサイクルを管理します。

ジョブにサービスコンテナを使用している場合、またはステップでコンテナアクションを使用する場合、サービスにアクセスする際にポート情報は必要ありません。 Dockerが同じネットワーク上のコンテナ間ですべてのポートを自動的に公開します。

ジョブとアクションのどちらもコンテナで実行される場合は、ホスト名でコンテナを直接参照できます。 ホスト名は自動的にサービス名にマップされます。

ステップでコンテナアクションを使用しない場合、localhostを使用してサービスにアクセスして、ポートをバインドする必要があります。

localhostを使用する例

次の例では、NginxとRedisに2つのサービスを作成します。 GitHubが仮想ホスト上で空きポートを選択し、Redisのデフォルトポートをバインドします。 GitHubはバインドされたホストポートを${{ job.services.<service_name>.ports[<port>] }}ジョブコンテキストで設定します。 たとえば、Redisポートは${{ job.services.redis.ports['6379'] }}環境変数で設定されます。

services:
  nginx:
    image: nginx
    ports:
      - 8080:80
    env:
      NGINX_PORT: 80
  redis:
    image: redis
    ports:
      - 6379/tcp

jobs.<job_id>.services.image

アクションを実行するサービスコンテナとして使用するDockerイメージ。 値はDockerベースイメージ名か、パブリックDocker Hubまたはレジストリです。

jobs.<job_id>.services.env

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

jobs.<job_id>.services.ports

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

jobs.<job_id>.services.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.options

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

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

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

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

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

- '**/README.md' # 正しい
- **/README.md   # 正しくない - パースエラーとなってワークフローは実行できない

ブランチ、タグ、およびパスフィルタの文法に関する詳しい情報については、「on.<push|pull_request>.<branches|tags>」および「on.<push|pull_request>.paths」を参照してください。

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

パターン 説明 マッチの例
機能/* ワイルドカードの*は任意のキャラクタにマッチしますが、スラッシュ(/)にはマッチしません。 -feature/my-branch
-feature/your-branch
機能/** ワイルドカードの**は、ブランチ及びタグ名のスラッシュ(/)を含む任意のキャラクタにマッチします。 -feature/beta-a/my-branch
-feature/your-branch
-feature/mona/the/octocat
-master
-releases/mona-the-octcat
ブランチあるいはタグ名に完全に一致したときにマッチします。 -master
-releases/mona-the-octocat
'*' スラッシュ(/)を含まないすべてのブランチ及びタグ名にマッチします。 *はYAMLにおける特別なキャラクタです。 パターンを*で始める場合は、クオートを使わなければなりません。 -master
-releases
'**' すべてのブランチ及びタグ名にマッチします。 これは branchesあるいはtagsフィルタを使わない場合のデフォルトの動作です。 -all/the/branches
-every/tag
'*機能' *はYAMLにおける特別なキャラクタです。 パターンを*で始める場合は、クオートを使わなければなりません。 -mona-feature
-feature
-ver-10-feature
v2* v2で始めるブランチ及びタグ名にマッチします。 -v2
-v2.0
-v2.9
v[12].[0-9]+.[0-9]+ メジャーバージョンが1もしくは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/README.md
-docs/file.txt
ドキュメント/** リポジトリのルートのdocs内にあるすべてのファイルにマッチします。 -docs/README.md
-docs/mona/octocat.txt
docs/**/*.md docsディレクトリ内にある.mdというサフィックスを持つファイルにマッチします。 -docs/README.md
-docs/mona/hello-world.md
-docs/a/markdown/file.md
'**/ドキュメント/**' リポジトリ内にある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
マッチしない
-README.md
-docs/hello.md
-*.md
-!README.md
-README*
パターンは順番にチェックされます。 先行するパターンを否定するパターンで、ファイルパスが再度含まれるようになります。 -hello.md
-README.md
-README.doc

担当者にお尋ねください

探しているものが見つからなかったでしょうか?

弊社にお問い合わせください