我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

GitHub 操作的元数据语法

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

GitHub Actions 可用于 GitHub Free、GitHub Pro、组织的 GitHub Free、GitHub Team、GitHub Enterprise Cloud 和 GitHub One。 GitHub Actions 不适用于使用旧版按仓库计划的帐户所拥有的私有仓库。 For more information, see "GitHub's products."

本文内容

此文档对您有帮助吗?

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。

关于 GitHub Actions 的 YAML 语法

Docker 和 JavaScript 操作需要元数据文件。 元数据文件名必须是 action.ymlaction.yaml。 元数据文件中的数据定义操作的输入、输出和主要进入点。

操作元数据文件使用 YAML 语法。 如果您是 YAML 的新用户,请参阅“五分钟了解 YAML”。

name

必要 操作的名称。 GitHub 在 Actions(操作)选项卡中显示 name,帮助从视觉上识别每项作业中的操作。

作者

可选 操作的作者姓名。

说明

必要 操作的简短描述。

inputs

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

示例

此示例配置两个输入:numOctocats 和 octocatEyeColor。 numOctocats 输入不是必要的,默认值为 '1'。 octocatEyeColor 输入是必要的,没有默认值。 使用此操作的工作流程文件必须使用 with 关键词来设置 octocatEyeColor 的输入值。 有关 with 语法的更多信息,请参阅“GitHub Actions 的工作流程语法”。

inputs:
  numOctocats:
    description: 'Number of Octocats'
    required: false
    default: '1'
  octocatEyeColor:
    description: 'Eye color of the Octocats'
    required: true

在指定工作流程文件中某个操作的输入或者使用默认输入值时,GitHub 将为名称为 INPUT_<VARIABLE_NAME> 的输入创建环境变量。 创建的环境变量将输入名称转换为大写,并将空格替换为 _ 字符。

例如,如果工作流程定义了 numOctocats and octocatEyeColor 输入,操作代码可使用 INPUT_NUMOCTOCATSINPUT_OCTOCATEYECOLOR 环境变量读取输入的值。

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。 当工作流程文件中未指定输入参数时使用默认值。

outputs

可选 输出参数允许您声明操作所设置的数据。 稍后在工作流程中运行的操作可以使用以前运行操作中的输出数据集。 例如,如果有操作执行两个输入的相加 (x + y = z),则该操作可能输出总和 (z),用作其他操作的输入。

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

示例

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 相同的参数(请参阅“用于 GitHub Actions 的

outputs”),但也包括 value 令牌。

示例

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

outputs.<output_id.value>

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

有关如何使用上下文和表达式语法的更多信息,请参阅“GitHub Actions 的上下文和表达式语法”。

用于 JavaScript 操作的 runs

必要 配置操作代码的路径和用于执行代码的应用程序。

使用 Node.js 的示例

runs:
  using: 'node12'
  main: 'main.js'

runs.using

必要 用于执行 main 中指定的代码的应用程序。

runs.main

必要 包含操作代码的文件。 using 中指定的应用程序执行此文件。

pre

可选 允许您在 main: 操作开始之前,在作业开始时运行脚本。 例如,您可以使用 pre: 运行基本要求设置脚本。 使用 using 语法指定的应用程序将执行此文件。 pre: 操作始终默认运行,但您可以使用 pre-if 覆盖该设置。

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

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

pre-if

可选 允许您定义 pre: 操作执行的条件。 pre: 操作仅在满足 pre-if 中的条件后运行。 如果未设置,则 pre-if 默认使用 always()。 请注意,step 上下文不可用,因为尚未运行任何步骤。

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

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

post

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

在此示例中,post: 操作会运行名为 cleanup.js 的脚本:

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

post: 操作始终默认运行,但您可以使用 post-if 覆盖该设置。

post-if

可选 允许您定义 post: 操作执行的条件。 post: 操作仅在满足 post-if 中的条件后运行。 如果未设置,则 post-if 默认使用 always()

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

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

用于组合运行步骤操作的 runs

必要 配置组合操作的路径和用于执行代码的应用程序。

runs.using

必要 要使用组合运行步骤操作,请将此设置为 "composite"

