注: GitHub 托管的运行器目前在 GitHub Enterprise Server 上不受支持。 您可以在 GitHub 公共路线图 上查看有关未来支持计划的更多信息。
关于 GitHub Actions 的 YAML 语法
所有操作都需要元数据文件。 元数据文件名必须是 action.yml
或 action.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>
的输入创建环境变量。 创建的环境变量将输入名称转换为大写,并将空� �替换为 _
字符。
如果该操作是使用 复合编写的,则它不会自动获得 INPUT_<VARIABLE_NAME>
。 如果不进行转换,您可以手动更改这些输入。
要访问 Docker 容器操作中的环境变量,您必须使用操作元数据文件中的关键字 args
� 递输入。 有关 Docker 容器操作的操作元数据文件的更多信息,请参阅“创建 Docker 容器操作”。
例如,如果工作流程定义了 numOctocats
和 octocatEyeColor
输入,操作代� �可使用 INPUT_NUMOCTOCATS
和 INPUT_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
。 当工作流程文件中未指定输入参数时使用默认值。
inputs.<input_id>.deprecationMessage
可选 如果使用输入参数,此 string
将记录为警告消息。 您可以使用此警告通知用户输入已被弃用,并提及任何其他替代方式。
用于 Docker 容器和 JavaScript 操作的 outputs
可选 输出参数允许您声明操作所设置的数据。 稍后在工作流程中运行的操作可以使用以前运行操作中的输出数据集。 例如,如果有操作执行两个输入的相� (x + y = z),则该操作可能输出总和 (z),用作其他操作的输入。
Outputs are Unicode strings, and can be a maximum of 1 MB. The total of all outputs in a workflow run can be a maximum of 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
令牌。
Outputs are Unicode strings, and can be a maximum of 1 MB. The total of all outputs in a workflow run can be a maximum of 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 "::set-output name=random-id::$(echo $RANDOM)"
shell: bash
outputs.<output_id>.value
必要 输出参数将会� 射到的值。 您可以使用上下文将此设置为 string
或表达式。 例如,您可以使用 steps
上下文将输出的 value
设置为步骤的输出值。
有关如何使用上下文语法的更多信息,请参阅“上下文”。
runs
必要 指定这是 JavaScript 操作、复合操作还是 Docker 容器操作以及操作的执行方式。
用于 JavaScript 操作的 runs
必要 配置操作代� �的路径和用于执行代� �的运行时。
示例:使用 Node.js v12
runs:
using: 'node12'
main: 'main.js'
runs.using
必要 用于执行 main
中指定的代� �的支行时。
- 将
node12
用于 Node.js v12。
runs.main
必要 包含操作代� �的文件。 using
中指定的运行时执行此文件。
runs.pre
可选 允许您在 main:
操作开始之前,在作业开始时运行脚本。 例如,您可以使用 pre:
运行基本要求设置脚本。 使用 using
语法指定的运行时将执行此文件。 pre:
操作始终默认运行,但您可以使用 runs.pre-if
覆盖该设置。
在此示例中,pre:
操作运行名为 setup.js
的脚本:
runs:
using: 'node12'
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: 'node12'
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
必要 您计划在此操作中的步骤。
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
更多信息请参阅“github context
”。
runs.steps[*].shell
必要 您想要在其中运行命令的 shell。 您可以使用这里列出的任何 shell。 如果设置了 run
,则必填。
runs.steps[*].name
可选 复合步骤的名称。
runs.steps[*].id
可选 步骤的唯一� �识符。 您可以使用 id
引用上下文中的步骤。 更多信息请参阅“上下文”。
runs.steps[*].env
可选 设置环境变量的 map
仅用于该步骤。 如果要修改存储在工作流程中的环境变量,请在组合运行步骤中使用 echo "{name}={value}" >> $GITHUB_ENV
。
runs.steps[*].working-directory
可选 指定命令在其中运行的工作目录。
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'
。
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
文档建议使用 exec 形式的 ENTRYPOINT
指令。
有关 entrypoint
如何执行的更多信息,请参阅“Dockerfile 对 GitHub Actions 的支持”。
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
,请遵循按偏好顺序排序的指导方针:
- 在操作的自述文件中记录必要的参数,并在
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 图� �创建徽� ,以个性化和识别操作。 徽� 显示在 GitHub Marketplace 中的操作名称旁边。
示例:为操作配置品牌宣�
branding:
icon: 'award'
color: 'green'
branding.color
徽� 的背景颜色。 可以是以下之一:white
、yellow
、blue
、green
、orange
、red
、purple
或 gray-dark
。
branding.icon
要使用的 v4.28.0 Feather 图� �的名称。 省略了品牌图� �以及以下内容:
coffee | 列 | divide-circle | divide-square |
divide | frown | hexagon | 键 |
meh | mouse-pointer | smile | 工具 |
x-octagon |
以下是当前支持的所有图� �的详尽列表:
活动 | 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 |
快进 | feather | file-minus | |
file-plus | file-text | 文件 | film |
filter | 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 |
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 | 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 |