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

GitHub Actionsのワークフロー構文

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

GitHub ActionsはGitHub Free、GitHub Pro、GitHub Team、GitHub Enterprise Cloud、GitHub Oneで利用できます。 GitHub Actions is not available for private repositories owned by accounts using legacy per-repository plans. 詳しい情報については「GitHubの製品」を参照してください。

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

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

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

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

使用制限

There are some limits on GitHub Actions usage, and will vary depending on whether you use GitHub-hosted or self-hosted runners. これらの制限は変更されることがあります。

  • Job execution time - Each job in a workflow can run for up to 6 hours of execution time. ジョブがこの制限に達すると、ジョブは終了させられ、完了できずに失敗します。 This limit does not apply to self-hosted runners.

  • Workflow run time - Each workflow run is limited to 72 hours. If a workflow run reaches this limit, the workflow run is cancelled. この制限は、セルフホストランナーにも適用されます。

  • Job queue time - Each job for self-hosted runners can be queued for a maximum of 24 hours. If a self-hosted runner does not start executing the job within this limit, the job is terminated and fails to complete. This limit does not apply to GitHub-hosted runners.

  • API requests - You can execute up to 1000 API requests in an hour across all actions within a repository. この制限を超えた場合、超過のAPIコールは失敗し、それによってジョブも失敗するかもしれません。 この制限は、セルフホストランナーにも適用されます。

  • Concurrent jobs - The number of concurrent jobs you can run in your account depends on your GitHub plan, as indicated in the following table. この制限を超えた場合、超過のジョブはキューイングされます。 There are no concurrency limits for self-hosted runners.

    GitHubプラン 最大同時ジョブ 最大同時macOSジョブ
    無料 20 5
    Pro 40 5
    Team 60 5
    Enterprise 180 50
  • Job matrix - A job matrix can generate a maximum of 256 jobs per workflow run. この制限は、セルフホストランナーにも適用されます。

usage-limits

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

on

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

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

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

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

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

アクティビティの種類もしくは設定を伴う複数のイベントを使用する例

イベントに対してアクティビティの種類もしくは設定を指定する必要がある場合、それぞれのイベントを個別に設定しなければなりません。 設定を持たないイベントも含め、すべてのイベントにはコロン (:)を追加しなければなりません。

on:
  # プッシュもしくはプルリクエストでワークフローを起動する
  # ただしmasterブランチに対してのみ
  push:
    branches:
      - master
  pull_request:
    branches:
      - master
  # page_buildとリリース作成イベントでも起動
  page_build:
  release:
    types: # この設定は上のpage_buildイベントには影響しない
      - created

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イベントを使用する場合、特定のブランチまたはタグで実行するワークフローを設定できます。 pull_requestでは、ベース上のブランチ及びタグだけが評価されます。 tagsもしくはbranchesだけを定義すると、定義されていない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分ごとです。

以下の例では、15分ごとにワークフローを実行します。

on:
  schedule:
    # * はYAMLに置ける特殊文字なので、この文字列は引用符で囲まなければならない
    - cron:  '*/15 * * * *'

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

env

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

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

env:
  SERVER: production

jobs

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

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

ワークフローの利用限度内であれば、実行するジョブ数に限度はありません。 詳細については「利用限度」を参照してください。

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 or windows-2019
Ubuntu 18.04 ubuntu-latestまたはubuntu-18.04
Ubuntu 16.04 ubuntu-16.04
macOS Catalina 10.15 macos-latest or macos-10.15
サンプル
runs-on: ubuntu-latest

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

セルフホストランナー

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

すべてのセルフホストランナーはself-hostedラベルを持ち、self-hostedラベルだけを提供すれば任意のセルフホストランナーを選択できます。 あるいは、特定のオペレーティングシステムやシステムアーキテクチャのラベルといった追加のラベルと合わせて配列中でself-hostedを使い、指定した種類のランナーだけを選択することもできます。

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

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

jobs.<job_id>.env

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

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

