我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

GitHub 操作的工作流程语法

您可以将工作流程文件添加到仓库来创建自动化流程,以自动化软件开发生命周期。

GitHub 操作 目前在有限公测阶段,可能会有变动。强烈建议在公测期间不要将此功能用于高价值工作流程和内容。

更多信息请参阅“关于 GitHub 操作”。

本文内容

关于工作流程的 YAML 语法

Workflow files use YAML syntax, and must have either a .yml or .yaml file extension. If you're new to YAML and want to learn more, see "Learn YAML in five minutes."

必须将工作流程文件存储在仓库的 .github/workflows 目录中。

使用限制

Exceeding usage limits may result in jobs queueing, failing to run, or failing to complete. Limits are subject to change.

name

工作流程的名称。 GitHub 在仓库的操作页面上显示工作流程的名称。 If you omit this field, GitHub sets the name to the workflow's filename.

on

必要 触发工作流程的 GitHub 事件的名称。 您可以提供单一事件 string、事件的 array 或事件配置 map,以安排工作流程的运行,或将工作流程的执行限于特定文件、标记或分支更改。 For a list of available events, see "Events that trigger workflows."

使用单一事件的示例

# Trigger on push
on: push

使用事件列表的示例

# Trigger the workflow on push or pull request
on: [push, pull_request]

on.<push|pull_request>.<tags|branches>

When using the push and pull_request events, you can configure a workflow to run on specific branches or tags.

You can match more than one branch or tag by using the wildcard characters supported by Go path.Match. The patterns defined in branches and tags are evaluated against the Git ref's name. For example, defining the pattern releases/10 in branches would match the refs/heads/releases/10 Git ref.

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches:    
      - master         # Push events on master branch
      - 'releases/*'   # Push events to branches matching refs/heads/releases/*
    # Sequence of patterns matched against refs/tags
    tags:        
      - v1             # Push events to v1 tag
      - v1.0           # Push events to v1.0 tag

Defining only one of tags: or branches: will mean the workflow skips events affecting the other type of ref.

When you specify a branches or tags filter, the workflow only runs if at least one pattern matches. Any changes to branches or tags that don't match a defined pattern will not trigger a workflow. The order that you define patterns matters:

on.<push|pull_request>.paths

When using the push and pull_request events, you can configure a workflow to run when at least one modified file matches a pattern defined in paths. If you omit paths, no file paths are filtered.

You can match more than one file path by using the wildcard characters supported by Go path.Match.

For example, a workflow with the following path filter will only run on pushes which modify at least one file that doesn't have the .js extension:

on:
  push:
    paths:
    - '*'    
    - '!*.js'

Path filter evaluation

Each modified file path is compared against each of the patterns defined in paths until an at least one match is found.

For example, to prevent a workflow from running when all the modified are JavaScript files, you must first include a positive match for all other files using the * wildcard character. If you only include the negative pattern !*.js, the workflow will never run because no positive match exists. Patterns are matched according to the following rules:

As a consequence of these rules, the following workflow will never run because no positive patterns are included by default.

on:
  push:
    paths:
    # This pattern removes possible paths but doesn't include any positive matches
    - '!*.js'

The patterns in paths are compared against the set of file paths modified by any commit in the push or pull request, even if the modification is undone by a later commit. This means the set of paths is a superset of files contained in a diff.

Example matching paths in nested directories

This example runs anytime the push or pull_request event includes a file in the sub-project directory or its subdirectories. For example, changes to any of these files would trigger a workflow run: sub-directory/index.js, sub-directory/my-nested-directory/README.md, sub-directory/mona/lisa/octocat.rb.

on:
  push:
    paths:
      # '*' matches any character except '/'
      - 'sub-project/*'
      - 'sub-project/*/*'
      - 'sub-project/*/*/*'

Example using negative pattern matching

This example runs a workflow when at least one modified file is not located in the /docs directory.

on:
  push:
    paths:
    - '*'        # Run workflow for all file paths
    - '!/docs/*' # Don't run workflow when files are only in the /docs directory

on.schedule

This example triggers the workflow every 15 minutes:

on:
schedule:
- cron:  */15 * * * *

For more information about cron syntax, see "Events that trigger workflows."

jobs

A workflow run is made up of one or more jobs. 作业默认是并行运行。 To run jobs sequentially, you can define dependencies on other jobs using the jobs.<job_id>.needs keyword.

