Skip to main content

ワークフローについて

Get a high level overview GitHub Actions workflows, including triggers, syntax, and advanced features.

ワークフローについて

ワークフローは、1つ以上のジョブを実行する設定可能な自動化されたプロセスです。 ワークフローはリポジトリにチェックインされるYAMLファイルで定義され、リポジトリ内のイベントでトリガーされるか、手動でトリガーされるか、定義されたスケジュールに従って実行されます。

ワークフローはリポジトリ中の.github/workflowsディレクトリで定義され、1つのリポジトリに複数のワークフローを持たせ、それぞれが様々なタスクのセットを実行するようにできます。 たとえば、1つのワークフローでPull Requestのビルドとテストを行い、他のワークフローでリリースが作成されるたびにアプリケーションをデプロイし、また別のワークフローで誰かが新しいIssueがオープンするたびにラベルを追加するといったことができます。

Workflow basics

A workflow must contain the following basic components:

  1. One or more events that will trigger the workflow.
  2. One or more jobs, each of which will execute on a runner machine and run a series of one or more steps.
  3. Each step can either run a script that you define or run an action, which is a reusable extension that can simplify your workflow.

For more information on these basic components, see "Understanding GitHub Actions."

ワークフローの概要

Triggering a workflow

ワークフロートリガーは、ワークフローの実行を引き起こすイベントです。 それらのイベントには以下のようなものがあります。

  • ワークフローのリポジトリ内で発生するイベント
  • GitHub Enterprise Serverの外部で発生し、GitHub Enterprise Server上でrepository_dispatchをトリガーするイベント
  • スケジュールされた時刻
  • 手動

たとえば、リポジトリのデフォルトブランチにプッシュが行われたときや、リリースが作成されたときや、Issueがオープンされたときにワークフローが実行されるように設定できます。

For more information, see "Triggering a workflow", and for a full list of events, see "Events that trigger workflows."

ワークフロー構文

Workflow are defined using YAML. For the full reference of the YAML syntax for authoring workflows, see "Workflow syntax for GitHub Actions."

サンプルワークフローを作成する

GitHub Actionsはワークフローの定義にYAMLの構文を使います。 各ワークフローはコードリポジトリ中の.github/workflowsというディレクトリに個別のYAMLファイルとして保存されます。

コードがプッシュされるたびに一連のコマンドを自動的にトリガーするサンプルワークフローをリポジトリに作成できます。 このワークフローでは、GitHub Actionsはプッシュされたコードをチェックアウトし、batsテスティングフレームワークをインストールし、bats -vというbatsのバージョンを出力するための基本的なコマンドを実行します。

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

  2. .github/workflows/ ディレクトリに、learn-github-actions.yml という名前の新しいファイルを作成し、次のコードを追加します。

    name: learn-github-actions
    on: [push]
    jobs:
      check-bats-version:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v2
          - uses: actions/setup-node@v2
            with:
              node-version: '14'
          - run: npm install -g bats
          - run: bats -v
    
  3. これらの変更をコミットして、GitHub リポジトリにプッシュします。

これで、新しい GitHub Actions ワークフローファイルがリポジトリにインストールされ、別のユーザがリポジトリに変更をプッシュするたびに自動的に実行されます。 ワークフローの実行履歴に関する詳細を見るには、「ワークフローの実行のアクティビティの表示」を参照してください。

ワークフローファイルを理解する

YAML 構文を使用してワークフローファイルを作成する方法を理解しやすくするために、このセクションでは、導入例の各行について説明します。

name: learn-github-actions
オプション - GitHub リポジトリの [Actions] タブに表示されるワークフローの名前。
on: [push]
このワークフローのトリガーを指定します。 この例はpushイベントを使っているので、ワークフローの実行は誰かが変更をリポジトリにプッシュするか、Pull Requestをマージするたびにトリガーされます。 これは、すべてのブランチに対するプッシュによってトリガーされます。特定のブランチ、パス、タグへのプッシュでのみ実行するための構文の例については「GitHub Actionsのワークフロー構文」を参照してください。
jobs:
learn-github-actionsワークフロー中で実行されるすべてのジョブをグループ化します。
check-bats-version:
check-bats-versionという名前のジョブを定義します。 子キーはジョブのプロパティを定義します。
  runs-on: ubuntu-latest