サンプル

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は、ジョブの前のステップが失敗した場合にのみ実行されます。 詳しい情報については、「GitHub Actions のコンテキストと式構文」を参照してください。

steps:
  - name: My first step
    uses: monacorp/action-name@master
  - 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を参照してください。

バージョンされたアクションを使用する例
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

ワークフローのリポジトリにあるアクションを含むディレクトリのパス。 You must check out your repository before using the action.

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v2
      - name: Use local my-action
        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」を参照してください。

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

パブリックなアクションは、READMEファイル中で期待する環境変数を指定できます。 環境変数に秘密情報を設定しようとしている場合、秘密情報はsecretsコンテキストを使って設定しなければなりません。 詳しい情報については「環境変数の利用」及び「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

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

jobs.<job_id>.strategy

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

jobs.<job_id>.strategy.matrix

You can define a matrix of different job configurations. A matrix allows you to create multiple jobs by performing variable substitution in a single job definition. For example, you can use a matrix to create jobs for more than one supported version of a programming language, operating system, or tool. A matrix reuses the job's configuration and creates a job for each matrix you configure.

A job matrix can generate a maximum of 256 jobs per workflow run. この制限は、セルフホストランナーにも適用されます。

Each option you define in the matrix has a key and value. The keys you define become properties in the matrix context and you can reference the property in other areas of your workflow file. For example, if you define the key os that contains an array of operating systems, you can use the matrix.os property as the value of the runs-on keyword to create a job for each operating system. 詳しい情報については、「GitHub Actions のコンテキストと式構文」を参照してください。

The order that you define a matrix matters. The first option you define will be the first job that runs in your workflow.

Example running with more than one version of Node.js

設定オプションに配列を指定すると、マトリクスを指定できます。 For example, if the runner supports Node.js versions 6, 8, and 10, you could specify an array of those versions in the matrix.

This example creates a matrix of three jobs by setting the node key to an array of three Node.js versions. To use the matrix, the example sets the matrix.node context property as the value of the setup-node action's input parameter node-version. As a result, three jobs will run, each using a different Node.js version.

strategy:
  matrix:
    node: [6, 8, 10]
steps:
  # Configures the node version used on GitHub-hosted runners
  - uses: actions/setup-node@v1
    with:
      # The Node.js version to configure
      node-version: ${{ matrix.node }}

The setup-node action is the recommended way to configure a Node.js version when using GitHub-hosted runners. For more information, see the setup-node action.

Example running with more than one operating system

You can create a matrix to run workflows on more than one runner operating system. You can also specify more than one matrix configuration. This example creates a matrix of 6 jobs:

  • 2 operating systems specified in the os array
  • 3 Node.js versions specified in the node array

When you define a matrix of operating systems, you must set the value of runs-on to the matrix.os context property you defined.

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の仮想環境」を参照してください。

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

既存のビルドマトリクスジョブに、設定オプションを追加できます。 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

ノート: ジョブをDockerコンテナ内で実行し、GitHubホストランナーを使う場合、ubuntu-latestランナーを使わなければなりません。 セルフホストランナーを使う場合、ランナーマシンが直接Dockerをサポートしているのでなければ、ランナーマシンには必要なすべてのDockerソフトウェアがインストールされていなければなりません。 サポートされているGitHubホストランナーに関する詳しい情報については「GitHubホストランナーの仮想環境」を参照してください。

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

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

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

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

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.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/* ワイルドカードの*は任意のキャラクタにマッチしますが、スラッシュ(/)にはマッチしません。 -feature/my-branch
-feature/your-branch
feature/** ワイルドカードの**は、ブランチ及びタグ名のスラッシュ(/)を含む任意のキャラクタにマッチします。 -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
'*feature' *は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のルートにあるすべてのファイルにマッチします。 -docs/README.md
-docs/file.txt
docs/** リポジトリのルートの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ディレクトリ内のすべてのファイルにマッチします、 -/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

担当者にお尋ねください

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

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