每项作业都在 runs-on 指定的虚拟环境全新实例中运行。

You can run an unlimited number of jobs as long as you are within the workflow usage limits. For more information, see "Usage limits."

jobs.<job_id>

每项作业必须关联一个 ID。 键值 job_id 是一个字符串,其值是作业配置数据的映像。 必须将 <job_id> 替换为 jobs 对象唯一的字符串。 <job_id> 必须以字母或 _ 开头,并且只能包含字母数字字符、-_

示例

jobs:
  my_first_job:
    name: My first job
  my_second_job:
    name: My second job

jobs.<job_id>.name

作业显示在 GitHub 上的名称。

jobs.<job_id>.needs

识别在此作业运行之前必须成功完成的任何作业。 它可以是一个字符串,也可以是字符串数组。 如果某个作业失败,则所有需要它的作业也会失败,除非这些作业使用让该作业继续的条件语句。

示例

jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]

In this example, job1 must complete successfully before job2 begins, and job3 waits for both job1 and job2 to complete.

此示例中的作业按顺序运行:

  1. job1
  2. job2
  3. job3

jobs.<job_id>.runs-on

Required The type of virtual host machine to run the job on. 每项作业都使用 runs-on 指定的虚拟环境全新实例运行。

可用的虚拟机类型包括:

For more information, see Virtual environments for GitHub 操作 for details.

示例

runs-on: ubuntu-18.04

jobs.<job_id>.steps

作业包含一系列任务,称为 steps。 步骤可以运行命令、运行设置任务,或者运行您的仓库、公共仓库中的操作或 Docker 注册表中发布的操作。 Not all steps run actions, but all actions run as a step. 每个步骤在虚拟机中以其自己的进程运行,且可以访问工作区和文件系统。 Because steps run in their own process, changes to environment variables are not preserved between steps. GitHub provides built-in steps to set up and complete a job.

You can run an unlimited number of steps as long as you are within the workflow usage limits. For more information, see "Usage limits."

示例

name: Greeting from Mona

on: push

jobs:
  my-job:
    name: My Job
    runs-on: ubuntu-latest
    steps:

    - name: Print a greeting
      env:
        MY_VAR: Hi there! My name is
        FIRST_NAME: Mona
        MIDDLE_NAME: The
        LAST_NAME: Octocat
      run: |
        echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME.

jobs.<job_id>.steps.id

步骤的唯一标识符。 您可以使用 id 引用上下文中的步骤。 For more information, see "Contexts and expression syntax for GitHub 操作."

jobs.<job_id>.steps.if

您可以使用 if 条件阻止步骤在条件得到满足之前运行。 您可以使用任何支持上下文和表达式来创建条件。

Expressions in an if conditional do not require the

${{ }} syntax. For more information, see "Contexts and expression syntax for GitHub 操作."

Example using contexts

This step only runs when the event type is a pull_request and the event action is unassigned.

steps:
  - name: My first step
    if: github.event_name == 'pull_request' && github.event.action == 'unassigned'
    run: echo This event is a pull request that had an assignee removed.
Example using status check functions

The my backup step only runs when the previous step of a job fails. For more information, see "Status check functions."

steps:
  - name: My first step
    # Use an action (`my-action`) in your repository
    uses: ./.github/actions/my-action
  - name: My backup step
    if: failure()
    uses: actions/heroku@master

jobs.<job_id>.steps.name

步骤显示在 GitHub 上的名称。

jobs.<job_id>.steps.uses

选择要作为作业中步骤的一部分运行的操作。 操作是一种可重复使用的代码单位。 您可以使用工作流程所在仓库中、公共仓库中或发布 Docker 容器映像中定义的操作。

强烈建议指定 Git ref、SHA 或 Docker 标记编号来包含所用操作的版本。 如果不指定版本,在操作所有者发布更新时可能会中断您的工作流程或造成非预期的行为。

Some actions require inputs that you must set using the with keyword. 请查阅操作的自述文件,确定所需的输入。

Actions are either JavaScript files or Docker containers. 如果您使用的操作是 Docker 容器,则必须在 Linux 虚拟环境中运行作业。 更多详细信息请参阅 runs-on 和“GitHub 操作 的虚拟环境”。

