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

ワークフローを設定する

リポジトリへの書き込みまたは管理者権限がある場合は、リポジトリのワークフローを作成、表示および編集できます。 ワークフローに含めるアクションの種類に応じて、ワークフローの設定をカスタマイズできます。

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

ワークフローについて

ワークフローとは、GitHubで任意のプロジェクトをビルド、テスト、パッケージ、リリース、またはデプロイするためにリポジトリで設定できる、カスタムの自動プロセスです。 ワークフローを使用すると、豊富なツールとサービスでソフトウェア開発のライフサイクルを自動化できます。 詳細については、「GitHub Actionsについて」を参照してください。

1つのリポジトリに複数のワークフローを作成できます。 ワークフローは、リポジトリのルートにある.github/workflowsディレクトリに保存する必要があります。

ワークフローには、少なくと1つのジョブが必要であり、ジョブには個々のタスクを実行する一連のステップが含まれます。 ステップでは、コマンドを実行するか、アクションを使用することができます。 独自のアクションを作成することも、GitHubコミュニティで共有されているアクションを使用し、必要に応じてカスタマイズすることもできます。

ワークフローは、GitHubイベントの発生時や、スケジュールに応じて、または外部イベントから開始することができます。

ワークフローは YAML 構文で設定し、リポジトリ内にワークフローファイルとして保存する必要があります。 YAMLワークフローファイルの作成に成功し、ワークフローをトリガーすると、ワークフローの各ステップのビルドログ、テスト結果、アーチファクト、およびステータスが表示されます。 詳細については、「ワークフロー実行の管理」を参照してください。

アノテーションされたワークフローの実行イメージ

ワークフローステータスの更新についても通知を受け取ることができます。 通知オプションの詳細については、「通知の配信方法を選択する」を参照してください。

個々のワークフローには、使用制限が適用されます。 詳しい情報については、「ワークフローの使用制限」を参照してください。

ワークフローファイルの作成

大まかに言うと、ワークフローファイルを追加する手順は以下のとおりです。 これ以降の各セクションに、個々の設定例があります。

  1. リポジトリのルートに、ワークフローファイルを保存するため、 .github/workflows という名前のディレクトリを作成します。

  2. .github/workflows に、ワークフローのため .yml または .yaml ファイルを追加します。 たとえば、.github/workflows/continuous-integration-workflow.ymlとなります。

  3. GitHub Actionsのワークフロー構文」リファレンスドキュメントを使用して、アクションをトリガーするイベント選択し、アクションを追加して、ワークフローをカスタマイズします。

  4. ワークフローでの変更を、ワークフローを実行するブランチにコミットします。

ワークフローファイルの例

name: Greet Everyone
# This workflow is triggered on pushes to the repository.
on: [push]

jobs:
  build:
    # Job name is Greeting
    name: Greeting
    # This job runs on Linux
    runs-on: ubuntu-latest
    steps:
      # This step uses GitHub's hello-world-javascript-action: https://github.com/actions/hello-world-javascript-action
      - name: Hello world
        uses: actions/hello-world-javascript-action@v1
        with:
          who-to-greet: 'Mona the Octocat'
        id: hello
      # This step prints an output (time) from the previous step's action.
      - name: Echo the greeting's time
        run: echo 'The time was ${{ steps.hello.outputs.time }}.'

イベントでワークフローをトリガーする

ワークフローは、次の条件で開始するように設定できます。

  • GitHub でイベントの発生時。例えば、リポジトリにコミットをプッシュするときや、Issueまたはプルリクエストが作成されるときなど。
  • スケジュールしたイベントの開始時。
  • 外部イベントの発生時。

GitHubでイベントが発生した後でワークフローをトリガーするには、ワークフロー名に続けて、on:とイベント値を追加します。 たとえば次のワークフローは、リポジトリのブランチに変更がプッシュされるときにトリガーされます。

name: descriptive-workflow-name
on: push

ワークフローをスケジュールするときは、ワークフローファイルで POSIX cron 構文を使用できます。 The shortest interval you can run scheduled workflows is once every 5 minutes. たとえば、次のワークフローは毎時間トリガーされます。

on:
  schedule:
    - cron:  '0 * * * *'

外部イベントの発生後にワークフローをトリガーするには、REST API エンドポイントの「リポジトリディスパッチイベントの作成」を呼び出すことにより repository_dispatch webhook イベントを起動できます。 詳しい情報については、GitHub 開発者ドキュメンテーション の「リポジトリディスパッチイベントの作成」を参照してください。