Ubuntu Linuxランナーの最新バージョンで実行されるよう、ジョブを設定します。 これは、ジョブが GitHub によってホストされている新しい仮想マシンで実行されるということです。 他のランナーを使う構文の例については「GitHub Actionsのワークフロー構文」を参照してください。
  steps:
check-bats-version ジョブで実行されるすべてのステップをグループ化します。 このセクションの下にネストされている各アイテムは、個別のアクションもしくはシェルスクリプトです。
    - uses: actions/checkout@v2
uses キーワードは、このステップがactions/checkoutアクションのv3を実行することを指定しています。 これは、リポジトリをランナーにチェックアウトするアクションで、コードに対してスクリプトや他のアクション(ビルドやテストツールなど)を実行できるようにしてくれます。 ワークフローがリポジトリのコードに対して実行されるときには、いつでもチェックアウトのアクションを使うべきです。
    - uses: actions/setup-node@v2
      with:
        node-version: '14'
このステップはactions/setup-node@v2アクションを使ってNode.jsの指定されたバージョンをインストールします(この例ではv14が使われます)。 これは、node及びnpmコマンドをどちらもPATHに置きます。
    - run: npm install -g bats
run キーワードは、ランナーでコマンドを実行するようにジョブに指示します。 この場合、npm を使用して bats ソフトウェアテストパッケージをインストールしています。
    - run: bats -v
最後に、ソフトウェアバージョンを出力するパラメータを指定して bats コマンドを実行します。

ワークフローファイルの視覚化

この図では、作成したワークフローファイルと、GitHub Actions コンポーネントが階層にどのように整理されているかを確認できます。 それぞれのステップは、1つのアクションもしくはシェルスクリプトを実行します。 ステップ1と2はアクションを実行しますが、ステップ3と4はシェルスクリプトを実行します。 ワークフローのビルド済みアクションの詳細については、「アクションの検索とカスタマイズ」を参照してください。

ワークフローの概要

ワークフローの実行のアクティビティの表示

ワークフローがトリガーされると、ワークフローを実行するワークフローの実行が生成されます。 ワークフローの実行が開始されると、実行の進行の可視化グラフを見ることができ、GitHub上の各ステップのアクティビティを表示できます。

  1. GitHub Enterprise Serverインスタンスで、リポジトリのメインページにアクセスしてください。

  2. リポジトリ名の下でActions(アクション)をクリックしてください。

    リポジトリに移動

  3. 左のサイドバーで、表示させたいワークフローをクリックしてください。

    ワークフロー結果のスクリーンショット

  4. "Workflow runs(ワークフローの実行)"の下で、表示させたい実行の名前をクリックしてください。

    ワークフロー実行のスクリーンショット

  5. [Jobs] または視覚化グラフで、表示するジョブをクリックします。

    ジョブを選択

  6. 各ステップの結果を表示させます。

    ワークフロー実行の詳細のスクリーンショット

For more on managing workflow runs, such as re-running, cancelling, or deleting a workflow run, see "Managing workflow runs."

Using starter workflows

GitHubは事前設定されたスターターワークフローを提供します。これは、カスタマイズして独自の継続的インテグレーションワークフローを作成できます。 GitHub Enterprise Serverはコードを分析し、リポジトリで役に立つであろうCIスターターワークフローを提示します。 たとえばリポジトリにNode.jsのコードが含まれているなら、Node.jsプロジェクトのためのサジェッションが提示されます。 スターターワークフローは、カスタムワークフローを構築するための出発点として使うことも、あるいはそのまま使うこともできます。

スターターワークフローの完全なリストは、GitHub Enterprise Serverインスタンス上のactions/starter-workflowsリポジトリで閲覧できます。

