Skip to main content

GitHub Actions 的元数据语法

您可以创建操作来执行仓库中的任务。 操作需要使用 YAML 语法的元数据文件。

关于 GitHub Actions 的 YAML 语法

所有操作都需要元数据文件。 元数据文件名必须是 action.ymlaction.yaml。 元数据文件中的数据定义操作的输入、输出和运行配置。

操作元数据文件使用 YAML 语法。 如果您是 YAML 的新用户,请参阅“五分钟了解 YAML”。

name

必要 操作的名称。 GitHub 在 Actions(操作)选项卡中显示 name,帮助从视觉上识别每项作业中的操作。

作者

可选 操作的作者姓名。

说明

必要 操作的简短描述。

inputs

可选 输入参数用于指定操作在运行时预期使用的数据。 GitHub 将输入参数存储为环境变量。 大写的输入 ID 在运行时转换为小写。 建议使用小写输入 ID。

示例:指定输入

此示例配置两个输入:numOctocats 和 octocatEyeColor。 numOctocats 输入不是必要的,默认值为 '1'。 octocatEyeColor 输入是必要的,没有默认值。 使用此操作的工作流程文件必须使用 with 关键词来设置 octocatEyeColor 的输入值。 有关 with 语法的更多信息,请参阅“GitHub Actions 的工作流程语法”。

inputs:
  numOctocats:
    description: 'Number of Octocats'
    required: false
    default: '1'
  octocatEyeColor:
    description: 'Eye color of the Octocats'
    required: true

在指定工作流程文件中输入或者使用默认输入值时,GitHub 将为名称为 INPUT_<VARIABLE_NAME> 的输入创建环境变量。 创建的环境变量将输入名称转换为大写,并将空格替换为 _ 字符。

如果该操作是使用 复合编写的,则它不会自动获得 INPUT_<VARIABLE_NAME>。 如果不进行转换,您可以手动更改这些输入。

要访问 Docker 容器操作中的环境变量,您必须使用操作元数据文件中的关键字 args 传递输入。 有关 Docker 容器操作的操作元数据文件的更多信息,请参阅“创建 Docker 容器操作”。

例如,如果工作流程定义了 numOctocatsoctocatEyeColor 输入,操作代码可使用 INPUT_NUMOCTOCATSINPUT_OCTOCATEYECOLOR 环境变量读取输入的值。

inputs.<input_id>

必要 要与输入关联的 string 识别符。 <input_id> 的值是输入元数据的映射。 <input_id> 必须是 inputs 对象中的唯一识别符。 <input_id> 必须以字母或 _ 开头,并且只能包含字母数字、-_

inputs.<input_id>.description

必要 输入参数的 string 描述。

inputs.<input_id>.required

必要 表示操作是否需要输入参数的 boolean。 当参数为必要时设置为 true

inputs.<input_id>.default

可选 表示默认值的 string。 当工作流程文件中未指定输入参数时使用默认值。

inputs.<input_id>.deprecationMessage

可选 如果使用输入参数,此 string 将记录为警告消息。 您可以使用此警告通知用户输入已被弃用,并提及任何其他替代方式。

用于 Docker 容器和 JavaScript 操作的 outputs

可选 输出参数允许您声明操作所设置的数据。 稍后在工作流程中运行的操作可以使用以前运行操作中的输出数据集。 例如,如果有操作执行两个输入的相加 (x + y = z),则该操作可能输出总和 (z),用作其他操作的输入。

Outputs are Unicode strings, and can be a maximum of 1 MB. The total of all outputs in a workflow run can be a maximum of 50 MB.

如果不在操作元数据文件中声明输出,您仍然可以设置输出并在工作流程中使用它们。 有关在操作中设置输出的更多信息,请参阅“GitHub Actions 的工作流程命令”。

示例:声明 Docker 容器和 JavaScript 操作的输出

outputs:
  sum: # id of the output
    description: 'The sum of the inputs'

outputs.<output_id>

必要 要与输出关联的 string 识别符。 <output_id> 的值是输出元数据的映射。 <output_id> 必须是 outputs 对象中的唯一识别符。 <output_id> 必须以字母或 _ 开头,并且只能包含字母数字、-_

outputs.<output_id>.description

必要 输出参数的 string 描述。

用于复合操作的 outputs

Optional outputs use the same parameters as outputs.<output_id> and outputs.<output_id>.description (see "outputs for Docker container and JavaScript actions"), but also includes the value token.

Outputs are Unicode strings, and can be a maximum of 1 MB. The total of all outputs in a workflow run can be a maximum of 50 MB.

示例:声明复合操作的 outputs