詳細と例については、「ワークフローをトリガーするイベント」を参照してください。

特定のブランチ、タグ、およびパスをフィルタリングする

ワークフローは、特定のブランチでのみ実行するように設定できます。

たとえば、このワークフローは test ディレクトリにあるファイルを含むプッシュが master ブランチで作成されたか、v1 タブにプッシュした場合に実行されます。

on:
  push:
    branches:
      - master
    tags:
      - v1
    # file paths to consider in the event. Optional; defaults to all.
    paths:
      - 'test/*'

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

仮想環境の選択

ワークフローは、GitHubにホストされた仮想環境で、またはDockerコンテナで実行できます。 ワークフローのジョブごとに仮想環境を指定することが可能です。

ワークフローを実行する仮想環境のオペレーティングシステム、ツール、パッケージ、および設定を指定するには、ワークフローファイルで特殊な構文を使用する必要があります。

詳細については、「GitHub Actionsの仮想環境」を参照してください。

仮想ホストマシン

You can select from different types and versions of virtual host machines, including Linux, Windows, and macOS. ワークフローの各ジョブは同じ仮想環境で実行されるので、ファイルシステムを使用して、そのジョブにおける複数のアクションで情報を共有することが可能です。

仮想環境の新しいインスタンスでジョブを実行するときは、ジョブで実行する仮想ホストを指定できます。

runs-on: ubuntu-18.04

サポートされるバージョンなどの詳細については、「GitHub Actionsのワークフロー構文」を参照してください。

ビルドマトリクスの設定

複数のオペレーティングシステム、プラットフォーム、言語バージョンにまたがって同時にテストするときは、ビルドマトリクスを設定できます。

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

ワークフローのビルドマトリクスは、strategy:にある設定オプションのリストの配列で指定できます。 たとえば次のビルドマトリクスは、バージョンの異なるNode.jsおよびUbuntuのLinux OSでジョブを実行します。

オペレーティングシステムのマトリクスを定義する際には、現在のジョブのオペレーティングシステムにはオペレーティングシステム名をハードコーディングするのではなく、必須のruns-onキーワードを設定しなければなりません。オペレーティングシステム名にアクセスするには、コンテキストパラメータのmatrix.osを使ってruns-onを設定できます。詳しい情報については「GitHub Actionsのコンテキストと式構文」を参照してください。

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

詳細については、「GitHub Actionsのワークフロー構文」を参照してください。

チェックアウトアクションの使用

ワークフローで使用できる標準アクションがいくつか用意されています。 チェックアウトアクションは、次の場合に、ワークフローで他のアクションより前に含める必要がある標準のアクションです。

  • リポジトリをビルドしてテストするとき、または継続的インテグレーションを使用するとき、ワークフローにリポジトリのコードのコピーが必要な場合。
  • 同じリポジトリで定義されているアクションが、ワークフローに1つ以上ある場合。 詳細については、「ワークフローでアクションを参照する」を参照してください。ワークフロー

他に何も指定せず、標準的なチェックアウトアクションを使用するには、以下のステップを含めます:

- uses: actions/checkout@v1

この例では、v1 を使用することにより、チェックアウトアクションの安定版を確実に使用するようにしています。

リポジトリを shallow clone する、すなわちリポジトリの最新版のみをコピーする場合、with 構文に fetch-depth を設定します:

- uses: actions/checkout@v1
  with:
    fetch-depth: 1

詳細については、「チェックアウトアクション」を参照してください。

ワークフローのアクションの種類を設定する

プロジェクトの必要に応じて、ワークフローでは次のようなアクションを使用できます。

  • Dockerコンテナのアクション
  • JavaScriptのアクション

詳細については、「アクションについて」を参照してください。

ワークフローで使用するアクションの種類を選択する際には、パブリックリポジトリまたはDockerハブで既存のアクションを確認し、場合によってはプロジェクトに応じてそれをカスタマイズすることをお勧めします。

github.com/actions Organizationで、GitHubによってビルドされたアクションを参照して使用することができます。 Docker Hubへのアクセスについては、Dockerサイトで「Docker Hub」を参照してください。

ワークフローでアクションを参照する

正しい構文を使用してワークフローファイルでアクションを参照するには、そのアクションをどこに定義するかを考慮する必要があります。

ワークフローを定義できる場所は次のとおりです。

  • パブリックリポジトリ
  • ワークフローファイルがアクションを参照するのと同じリポジトリ
  • Dockerハブで公開されているDockerコンテナイメージ

