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

ワークフローを設定する

プロジェクトのソフトウェア開発ライフサイクルのプロセスを自動化するためのカスタムワークフローを作成できます。

GitHub ActionsはGitHub Free、GitHub Pro、GitHub FreeのOrganization、GitHub Team、GitHub Enterprise Cloud、GitHub Oneで利用できます。 GitHub Actionsは、レガシーのリポジトリごとのプランを使っているアカウントが所有しているプライベートリポジトリでは利用できません。 詳しい情報については「GitHubの製品」を参照してください。

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

リポジトリに対する書き込みもしくは管理権限を持つ人は、ワークフローの作成、編集、閲覧ができます。

ワークフローについて

ワークフローとは、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/workflowsに不正なワークフローファイルが含まれていると、GitHub Actionsは新規のコミットのたびに失敗するワークフローの実行を生成します。

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

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

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

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

name: descriptive-workflow-name
on: push

ワークフローをスケジュールするときは、ワークフローファイルで POSIX cron 構文を使用できます。 スケジュールされたワークフローを実行できる最短のインターバルは5分ごとです。 たとえば、次のワークフローは毎時間トリガーされます。

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

Manually running a workflow

To manually run a workflow, you must first configure your workflow to use the workflow_dispatch event. You can configure custom-defined input properties, default input values, and required inputs directly in your workflow. When the workflow runs, you can access the input values in the github.event.inputs context. For more information, see "Events that trigger workflows" and "Context and expression syntax for GitHub Actions."

This example defines the name and home inputs and prints them using the github.event.inputs.name and github.event.inputs.home contexts. If a name isn't provided, the default value 'Mona the Octocat' is printed.

name: Manually triggered workflow
on:
  workflow_dispatch:
    inputs:
      name:
        description: 'Person to greet'
        required: true
        default: 'Mona the Octocat'
      home:
        description: 'location'
        required: false

jobs:
  say_hello:
    runs-on: ubuntu-latest
    steps:
    - run: |
        echo "Hello ${{ github.event.inputs.name }}!"
        echo "- in ${{ github.event.inputs.home }}!"

You can trigger the workflow_dispatch event from the Actions tab on GitHub or using the REST API. For more information about using the REST API, see the "Create a workflow dispatch event." When using the REST API, you configure the inputs and ref as request body parameters. If the inputs are omitted, the default values defined in the workflow file are used.

To trigger the workflow_dispatch event on GitHub, your workflow must be in the default branch. Follow these steps to manually trigger a workflow run.

  1. GitHubで、リポジトリのメインページにアクセスしてください。
  2. リポジトリ名の下でActions(アクション)をクリックしてください。
    メインのリポジトリナビゲーション内のアクションタブ
  3. In the left sidebar, click the workflow you want to run.
    actions select workflow
  4. Above the list of workflow runs, select Run workflow.
    actions workflow dispatch
  5. Select the branch where the workflow will run and type the input parameters used by the workflow. Click Run workflow.
    actions manually run workflow

Triggering workflows from external events

外部イベントの発生後にワークフローをトリガーするには、REST API エンドポイントの「リポジトリディスパッチイベントの作成」を呼び出すことにより repository_dispatch webhook イベントを起動できます。 For more information, see "Create a repository dispatch event."

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

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

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

たとえば、このワークフローは 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コンテナで実行することもできます。

ワークフロー内のそれぞれのジョブのランナーは、runs-onを使って指定できます。 runs-on の詳細については、「GitHub Actionsのためのワークフローの構文」を参照してください。

GitHubホストランナーの利用

Linux、Windows、macOSなど、タイプとバージョンの異なる仮想ホストマシンを選択できます。 ワークフロー内の各ジョブは仮想環境の新しいインスタンスで実行され、1つのジョブ内のステップはファイルシステムを使って情報を共有できます。 詳しい情報については「GitHub Actionsホストランナーの仮想環境」を参照してください。

たとえばubuntu-latestを使い、最新バージョンのUbuntu GitHubホストランナーを指定できます。

runs-on: ubuntu-latest

セルフホストランナーの利用

ジョブを特定の種類のセルフホストランナーにまわすために、ラベルを利用できます。 すべてのセルフホストランナーにはself-hostedというラベルが付けられ、それぞれのセルフホストランナーにはそのオペレーティングシステムとシステムのアーキテクチャに応じたラベルが付けられます。 詳しい情報については「ワークフロー内でのセルフホストランナーの利用」を参照してください。

たとえばオペレーティングシステムがLinuxでARM32アーキテクチャのセルフホストランナーを追加したなら、そのランナーはself-hostedlinuxARM32といラベルを使って選択できます。

runs-on: [self-hosted, linux, ARM32]

ビルドマトリクスの設定

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

ビルドマトリクスを利用すれば、コードを様々なソフトウェアやオペレーティングシステムの構成でテストできます。 たとえば、1つの言語、オペレーティングシステム、またはツールについてサポートされている複数のバージョンに対して、1つのワークフローで1つのジョブを実行できます。 設定ごとにジョブのコピーが実行され、ステータスがレポートされます。

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

オペレーティングシステムのマトリックスを定義する際には、runs-onの値を、定義したmatrix.osコンテキストのプロパティに設定しなければなりません。

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

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

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

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

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

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

- uses: actions/checkout@v2

この例では、v2 を使用することにより、チェックアウトアクションの安定版を確実に使用するようにしています。 詳細については、「チェックアウトアクション」を参照してください。

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

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

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

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

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

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

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

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

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

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

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

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

ワークフローに追加したアクションに対してGitHub Dependabotバージョンアップデートを有効化することもできます。 For more information, see "Keeping your actions up to date with GitHub Dependabot."

設定オプションのさらなる詳細については、「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@v2
      # 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

Dockerアクションの例については、Docker-image.ymlのワークフロー及び「Dockerコンテナのアクションの作成」を参照してください。

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

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

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

example status badge

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

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

あるいは、ワークフローにnameがない場合、リポジトリのルートディレクトリへの相対パスを使用してワークフローファイルを参照しなければなりません。

ノート: ワークフローがnameを持っている場合は、ファイルパスを使ったワークフローファイルの参照はできません。

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

ワークフロー名の使用例

このMarkdownの例では、「Greet Everyone」という名前のワークフローにステータスバッジを追加しています。リポジトリのOWNERactions Organizationで、REPOSITORY名はhello-worldです。

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

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

このMarkdownの例では、ファイルパスが.github/workflows/main.ymlであるワークフローにステータスバッジを追加しています。 リポジトリのOWNERactions Organizationで、REPOSITORY名はhello-worldです。

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

branchパラメータの使用例

このMarkdownの例は、feature-1という名前のブランチにステータスバッジを追加しています。

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

eventパラメータの使用例

このMarkdownの例は、pull_requestイベントで起動されたワークフローの実行のステータスを表示するバッジを追加します。

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

参考リンク

担当者にお尋ねください

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

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