使用版本化操作的示例
steps:    
  - uses: actions/setup-node@74bc508 # Reference a specific commit
  - uses: actions/setup-node@v1      # Reference the major version of a release   
  - uses: actions/setup-node@v1.2    # Reference a minor version of a release  
  - uses: actions/setup-node@master  # Reference a branch
使用公共操作的示例

{owner}/{repo}@{ref}

您可以指定公共 GitHub 仓库中特定的分支、引用或 SHA。

jobs:
  my_first_job:
    steps:
      - name: My first step
      # Uses the master branch of a public repository
        uses: actions/heroku@master
      # use a specific version tag of a public repository
      - name: My second step
        uses: actions/aws@v2.0.1
在子目录中使用公共操作的示例

{owner}/{repo}/{path}@{ref}

公共 GitHub 仓库中特定分支、引用或 SHA 上的子目录。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/aws/ec2@master
使用工作流程所在仓库中操作的示例

./path/to/dir

包含工作流程的仓库中操作的目录路径。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: ./.github/actions/my-action
使用 Docker 中枢操作的示例

docker://{image}:{tag}

Docker 中枢上发布的 Docker 映像。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://alpine:3.8
使用 Docker 公共注册表操作的示例

docker://{host}/{image}:{tag}

公共注册表中的 Docker 映像。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://gcr.io/cloud-builders/gradle

jobs.<job_id>.steps.run

使用操作系统 shell 运行命令行程序。 如果不提供 name,步骤名称将默认使用 run 命令。 命令默认使用非登录 shell 运行。

Each run keyword represents a new process and shell in the virtual environment. When you provide multi-line commands, each line runs in the same shell:

Example single-line command
- name: Install Dependencies
  run: npm install      
Example multi-line command
- name: Clean install dependencies and build
- run: |
    npm ci
    npm run build
Using a specific shell

You can override the default shell settings in the virtual environment's operating system using the shell keyword. 您可以使用内置的 shell 关键词,也可以自定义 shell 选项集。

Supported platform shell parameter 描述 Command run internally
所有 bash The default shell on non-Windows platforms with a fallback to sh. When specifying a bash shell on Windows, the bash shell included with Git for Windows is used. bash --noprofile --norc -eo pipefail {0}
所有 pwsh The PowerShell Core. GitHub appends the extension .ps1 to your script name. pwsh -command "& '{0}'"
所有 python Executes the python command. python {0}
Linux / macOS sh The fallback behavior for non-Windows platforms if no shell is provided and bash is not found in the path. sh -e {0}
Windows cmd This is the default shell used on Windows. GitHub appends the extension .cmd to your script name and substitutes for {0}. %ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}"".
Windows powershell The Desktop PowerShell. GitHub appends the extension .ps1 to your script name. powershell -command "& '{0}'".
Example running a script using bash
steps:
  - name: Display the path
    run: echo ${PATH}
    shell: bash
Example running a script using Windows cmd:
steps:
  - name: Display the path
    run: echo %PATH%
    shell: cmd
Example running a script using PowerShell Core:
steps:
  - name: Display the path
    run: echo ${env:PATH}
    shell: pwsh
Example running a python script:
steps:
  - name: Display the path
    run: |
      import os
      print(os.environ['PATH'])
    shell: python
自定义 shell

您可以使用 command […options] {0} [..more_options]shell 值设置为模板字符串。 GitHub interprets the first whitespace-delimited word of the string as the command, and inserts the file name for the temporary script at {0}.

退出代码和错误操作首选项

For built-in shell keywords, we provide the following defaults that are executed by GitHub-hosted runners. You should use these guidelines when running shell scripts.

jobs.<job_id>.steps.with

A map of the input parameters defined by the action. 每个输入参数都是一个键/值对。 Input parameters are set as environment variables. The variable is prefixed with INPUT_ and converted to upper case.

示例

定义 hello_world 操作所定义的三个输入参数(first_namemiddle_namelast_name)。 These input variables will be accessible to the hello-world action as INPUT_FIRST_NAME, INPUT_MIDDLE_NAME, and INPUT_LAST_NAME environment variables.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/hello_world@master
        with:
          first_name: Mona
          middle_name: The
          last_name: Octocat      

jobs.<job_id>.steps.with.args

A string that defines the inputs for a Docker container. GitHub passes the args to the container's ENTRYPOINT when the container starts up. An array of strings is not supported by this parameter.

