元数据语法参考

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

如果操作是使用 composite 编写的，则不会自动获得 INPUT_<VARIABLE_NAME>。通过复合操作，可以使用 inputs上下文参考访问操作输入。

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

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

`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)，用作其他操作的输入。

每个作业的输出最多可以为 1 MB。工作流运行中所有输出的总和最大为 50 MB。大小是基于 UTF-16 编码的近似值。

如果不在操作元数据文件中声明输出，您仍然可以设置输出并在工作流程中使用它们。有关在操作中设置输出的详细信息，请参阅“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`

必填：输出参数的说明。

`runs`

（必需）指定该操作是 JavaScript 操作、组合操作还是 Docker 容器操作，以及操作的执行方式。

JavaScript 操作的 `runs`

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

示例：使用 Node.js v24

runs:
  using: 'node24'
  main: 'main.js'

JavaScript 操作的 `runs.using`

（必需）用于执行 **** 中指定的代码的运行时。

对于 Node.js v20 应使用 node20。
对于 Node.js v24 应使用 node24。

`runs.pre`

          **可选** 允许在 `main:` 操作开始之前在作业启动时运行脚本。 例如，可以使用 `pre:` 运行先决条件安装脚本。 使用 [`using`](#runsusing-for-javascript-actions) 语法指定的运行时将执行此文件。 
          `pre:` 操作始终默认运行，但你也可使用 [`runs.pre-if`](#runspre-if) 替代该操作。

注意

          `runs.pre` 不支持本地操作。

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

runs:
  using: 'node24'
  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: 'node24'
  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[*].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` 仅在组合操作的上一步失败时运行。 有关详细信息，请参阅“[AUTOTITLE](/actions/learn-github-actions/expressions#status-check-functions)”。

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[*].id`

（可选）步骤的唯一标识符。可以使用 id 在上下文中引用该步骤。有关详细信息，请参阅“上下文参考”。

`runs.steps[*].env`

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

`runs.steps[*].working-directory`

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

`runs.steps[*].uses`

          **可选** 选择要作为作业中步骤的一部分运行的操作。 操作是一种可重复使用的代码单位。 可以使用在与工作流、公共存储库或[已发布的 Docker 容器映像](https://hub.docker.com/)相同的存储库中定义的操作。

我们强烈建议您通过指定 Git 引用、SHA 或 Docker 标签号来明确所用操作的版本。如果不指定版本，在操作所有者发布更新时可能会中断您的工作流程或造成非预期的行为。

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

某些操作需要必须使用 with 关键字设置的输入。请查阅操作的自述文件，确定所需的输入。

runs:
  using: "composite"
  steps:
    # Reference a specific commit
    - uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3
    # Reference the major version of a release
    - uses: actions/checkout@v5
    # Reference a specific version
    - uses: actions/checkout@v5.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`。 每个输入参数都是一个键/值对。 有关详细信息，请参阅[示例：指定输入](#example-specifying-inputs)。

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

`runs.steps[*].continue-on-error`

可选：在步骤失败时，防止操作失败。设置为 true 以在此步骤失败时让操作能够通过。

用于 Docker 容器操作的 `runs`

（必需）配置用于 Docker 容器操作的映像。

示例：在仓库中使用 Dockerfile

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

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

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

          `runs.using` 用于 Docker 容器操作

          **必需** 必须将此值设置为 `'docker'`。

（可选）允许在 **** 操作开始之前运行脚本。例如，可以使用 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`，否则对其进行设置。 如果 `entrypoint` 未指定 `Dockerfile` 或要替代 `ENTRYPOINT` 指令，请使用 `ENTRYPOINT`。 如果省略 `entrypoint`，将执行在 Docker `ENTRYPOINT` 指令中指定的命令。 Docker `ENTRYPOINT` 指令具有 shell 形式和 exec 形式 。 Docker `ENTRYPOINT` 文档建议使用 `ENTRYPOINT` 指令的 _exec_ 形式。

有关 entrypoint 的执行方式的详细信息，请参阅“Dockerfile 对 GitHub Actions 的支持”。

`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` 用于代替 `CMD` 中的 `Dockerfile` 指令。 如果在 `Dockerfile` 中使用 `CMD`，请使用按偏好排序的指南：

在操作的自述文件中记录必要的参数，并在 CMD 指令的中忽略它们。
使用默认值，允许不指定任何 args 即可使用操作。
如果操作显示 --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](https://feathericons.com/) 图标来创建徽章，以个性化设置和区分操作。 在 [GitHub Marketplace](https://github.com/marketplace?type=actions) 中，操作名称旁边会显示徽章。

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

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

`branding.color`

徽章的背景颜色。可以是以下项之一：white、black、yellow、blue、green、orange、red、purple 或 gray-dark。

`branding.icon`

要使用的 v4.28.0 Feather 图标的名称。

省略的图标

省略了品牌图标和下列所有图标。

咖啡
列
divide-circle
divide-square
相割
皱眉
六边形
关键值
无所谓
鼠标指针
微笑
工具
x-八边形

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

活动
airplay
alert-circle
alert-octagon
警报三角形
align-center
align-justify
align-left
align-right
定位标记
光圈
存档
向下箭头圆圈
向左下箭头
arrow-down-right
向下箭头
arrow-left-circle
左箭头
arrow-right-circle
向右箭头
上箭头圆圈
arrow-up-left
arrow-up-right
向上箭头
at-sign
奖
条形图-2
bar-chart
电池充电
电池
bell-off
响铃
蓝牙
粗体
book-open
book
书签
盒子
公文包
日历
摄像头关闭
照相机
强制转换
check-circle
check-square
检查
向下箭头
chevron-left
chevron-right
chevron-up
chevrons-down
chevrons-left
chevrons-right
chevrons-up
圆
剪贴板
时钟
云细雨
云-闪电
cloud-off
云雨
雪云
云
代码
命令
指南针
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)
信用卡
剪切
crosshair
数据库
删除
磁盘
美元符号
download-cloud
下载
Droplet
edit-2
edit-3
编辑
外部链接
eye-off
眼睛
fast-forward
羽毛
file-minus
file-plus
文件文本
文件
film
筛选器
标志
folder-minus
folder-plus
文件夹
礼物
git-branch
git-commit
git-merge
git-pull-request
地球仪
网格
硬盘
哈希
耳机
heart
help-circle
主页
图像
收件箱
info
斜体
图层
布局
救生圈
link-2
链接
列表
加载器
锁定
登录
退出
邮件
map-pin
映射
maximize-2
最大化
菜单
消息圈
message-square
麦克风关闭
麦克风_
minimize-2
最小化
minus-circle
minus-square
减
监视
月亮
more-horizontal
more-vertical
move
音乐
navigation-2
导航
八边形
包
paperclip
pause-circle
暂停
百分比
电话通话
phone-forwarded
phone-incoming
phone-missed
关闭手机
phone-outgoing
电话
pie-chart
play-circle
播放
plus-circle
plus-square
加号
pocket
电源
打印机
收音机
refresh-ccw
refresh-cw
repeat
后退
rotate-ccw
rotate-cw
rss
保存
剪刀
搜索
发送
服务器
设置
分享-2
共享
屏蔽
shield
购物袋
购物车
shuffle
边栏
skip-back
skip-forward
slash
滑块
智能手机
扬声器
square
star
stop-circle
太阳
日出
日落
表
平板电脑
标签
目标
终端
温度计
thumbs-down
点赞
toggle-left
toggle-right
垃圾-2
回收站
下降趋势
趋势上升
三角形
卡车
电视
类型
雨伞
下划线
解锁
upload-cloud
上传
用户验证
user-minus
user-plus
user-x
用户
用户
video-off
视频
语音信箱
卷1
volume-2
音量-x
容量
监视
关闭Wi-Fi
wifi
风
x-circle
x平方
x
zap-off
zap
放大
zoom-out

更改元数据文件名

虽然操作元数据文件支持这两种 YAML 格式，但更改元数据文件名（从 action.yml 更改为 action.yaml，反之亦然）会影响已发布到 GitHub Marketplace 的以前版本。更改文件名将导致在 GitHub Marketplace 中隐藏与先前文件名关联的所有发布版本。用户仍可通过源存储库访问先前的发布版本。

当发布新版本时，只有在元数据文件名更改后发布的版本才会具有 GitHub Marketplace 标记，并将显示在 GitHub Marketplace 上

在本文中