runs.steps

必要 您计划在此操作中运行的步骤。

runs.steps.run

必要 您想要运行的命令。 这可以是内联的,也可以是操作仓库中的脚本:

runs:
  using: "composite"
  steps: 
    - run: $/test/script.sh
      shell: bash

或者,您也可以使用 $GITHUB_ACTION_PATH

runs:
  using: "composite"
  steps: 
    - run: $GITHUB_ACTION_PATH/script.sh
      shell: bash

更多信息请参阅“github context”。

runs.steps.shell

必要 您想要在其中运行命令的 shell。 您可以使用这里列出的任何 shell。

runs.steps.name

可选 组合运行步骤的名称。

runs.steps.id

可选 步骤的唯一标识符。 您可以使用 id 引用上下文中的步骤。 更多信息请参阅“GitHub Actions 的上下文和表达式语法”。

runs.steps.env

可选 设置环境变量的 map 仅用于该步骤。 如果要修改工作流程中存储的环境变量,请在复合运行步骤中使用 echo "{name}={value}" >> $GITHUB_ENV

runs.steps.working-directory

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

用于 Docker 操作的 runs

必要 配置用于 Docker 操作的图像。

在仓库中使用 Dockerfile 的示例

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

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

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

runs.using

必要 必须将此值设置为 'docker'

pre-entrypoint

可选 允许您在 entrypoint 操作开始之前运行脚本。 例如,您可以使用 pre-entrypoint: 运行基本要求设置脚本。 GitHub Actions 使用 docker run 启动此操作,并在使用同一基本映像的新容器中运行脚本。 这意味着运行时状态与主 entrypoint 容器不同,并且必须在任一工作空间中访问所需的任何状态,HOME 或作为 STATE_ 变量。 pre-entrypoint: 操作始终默认运行,但您可以使用 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,请使用操作元数据文件的相对路径。 Docker 应用程序将执行此文件。

runs.env

可选 指定要在容器环境中设置的环境变量的键/值映射。

runs.entrypoint

可选 覆盖 Dockerfile 中的 Docker ENTRYPOINT,或在未指定时设置它。 当 Dockerfile 未指定 ENTRYPOINT 或者您想要覆盖 ENTRYPOINT 指令时使用 entrypoint。 如果您省略 entrypoint,您在 Docker ENTRYPOINT 指令中指定的命令将执行。 Docker ENTRYPOINT 指令有 shell 形式和 exec 形式。 Docker ENTRYPOINT 文档建议使用 exec 形式的 ENTRYPOINT 指令。

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

post-entrypoint

可选 允许您在 runs.entrypoint 操作完成后运行清理脚本。 GitHub Actions 使用 docker run 来启动此操作。 因为 GitHub Actions 使用同一基本映像在新容器内运行脚本,所以运行时状态与主 entrypoint 容器不同。 您可以在任一工作空间中访问所需的任何状态,HOME 或作为 STATE_ 变量。 post-entrypoint: 操作始终默认运行,但您可以使用 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 的支持”。

示例
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

要使用的 Feather 图标的名称。

活动 airplay alert-circle alert-octagon
alert-triangle align-center align-justify align-left
align-right anchor 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 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 代码
命令 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
facebook 快进 feather file-minus
file-plus file-text 文件 film
过滤 flag folder-minus folder-plus
folder gift git-branch git-commit
git-merge git-pull-request globe grid
hard-drive 哈希 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 倒回 rotate-ccw rotate-cw
rss save scissors search
send server settings share-2
share shield-off shield shopping-bag
shopping-cart shuffle 边栏 skip-back
skip-forward slash sliders smartphone
speaker square 星标 stop-circle
sun sunrise sunset tablet
标记 target terminal thermometer
thumbs-down thumbs-up toggle-left toggle-right
trash-2 trash trending-down trending-up
triangle truck tv type
umbrella underline unlock upload-cloud
上传 user-check user-minus user-plus
user-x 用户 用户 video-off
video voicemail volume-1 volume-2
volume-x volume 查看 wifi-off
wifi wind x-circle x-square
x zap-off zap zoom-in
zoom-out

此文档对您有帮助吗?

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。