示例
steps:

  - name: Explain why this job ran
    uses: monacorp/action-name@master
    with:
      entrypoint: /bin/echo
      args: The ${{ github.event_name }} event triggered this step.

The args are used in place of the CMD instruction in a Dockerfile. If you use CMD in your Dockerfile, use the guidelines ordered by preference:

  1. 在操作的自述文件中记录必要的参数,并在 CMD 指令的中忽略它们。
  2. 使用默认值,允许不指定任何 args 即可使用操作。
  3. 如果操作显示 --help 标记或类似项,请将其用作默认值,以便操作自行记录。

jobs.<job_id>.steps.with.entrypoint

Overrides the Docker ENTRYPOINT in the Dockerfile, or sets it if one wasn't already specified. Unlike the Docker ENTRYPOINT instruction which has a shell and exec form, entrypoint keyword accepts only a single string defining the executable to be run.

示例
steps:
  - name: Run a custom command
    uses: monacorp/action-name@master
    with:
      entrypoint: /a/different/executable

The entrypoint keyword is meant to use with Docker container actions, but you can also use it with JavaScript actions that don't define any inputs.

jobs.<job_id>.steps.env

Sets environment variables for steps to use in the virtual environment. Public actions may specify expected environment variables in the README file. If you are setting a secret in an environment variable, you must set secrets using the secrets context. For more information, see "Virtual environments for GitHub 操作" and "Contexts and expression syntax for GitHub 操作."

示例
steps:

  - name: My first action
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      FIRST_NAME: Mona
      LAST_NAME: Octocat

jobs.<job_id>.steps.working-directory

The default directory that the action uses in a job's workspace.

jobs.<job_id>.steps.continue-on-error

Prevents a job from failing when a step fails. Set to true to allow a job to pass when this step fails.

jobs.<job_id>.steps.timeout-minutes

The maximum number of minutes to run the step before killing the process.

jobs.<job_id>.timeout-minutes

在 GitHub 自动取消运行之前可让工作流程运行的最大分钟数。 默认值:360

jobs.<job_id>.strategy

策略创建作业的构建矩阵。 您可以定义要在其中运行每项作业的环境的不同变种。

jobs.<job_id>.strategy.matrix

构建矩阵是虚拟环境测试的一组不同配置。 例如,您可能在多个支持的语言、操作系统或工具版本上运行作业。 每项配置是运行并报告状态的作业的副本。

您可以提供配置选项阵列来指定矩阵。 例如,如果 GitHub 虚拟环境支持 Node.js 版本 6、8 和 10,则您可以在 matrix 中指定这些版本的阵列。

When you define a matrix of operating systems, you must set the required runs-on keyword to the operating system of the current job, rather than hard-coding the operating system name. To access the operating system name, you can use the matrix.os context parameter to set runs-on. For more information, see "Contexts and expression syntax for GitHub 操作."

You can run an unlimited number of jobs as long as you are within the workflow usage limits. For more information, see "Usage limits."

示例

This example creates a matrix of three jobs, setting the node variable to a different value for each and using that variable as input to the setup-node action. As a result, each job will use a different node version.

strategy:
  matrix:
    node: [6, 8, 10]
steps:

  - uses: actions/setup-node@v1
    with:
      node-version: ${{ matrix.node }}

You could also run those jobs in two different Linux versions, using a matrix variable as input to the runs-on specifier, to create a total of 6 jobs (3 node versions x 2 Linux versions).

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    os: [ubuntu-16.04, ubuntu-18.04]
    node: [6, 8, 10]
steps:

  - uses: actions/setup-node@v1
    with:
      node-version: ${{ matrix.node }}

To find supported configuration options for a GitHub virtual environment, see "Virtual environments for GitHub 操作."

Example including configurations in a matrix build

You can add additional configuration options to a build matrix job that already exists. You cannot use include to add new jobs to a build matrix. For example, if you want to use a specific version of npm when the job that uses windows-2016 and version 4 of node runs, you can use include to specify that additional option.

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    os: [macOS-10.14, windows-2016, ubuntu-18.04]
    node: [4, 6, 8, 10]
    include:
      # includes a new variable of npm with a value of 2 for the matrix leg matching the os and version

      - os: windows-2016
        node: 4
        npm: 2
Example excluding configurations from a matrix

