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

GitHub Actionsのワークフロー構文

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

GitHub Actionsは現在、限定パブリックベータとして利用可能で、変更となる可能性があります。ベータ期間中は、高価なワークフローやコンテンツにこの機能を利用することは避けてください。

詳細は「GitHub Actionsについて」(/articles/about-github-actions) を参照してください。

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

About YAML syntax for workflows

ワークフローファイルでは、YAML構文を使用します。 If you're new to YAML and want to learn more, see "Learn YAML in five minutes."

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

Usage limits

Exceeding usage limits may result in jobs queueing, failing to run, or failing to complete. Limits are subject to change.

name

ワークフローの名前。 GitHubでは、リポジトリのアクションページにワークフローの名前が表示されます。 If you omit this field, GitHub sets the name to the workflow's filename.

on

必須 ワークフローをトリガーするGitHubイベントの名前。 指定できるのは、1つのイベントstringかイベントのarrayです。あるいは、ワークフローをスケジュールする、またはワークフロー実行を特定のファイルやタグ、ブランチ変更に限定するイベント設定mapも指定できます。 For a list of available events, see "Events that trigger workflows."

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

# Trigger on push
on: push

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

# Trigger the workflow on push or pull request
on: [push, pull_request]

Example restricting the workflow run to specific refs and paths

You can restrict the execution of a workflow to changes on specific branches, tags, or file paths.

.gitignoreファイルで使用されるのと同じパターンマッチング構文を使用すれば、複数のパスやGit refを含めることができます。

When you specify branches, tags, or paths, the workflow will only run when all patterns match.

# File paths to consider in the event. Optional; defaults to all
push:
  branches:    # Array of patterns that match refs/heads
  - master     # Push events on master branch
  - releases/* # Push events to branches matching refs/heads/releases/*
  - !refs/pull/*
  tags:        # Array of patterns that match refs/tags.
  - v1         # Push events to v1 tag
  paths:       # Push events containing matching files
  - test/*
  - *.xml
pull_request:  # Specify a second event with pattern matching
  paths:
  - js/*

cron構文を使用してワークフローをスケジュールする例

This example triggers the workflow every 15 minutes:

on:
schedule:
- cron:  */15 * * * *

jobs

A workflow run is made up of one or more jobs. デフォルトでは、ジョブは並行して実行されます。 To run jobs sequentially, you can define dependencies on other jobs using the jobs.<job_id>.needs keyword.

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

You can run an unlimited number of jobs as long as you are within the workflow usage limits. For more information, see "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]

In this example, job1 must complete successfully before job2 begins, and job3 waits for both job1 and job2 to complete.

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

  1. job1
  2. job2
  3. job3

jobs.<job_id>.runs-on

Required The type of virtual host machine to run the job on. 各ジョブは、runs-onで指定した仮想環境の新しいインスタンスで実行されます。

使用可能な仮想マシンの種類は、次のとおりです。

For more information, see Virtual environments for GitHub Actions for details.

runs-on: ubuntu-18.04

jobs.<job_id>.steps

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

You can run an unlimited number of steps as long as you are within the workflow usage limits. For more information, see "Usage limits."

jobs:
  my_first_job:
    steps:

      - name: My first step
        uses: actions/hello-world@master
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          MY_VAR1: a_variable
        with:
          first_name: Mona
          middle_name: The
          last_name: Octocat
      - run: echo All Done!

jobs.<job_id>.steps.id

ステップの一意の識別子。 idを使って、コンテキストのステップを参照することができます。 For more information, see "Contexts and expression syntax for GitHub Actions."

jobs.<job_id>.steps.if

You can use the if conditional to prevent a step from running unless a condition is met. You can use any supported context and expression to create a conditional.

Expressions in an if conditional do not require the

${{ }} sytnax. For more information, see "Contexts and expression syntax for GitHub Actions."

Example using contexts

This step only runs when the event type is a pull_request and the event action is unassigned.

steps:
  - name: My first step
    if: github.event_name == 'pull_request' && github.event.action == 'unassigned'
    run: echo did my first step run?

Example using status check functions

The my backup step only runs when the previous step of a job fails. For more information, see "Status check functions."

    steps:
      - name: My first step
        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タグ番号を指定して、使用しているアクションのバージョンを含めることを強くお勧めします。 バージョンを指定しないと、アクションのオーナーがアップデートを公開したとき、ワークフローが中断したり、予期せぬ動作をしたりすることがあります。

Some actions require inputs that you must set using the with keyword. 必要な入力を判断するには、アクションのREADMEファイルをお読みください。

Actions are either JavaScript files or Docker containers. 使用するアクションが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は、それぞれが仮想環境での新しいプロセスとシェルです。 複数行のコンテンツを指定し、各行を同じシェルで実行することもできます。

- name: Install Dependencies
  run: npm install      

jobs.<job_id>.steps.run.shell

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

Supported for Windows platforms
Support for all platforms
Support for Linux and macOS platforms
カスタムシェル

command […options] {0} [..more_options]を使用すると、テンプレート文字列にshell値を設定できます。 GitHub interprets the first whitespace-delimited word of the string as the command, and inserts the file name for the temporary script at {0}.

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

