GitHub Actions 的元数据语法

用于复合操作的 runs
- runs.using
- runs.steps
  runs.steps[*].run
  runs.steps[*].shell
  runs.steps[*].if
  runs.steps[*].name
  runs.steps[*].id
  runs.steps[*].env
  runs.steps[*].working-directory
  runs.steps[*].uses
  runs.steps[*].with

用于 Docker 容器操作的 runs

branding

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

关于 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)，用作其他操作的输入。

如果不在操作元数据文件中声明输出，您仍然可以设置输出并在工作流程中使用它们。有关在操作中设置输出的更多信息，请参阅“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

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 v16

runs:
  using: 'node16'
  main: 'main.js'

`runs.using`

必要用于执行 main 中指定的代码的支行时。

将 node12 用于 Node.js v12。
将 node16 用于 Node.js v16。

`runs.main`

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

`runs.pre`

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

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

runs:
  using: 'node16'
  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: 'node16'
  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`

必要您计划在此操作中的步骤。这些步骤可以是 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

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

`runs.steps[*].shell`

可选您想要在其中运行命令的 shell。您可以使用这里列出的任何 shell。如果设置了 run，则必填。

`runs.steps[*].if`

可选您可以使用 if 条件使步骤仅在满足条件时才运行。您可以使用任何支持上下文和表达式来创建条件。

在 if 条件下使用表达式时，可以省略表达式语法 (${{ }})，因为 GitHub 会自动将 if 条件作为表达式求值。更多信息请参阅“表达式”。

示例：使用上下文

此步骤仅在事件类型为 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 仅在组合操作的上一步失败时运行。 For more information, see "Expressions."

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@a81bbbf8298c0fa03ea29cdc473d45769f953675
    # Reference the major version of a release
    - uses: actions/checkout@v2
    # Reference a specific version
    - uses: actions/checkout@v2.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 由操作定义。每个输入参数都是一个键/值对。输入参数被设置为环境变量。该变量的前缀为 INPUT_，并转换为大写。

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'

`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
facebook	快进	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
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

Feb	MAR	Apr
	08
2021	2022	2023

GitHub Actions 的元数据语法

本文内容

关于 GitHub Actions 的 YAML 语法

name

作者

说明

inputs

示例：指定输入

inputs.<input_id>

inputs.<input_id>.description

inputs.<input_id>.required

inputs.<input_id>.default

inputs.<input_id>.deprecationMessage

用于 Docker 容器和 JavaScript 操作的 outputs

示例：声明 Docker 容器和 JavaScript 操作的输出

outputs.<output_id>

outputs.<output_id>.description

用于复合操作的 outputs

示例：声明复合操作的 outputs

outputs.<output_id>.value

runs

用于 JavaScript 操作的 runs

示例：使用 Node.js v16

runs.using

runs.main

runs.pre

runs.pre-if

runs.post

runs.post-if

用于复合操作的 runs

runs.using

runs.steps

runs.steps[*].run

runs.steps[*].shell

runs.steps[*].if

runs.steps[*].name

runs.steps[*].id

runs.steps[*].env

runs.steps[*].working-directory

runs.steps[*].uses

runs.steps[*].with

用于 Docker 容器操作的 runs

示例：在仓库中使用 Dockerfile

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

runs.using

runs.pre-entrypoint

runs.image

runs.env

runs.entrypoint

post-entrypoint

runs.args

示例：为 Docker 容器定义参数

branding

示例：为操作配置品牌宣传

branding.color

branding.icon

`name`

`作者`

`说明`

`inputs`

`inputs.<input_id>`

`inputs.<input_id>.description`

`inputs.<input_id>.required`

`inputs.<input_id>.default`

`inputs.<input_id>.deprecationMessage`

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

`outputs.<output_id>`

`outputs.<output_id>.description`

用于复合操作的 `outputs`

`outputs.<output_id>.value`

`runs`

用于 JavaScript 操作的 `runs`

`runs.using`

`runs.main`

`runs.pre`

`runs.pre-if`

`runs.post`

`runs.post-if`

用于复合操作的 `runs`

`runs.using`

`runs.steps`

`runs.steps[*].run`

`runs.steps[*].shell`

`runs.steps[*].if`

`runs.steps[*].name`

`runs.steps[*].id`

`runs.steps[*].env`

`runs.steps[*].working-directory`

`runs.steps[*].uses`

`runs.steps[*].with`

用于 Docker 容器操作的 `runs`

`runs.using`

`runs.pre-entrypoint`

`runs.image`

`runs.env`

`runs.entrypoint`

`post-entrypoint`

`runs.args`

`branding`

`branding.color`

`branding.icon`