GitHub Actions 元数据语法 - GitHub Docs

关于 GitHub Actions 的 YAML 语法

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

操作元数据文件使用 YAML 语法。如果您不熟悉 YAML，可以阅读“五分钟学会 YAML”。

`name`

必需操作的名称。GitHub 在“操作”选项卡中显示 name，以帮助直观地识别每个作业中的操作。

`inputs`

可选输入参数允许您指定操作在运行时预期使用的数据。GitHub 将输入参数存储为环境变量。我们建议使用小写输入 ID。

示例：指定输入

此示例配置了两个输入：num-octocats 和 octocat-eye-color。num-octocats 输入不是必需的，其默认值为 1。octocat-eye-color 是必需的，并且没有默认值。

注意

使用 required: true 的操作不会在未指定输入时自动返回错误。

使用此操作的工作流文件可以使用 with 关键字为 octocat-eye-color 设置输入值。有关 with 语法的更多信息，请参阅“GitHub Actions 的工作流语法”。

inputs:
  num-octocats:
    description: 'Number of Octocats'
    required: false
    default: '1'
  octocat-eye-color:
    description: 'Eye color of the Octocats'
    required: true

指定输入时，GitHub 会为该输入创建一个环境变量，其名称为 INPUT_<VARIABLE_NAME>。创建的环境变量会将输入名称转换为大写字母，并将空格替换为 _ 字符。

如果操作使用组合编写，则它不会自动获取 INPUT_<VARIABLE_NAME>。对于组合操作，您可以使用 inputs 访问有关工作流运行的上下文信息来访问操作输入。

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

例如，如果工作流定义了 num-octocats 和 octocat-eye-color 输入，则操作代码可以使用 INPUT_NUM-OCTOCATS 和 INPUT_OCTOCAT-EYE-COLOR 环境变量读取输入的值。

`inputs.<input_id>`

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

`inputs.<input_id>.description`

必填输入参数的 字符串 描述。

`inputs.<input_id>.required`

可选一个 布尔值，指示操作是否需要输入参数。当参数是必需时，设置为 true。

`inputs.<input_id>.deprecationMessage`

可选如果使用了输入参数，则此 字符串 将作为警告消息记录。您可以使用此警告通知用户输入即将关闭，并提及任何替代方案。

Docker 容器和 JavaScript 操作的 `outputs`

可选输出参数允许您声明操作设置的数据。工作流中稍后运行的操作可以使用先前运行的操作中设置的输出数据。例如，如果您有一个操作执行两个输入的加法（x + y = z），则该操作可以输出总和 (z) 供其他操作用作输入。

输出是 Unicode 字符串，最大为 1 MB。工作流运行中所有输出的总和最大为 50 MB。

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

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

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

`outputs.<output_id>`

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

`outputs.<output_id>.description`

必填输出参数的 字符串 描述。

组合操作的 `outputs`

可选 outputs 使用与 outputs.<output_id> 和 outputs.<output_id>.description 相同的参数（请参阅“Docker 容器和 JavaScript 操作的 outputs”），但也包含 value 令牌。

输出是 Unicode 字符串，最大为 1 MB。工作流运行中所有输出的总和最大为 50 MB。

示例：声明组合操作的输出

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

`outputs.<output_id>.value`

必填输出参数将映射到的值。您可以将其设置为 字符串 或带有上下文的表达式。例如，您可以使用 steps 上下文将输出的 value 设置为步骤的输出值。

有关如何使用上下文语法的更多信息，请参阅“访问有关工作流运行的上下文信息”。

`runs`

必填指定这是 JavaScript 操作、组合操作还是 Docker 容器操作，以及如何执行操作。

JavaScript 操作的 `runs`

必填配置操作代码的路径以及用于执行代码的运行时。

示例：使用 Node.js v20

runs:
  using: 'node20'
  main: 'main.js'

JavaScript 操作的 `runs.using`

必填用于执行 main 中指定的代码的运行时。

对于 Node.js v20，请使用 node20。

`runs.pre`

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

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

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

`runs.pre-if`

