GitHub Actions 元数据语法

关于 GitHub Actions 的 YAML 语法

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

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

`name`

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

`inputs`

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

示例：指定输入

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

注意： 使用 required: true 的工作流不会在自动触发工作流运行的事件中，如果未指定输入，则不会自动返回错误。如果您在工作流文件中设置了 required: true，并且使用 workflow_dispatch 手动运行工作流，则需要在 GitHub 上指定输入。有关更多信息，请参阅 "触发工作流的事件。"。

使用此操作的工作流文件可以使用 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>。如果转换没有发生，您可以手动更改这些输入。

要访问 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 类型的值将作为警告消息记录。您可以使用此警告通知用户该输入已弃用，并提及任何替代方案。

`outputs` 用于 Docker 容器和 JavaScript 操作

可选输出参数允许您声明操作设置的数据。工作流中稍后运行的操作可以使用在先前运行的操作中设置的输出数据。例如，如果您有一个执行两个输入相加（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>`

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

`outputs.<output_id>.description`

必需一个 string 类型的值，用于描述输出参数。

`outputs` 用于复合操作

可选 outputs 使用与 outputs.<output_id> 和 outputs.<output_id>.description 相同的参数（参见 "outputs for Docker container and JavaScript actions"），但也包含 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`

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

有关如何使用上下文语法的更多信息，请参见 "Contexts."

`runs`

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

`runs` for JavaScript actions

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

示例：使用 Node.js v20

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

`runs.using` for JavaScript actions

必需用于执行 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`

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

在本例中，post: 操作运行名为 cleanup.js 的脚本。

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

post: 操作默认情况下始终运行，但您可以使用 post-if 覆盖此行为。

`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
云关闭
云雨
云雪
云
代码
命令
指南针
复制
左下角
右下角
左下角
左上角
右下角
右上角
左上角
右上角
中央处理器
信用卡
裁剪
十字准星
数据库
删除
磁盘
美元符号
云下载
下载
水滴
编辑2
编辑3
编辑
外部链接
关闭眼睛
眼睛
快进
羽毛
文件减号
文件加号
文件文本
文件
电影
过滤器
旗帜
文件夹减号
文件夹加号
文件夹
礼物
Git 分支
Git 提交
Git 合并
Git 拉取请求
地球
网格
硬盘
哈希
耳机
心
帮助圈
主页
图像
收件箱
信息
斜体
图层
布局
救生圈
链接2
链接
列表
加载器
锁
登录
退出
邮件
地图针
地图
最大化2
最大化
菜单
消息圆圈
消息方块
关闭麦克风
麦克风
最小化2
最小化
减号圆圈
减号方块
减号
显示器
月亮
更多水平
更多垂直
移动
音乐
导航2
导航
八边形
包裹
回形针
暂停圆圈
暂停
百分比
电话呼叫
电话转接
电话来电
电话未接
电话关闭
电话拨出
电话
饼图
播放圆圈
播放
加号圆圈
加号方块
加号
口袋
电源
打印机
收音机
逆时针刷新
顺时针刷新
重复
倒带
逆时针旋转
顺时针旋转
RSS
保存
剪刀
搜索
发送
服务器
设置
分享2
分享
关闭盾牌
盾牌
购物袋
购物车
随机播放
侧边栏
后退
快进
斜杠
滑块
智能手机
扬声器
正方形
星形
停止圆圈
太阳
日出
日落
平板电脑
标签
目标
终端
温度计
拇指向下
拇指向上
向左切换
向右切换
垃圾桶 2
垃圾桶
趋势下降
趋势上升
三角形
卡车
电视
类型
雨伞
下划线
解锁
上传云
上传
用户检查
用户减号
用户加号
用户叉号
用户
用户
视频关闭
视频
语音邮件
音量 1
音量 2
静音
音量
手表
Wi-Fi 关闭
Wi-Fi
风
圆圈叉号
正方形叉号
叉号
闪电关闭
闪电
放大
缩小

GitHub Actions 的元数据语法

本文内容