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

GitHub 操作的元数据语法

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

GitHub 操作 可用于 GitHub Free、GitHub Pro、组织的 GitHub Free、GitHub Team、GitHub Enterprise Cloud 和 GitHub One。 GitHub 操作 不适用于使用旧版按仓库计划的帐户所拥有的私有仓库。 更多信息请参阅“GitHub 的产品”。

本文内容

关于 GitHub 操作 的 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 操作 的工作流程语法”。

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 操作 的工作流程命令”。

示例

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 描述。

用于 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'

用于 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 操作 使用 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 操作 的支持”。

post-entrypoint

可选 允许您在 runs.entrypoint 操作完成后运行清理脚本。 GitHub 操作 使用 docker run 来启动此操作。 因为 GitHub 操作 使用同一基本映像在新容器内运行脚本,所以运行时状态与主 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 操作 一起使用的更多信息,请参阅“Dockerfile 对 GitHub 操作 的支持”。

示例
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 图标的名称。

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
facebook fast-forward 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 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 phone
pie-chart play-circle play plus-circle
plus-square plus pocket power
printer radio refresh-ccw refresh-cw
repeat rewind rotate-ccw rotate-cw
rss save scissors search
send server settings share-2
share shield-off shield shopping-bag
shopping-cart shuffle sidebar skip-back
skip-forward slash sliders smartphone
speaker square star stop-circle
sun sunrise sunset tablet
tag 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
upload user-check user-minus user-plus
user-x user 用户 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

问问别人

找不到要找的内容?

联系我们