outputs:
  random-number:
    description: "Random number"
    value: ${{ steps.random-number-generator.outputs.random-id }}
runs:
  using: "composite"
  steps:
    - id: random-number-generator
      run: echo "::set-output name=random-id::$(echo $RANDOM)"
      shell: bash

outputs.<output_id>.value

必要 输出参数将会映射到的值。 您可以使用上下文将此设置为 string 或表达式。 例如,您可以使用 steps 上下文将输出的 value 设置为步骤的输出值。

有关如何使用上下文语法的更多信息,请参阅“上下文”。

runs

必要 指定这是 JavaScript 操作、复合操作还是 Docker 容器操作以及操作的执行方式。

用于 JavaScript 操作的 runs

必要 配置操作代码的路径和用于执行代码的运行时。

示例:使用 Node.js v16

runs:
  using: 'node16'
  main: 'main.js'

runs.using

必要 用于执行 main 中指定的代码的支行时。

  • node12 用于 Node.js v12。
  • node16 用于 Node.js v16。

runs.main

必要 包含操作代码的文件。 using 中指定的运行时执行此文件。

runs.pre

可选 允许您在 main: 操作开始之前,在作业开始时运行脚本。 例如,您可以使用 pre: 运行基本要求设置脚本。 使用 using 语法指定的运行时将执行此文件。 pre: 操作始终默认运行,但您可以使用 runs.pre-if 覆盖该设置。

在此示例中,pre: 操作运行名为 setup.js 的脚本:

runs:
  using: 'node16'
  pre: 'setup.js'
  main: 'index.js'
  post: 'cleanup.js'

runs.pre-if

可选 允许您定义 pre: 操作执行的条件。 pre: 操作仅在满足 pre-if 中的条件后运行。 如果未设置,则 pre-if 默认使用 always()。 在 pre-if 中,状态检查函数根据作业的状态而不是操作自己的状态进行评估。

请注意,step 上下文不可用,因为尚未运行任何步骤。

在此示例中,cleanup.js 仅在基于 Linux 的运行器上运行:

  pre: 'cleanup.js'
  pre-if: runner.os == 'linux'

runs.post

可选 允许您在 main: 操作完成后,在作业结束时运行脚本。 例如,您可以使用 post: 终止某些进程或删除不需要的文件。 使用 using 语法指定的运行时将执行此文件。

在此示例中,post: 操作会运行名为 cleanup.js 的脚本:

runs:
  using: 'node16'
  main: 'index.js'
  post: 'cleanup.js'

post: 操作始终默认运行,但您可以使用 post-if 覆盖该设置。

runs.post-if

可选 允许您定义 post: 操作执行的条件。 post: 操作仅在满足 post-if 中的条件后运行。 如果未设置,则 post-if 默认使用 always()。 在 post-if 中,状态检查函数根据作业的状态而不是操作自己的状态进行评估。

例如,此 cleanup.js 仅在基于 Linux 的运行器上运行:

  post: 'cleanup.js'
  post-if: runner.os == 'linux'

用于复合操作的 runs

必要 配置组合操作的路径。

runs.using

必要 必须将此值设置为 'composite'

runs.steps

必要 您计划在此操作中的步骤。 这些步骤可以是 run 步骤或 uses 步骤。

runs.steps[*].run

可选 您想要运行的命令。 这可以是内联的,也可以是操作仓库中的脚本:

runs:
  using: "composite"
  steps:
    - run: ${{ github.action_path }}/test/script.sh
      shell: bash

或者,您也可以使用 $GITHUB_ACTION_PATH

runs:
  using: "composite"
  steps:
    - run: $GITHUB_ACTION_PATH/script.sh
      shell: bash

更多信息请参阅“github context”。

runs.steps[*].shell

可选 您想要在其中运行命令的 shell。 您可以使用这里列出的任何 shell。 如果设置了 run,则必填。

runs.steps[*].if

可选 您可以使用 if 条件使步骤仅在满足条件时才运行。 您可以使用任何支持上下文和表达式来创建条件。

if 条件下使用表达式时,可以省略表达式语法 (${{ }}),因为 GitHub 会自动将 if 条件作为表达式求值。 更多信息请参阅“表达式”。

示例:使用上下文

此步骤仅在事件类型为 pull_request 并且事件操作为 unassigned 时运行。

steps:
 - run: echo This event is a pull request that had an assignee removed.
   if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}

示例:使用状态检查功能

my backup step 仅在组合操作的上一步失败时运行。 更多信息请参阅“表达式”。

steps:
  - name: My first step
    uses: octo-org/action-name@main
  - name: My backup step
    if: ${{ failure() }}
    uses: actions/heroku@1.0.0

