此版本的 GitHub Enterprise 已停止服务 2021-09-23. 即使针对重大安全问题,也不会发布补丁。 要获得更好的性能、改进的安全性和新功能,请升级到 GitHub Enterprise 的最新版本。 如需升级方面的帮助,请联系 GitHub Enterprise 支持

GitHub Actions 的元数据语法

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

注:GitHub Enterprise Server 2.22 上的 GitHub Actions 支持是有限的公测版。 测试已结束。 GitHub Actions 现在一般可用于 GitHub Enterprise Server 3.0 或更新版本。 更多信息请参阅 GitHub Enterprise Server 3.0 发行说明


注: GitHub 托管的运行器目前在 GitHub Enterprise Server 上不受支持。 您可以在 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> 的输入创建环境变量。 创建的环境变量将输入名称转换为大写,并将空格替换为 _ 字符。

如果该操作是使用 复合编写的,则它不会自动获得 INPUT_<VARIABLE_NAME>。 如果不进行转换,您可以手动更改这些输入。

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

例如,如果工作流程定义了 numOctocatsoctocatEyeColor 输入,操作代码可使用 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。 当工作流程文件中未指定输入参数时使用默认值。

inputs.<input_id>.deprecationMessage

可选 如果使用输入参数,此 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 设置为步骤的输出值。

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

用于 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: ${{ 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 "::set-env name={name}::{value}"

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,文件必须命名为 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 图标的名称。

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 file film
filter 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 users video-off
video voicemail volume-1 volume-2
volume-x volume watch wifi-off
wifi wind x-circle x-square
x zap-off zap zoom-in
zoom-out