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

ワークフローを設定する

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

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

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

本記事の内容:

ワークフローについて

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

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

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

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

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

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

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

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

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

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

  1. リポジトリのルートで、.github/workflowsという新しいディレクトリに、ワークフローの新しい.ymlファイルを作成します。 たとえば、.github/workflows/continuous-integration-workflow.ymlとなります。

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

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

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

name: Greet Everybody
# 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:

    - uses: actions/checkout@v1
    # This step uses the hello-world-action stored in this workflow's repository.
    - uses: ./hello-world-action
      with:
        who-to-greet: 'Octocat'
      id: hello
    # This step prints the time.
    - run: echo "The time was ${{ steps.hello.outputs.time }}"

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

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

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

name: descriptive-workflow-name
on: push

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

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

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

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

特定のブランチをフィルタリングする

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

たとえば次のワークフローは、masterブランチでプッシュがあったときに実行されます。

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

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

仮想環境の選択

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

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

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

仮想ホストマシン

Ubuntu、Linux、macOSなど、タイプとバージョンの異なる仮想ホストマシンを選択できます。 ワークフローの各ジョブは同じ仮想環境で実行されるので、ファイルシステムを使用して、そのジョブにおける複数のアクションで情報を共有することが可能です。

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

runs-on: ubuntu-18.04

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

ビルドマトリクスの設定

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

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

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

strategy:
  matrix:
    node: [6, 8, 10]
    os: [ubuntu-14.04, ubuntu-18.04]

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

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

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

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

<br />- uses: actions/checkout@v1

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

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

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

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

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

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

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

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

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

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

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

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

プライベートリポジトリで定義されているアクションを使用するには、ワークフローファイルとそのアクションが同じリポジトリになければなりません。 同じ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の構文を使用して参照することができます。

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

.github
└── workflows
    └── my-first-workflow.yml
.
└── 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: ./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のワークフローworkflow、またはDockerアクションの理リポジトリを参照してください。

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

参考リンク

担当者にお尋ねください

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

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