Skip to main content

GitHub Actions 的元数据语法

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

关于 GitHub Actions 的 YAML 语法

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

操作元数据文件使用 YAML 语法。 如果不熟悉 YAML,可以阅读“用五分钟的时间来了解 YAML”。

name

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

author

(可选)操作创建者的姓名。

description

(必需)操作的简短说明。

inputs

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

示例:指定输入

此示例配置两个输入:num-octocatsoctocat-eye-colornum-octocats 输入并非必需,默认值为 1octocat-eye-color 必需,没有默认值。

注意:如果未为自动触发工作流运行的事件指定输入,则使用 required: true 的工作流不会自动返回错误。 如果你在工作流文件中设置了 required: true 并且正在使用 workflow_dispatch 手动运行工作流,则需要对 GitHub.com 指定输入。 有关详细信息,请参阅“触发工作流的事件”。

使用此操作的工作流文件可以使用 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>。 如果不进行转换,您可以手动更改这些输入。

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

例如,如果工作流定义了 num-octocatsoctocat-eye-color 输入,则操作代码可以使用 INPUT_NUM-OCTOCATSINPUT_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),用作其他操作的输入。

输出是 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 相同的参数(请参阅“用于 Docker 容器和 JavaScript 操作的 outputs”),但也包括 value 令牌。

输出是 Unicode 字符串,最大为 1 MB。 工作流运行中所有输出的总和最大为 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 "random-id=$(echo $RANDOM)" >> $GITHUB_OUTPUT
      shell: bash

outputs.<output_id>.value

(必需)输出参数将映射到的值。 可以将此项设置为 string 或带有上下文的表达式。 例如,可以使用 steps 上下文将输出的 value 设置为步骤的输出值。

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

runs

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

JavaScript 操作的 runs

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

示例:使用 Node.js v20

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

JavaScript 操作的 runs.using

(必需)用于执行 main 中指定的代码的运行时。

  • node20 用于 Node.js v20。

runs.main

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

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.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

有关详细信息,请参阅“上下文”。

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/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@8f4b7f84864484a7bf31766abe9204da3cbe65b3
    # Reference the major version of a release
    - uses: actions/checkout@v4
    # Reference a specific version
    - uses: actions/checkout@v4.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。 每个输入参数都是一个键/值对。 有关详细信息,请参阅示例:指定输入

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'

用于 Docker 容器操作的 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 文档建议使用 ENTRYPOINT 指令的 exec 形式。

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

runs.post-entrypoint

(可选)允许在 runs.entrypoint 操作完成后运行清理脚本。 GitHub Actions 使用 docker run 启动此操作。 由于 GitHub Actions 使用相同的基础映像在新容器内运行脚本,因此运行时状态与主 entrypoint 容器不同。 可以在工作区、HOMESTATE_ 变量中访问所需的任何状态。 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 图标的名称。

省略的图标

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

  • 咖啡
  • divide-circle
  • divide-square
  • divide
  • frown
  • 六边形
  • key
  • meh
  • mouse-pointer
  • smile
  • 工具 (tool)
  • x-octagon

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

  • activity
  • airplay
  • alert-circle
  • alert-octagon
  • alert-triangle
  • align-center
  • align-justify
  • align-left
  • align-right
  • 定位点
  • 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
  • 向上箭头
  • at-sign
  • award
  • bar-chart-2
  • bar-chart
  • battery-charging
  • 电池
  • bell-off
  • 响铃
  • 蓝牙
  • 粗体
  • book-open
  • book
  • 书签 (bookmark)
  • box
  • briefcase
  • 日历
  • camera-off
  • 照相机
  • 强制转换
  • check-circle
  • check-square
  • 选中
  • chevron-down
  • chevron-left
  • chevron-right
  • chevron-up
  • chevrons-down
  • chevrons-left
  • chevrons-right
  • chevrons-up
  • circle
  • 剪贴板
  • clock
  • cloud-drizzle
  • cloud-lightning
  • cloud-off
  • cloud-rain
  • cloud-snow
  • cloud
  • code
  • 命令
  • 指南针
  • 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
  • 裁剪
  • crosshair
  • database
  • delete
  • disc
  • dollar-sign
  • download-cloud
  • 下载
  • droplet
  • edit-2
  • edit-3
  • 编辑
  • external-link
  • eye-off
  • eye
  • fast-forward
  • feather
  • file-minus
  • file-plus
  • file-text
  • file
  • film
  • filter
  • 标志
  • folder-minus
  • folder-plus
  • 文件夹
  • gift
  • git-branch
  • git-commit
  • git-merge
  • git-pull-request
  • globe
  • grid
  • hard-drive
  • hash
  • headphones
  • heart
  • help-circle
  • 主页
  • image
  • inbox
  • info
  • 斜体
  • 图层
  • 布局
  • life-buoy
  • link-2
  • 链接
  • list
  • loader
  • 锁 (lock)
  • log-in
  • log-out
  • mail
  • map-pin
  • map
  • maximize-2
  • maximize
  • “菜单”
  • message-circle
  • message-square
  • mic-off
  • mic
  • minimize-2
  • 最小化
  • minus-circle
  • minus-square
  • minus
  • 监视
  • moon
  • more-horizontal
  • more-vertical
  • 移动
  • music
  • navigation-2
  • 导航
  • octagon
  • paperclip
  • pause-circle
  • pause
  • %
  • phone-call
  • phone-forwarded
  • phone-incoming
  • phone-missed
  • phone-off
  • phone-outgoing
  • phone
  • pie-chart
  • play-circle
  • 玩游戏
  • plus-circle
  • plus-square
  • plus
  • pocket
  • power
  • 打印机
  • radio
  • refresh-ccw
  • refresh-cw
  • repeat
  • rewind
  • rotate-ccw
  • rotate-cw
  • rss
  • 保存
  • scissors
  • search
  • 发送
  • server
  • 设置
  • share-2
  • 共享
  • shield-off
  • shield
  • shopping-bag
  • shopping-cart
  • 随机选择
  • 边栏
  • skip-back
  • skip-forward
  • slash
  • 滑块
  • 智能手机
  • 扬声器
  • square
  • 星号键
  • stop-circle
  • 周六
  • sunrise
  • 日落
  • 平板电脑
  • 标记
  • 目标
  • terminal
  • thermometer
  • thumbs-down
  • thumbs-up
  • toggle-left
  • toggle-right
  • trash-2
  • trash
  • trending-down
  • trending-up
  • 三角形
  • 卡车
  • 电视
  • 类型
  • 雨伞
  • 下划线
  • 解锁
  • upload-cloud
  • upload
  • user-check
  • user-minus
  • user-plus
  • user-x
  • user
  • users
  • video-off
  • 视频
  • voicemail
  • volume-1
  • volume-2
  • volume-x
  • 查看
  • wifi-off
  • wifi
  • wind
  • x-circle
  • x-square
  • x
  • zap-off
  • zap
  • zoom-in
  • zoom-out