GitHub Actions 元数据语法

关于 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_ 的输入环境变量。创建的环境变量会将输入名称转换为大写字母，并将空格替换为 _ 字符。

如果操作是使用复合操作编写的，则它不会自动获取 INPUT_。对于复合操作，您可以使用 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 中执行。

有关在 GitHub Actions 中使用CMD指令的更多信息，请参见“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
电话
饼状图
播放圆圈
播放
加号圆圈
加号方块
加号
口袋
电源
打印机
收音机
逆时针刷新
顺时针刷新
重复
倒回
逆时针旋转
顺时针旋转
RSS
保存
剪刀
搜索
发送
服务器
设置
分享（两人）
分享
关闭防护盾
防护盾
购物袋
购物车
随机播放
侧边栏
跳过上一首
跳过下一首
斜杠
滑块
智能手机
扬声器
方块
星号
停止圆圈
太阳
日出
日落
表格
平板电脑
标签
目标
终端
温度计
竖起大拇指（向下）
竖起大拇指（向上）
切换到左边
切换到右边
垃圾桶（两个）
垃圾桶
趋势下降
趋势上升
三角形
卡车
电视
文本类型
雨伞
下划线
解锁
上传到云端
上传
已验证用户
移除用户
添加用户
删除用户
用户
用户们
关闭视频
视频
语音邮件
音量1
音量2
静音
音量
手表
关闭WiFi
WiFi
风
关闭圆圈（X）
关闭方块（X）
X
关闭闪电
闪电
放大
缩小

本文内容