For more information on using and creating starter workflows, see "Using starter workflows" and "Creating starter workflows for your organization."

Advanced workflow features

This section briefly describes some of the advanced features of GitHub Actions that help you create more complex workflows.

シークレットを保存する

ワークフローでパスワードや証明書などの機密データを使用する場合は、これらを GitHub に secrets として保存すると、ワークフローで環境変数として使用できます。 This means that you will be able to create and share workflows without having to embed sensitive values directly in the workflow's YAML source.

This example job demonstrates how to reference an existing secret as an environment variable, and send it as a parameter to an example command.

jobs:
  example-job:
    runs-on: ubuntu-latest
    steps:
      - name: Retrieve secret
        env:
          super_secret: ${{ secrets.SUPERSECRET }}
        run: |
          example-command "$super_secret"

For more information, see "Encrypted secrets."

依存ジョブを作成する

デフォルトでは、ワークフロー内のジョブはすべて同時並行で実行されます。 If you have a job that must only run after another job has completed, you can use the needs keyword to create this dependency. If one of the jobs fails, all dependent jobs are skipped; however, if you need the jobs to continue, you can define this using the if conditional statement.

この例では、setupbuild、および test ジョブが連続して実行され、buildtest は、それらに先行するジョブが正常に完了したかどうかに依存します。

jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - run: ./setup_server.sh
  build:
    needs: setup
    runs-on: ubuntu-latest
    steps:
      - run: ./build_server.sh
  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: ./test_server.sh

For more information, see "Defining prerequisite jobs."

Using a matrix

マトリックス戦略を使うと、単一のジョブ定義中で変数を使って、変数の組み合わせに基づく複数のジョブの実行を自動的に生成できます。 たとえばマトリックス戦略を使って、コードを言語の複数のバージョンや、複数のオペレーティングシステムでテストできます。 The matrix is created using the strategy keyword, which receives the build options as an array. For example, this matrix will run the job multiple times, using different versions of Node.js:

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: [12, 14, 16]
    steps:
      - uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.node }}

For more information, see "Using a matrix for your jobs."

データベースとサービスコンテナの利用

ジョブにデータベースまたはキャッシュサービスが必要な場合は、services キーワードを使用して、サービスをホストするための一時コンテナを作成できます。 この例は、ジョブが services を使用して postgres コンテナを作成し、node を使用してサービスに接続する方法を示しています。

jobs:
  container-job:
    runs-on: ubuntu-latest
    container: node:10.18-jessie
    services:
      postgres:
        image: postgres
    steps:
      - name: Check out repository code
        uses: actions/checkout@v2
      - name: Install dependencies
        run: npm ci
      - name: Connect to PostgreSQL
        run: node client.js
        env:
          POSTGRES_HOST: postgres
          POSTGRES_PORT: 5432

For more information, see "Using containerized services."

ラベルを使用してワークフローを転送する

特定のタイプのランナーがジョブを処理することを確認したい場合は、ラベルを使用してジョブの実行場所を制御できます。 You can assign labels to a self-hosted runner in addition to their default label of self-hosted. Then, you can refer to these labels in your YAML workflow, ensuring that the job is routed in a predictable way. GitHub-hosted runners have predefined labels assigned.

この例は、ワークフローがラベルを使用して必要なランナーを指定する方法を示しています。

jobs:
  example-job:
    runs-on: [self-hosted, linux, x64, gpu]

A workflow will only run on a runner that has all the labels in the runs-on array. The job will preferentially go to an idle self-hosted runner with the specified labels.

To learn more about self-hosted runner labels, see "Using labels with self-hosted runners."

環境の使用

You can configure environments with protection rules and secrets to control the execution of jobs in a workflow. ワークフロー内の各ジョブは、1つの環境を参照できます。 この環境を参照するとジョブがランナーに送信される前に、環境に設定された保護ルールをパスしなければなりません。 詳しい情報については「デプロイメントの環境の利用」を参照してください。