Skip to main content

About workflows

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

About workflows

工作流程是一个可配置的自动化过程,它将运行一个或多个作业。 工作流程由签入到存储库的 YAML 文件定义,并在存储库中的事件触发时运行,也可以手动触发,或按定义的时间表触发。

工作流程在存储库的 .github/workflows 目录中定义,存储库可以有多个工作流程,每个工作流程都可以执行不同的任务集。 例如,您可以有一个工作流程来构建和测试拉取请求,另一个工作流程用于在每次创建发布时部署应用程序,还有一个工作流程在每次有人打开新议题时添加标签。

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

创建示例工作流程

GitHub Actions 使用 YAML 语法来定义工作流程。 每个工作流都作为单独的 YAML 文件存储在代码存储库中名为 .github/workflows 的目录中。

您可以在仓库中创建示例工作流程,只要推送代码,该工作流程就会自动触发一系列命令。 在此工作流中,GitHub Actions 签出推送的代码,安装 bats 测试框架,并运行基本命令来输出 bats 版本: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 工作流程文件现在安装在您的仓库中,每次有人推送更改到仓库时都会自动运行。 若要查看关于工作流执行历史记录的详细信息,请参阅“查看工作流运行的活动”。

了解工作流程文件

为帮助您了解如何使用 YAML 语法来创建工作流程文件,本节解释介绍示例的每一行:

name: learn-github-actions
可选 - 工作流的名称,它将显示在 GitHub 存储库的“操作”选项卡中。
on: [push]
指定此工作流程的触发器。 此示例使用 push 事件,因此每当有人将更改推送到存储库或合并拉取请求时都会触发工作流运行。 这是由到每个分支的推送触发的;有关仅在推送到特定分支、路径或标记时运行的语法示例,请参阅“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 作业中运行的所有步骤组合在一起。 此部分下嵌套的每项都是一个单独的操作或 shell 脚本。
    - uses: actions/checkout@v2
uses 关键字指定此步骤将运行 actions/checkout 操作的 v3。 这是一个将存储库签出到运行器上的操作,允许您对代码(如生成和测试工具)运行脚本或其他操作。 每当工作流程将针对存储库的代码运行时,都应使用签出操作。
    - uses: actions/setup-node@v2
      with:
        node-version: '14'
此步骤使用 actions/setup-node@v2 操作安装指定的 Node.js 版本(本示例使用 v14)。 这会将 nodenpm 命令都放在 PATH 中。
    - run: npm install -g bats
run 关键字指示作业在运行器上执行命令。 在这种情况下,你使用 npm 来安装 bats 软件测试包。
    - run: bats -v
最后,你将使用输出软件版本的参数运行 bats 命令。

可视化工作流程文件

在此关系图中,您可以看到刚刚创建的工作流程文件,以及 GitHub Actions 组件在层次结构中的组织方式。 每个步骤执行单个操作或 shell 脚本。 步骤 1 和 2 运行操作,步骤 3 和 4 运行 shell 脚本。 若要为工作流查找更多预先创建的操作,请参阅“查找和自定义操作”。

工作流概述

查看工作流运行的活动

触发工作流时,将创建执行工作流的“工作流运行”。 工作流运行开始后,可以查看运行进度的可视化图表,并在 GitHub 上查看每个步骤的活动。

  1. 在 your GitHub Enterprise Server instance 上,导航到存储库的主页。

  2. 在你的存储库名称下,单击“操作”。

    导航到仓库

  3. 在左侧边栏中,单击您想要查看的工作流程。

    工作流程结果的屏幕截图

  4. 在“Workflow runs(工作流程运行)”下,单击您想要查看的运行的名称。

    工作流程运行的屏幕截图

  5. 在“作业”或可视化图中,选择要查看的作业。

    选择作业

  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 provides preconfigured starter workflows that you can customize to create your own continuous integration workflow. GitHub Enterprise Server analyzes your code and shows you CI starter workflows that might be useful for your repository. For example, if your repository contains Node.js code, you'll see suggestions for Node.js projects. You can use starter workflows as a starting place to build your custom workflow or use them as-is.

You can browse the full list of starter workflows in the actions/starter-workflows repository on your GitHub Enterprise Server instance.

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

使用矩阵策略,可以在单个作业定义中使用变量自动创建基于变量组合的多个作业运行。 例如,可以使用矩阵策略在某个语言的多个版本或多个操作系统上测试代码。 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."

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

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

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