プライベートリポジトリで定義されているアクションを使用するには、ワークフローファイルとそのアクションが同じリポジトリになければなりません。 同じOrganizationにある場合でも、他のリポジトリで定義されているアクションは、ワークフローで使用できません。

アクションに対して更新がある場合でもワークフローの安定を保つには、ワークフローファイルでGit refまたはDockerタグを指定して、使用しているアクションのバージョンを参照します。 例については、「GitHub Actionsのワークフロー構文」を参照してください。

設定オプションの詳細については、「GitHub Actionsのワークフロー構文」を参照してください。

パブリックリポジトリからアクションを参照する

アクションがパブリックリポジトリで定義されている場合には、{owner}/{repo}@{ref}または {owner}/{repo}/{path}@{ref}の構文を使用してそのアクションを参照する必要があります。

jobs:
  my_first_job:
    name: My Job Name
      steps:
        - uses: actions/setup-node@v1
          with:
            node-version: 10.x

ワークフローの詳細な例については、setup nodeテンプレートリポジトリを参照してください。

ワークフローファイルがアクションを使用するのと同じリポジトリにあるアクションを参照する

ワークフローファイルがアクションを使用するのと同じリポジトリに定義されているアクションは、ワークフローファイルで{owner}/{repo}@{ref}または./path/to/dirの構文を使用して参照することができます。

リポジトリファイル構造の例:

|-- hello-world (repository)
|   |__ .github
|       └── workflows
|           └── my-first-workflow.yml
|       └── actions
|           |__ hello-world-action
|               └── action.yml

ワークフローファイルの例:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # This step checks out a copy of your repository.
      - uses: actions/checkout@v1
      # This step references the directory that contains the action.
      - uses: ./.github/actions/hello-world-action

Dockerハブのコンテナを参照する

Dockerハブで公開されているDockerコンテナイメージで定義されているアクションは、ワークフローファイルのdocker://{image}:{tag}構文を使用して参照する必要があります。 コードとデータを保護するには、ワークフローで使用する前にDocker HubからのDockerコンテナイメージの整合性を確認してください。

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

For some examples of Docker actions, see the Docker-image.yml workflow and "Creating a Docker container action."

詳細については、「GitHub Actionsのワークフロー構文」を参照してください。

ワークフローのステータスバッジをリポジトリに追加する

ステータスバッジは、ワークフローが現在失敗しているかパスしているかを示します。 ステータスバッジを追加する一般的な場所は、リポジトリのREADME.mdファイル中ですが、任意の好きなWebページに追加できます。 デフォルトでは、バッジはデフォルトブランチ(通常はmaster)のステータスを表示します。 特定のブランチやイベントに対するワークフローの実行のステータスを、URL中のbranch及びeventクエリパラメータを使って表示することもできます。

ワークフローがnameキーワードを使用している場合、ワークフローを名前で参照できます。 ワークフローの名前に空白文字が含まれている場合、その文字をURLエンコードした文字列「%20」に置換する必要があります。 name キーワードに関する詳しい情報については、「"GitHub Actionsのためのワークフローの構文」を参照してください。

https://github.com/<OWNER>/<REPOSITORY>/workflows/<WORKFLOW_NAME>/badge.svg

ワークフローにnameがない場合、リポジトリのルートディレクトリへの相対パスを使用して、ワークフローファイルを参照できます。

https://github.com/<OWNER>/<REPOSITORY>/workflows/<WORKFLOW_FILE_PATH>/badge.svg

ワークフロー名の使用例

This Markdown example adds a status badge for a workflow with the name "Greet Everyone." The OWNER of the repository is the actions organization and the REPOSITORY name is hello-world.

![](https://github.com/actions/hello-world/workflows/Greet%20Everyone/badge.svg)

ワークフローのファイルパスの例

This Markdown example adds a status badge for a workflow with the file path .github/workflows/main.yml. リポジトリのOWNERactions Organizationで、REPOSITORY名はhello-worldです。

![](https://github.com/actions/hello-world/workflows/.github/workflows/main.yml/badge.svg)

Example using the branch parameter

This Markdown example adds a status badge for a branch with the name feature-1.

![](https://github.com/actions/hello-world/workflows/Greet%20Everyone/badge.svg?branch=feature-1)

Example using the event parameter

This Markdown example adds a badge that displays the status of workflow runs triggered by the pull_request event.

![](https://github.com/actions/hello-world/workflows/Greet%20Everyone/badge.svg?event=pull_request)

参考リンク

担当者にお尋ねください

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

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