runs.steps[*].name

可选 复合步骤的名称。

runs.steps[*].id

可选 步骤的唯一标识符。 您可以使用 id 引用上下文中的步骤。 更多信息请参阅“上下文”。

runs.steps[*].env

可选 设置环境变量的 map 仅用于该步骤。 如果要修改存储在工作流程中的环境变量,请在组合运行步骤中使用 echo "{name}={value}" >> $GITHUB_ENV

runs.steps[*].working-directory

可选 指定命令在其中运行的工作目录。

runs.steps[*].uses

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

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

  • 使用已发行操作版本的 SHA 对于稳定性和安全性是最安全的。
  • 使用特定主要操作版本可在保持兼容性的同时接收关键修复和安全补丁。 还可确保您的工作流程继续工作。
  • 使用操作的默认分支可能很方便,但如果有人新发布具有突破性更改的主要版本,您的工作流程可能会中断。

有些操作要求必须通过 with 关键词设置输入。 请查阅操作的自述文件,确定所需的输入。

runs:
  using: "composite"
  steps:
    # Reference a specific commit
    - uses: actions/checkout@a81bbbf8298c0fa03ea29cdc473d45769f953675
    # Reference the major version of a release
    - uses: actions/checkout@v3
    # Reference a specific version
    - uses: actions/checkout@v3.2.0
    # Reference a branch
    - uses: actions/checkout@main
    # References a subdirectory in a public GitHub repository at a specific branch, ref, or SHA
    - uses: actions/aws/ec2@main
    # References a local action
    - uses: ./.github/actions/my-action
    # References a docker public registry action
    - uses: docker://gcr.io/cloud-builders/gradle
    # Reference a docker image published on docker hub
    - uses: docker://alpine:3.8

runs.steps[*].with

可选 输入参数的 map 由操作定义。 每个输入参数都是一个键/值对。 输入参数被设置为环境变量。 该变量的前缀为 INPUT_,并转换为大写。

runs:
  using: "composite"
  steps:
    - name: My first step
      uses: actions/hello_world@main
      with:
        first_name: Mona
        middle_name: The
        last_name: Octocat  

用于 Docker 容器操作的 runs

必要 配置用于 Docker 容器操作的图像。

示例:在仓库中使用 Dockerfile

runs:
  using: 'docker'
  image: 'Dockerfile'

示例:使用公共 Docker 注册表容器

runs:
  using: 'docker'
  image: 'docker://debian:stretch-slim'

runs.using

必要 必须将此值设置为 'docker'

runs.pre-entrypoint

可选 允许您在 entrypoint 操作开始之前运行脚本。 例如,您可以使用 pre-entrypoint: 运行基本要求设置脚本。 GitHub Actions 使用 docker run 启动此操作,并在使用同一基本映像的新容器中运行脚本。 这意味着运行时状态与主 entrypoint 容器不同,并且必须在任一工作空间中访问所需的任何状态,HOME 或作为 STATE_ 变量。 pre-entrypoint: 操作始终默认运行,但您可以使用 runs.pre-if 覆盖该设置。

使用 using 语法指定的运行时将执行此文件。

在此示例中,pre-entrypoint: 操作会运行名为 setup.sh 的脚本:

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - 'bzz'
  pre-entrypoint: 'setup.sh'
  entrypoint: 'main.sh'

runs.image

必要 要用作容器来运行操作的 Docker 映像。 值可以是 Docker 基本映像名称、仓库中的本地 Dockerfile、Docker Hub 中的公共映像或另一个注册表。 要引用仓库本地的 Dockerfile,文件必须命名为 Dockerfile,并且您必须使用操作元数据文件的相对路径。 Docker 应用程序将执行此文件。

runs.env

可选 指定要在容器环境中设置的环境变量的键/值映射。

runs.entrypoint

可选 覆盖 Dockerfile 中的 Docker ENTRYPOINT,或在未指定时设置它。 当 Dockerfile 未指定 ENTRYPOINT 或者您想要覆盖 ENTRYPOINT 指令时使用 entrypoint。 如果您省略 entrypoint,您在 Docker ENTRYPOINT 指令中指定的命令将执行。 Docker ENTRYPOINT 指令有 shell 形式和 exec 形式。 Docker ENTRYPOINT 文档建议使用 exec 形式的 ENTRYPOINT 指令。

有关 entrypoint 如何执行的更多信息,请参阅“Dockerfile 对 GitHub Actions 的支持”。

post-entrypoint