For built-in shell keywords, we provide the following defaults that are executed by GitHub-hosted runners. You should use these guidelines when running shell scripts.

jobs.<job_id>.steps.with

A map of the input parameters defined by the action. 各入力パラメータはキー/値ペアです。 Input parameters are set as environment variables. The variable is prefixed with INPUT_ and converted to upper case.

hello_worldアクションで定義される3つの入力パラメータ (first_namemiddle_namelast_name) を定義します。 These input variables will be accessible to the hello-world action as INPUT_FIRST_NAME, INPUT_MIDDLE_NAME, and INPUT_LAST_NAME environment variables.

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

A string that defines the inputs for a Docker container. GitHub passes the args to the container's ENTRYPOINT when the container starts up. An array of strings is not supported by this parameter.

steps:
- name: Explain why this job ran
  uses: monacorp/action-name@master
  with:
    entrypoint: /bin/echo
    args: this was run due to a $

The args are used in place of the CMD instruction in a Dockerfile. If you use CMD in your Dockerfile, use the guidelines ordered by preference:

  1. Document required arguments in the action's README and omit them from the CMD instruction.
  2. Use defaults that allow using the action without specifying any args.
  3. If the action exposes a --help flag, or something similar, use that as the default to make your action self-documenting.

jobs.<job_id>.steps.with.entrypoint

Overrides the Docker ENTRYPOINT in the Dockerfile, or sets it if one wasn't already specified. Unlike the Docker ENTRYPOINT instruction which has a shell and exec form, entrypoint keyword accepts only a single string defining the executable to be run.

steps:
- name: Run a custom command
  uses: monacorp/action-name@master
  with:
    entrypoint: /a/different/executable

The entrypoint keyword is meant to use with Docker container actions, but you can also use it with JavaScript actions that don't define any inputs.

jobs.<job_id>.steps.env

Sets environment variables for steps to use in the virtual environment. Public actions may specify expected environment variables in the README file. If you are setting a secret in an environment variable, you must set secrets using the secrets context. For more information, see "Virtual environments for GitHub Actions" and "Contexts and expression syntax for GitHub Actions."

steps:

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

jobs.<job_id>.steps.working-directory

The default directory that the action uses in a job's workspace.

jobs.<job_id>.steps.continue-on-error

Prevents a job from failing when a step fails. Set to true to allow a job to pass when this step fails.

jobs.<job_id>.steps.timeout-minutes

The maximum number of minutes to run the step before killing the process.

jobs.<job_id>.timeout-minutes

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

jobs.<job_id>.strategy

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

jobs.<job_id>.strategy.matrix

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

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

You can run an unlimited number of jobs as long as you are within the workflow usage limits. For more information, see "Usage limits."

This example creates a matrix of three jobs, setting the node variable to a different value for each and using that variable as input to the setup-node action. As a result, each job will use a different node version.

strategy:
  matrix:
    node: [6, 8, 10]
steps:

- uses: actions/setup-node@v1
  with:
    node-version: ${{ matrix.node }}

You could also run those jobs in two different Linux versions, using a matrix variable as input to the runs-on specifier, to create a total of 6 jobs (3 node versions x 2 Linux versions).

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    node: [6, 8, 10]
    os: [ubuntu-16.04, ubuntu-18.04]
steps:

- uses: actions/setup-node@v1
  with:
    node-version: ${{ matrix.node }}

To find supported configuration options for a GitHub virtual environment, see "Virtual environments for GitHub Actions."

includeおよびexcludeオプションを使用すると、ジョブの実行をマトリクスにおける設定のサブセットに限定することができます。

ジョブの数は、 included in the arrays you provide along with any 加算 (include) または減算 (exclude) とともに指定する配列に含まれるバージョンの数の外積です。

strategy:
  matrix:
    node: [4, 6, 8, 10]
    os: [macOS-10.14, windows-2016, ubuntu-18.04]
    include:
      # includes a new variable of npm with a value of 2 for the matrix leg matching the os and version
    - os: windows-2016
      node: 4
      npm: 2
    exclude:
      # excludes node 4 on macOS
    - os: macos-10.14
      node: 4

includeリストを使って、必要な組み合わせを詳細に指定することもできます。

strategy:
  matrix:
    include:
    - node: 4.0.0
      os: macOS-10.14
    - rvm: 6.0.0
      os: macOS-10.14
    - rvm: 8.0.0
      os: macOS-10.14

jobs.<job_id>.strategy.fail-fast

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

jobs.<job_id>.strategy.max-parallel

matrixジョブ戦略を使用するとき、同時に実行できるジョブの最大数。 By default, GitHub will maximize the number of jobs run in parallel depending on the available runners on GitHub-hosted virtual machines.

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が自動的にネットワークを作成し、サービスコンテナのライフサイクルを管理します。

GitHub ActionsのアウトバウンドトラフィックのIPアドレスのリストは動的です。 GitHubは、使用可能なIPアドレスの一貫したリストを提供していません。

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

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のオプション」を参照してください。

担当者にお尋ねください

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

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