Skip to main content

About workflows

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

About workflows

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

ワークフローはリポジトリ内の .github/workflows ディレクトリで定義され、リポジトリには複数のワークフローを含めることができます。各ワークフローは、それぞれ異なる一連のタスクを実行できます。 たとえば、あるワークフローでは、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."

Workflow overview

Triggering a workflow

ワークフロー トリガーは、ワークフローの実行を引き起こすイベントです。 次のようなイベントがあります。

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

たとえば、リポジトリの既定のブランチに対してプッシュが行われたときや、リリースが作成されたとき、またはイシューが開かれたときに実行するようにワークフローを構成できます。

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

Workflow syntax

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

Create an example workflow

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.

You can create an example workflow in your repository that automatically triggers a series of commands whenever code is pushed. 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. In your repository, create the .github/workflows/ directory to store your workflow files.

  2. In the .github/workflows/ directory, create a new file called learn-github-actions.yml and add the following code.

    YAML
    name: learn-github-actions
    on: [push]
    jobs:
      check-bats-version:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v3
          - uses: actions/setup-node@v3
            with:
              node-version: '14'
          - run: npm install -g bats
          - run: bats -v
  3. Commit these changes and push them to your GitHub repository.

Your new GitHub Actions workflow file is now installed in your repository and will run automatically each time someone pushes a change to the repository. To see the details about a workflow's execution history, see "Viewing the activity for a workflow run."

Understanding the workflow file

To help you understand how YAML syntax is used to create a workflow file, this section explains each line of the introduction's example:

name: learn-github-actions
Optional - The name of the workflow as it will appear in the "Actions" tab of the GitHub repository.
on: [push]
Specifies the trigger for this workflow. This example uses the push event, so a workflow run is triggered every time someone pushes a change to the repository or merges a pull request. This is triggered by a push to every branch; for examples of syntax that runs only on pushes to specific branches, paths, or tags, see "Workflow syntax for GitHub Actions."
jobs:
Groups together all the jobs that run in the learn-github-actions workflow.
check-bats-version:
Defines a job named check-bats-version. The child keys will define properties of the job.
  runs-on: ubuntu-latest
Configures the job to run on the latest version of an Ubuntu Linux runner. This means that the job will execute on a fresh virtual machine hosted by GitHub. For syntax examples using other runners, see "Workflow syntax for GitHub Actions."
  steps:
Groups together all the steps that run in the check-bats-version job. Each item nested under this section is a separate action or shell script.
    - uses: actions/checkout@v3
The uses keyword specifies that this step will run v3 of the actions/checkout action. This is an action that checks out your repository onto the runner, allowing you to run scripts or other actions against your code (such as build and test tools). You should use the checkout action any time your workflow will run against the repository's code.
    - uses: actions/setup-node@v3
      with:
        node-version: '14'
This step uses the actions/setup-node@v3 action to install the specified version of the Node.js (this example uses v14). This puts both the node and npm commands in your PATH.
    - run: npm install -g bats
The run keyword tells the job to execute a command on the runner. In this case, you are using npm to install the bats software testing package.
    - run: bats -v
Finally, you'll run the bats command with a parameter that outputs the software version.

Visualizing the workflow file

In this diagram, you can see the workflow file you just created and how the GitHub Actions components are organized in a hierarchy. Each step executes a single action or shell script. Steps 1 and 2 run actions, while steps 3 and 4 run shell scripts. To find more prebuilt actions for your workflows, see "Finding and customizing actions."

Workflow overview

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. your GitHub Enterprise Server instance で、リポジトリのメイン ページへ移動します。

  2. Under your repository name, click Actions.

    Navigate to repository

  3. In the left sidebar, click the workflow you want to see.

    Screenshot of workflow results

  4. Under "Workflow runs", click the name of the run you want to see.

    Screenshot of workflow runs

  5. Under Jobs or in the visualization graph, click the job you want to see.

    Select job

  6. View the results of each step.

    Screenshot of workflow run details

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プロジェクトのためのサジェッションが提示されます。 スターター ワークフローは、カスタム ワークフローの構築の出発点として利用することも、そのまま利用することもできます。

スターター ワークフローの完全なリストは、 your GitHub Enterprise Server instance の 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.

Storing secrets

If your workflows use sensitive data, such as passwords or certificates, you can save these in GitHub as secrets and then use them in your workflows as environment variables. 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."

Creating dependent jobs

By default, the jobs in your workflow all run in parallel at the same time. 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.

In this example, the setup, build, and test jobs run in series, with build and test being dependent on the successful completion of the job that precedes them:

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

マトリックス戦略を使用すると、1 つのジョブ定義で変数を使用して、変数の組み合わせに基づく複数のジョブ実行を自動的に作成できます。 たとえば、マトリックス戦略を使用して、複数バージョンの言語または複数のオペレーティング システムでコードをテストできます。 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@v3
        with:
          node-version: ${{ matrix.node }}

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

Caching dependencies

If your jobs regularly reuse dependencies, you can consider caching these files to help improve performance. Once the cache is created, it is available to all workflows in the same repository.

This example demonstrates how to cache the ~/.npm directory:

jobs:
  example-job:
    steps:
      - name: Cache node modules
        uses: actions/cache@v3
        env:
          cache-name: cache-node-modules
        with:
          path: ~/.npm
          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-build-${{ env.cache-name }}-

For more information, see "Caching dependencies to speed up workflows."

Using databases and service containers

If your job requires a database or cache service, you can use the services keyword to create an ephemeral container to host the service; the resulting container is then available to all steps in that job and is removed when the job has completed. This example demonstrates how a job can use services to create a postgres container, and then use node to connect to the service.

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@v3
      - 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."

Using labels to route workflows

If you want to be sure that a particular type of runner will process your job, you can use labels to control where jobs are executed. 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.

This example shows how a workflow can use labels to specify the required runner:

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."

Reusing workflows

You can share workflows with your organization, publicly or privately, by calling one workflow from within another workflow. This allows you to reuse workflows, avoiding duplication and making your workflows easier to maintain. For more information, see "Reusing workflows."

Using environments

You can configure environments with protection rules and secrets to control the execution of jobs in a workflow. Each job in a workflow can reference a single environment. Any protection rules configured for the environment must pass before a job referencing the environment is sent to a runner. For more information, see "Using environments for deployment."