可选 允许您在 runs.entrypoint 操作完成后运行清理脚本。 GitHub Actions 使用 docker run 来启动此操作。 因为 GitHub Actions 使用同一基本映像在新容器内运行脚本,所以运行时状态与主 entrypoint 容器不同。 您可以在任一工作空间中访问所需的任何状态,HOME 或作为 STATE_ 变量。 post-entrypoint: 操作始终默认运行,但您可以使用 runs.post-if 覆盖该设置。

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - 'bzz'
  entrypoint: 'main.sh'
  post-entrypoint: 'cleanup.sh'

runs.args

可选 定义 Docker 容器输入的字符串数组。 输入可包含硬编码的字符串。 GitHub 在容器启动时将 args 传递到容器的 ENTRYPOINT

args 用来代替 Dockerfile 中的 CMD 指令。 如果在 Dockerfile 中使用 CMD,请遵循按偏好顺序排序的指导方针:

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

如果需要将环境变量传递到操作中,请确保操作运行命令 shell 以执行变量替换。 例如,如果 entrypoint 属性设置为 "sh -c"args 将在命令 shell 中运行。 或者,如果 Dockerfile 使用 ENTRYPOINT 运行同一命令 ("sh -c"),args 将在命令 shell 中执行。

有关将 CMD 指令与 GitHub Actions 一起使用的更多信息,请参阅“Dockerfile 对 GitHub Actions 的支持”。

示例:为 Docker 容器定义参数

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - ${{ inputs.greeting }}
    - 'foo'
    - 'bar'

branding

您可以使用颜色和 Feather 图标创建徽章,以个性化和识别操作。 徽章显示在 GitHub Marketplace 中的操作名称旁边。

示例:为操作配置品牌宣传

branding:
  icon: 'award'  
  color: 'green'

branding.color

徽章的背景颜色。 可以是以下之一:whiteyellowbluegreenorangeredpurplegray-dark

branding.icon

要使用的 v4.28.0 Feather 图标的名称。 省略了品牌图标以及以下内容:

coffee divide-circle divide-square
divide frown hexagon
meh mouse-pointer smile 工具
x-octagon

以下是当前支持的所有图标的详尽列表:

活动 airplay alert-circle alert-octagon
alert-triangle align-center align-justify align-left
align-right anchor aperture 存档
arrow-down-circle arrow-down-left arrow-down-right arrow-down
arrow-left-circle arrow-left arrow-right-circle arrow-right
arrow-up-circle arrow-up-left arrow-up-right arrow-up
at-sign award bar-chart-2 bar-chart
battery-charging battery bell-off bell
bluetooth bold book-open book
bookmark box briefcase calendar
camera-off camera cast check-circle
check-square check chevron-down chevron-left
chevron-right chevron-up chevrons-down chevrons-left
chevrons-right chevrons-up circle clipboard
clock cloud-drizzle cloud-lightning cloud-off
cloud-rain cloud-snow cloud 代码
命令 compass copy corner-down-left
corner-down-right corner-left-down corner-left-up corner-right-down
corner-right-up corner-up-left corner-up-right cpu
credit-card crop crosshair database
delete disc dollar-sign download-cloud
download droplet edit-2 edit-3
edit external-link eye-off eye
facebook 快进 feather file-minus
file-plus file-text 文件 film
filter flag folder-minus folder-plus
folder gift git-branch git-commit
git-merge git-pull-request globe grid
hard-drive 哈希 headphones heart
help-circle home image inbox
info italic layers layout
life-buoy link-2 link list
loader lock log-in log-out
mail map-pin map maximize-2
maximize menu message-circle message-square
mic-off mic minimize-2 minimize
minus-circle minus-square minus monitor
moon more-horizontal more-vertical move
music navigation-2 navigation octagon
package paperclip pause-circle pause
percent phone-call phone-forwarded phone-incoming
phone-missed phone-off phone-outgoing phone
pie-chart play-circle play plus-circle
plus-square plus pocket power
printer radio refresh-ccw refresh-cw
repeat 倒回 rotate-ccw rotate-cw
rss save scissors search
send server settings share-2
share shield-off shield shopping-bag
shopping-cart shuffle 边栏 skip-back
skip-forward slash sliders smartphone
speaker square 星标 stop-circle
sun sunrise sunset tablet
标记 target terminal thermometer
thumbs-down thumbs-up toggle-left toggle-right
trash-2 trash trending-down trending-up
triangle truck tv type
umbrella underline unlock upload-cloud
上传 user-check user-minus user-plus
user-x 用户 用户 video-off
video voicemail volume-1 volume-2
volume-x volume 查看 wifi-off
wifi wind x-circle x-square
x zap-off zap zoom-in
zoom-out