ワークフローについて

ワークフローについて

A workflow is a configurable automated process that will run one or more jobs. Workflows are defined by a YAML file checked in to your repository and will run when triggered by an event in your repository, or they can be triggered manually, or at a defined schedule.

Workflows are defined in the .github/workflows directory in a repository, and a repository can have multiple workflows, each of which can perform a different set of tasks. For example, you can have one workflow to build and test pull requests, another workflow to deploy your application every time a release is created, and still another workflow that adds a label every time someone opens a new 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

Workflow triggers are events that cause a workflow to run. These events can be:

• Events that occur in your workflow's repository
• Events that occur outside of GitHub Enterprise Server and trigger a repository_dispatch event on GitHub Enterprise Server
• Scheduled times
• Manual

For example, you can configure your workflow to run when a push is made to the default branch of your repository, when a release is created, or when an issue is opened.

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 uses YAML syntax to define the workflow. Each workflow is stored as a separate YAML file in your code repository, in a directory named .github/workflows.

コードがプッシュされるたびに一連のコマンドを自動的にトリガーするサンプルワークフローをリポジトリに作成できます。 In this workflow, GitHub Actions checks out the pushed code, installs the bats testing framework, and runs a basic command to output the bats version: bats -v.

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 ワークフローファイルがリポジトリにインストールされ、別のユーザがリポジトリに変更をプッシュするたびに自動的に実行されます。 To see the details about a workflow's execution history, see "Viewing the activity for a workflow run."

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

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

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

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

この図では、作成したワークフローファイルと、GitHub Actions コンポーネントが階層にどのように整理されているかを確認できます。 Each step executes a single action or shell script. Steps 1 and 2 run actions, while steps 3 and 4 run shell scripts. ワークフローのビルド済みアクションの詳細については、「アクションの検索とカスタマイズ」を参照してく� さい。

Viewing the activity for a workflow run

When your workflow is triggered, a workflow run is created that executes the workflow. After a workflow run has started, you can see a visualization graph of the run's progress and view each step's activity on GitHub.

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

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

   

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

   

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

   

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

   

6. View the results of each step.

   

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

Using starter workflows

GitHub provides preconfigured starter workflow that you can customize to create your own continuous integration workflow. GitHub Enterprise Server analyzes your code and shows you CI starter workflow that might be useful for your repository. たとえばリポジトリにNode.jsのコードが含まれているなら、Node.jsプロジェクトのためのサジェッションが提示されます。 You can use starter workflow as a starting place to build your custom workflow or use them as-is.

You can browse the full list of starter workflow in the actions/starter-workflows repository on GitHub Enterprise Serverインスタンス.

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.

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

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

A matrix strategy lets you use variables in a single job definition to automatically create multiple job runs that are based the combinations of the variables. For example, you can use a matrix strategy to test your code in multiple versions of a language or on multiple operating systems. 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つの環境を参照できます。 この環境を参照するとジョブがランナーに送信される前に、環境に設定された保護ルールをパスしなければなりません。 For more information, see "Using environments for deployment."