可选允许您为 pre: 操作执行定义条件。只有在满足 pre-if 中的条件时，才会运行 pre: 操作。如果未设置，则 pre-if 默认值为 always()。在 pre-if 中，状态检查函数根据作业的状态进行评估，而不是操作自身的状态。

请注意，step 上下文不可用，因为还没有运行任何步骤。

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

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

`runs.post-if`

可选允许您为 post: 操作执行定义条件。只有在满足 post-if 中的条件时，才会运行 post: 操作。如果未设置，则 post-if 默认值为 always()。在 post-if 中，状态检查函数根据作业的状态进行评估，而不是操作自身的状态。

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

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

组合操作的 `runs`

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

`runs.steps`

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

`runs.steps[*].shell`

可选您要在其中运行命令的 shell。您可以使用“GitHub Actions 的工作流语法”中列出的任何 shell。如果设置了 run，则需要此项。

`runs.steps[*].if`

可选您可以使用 if 条件来防止步骤在不满足条件的情况下运行。您可以使用任何受支持的上下文和表达式来创建条件。

在 if 条件中使用表达式时，您可以选择省略 ${{ }} 表达式语法，因为 GitHub Actions 会自动将 if 条件评估为表达式。但是，此例外情况并非在所有地方都适用。

当表达式以 ! 开头时，您必须始终使用 ${{ }} 表达式语法或使用 ''、"" 或 () 进行转义，因为 ! 是 YAML 格式中的保留符号。例如

if: ${{ ! startsWith(github.ref, 'refs/tags/') }}

有关更多信息，请参阅“评估工作流和操作中的表达式”。

示例：使用上下文

此步骤仅在事件类型为 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/[email protected]

`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 关键字设置的输入。查看操作的 README 文件以确定所需的输入。

runs:
  using: "composite"
  steps:
    # Reference a specific commit
    - uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3
    # Reference the major version of a release
    - uses: actions/checkout@v4
    # Reference a specific version
    - uses: actions/[email protected]
    # 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。每个输入参数都是一个键/值对。有关更多信息，请参阅示例：指定输入。

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

可选允许您在 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 文档建议使用 ENTRYPOINT 指令的exec 形式。

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

`runs.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，请按优先级顺序使用以下指南

在操作的 README 中记录必需的参数，并从 CMD 指令中省略它们。
使用允许在不指定任何 args 的情况下使用操作的默认值。
如果操作公开了 --help 标志或类似内容，请使用它使您的操作具有自文档功能。

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

有关将 CMD 指令与 GitHub Actions 结合使用的更多信息，请参阅“GitHub Actions 的 Dockerfile 支持”。

示例：为 Docker 容器定义参数

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

`branding`

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

示例：配置操作的品牌

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

coffee
columns
divide-circle
divide-square
divide
frown
hexagon
key
meh
mouse-pointer
smile
tool
x-octagon

所有当前支持的图标的详尽列表

activity
airplay
alert-circle
alert-octagon
alert-triangle
align-center
align-justify
align-left
align-right
anchor
aperture
archive
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
code
command
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
fast-forward
feather
file-minus
file-plus
file-text
file
film
filter
flag
folder-minus
folder-plus
folder
gift
git-branch
git-commit
git-merge
git-pull-request
globe
grid
hard-drive
hash
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
rewind
rotate-ccw
rotate-cw
rss
save
scissors
search
send
server
settings
share-2
share
shield-off
shield
shopping-bag
shopping-cart
shuffle
sidebar
后退
前进
斜杠
滑块
智能手机
扬声器
正方形
星号
停止圆圈
太阳
日出
日落
表格
平板电脑
标签
目标
终端
温度计
竖起大拇指（向下）
竖起大拇指（向上）
切换至左
切换至右
垃圾桶 2
垃圾桶
趋势下降
趋势上升
三角形
卡车
电视
类型
雨伞
下划线
解锁
云端上传
上传
用户已验证
移除用户
添加用户
移除用户
用户
用户
视频关闭
视频
语音邮件
音量 1
音量 2
静音
音量
手表
WiFi 关闭
WiFi
风
带圆圈的 X
带方框的 X
X
闪电关闭
闪电
放大
缩小

GitHub Actions 的元数据语法

本文内容