You can remove a specific configurations defined in the build matrix using the exclude option. Using exclude removes a job defined by the build matrix. The number of jobs is the cross product of the number of operating systems (os) included in the arrays you provide, minus any subtractions (exclude).

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    os: [macOS-10.14, windows-2016, ubuntu-18.04]
    node: [4, 6, 8, 10]
    exclude:
      # excludes node 4 on macOS

      - os: macos-10.14
        node: 4

jobs.<job_id>.strategy.fail-fast

设置为 true 时,如果任何 matrix 作业失败,GitHub 将取消所有进行中的作业。 默认值:true

jobs.<job_id>.strategy.max-parallel

使用 matrix 作业策略时可同时运行的最大作业数。 By default, GitHub will maximize the number of jobs run in parallel depending on the available runners on GitHub-hosted virtual machines.

strategy:
  max-parallel: 2

jobs.<job_id>.container

用于运行作业中尚未指定容器的任何步骤的容器。 若不设置 container,所有步骤将直接在 runs-on 指定的主机上运行,除非步骤引用已配置为在容器中运行的操作。 如有步骤同时使用脚本和容器操作,则容器操作将运行为同一网络上使用相同卷挂载的同级容器。

示例

jobs:
  my_job:
    container:
      image: node:10.16-jessie
      env:
        NODE_ENV: development
      ports:
        - 80
      volumes:
        - my_docker_volume:/volume_mount
      options: --cpus 1

只指定容器映像时,可以忽略 image 关键词。

jobs:
  my_job:
    container: node:10.16-jessie

jobs.<job_id>.container.image

要用作运行操作的容器的 Docker 图像。 值可以是 Docker 中枢映像名称或公共 Docker 注册表名称。

jobs.<job_id>.container.env

设置容器中环境变量的 array

jobs.<job_id>.container.ports

设置要在容器上显示的端口 array

jobs.<job_id>.container.volumes

设置要使用的容器卷的 array。 您可以使用卷分享作业中服务或其他步骤之间的数据。 可以指定命名的 Docker 卷、匿名的 Docker 卷或主机上的绑定挂载。

要指定卷,需指定来源和目标路径:

<source>:<destinationPath>.

<source> 是主机上的卷名称或绝对路径,<destinationPath> 是容器中的绝对路径。

示例
volumes:
  - my_docker_volume:/volume_mount
  - /data/my_data
  - /source/directory:/destination/directory

jobs.<job_id>.container.options

附加 Docker 容器资源选项。 有关选项列表,请参阅“docker create options”。

jobs.<job_id>.services

托管用于工作流程中作业的服务的其他容器。 这些适用于创建数据库或缓存服务,如 redis。 虚拟机上的运行程序将自动创建网络和管理服务容器的生命周期。

GitHub 操作 出站流量的 IP 地址列表是动态变化的。 GitHub 无法提供一致的允许 IP 地址列表。

示例

此示例创建分别用于 nginx 和 redis 的两项服务。 GitHub 选择虚拟主机上的开放端口来绑定 redis 的默认端口。 GitHub 在 ${{ job.services.<service_name>.ports[<port>] }} 作业上下文中设置出站主机端口。 For example, the redis port would be set in the ${{ job.services.redis.ports['6379'] }} environment variable.

services:
  nginx:
    image: nginx
    ports:
      - 8080:80
    env:
      NGINX_PORT: 80
  redis:
    image: redis
    ports:
      - 6379/tcp

jobs.<job_id>.services.image

要用作运行操作的服务容器的 Docker 图像。 值可以是 Docker 基本映像名称或公共 Docker 中枢或注册表。

jobs.<job_id>.services.env

设置服务容器中环境变量的 array

jobs.<job_id>.services.ports

设置要在服务容器上显示的端口 array

jobs.<job_id>.services.volumes

设置要使用的服务容器卷的 array。 您可以使用卷分享作业中服务或其他步骤之间的数据。 可以指定命名的 Docker 卷、匿名的 Docker 卷或主机上的绑定挂载。

要指定卷,需指定来源和目标路径:

<source>:<destinationPath>.

<source> 是主机上的卷名称或绝对路径,<destinationPath> 是容器中的绝对路径。

示例
volumes:
  - my_docker_volume:/volume_mount
  - /data/my_data
  - /source/directory:/destination/directory

jobs.<job_id>.services.options

附加 Docker 容器资源选项。 有关选项列表,请参阅“docker create options”。

问问别人

找不到要找的内容?

联系我们