# GitHub Actions 的工作流语法 工作流程是可配置的自动化过程，由一个或多个作业组成。 您必须创建 YAML 文件来定义工作流程配置。 > \[!NOTE] > GitHub Enterprise Server 目前不支持 GitHub 托管的运行器。 ## 关于工作流程的 YAML 语法 工作流文件使用 YAML 语法，并且必须具有 `.yml` 或 `.yaml` 文件扩展名。 如果你不熟悉 YAML 并且想要了解详细信息，请参阅“[在 Y 分钟内了解 YAML](https://learnxinyminutes.com/docs/yaml/)”。 必须将工作流文件存储在存储库的 `.github/workflows` 目录中。 ## `name` 工作流的名称。 GitHub 在存储库的“操作”选项卡下显示工作流的名称。如果省略 `name`，GitHub 会显示相对于存储库根目录的工作流文件路径。 ## `run-name` 从工作流生成的工作流运行的名称。 GitHub 在存储库的“操作”选项卡上，在工作流运行列表中显示工作流运行名称。如果 `run-name` 省略或只是空格，则运行名称设置为工作流运行的事件特定信息。 例如，对于由 `push` 或 `pull_request` 事件触发的工作流，将其设置为提交消息或拉取请求的标题。 此值可包含表达式，且可引用 [`github`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#github-context) 和 [`inputs`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#inputs-context) 上下文。 ### `run-name` 的示例 ```yaml run-name: Deploy to ${{ inputs.deploy_target }} by @${{ github.actor }} ``` ## `on` 若要自动触发工作流，请使用 `on` 定义哪些事件可以触发工作流运行。 有关可用事件的列表，请参阅“[触发工作流的事件](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/events-that-trigger-workflows)”。 可以定义单个或多个可以触发工作流的事件，或设置时间计划。 还可以将工作流限制为仅在特定文件、标签或分支发生更改时才执行。 后续部分将介绍这些选项。 ### 使用单个事件 例如，当推送到工作流存储库中的任何分支时，将运行具有以下 `on` 值的工作流： ```yaml on: push ``` ### 使用多个事件 可以指定单个事件或多个事件。 例如，当推送到存储库中的任何分支或有人创建存储库的分支时，将运行具有以下 `on` 值的工作流： ```yaml on: [push, fork] ``` 如果指定多个事件，仅需发生其中一个事件就可触发工作流。 如果触发工作流的多个事件同时发生，将触发多个工作流运行。 ### 使用活动类型 某些事件具有活动类型，可让你更好地控制工作流的运行时间。 使用 `on..types` 定义将触发工作流运行的事件活动类型。 例如，`issue_comment` 事件具有 `created`、`edited` 和 `deleted` 活动类型。 如果工作流在 `label` 事件上触发，则每当创建、编辑或删除标签时，它都会运行。 如果为 `created` 事件指定 `label` 活动类型，则工作流将在创建标签时运行，但不会在编辑或删除标签时运行。 ```yaml on: label: types: - created ``` 如果指定多个活动类型，则只需要发生其中一种事件活动类型就可触发工作流。 如果触发工作流的多个事件活动类型同时发生，则将触发多个工作流运行。 例如，当某个议题被创建或被加上标签时，以下工作流将被触发。 如果打开了一个带有两个标签的议题，则会启动三个工作流运行：一个对应议题打开事件，另外两个对应这两个议题加标签事件。 ```yaml on: issues: types: - opened - labeled ``` 有关每个事件及其活动类型的详细信息，请参阅“[触发工作流的事件](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/events-that-trigger-workflows)”。 ### 使用筛选器 某些事件具有筛选器，可让你更好地控制工作流的运行时间。 例如，`push` 事件具有 `branches` 筛选器，该筛选器仅在发生目标为与 `branches` 筛选器匹配的分支的推送时（而不是在发生任何推送时）运行工作流。 ```yaml on: push: branches: - main - 'releases/**' ``` ### 将活动类型和筛选器用于多个事件 如果为事件指定活动类型或筛选器，并且针对多个事件指定工作流触发器，则必须单独配置每个事件。 必须为所有事件附加冒号 (`:`)，包括没有配置的事件。 例如，具有以下 `on` 值的工作流将在以下情况下运行： * 创建标签 * 推送到存储库中的 `main` 分支 * 推送到启用了 GitHub Pages 的分支 ```yaml on: label: types: - created push: branches: - main page_build: ``` ## `on..types` 使用 `on..types` 定义将触发工作流运行的活动类型。 大多数 GitHub 事件由多种活动触发。 例如，当标签为 `label`、`created` 或 `edited` 时，会触发 `deleted`。 通过 `types` 关键词可缩小触发工作流运行的活动类型的范围。 如果只有一种活动类型可触发 Webhook 事件，则不需要 `types` 关键字。 可以使用事件 `types` 的数组。 有关每个事件及其活动类型的详细信息，请参阅 [触发工作流的事件](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/events-that-trigger-workflows)。 ```yaml on: label: types: [created, edited] ``` ## `on..` 使用 `pull_request` 和 `pull_request_target` 事件时，可以将工作流配置为仅针对面向特定分支的拉取请求运行。 如果要包含分支名称模式或同时包含和排除分支名称模式，请使用 `branches` 筛选器。 当您只想排除分支名称模式时，请使用 `branches-ignore` 筛选器。 不能对工作流中的同一事件同时使用 `branches` 和 `branches-ignore` 筛选器。 如果你同时定义 `branches`/`branches-ignore` 和 [`paths`/`paths-ignore`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore)，则工作流将只在这两个筛选器都满足条件时运行。 `branches` 和 `branches-ignore` 关键词接受使用 `*`、`**`、`+`、`?` 和 `!` 等字符匹配多个路径名称的 glob 模式。 如果名称包含其中任一字符，而你想要逐字匹配，则需要使用 `\` 转义每个特殊字符。 有关 glob 模式的详细信息，请参阅 [GitHub Actions 的工作流语法](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#filter-pattern-cheat-sheet)。 ### 示例：包括分支 在 `branches` 中定义的模式会针对 Git ref 的名称进行评估。 例如，对于目标为以下内容的拉取请求，每当发生 `pull_request` 事件时，以下工作流都会运行： * 名为 `main` 的分支 (`refs/heads/main`) * 名为 `mona/octocat` 的分支 (`refs/heads/mona/octocat`) * 名称以 `releases/` 开头的分支，如 `releases/10` (`refs/heads/releases/10`) ```yaml on: pull_request: # Sequence of patterns matched against refs/heads branches: - main - 'mona/octocat' - 'releases/**' ``` 如果工作流需要在合并之前通过，则不应使用路径或分支筛选来跳过工作流运行。 有关详细信息，请参阅 [跳过工作流程运行](/zh/enterprise-server@3.22/actions/how-tos/manage-workflow-runs/skip-workflow-runs) 和 [规则集的可用规则](/zh/enterprise-server@3.22/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-workflows-to-pass-before-merging)。 如果因分支筛选、[路径筛选](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore)或[提交消息](/zh/enterprise-server@3.22/actions/how-tos/manage-workflow-runs/skip-workflow-runs)而跳过某工作流，则与该工作流关联的检查将保持为“挂起”状态。 要求这些检查必须通过的拉取请求将无法合并。 ### 示例：排除分支 当模式与 `branches-ignore` 模式匹配时，工作流将不会运行。 在 `branches-ignore` 中定义的模式根据 Git 引用的名称进行评估。 例如，除非拉取请求面向以下内容，否则每当有 `pull_request` 事件时，以下工作流都会运行： * 名为 `mona/octocat` 的分支 (`refs/heads/mona/octocat`) * 名称匹配 `releases/**-alpha` 的分支，如 `releases/beta/3-alpha` (`refs/heads/releases/beta/3-alpha`) ```yaml on: pull_request: # Sequence of patterns matched against refs/heads branches-ignore: - 'mona/octocat' - 'releases/**-alpha' ``` ### 示例：包括和排除分支 不能在单个工作流中使用 `branches` 和 `branches-ignore` 筛选同一事件。 如果要同时包括和排除单个事件的分支模式，请使用 `branches` 筛选器以及 `!` 字符来指示应排除哪些分支或标记。 如果使用字符 `!` 定义分支，则还必须至少定义一个没有 `!` 字符的分支。 如果只想排除分支，请改用 `branches-ignore`。 您定义模式事项的顺序。 * 肯定匹配后的匹配否定模式（前缀为 `!`）将排除 Git 引用。 * 否定匹配后的匹配肯定模式将再次包含 Git 引用。 以下工作流将在针对面向 `pull_request` 或 `releases/10` 的拉取请求的 `releases/beta/mona` 事件上运行，但不针对面向 `releases/10-alpha` 或 `releases/beta/3-alpha` 的拉取请求，由于负模式，`!releases/**-alpha` 将遵循正模式。 ```yaml on: pull_request: branches: - 'releases/**' - '!releases/**-alpha' ``` ## `on.push.` 使用 `push` 事件时，可以将工作流配置为在特定分支或标记上运行。 如果要包含分支名称模式或要同时包含和排除分支名称模式，请使用 `branches` 筛选器。 只希望排除分支名称时，请使用 `branches-ignore` 筛选器。 不能对工作流中的同一事件同时使用 `branches` 和 `branches-ignore` 筛选器。 如果要包含标记名称模式或要同时包含和排除标记名称模式，请使用 `tags` 筛选器。 只需要排除标记名称模式时，请使用 `tags-ignore` 筛选器。 不能对工作流中的同一事件同时使用 `tags` 和 `tags-ignore` 筛选器。 如果仅定义了 `tags`/`tags-ignore` 或者仅定义了 `branches`/`branches-ignore`，那么对于影响未定义的 Git 引用的事件，工作流将不会运行。如果既未定义 `tags`/`tags-ignore` 也未定义 `branches`/`branches-ignore`，则工作流将针对影响分支或标记的事件运行。 如果你同时定义 `branches`/`branches-ignore` 和 [`paths`/`paths-ignore`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore)，则工作流将只在这两个筛选器都满足条件时运行。 `branches`、`branches-ignore`、`tags` 和 `tags-ignore` 关键词接受使用 `*`、`**`、`+`、`?` 和 `!` 等字符匹配多个分支或标记名称的 glob 模式。 如果名称包含其中任一字符，而你想要逐字匹配，则需要使用 \_\_ 转义每个特殊字符。 有关 glob 模式的详细信息，请参阅 [GitHub Actions 的工作流语法](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#filter-pattern-cheat-sheet)。 ### 示例：包括分支和标记 在 `branches` 和 `tags` 中定义的模式根据 Git ref 的名称进行评估。 例如，当以下项出现 `push` 事件时，将运行以下工作流： * 名为 `main` 的分支 (`refs/heads/main`) * 名为 `mona/octocat` 的分支 (`refs/heads/mona/octocat`) * 名称以 `releases/` 开头的分支，如 `releases/10` (`refs/heads/releases/10`) * 名为 `v2` 的标记 (`refs/tags/v2`) * 名称以 `v1.` 开头的标记，如 `v1.9.1` (`refs/tags/v1.9.1`) ```yaml on: push: # Sequence of patterns matched against refs/heads branches: - main - 'mona/octocat' - 'releases/**' # Sequence of patterns matched against refs/tags tags: - v2 - v1.* ``` ### 示例：排除分支和标记 当某个模式与 `branches-ignore` 或 `tags-ignore` 模式匹配时，工作流将不会运行。 在 `branches` 和 `tags` 中定义的模式根据 Git ref 的名称进行评估。 例如，只要出现 `push` 事件，就会运行以下工作流，除非以下项出现 `push` 事件： * 名为 `mona/octocat` 的分支 (`refs/heads/mona/octocat`) * 名称与 `releases/**-alpha` 匹配的分支，如 `releases/beta/3-alpha` (`refs/heads/releases/beta/3-alpha`) * 名为 `v2` 的标记 (`refs/tags/v2`) * 名称以 `v1.` 开头的标记，如 `v1.9` (`refs/tags/v1.9`) ```yaml on: push: # Sequence of patterns matched against refs/heads branches-ignore: - 'mona/octocat' - 'releases/**-alpha' # Sequence of patterns matched against refs/tags tags-ignore: - v2 - v1.* ``` ### 示例：包括和排除分支和标签 不能在一个工作流中使用 `branches` 和 `branches-ignore` 筛选同一事件。 同样，不能在一个工作流中使用 `tags` 和 `tags-ignore` 筛选同一事件。 如果要同时包括和排除一个事件的分支或标记模式，请使用 `branches` 或 `tags` 筛选器以及 `!` 字符来指示应排除哪些分支或标记。 如果使用字符 `!` 定义分支，则还必须至少定义一个没有 `!` 字符的分支。 如果只想排除分支，请改用 `branches-ignore`。 同样，如果使用字符 `!` 定义标记，则还必须至少定义一个没有 `!` 字符的标记。 如果只想排除标记，请改用 `tags-ignore`。 您定义模式事项的顺序。 * 肯定匹配后的匹配否定模式（前缀为 `!`）将排除 Git 引用。 * 否定匹配后的匹配肯定模式将再次包含 Git 引用。 以下工作流将在推送到 `releases/10` 或 `releases/beta/mona` 时运行，但不在推送到 `releases/10-alpha` 或 `releases/beta/3-alpha` 时运行，因为否定模式 `!releases/**-alpha` 遵循肯定模式。 ```yaml on: push: branches: - 'releases/**' - '!releases/**-alpha' ``` ## `on..` 使用 `push` 和 `pull_request` 事件时，可以配置工作流以根据更改的文件路径运行。 路径筛选器不会对标签推送进行评估。 如果想要包括文件路径模式或想要同时包括和排除文件路径模式，请使用 `paths` 筛选器。 如果只想排除文件路径模式，请使用 `paths-ignore` 筛选器。 不能对工作流中的同一事件同时使用 `paths` 和 `paths-ignore` 筛选器。 如果要同时包括和排除单个事件的路径模式，请使用前缀为 `paths` 字符的 `!` 筛选器来指示应排除哪些路径。 > \[!NOTE] > 您定义 `paths` 模式的顺序很重要： > > * 在正向匹配之后，如果又匹配到否定模式（前缀为 `!`），则将排除该路径。 > * 在负向匹配之后出现的正向模式会再次包含该路径。 如果你同时定义 `branches`/`branches-ignore` 筛选器和 `paths`/`paths-ignore` 筛选器，则工作流将只在这两个筛选器都满足条件时运行。 `paths` 和 `paths-ignore` 关键字支持 glob 模式，这些模式使用 `*` 和 `**` 通配符字符来匹配多个路径名。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#filter-pattern-cheat-sheet)”。 ### 示例：包括路径 如果至少一个路径与 `paths` 筛选器中的模式匹配，则工作流将运行。 例如，只要推送 JavaScript 文件 (`.js`)，就会运行以下工作流。 ```yaml on: push: paths: - '**.js' ``` 如果工作流需要在合并之前通过，则不应使用路径或分支筛选来跳过工作流运行。 有关详细信息，请参阅 [跳过工作流程运行](/zh/enterprise-server@3.22/actions/how-tos/manage-workflow-runs/skip-workflow-runs) 和 [规则集的可用规则](/zh/enterprise-server@3.22/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-workflows-to-pass-before-merging)。 如果因路径筛选、[分支筛选](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#onpull_requestpull_request_targetbranchesbranches-ignore)或[提交消息](/zh/enterprise-server@3.22/actions/how-tos/manage-workflow-runs/skip-workflow-runs)而跳过某工作流，则与该工作流关联的检查将保持为“挂起”状态。 要求这些检查成功的拉取请求将被阻止合并。 ### 示例：排除路径 当所有路径名称匹配 `paths-ignore` 中的模式时，工作流不会运行。 如果任何路径名与 `paths-ignore` 中的模式不匹配，即使某些路径名与模式匹配，工作流也会运行。 具有以下路径筛选器的工作流将仅在 `push` 事件上运行，这些事件包括至少一个位于存储库根目录的 `docs` 目录外的文件。 ```yaml on: push: paths-ignore: - 'docs/**' ``` ### 示例：包括和排除路径 不能在单个工作流中使用 `paths` 和 `paths-ignore` 筛选同一事件。 如果要同时包括和排除单个事件的路径模式，请使用前缀为 `!` 字符的 `paths` 筛选器来指示应排除哪些路径。 如果使用 `!` 字符定义路径，则还必须定义至少一个不带 `!` 字符的路径。 如果只想排除路径，请改用 `paths-ignore`。 您定义 `paths` 模式事项的顺序： * 肯定匹配后的匹配否定模式（前缀为 `!`）将排除路径。 * 否定匹配后的匹配肯定模式将再次包含路径。 只要 `push` 事件包括 `sub-project` 目录或其子目录中的文件，此示例就会运行，除非该文件在 `sub-project/docs` 目录中。 例如，更改了 `sub-project/index.js` 或 `sub-project/src/index.js` 的推送将会触发工作流运行，但只更改 `sub-project/docs/readme.md` 的推送不会触发。 ```yaml on: push: paths: - 'sub-project/**' - '!sub-project/docs/**' ``` ### Git 差异比较 筛选器通过评估更改的文件并针对 `paths-ignore` 或 `paths` 列表运行它们来确定是否应运行工作流。 如果没有更改文件，工作流程将不会运行。 GitHub 对于推送使用双点差异比较，对于拉取请求使用三点差异比较来生成已更改文件的列表： * **拉取请求：** 三点比较是指对主题分支的最新版本与主题分支上次与基础分支同步时所在提交之间的比较。 * **推送到现有分支：** 双点差异直接相互比较头部和基础 SHA。 * **推送到新分支：** 根据已推送最深提交的上级父项的两点差异。 在某些情况下， GitHub Actions 应用更改筛选工作流运行方式的限制： * 如果推送包含超过 1,000 个提交，工作流 **将始终** 运行。 * 如果生成差异超时，工作流 **将始终** 运行。 * 如果生成的差异包含 3,000 多个文件，并且工作流筛选器匹配的文件不在筛选器返回的前 3,000 个文件中，则工作流 **将不会** 运行。 如果观察到这些行为，则可能需要使筛选器更加具体，或更改处理推送和拉取请求的方式，以生成更简单的差异。 有关详细信息，请参阅“[分支](/zh/enterprise-server@3.22/pull-requests/reference/branches)”。 ## `on.schedule` 可以使用 `on.schedule` 定义工作流的时间计划。 使用 [POSIX cron 语法](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07) 计划工作流在特定时间运行。 默认情况下，计划的工作流以 UTC 方式运行。 可以选择使用 [IANA 时区字符串](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)指定时区，以 UTC工作流。 计划的工作流在默认分支的最新提交上运行。 您可以运行预定工作流程的最短间隔是每 5 分钟一次。 > \[!NOTE] > 对于设置为 `timezone` 观察夏令时（DST）的时区（DST）的计划，在 DST 春季前移转换期间，计划工作流将提前数小时前进到下一个有效时间。 例如，上午 2：30 的计划将提前到凌晨 3：00。 计划任务语法有五个字段，中间用空格分隔，每个字段代表一个时间单位。 ```text ┌───────────── minute (0 - 59) │ ┌───────────── hour (0 - 23) │ │ ┌───────────── day of the month (1 - 31) │ │ │ ┌───────────── month (1 - 12 or JAN-DEC) │ │ │ │ ┌───────────── day of the week (0 - 6 or SUN-SAT) │ │ │ │ │ * * * * * ``` 你可在这五个字段中使用以下运算符： | 运算符 | 说明 | 示例 | | ---------------------------------------------------------------- | ------ | -- | | \* | 任何值 | | | `15 * * * *` 在每天每小时的每个第 15 分钟运行。 | | | | " | 值列表分隔符 | | | `2,10 4,5 * * *` 在每天第 4 和第 5 小时的第 2 和第 10 分钟运行。 | | | | - | 值的范围 | | | `30 4-6 * * *` 在第 4、5 和 6 小时的第 30 分钟运行。 | | | | / | 步骤值 | | | `20/15 * * * *` 从第 20 分钟到第 59 分钟之间每隔 15 分钟运行一次（第 20、35 和 50 分钟）。 | | | 本示例触发工作流在美国/纽约时区每周一到周五的凌晨5:30运行。 ```yaml on: schedule: - cron: '30 5 * * 1-5' timezone: "America/New_York" ``` 多个 `schedule` 事件可以触发单个工作流。 通过 `schedule` 上下文访问触发工作流的 `github.event.schedule` 事件。 此示例触发工作流在每周一至周四 UTC 时间 5:30 以及周二和周四 UTC 时间 17:30 运行，但在周一和周三跳过 `Not on Monday or Wednesday` 步骤。 ```yaml on: schedule: - cron: '30 5 * * 1,3' - cron: '30 5,17 * * 2,4' jobs: test_schedule: runs-on: ubuntu-latest steps: - name: Not on Monday or Wednesday if: github.event.schedule != '30 5 * * 1,3' run: echo "This step will be skipped on Monday and Wednesday" - name: Every time run: echo "This step will always run" ``` 有关 `schedule` 事件的详细信息，请参阅 [触发工作流的事件](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/events-that-trigger-workflows#schedule)。 ## `on.workflow_call` 使用 `on.workflow_call` 定义可重用工作流的输入和输出。 您还可以映射可用于被调用工作流程的机密。 有关可重用工作流的详细信息，请参阅“[重用工作流](/zh/enterprise-server@3.22/actions/how-tos/reuse-automations/reuse-workflows)”。 ## `on.workflow_call.inputs` 使用 `workflow_call` 关键字时，可以选择指定从调用方工作流传递到被调用工作流的输入。 有关 `workflow_call` 关键字的详细信息，请参阅 [触发工作流的事件](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/events-that-trigger-workflows#workflow_call)。 除了可用的标准输入参数外，`on.workflow_call.inputs` 还需要一个 `type` 参数。 有关详细信息，请参阅 [`on.workflow_call.inputs..type`](#onworkflow_callinputsinput_idtype)。 如果未设置 `default` 参数，则对布尔值、数字和字符串来说，输入的默认值依次为 `false`、`0` 和 `""`。 在被调用的工作流中，可以使用 `inputs` 上下文来引用输入。 有关详细信息，请参阅“[上下文参考](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#inputs-context)”。 如果调用方工作流程传递的输入未在被调用工作流程中指定，则会导致错误。 ### `on.workflow_call.inputs` 的示例 ```yaml on: workflow_call: inputs: username: description: 'A username passed from the caller workflow' default: 'john-doe' required: false type: string jobs: print-username: runs-on: ubuntu-latest steps: - name: Print the input name to STDOUT run: echo The username is ${{ inputs.username }} ``` 有关详细信息，请参阅“[重用工作流](/zh/enterprise-server@3.22/actions/how-tos/reuse-automations/reuse-workflows)”。 ## `on.workflow_call.inputs..type` 如果为 `on.workflow_call` 关键字定义了输入，则为必需。 此参数的值是指定输入的数据类型的字符串。 其必须是 `boolean`、`number` 或 `string`。 ## `on.workflow_call.outputs` 被调用工作流程的输出映射。 调用的工作流程输出可用于调用方工作流程中的所有下游作业。 每个输出都有一个标识符、一个可选 `description,` 和一个 `value.`。必须将 `value` 设置为被调用工作流内作业中的输出值。 在下面的示例中，为此可重用工作流定义了两个输出：`workflow_output1` 和 `workflow_output2`。 这些输出被映射为 `job_output1` 和 `job_output2`，两者均来自称为 `my_job` 的作业。 ### `on.workflow_call.outputs` 的示例 ```yaml on: workflow_call: # Map the workflow outputs to job outputs outputs: workflow_output1: description: "The first job output" value: ${{ jobs.my_job.outputs.job_output1 }} workflow_output2: description: "The second job output" value: ${{ jobs.my_job.outputs.job_output2 }} ``` 有关如何引用作业输出的信息，请参阅 [`jobs..outputs`](#jobsjob_idoutputs)。 有关详细信息，请参阅“[重用工作流](/zh/enterprise-server@3.22/actions/how-tos/reuse-automations/reuse-workflows)”。 ## `on.workflow_call.secrets` 可在被调用工作流程中使用的机密的映射。 在调用的工作流中，可以使用 `secrets` 上下文来引用机密。 > \[!NOTE] > 如果要将机密传递给嵌套的可重用工作流，则必须再次使用 [`jobs..secrets`](#jobsjob_idsecrets) 来传递机密。 有关详细信息，请参阅“[重用工作流](/zh/enterprise-server@3.22/actions/how-tos/reuse-automations/reuse-workflows#passing-secrets-to-nested-workflows)”。 如果调用方工作流程传递的机密未在被调用的工作流程中指定，则会导致错误。 ### `on.workflow_call.secrets` 的示例 ```yaml on: workflow_call: secrets: access-token: description: 'A token passed from the caller workflow' required: false jobs: pass-secret-to-action: runs-on: ubuntu-latest steps: # passing the secret to an action - name: Pass the received secret to an action uses: ./.github/actions/my-action with: token: ${{ secrets.access-token }} # passing the secret to a nested reusable workflow pass-secret-to-workflow: uses: ./.github/workflows/my-workflow secrets: token: ${{ secrets.access-token }} ``` ## `on.workflow_call.secrets.` 用于与机密关联的字符串标识符。 ## `on.workflow_call.secrets..required` 指定一个布尔变量来表明该机密值是否必须提供。 ## `on.workflow_run.` 使用 `workflow_run` 事件时，可以指定触发工作流必须在哪些分支上运行才能触发工作流。 `branches` 和 `branches-ignore` 筛选器接受使用 `*`、`**`、`+`、`?` 和 `!` 等字符匹配多个分支名称的 glob 模式。 如果名称包含这些字符中的任意一个，而你想按字面匹配，则需要使用 \_\_ 对这些特殊字符中的每一个进行 `\`。 有关 glob 模式的详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#filter-pattern-cheat-sheet)”。 例如，仅当名为 `Build` 的工作流在名称以 `releases/` 开头的分支上运行时，具有以下触发器的工作流才会运行： ```yaml on: workflow_run: workflows: ["Build"] types: [requested] branches: - 'releases/**' ``` 仅当名为 `Build` 的工作流不在名为 `canary` 的分支上运行时，具有以下触发器的工作流才会运行： ```yaml on: workflow_run: workflows: ["Build"] types: [requested] branches-ignore: - "canary" ``` 不能对工作流中的同一事件同时使用 `branches` 和 `branches-ignore` 筛选器。 如果要同时包括和排除单个事件的分支模式，请使用 `branches` 筛选器以及 `!` 字符来指示应排除哪些分支。 您定义模式的顺序很重要。 * 在正向匹配之后，如果又匹配到一个否定模式（前缀为 `!`），则该分支将被排除。 * 在否定匹配之后，匹配的肯定模式会再次包含该分支。 例如，当名为 `Build` 的工作流在名为 `releases/10` 或 `releases/beta/mona` 但不在名为 `releases/10-alpha`、`releases/beta/3-alpha` 或 `main` 的分支上运行时，具有以下触发器的工作流将运行。 ```yaml on: workflow_run: workflows: ["Build"] types: [requested] branches: - 'releases/**' - '!releases/**-alpha' ``` ## `on.workflow_dispatch` 使用 `workflow_dispatch` 事件时，你可以选择性指定传递到工作流的输入。 此触发器仅当工作流文件位于默认分支时接收事件。 ## `on.workflow_dispatch.inputs` 触发的工作流接收 `inputs` 上下文中的输入。 有关详细信息，请参阅“[上下文](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#inputs-context)”。 > \[!NOTE] > > * 工作流还将接收 `github.event.inputs` 上下文中的输入。 > `inputs` 上下文和 `github.event.inputs` 上下文中的信息完全相同，但 `inputs` 上下文将布尔值保留为布尔值，而不是将它们转换为字符串。 > `choice` 类型解析为字符串，是单个可选选项。 > * 顶级属性 `inputs` 的最大数目为 10 。 > * `inputs` 的最大有效负载为 65,535 个字符。 ### `on.workflow_dispatch.inputs` 的示例 ```yaml on: workflow_dispatch: inputs: logLevel: description: 'Log level' required: true default: 'warning' type: choice options: - info - warning - debug print_tags: description: 'True to print to STDOUT' required: true type: boolean tags: description: 'Test scenario tags' required: true type: string environment: description: 'Environment to run tests against' type: environment required: true jobs: print-tag: runs-on: ubuntu-latest if: ${{ inputs.print_tags }} steps: - name: Print the input tag to STDOUT run: echo The tags are ${{ inputs.tags }} ``` ## `on.workflow_dispatch.inputs..required` 指定是否必须提供输入的布尔值。 ## `on.workflow_dispatch.inputs..type` 此参数的值是指定输入的数据类型的字符串。 这必须是 `boolean`、`choice`、`number`、`environment` 或 `string`。 ## `permissions` 可以使用 `permissions` 修改授予 `GITHUB_TOKEN` 的默认权限，根据需要添加或删除访问权限，以便只授予所需的最低访问权限。 有关详细信息，请参阅“[在工作流中使用 GITHUB\_TOKEN 进行身份验证](/zh/enterprise-server@3.22/actions/tutorials/authenticate-with-github_token#modifying-the-permissions-for-the-github_token)”。 可以使用 `permissions` 作为顶级密钥，以应用于工作流中的所有作业或特定作业。 当你在特定作业中添加 `permissions` 密钥时，该作业中使用 `GITHUB_TOKEN` 的所有操作和运行命令都将获得你指定的访问权限。 有关详细信息，请参阅 [`jobs..permissions`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idpermissions)。 组织 或企业 的所有者可以在存储库级别限制 `GITHUB_TOKEN` 的写入权限。 有关详细信息，请参阅 [禁用或限制组织的 GitHub Actions](/zh/enterprise-server@3.22/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#setting-the-permissions-of-the-github_token-for-your-organization) 和 [在企业中强制实施GitHub Actions策略](/zh/enterprise-server@3.22/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#enforcing-a-policy-for-workflow-permissions-in-your-enterprise)。 当工作流由 [`pull_request_target`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request_target) 事件触发时，将授予 `GITHUB_TOKEN` 读/写存储库权限，即使从公共分支触发也是如此。 有关详细信息，请参阅“[触发工作流的事件](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request_target)”。 对于下表中显示的每个可用权限，可以分配以下访问级别之一：`read`（如果适用）、`write` 或 `none`。 `write` 包括 `read`。 如果你指定其中任何权限的访问权限，则所有未指定的作用域都被设置为 `none`。 可用的权限以及每个权限允许执行的操作的详细信息： | 权限 | 允许操作使用 `GITHUB_TOKEN` | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `actions` | 使用 GitHub Actions。 例如，`actions: write` 允许操作取消工作流运行。 有关详细信息，请参阅“[GitHub应用所需的权限](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-actions)”。 | | | | | | | | `checks` | 使用检查运行和检查套件。 例如，`checks: write` 允许操作创建检查运行。 有关详细信息，请参阅“[GitHub应用所需的权限](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-checks)”。 | | | | | `contents` | 处理存储库的内容。 例如，`contents: read` 允许操作列出提交，`contents: write` 允许操作创建发布。 有关详细信息，请参阅“[GitHub应用所需的权限](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-contents)”。 | | `deployments` | 处理部署。 例如，`deployments: write` 允许操作创建新部署。 有关详细信息，请参阅“[GitHub应用所需的权限](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-deployments)”。 | | `discussions` | 使用 GitHub Discussions。 例如，`discussions: write` 允许操作关闭或删除讨论。 有关详细信息，请参阅“[使用 GraphQL API 进行讨论](/zh/enterprise-server@3.22/graphql/guides/using-the-graphql-api-for-discussions)”。 | | | | | `issues` | 处理问题。 例如，`issues: write` 允许操作向问题添加注释。 有关详细信息，请参阅“[GitHub应用所需的权限](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-issues)”。 | | `packages` | 使用 GitHub Packages。 例如，`packages: write` 允许操作在 GitHub Packages 上上传和发布包。 有关详细信息，请参阅“[关于 GitHub Packages 的权限](/zh/enterprise-server@3.22/packages/learn-github-packages/about-permissions-for-github-packages#about-scopes-and-permissions-for-package-registries)”。 | | `pages` | 使用 GitHub Pages。 例如，`pages: write` 允许操作请求 GitHub Pages 生成。 有关详细信息，请参阅“[GitHub应用所需的权限](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-pages)”。 | | `pull-requests` | 处理拉取请求。 例如，`pull-requests: write` 允许操作向拉取请求添加标签。 有关详细信息，请参阅“[GitHub应用所需的权限](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-pull-requests)”。 | | `security-events` | 处理 GitHub 代码扫描警报。 例如，`security-events: read` 允许操作列出存储库的代码扫描警报，而 `security-events: write` 允许操作更新代码扫描警报的状态。 有关详细信息，请参阅 [“代码扫描警报”的存储库权限](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-code-scanning-alerts)。

| | 。 有关详细信息，请参阅“GitHub 应用所需的权限”中的 [“Dependabot 警报”](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-dependabot-alerts) 和 [存储库权限中的“机密扫描警报](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-secret-scanning-alerts) ”。 | | | `statuses` | 处理提交状态。 例如，`statuses:read` 允许操作列出给定引用的提交状态。 有关详细信息，请参阅“[GitHub应用所需的权限](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-commit-statuses)”。 | | | | ### 为 `GITHUB_TOKEN` 范围定义访问权限 可以通过将 `GITHUB_TOKEN`、`read` 或 `write` 指定为 `none` 键中可用权限的值来定义 `permissions` 将允许的访问。 ```yaml permissions: actions: read|write|none checks: read|write|none contents: read|write|none deployments: read|write|none issues: read|write|none discussions: read|write|none packages: read|write|none pages: read|write|none pull-requests: read|write|none security-events: read|write|none statuses: read|write|none ``` 如果为其中任何权限指定了访问权限，则所有未指定的权限都将设置为 `none`。 可以使用以下语法来定义所有可用权限中的一种访问类型：`read-all` 或 `write-all` 访问。 ```yaml permissions: read-all ``` ```yaml permissions: write-all ``` 可以使用以下语法来禁用所有可用的权限： ```yaml permissions: {} ``` #### 更改分支存储库中的权限 可以使用 `permissions` 密钥添加和删除分叉存储库的读取权限，但通常不能授予其写入权限。 此行为的例外情况是，管理员用户在设置中选择了“从拉取请求发送写入令牌到工作流”选项。 有关详细信息，请参阅“[管理存储库的GitHub Actions设置](/zh/enterprise-server@3.22/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-forks-of-private-repositories)”。 ### 如何计算工作流作业的权限 `GITHUB_TOKEN` 的权限最初设置为企业、组织或存储库的默认设置。 如果默认设置为任何一个级别的限制权限，则将适用于相关的库。 例如，如果您在组织级别选择受限制的默认值，则该组织中的所有仓库将使用限制的权限作为默认值。 然后根据工作流程文件中的任何配置（首先在工作流程级别，然后在作业级别）对权限进行调整。 最后，如果工作流是由分叉存储库以外的 `pull_request_target` 拉取请求事件触发的，并且未选择 **从拉取请求设置将写入令牌发送到工作流** ，则会调整权限以将任何写入权限更改为只读。 ### 为工作流中的所有作业设置 `GITHUB_TOKEN` 权限 可以在工作流的顶层指定 `permissions`，以便设置应用于工作流中的所有作业。 #### 示例：为整个工作流设置 `GITHUB_TOKEN` 权限 此示例显示为将要应用到工作流中所有作业的 `GITHUB_TOKEN` 设置的权限。 所有权限都被授予读取权限。 ```yaml name: "My workflow" on: [ push ] permissions: read-all jobs: ... ``` ### 对分支存储库使用 `permissions` 键 可以使用 `permissions` 键为分支存储库添加和删除 `read` 权限，但通常不能授予 `write` 访问权限。 此行为的例外情况是管理员用户在 \*\*\*\* 设置中选择了“从拉取请求向工作流发送写入令牌”GitHub Actions选项。 有关详细信息，请参阅“[管理存储库的GitHub Actions设置](/zh/enterprise-server@3.22/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-forks-of-private-repositories)”。 ### Dependabot 触发的工作流运行权限 由 Dependabot 拉取请求触发的工作流运行被视为来自分支存储库，因此会使用只读的 `GITHUB_TOKEN`。 这些工作流运行无法访问任何机密信息。 有关保护这些工作流安全的策略的信息，请参阅“[安全使用指南](/zh/enterprise-server@3.22/actions/reference/security/secure-use)”。 ## `env` 可用于工作流中所有作业步骤的变量集合 `map`。 还可以设置仅适用于单个作业的步骤或单个步骤的变量。 有关详细信息，请参阅 [`jobs..env`](#jobsjob_idenv) 和 [`jobs..steps[*].env`](#jobsjob_idstepsenv)。 `env` 映射中的变量不能根据映射中的其他变量进行定义。 当多个环境变量使用相同的名称定义时，GitHub 会使用最特定的变量。 例如，步骤中定义的环境变量在步骤执行时将覆盖名称相同的作业和工作流环境变量。 为作业定义的环境变量在作业执行时将覆盖名称相同的工作流变量。 ### `env` 的示例 ```yaml env: SERVER: production ``` ## `defaults` 使用 `defaults` 创建将应用于工作流中所有作业的默认设置的 `map`。 您也可以设置只可用于作业的默认设置。 有关详细信息，请参阅 [`jobs..defaults`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_iddefaults)。 使用相同名称定义了多个默认设置时，GitHub 会使用最具体的默认设置。 例如，在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。 ## `defaults.run` 你可以使用 `defaults.run` 为工作流中所有 `working-directory` 步骤提供默认的 `run` 和 [](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsrun) 选项。 你也可以为只可用于作业的 `run` 设定默认设置。 有关详细信息，请参阅 [`jobs..defaults.run`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_iddefaultsrun)。 您不能在此关键词中使用上下文或表达式。 使用相同名称定义了多个默认设置时，GitHub 会使用最具体的默认设置。 例如，在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。 ### 示例：设置默认 shell 和工作目录 ```yaml defaults: run: shell: bash working-directory: ./scripts ``` ## `defaults.run.shell` 使用 `shell` 为步骤定义 `shell`。 此关键字可以引用多个上下文。 有关详细信息，请参阅“[上下文](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#context-availability)”。 | 支持的平台 | `shell` 参数 | 说明 | 内部运行命令 | | ----------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | | Linux/macOS | unspecified | 非 Windows 平台上的默认 shell。 请注意，这与显式指定 `bash` 时运行的命令不同。 如果在路径中找不到 `bash`，则将其视为 `sh`。 | `bash -e {0}` | | All | `bash` | 非 Windows 平台上回退到 `sh` 的默认 shell。 指定 Windows 上的 bash shell 时，将使用 Git for Windows 随附的 bash shel。 | `bash --noprofile --norc -eo pipefail {0}` | | 全部 | `pwsh` | PowerShell Core。 GitHub 将扩展名 `.ps1` 追加到你的脚本名称。 | `pwsh -command ". '{0}'"` | | All | `python` | 执行 python 命令。 | `python {0}` | | Linux/macOS | `sh` | 未提供 shell 且在路径中找不到 `bash` 时的非 Windows 平台的后退行为。 | `sh -e {0}` | | Windows | `cmd` | GitHub 将扩展名 `.cmd` 追加到你的脚本名称并替换 `{0}`。 | `%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}""`。 | | Windows | `pwsh` | 这是 Windows 上使用的默认 shell。 PowerShell Core。 GitHub 将扩展名 `.ps1` 追加到你的脚本名称。 如果自承载 Windows 运行器未安装 PowerShell Core，则改用 PowerShell Desktop。 | `pwsh -command ". '{0}'"`。 | | Windows | `powershell` | PowerShell 桌面。 GitHub 将扩展名 `.ps1` 追加到你的脚本名称。 | `powershell -command ". '{0}'"`。 | 使用相同名称定义了多个默认设置时，GitHub 会使用最具体的默认设置。 例如，在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。 ## `defaults.run.working-directory` 使用 `working-directory` 为步骤定义用于 `shell` 的工作目录。 此关键字可以引用多个上下文。 有关详细信息，请参阅“[上下文](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#context-availability)”。 > \[!TIP] > 在运行 shell 之前，请确保你分配的 `working-directory` 在运行器上存在。 > 使用相同名称定义了多个默认设置时，GitHub 会使用最具体的默认设置。 例如，在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。 ## `concurrency` 使用 `concurrency` 以确保只有使用相同并发组的单一作业或工作流才会同时运行。 并发组可以是任何字符串或表达式。 表达式只能使用 [`github`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#github-context)、[`inputs`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#inputs-context) 和 [`vars`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#vars-context) 上下文。 有关表达式的详细信息，请参阅“[对工作流和操作中的表达式求值](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/expressions)”。 你还可以在作业级别指定 `concurrency`。 有关详细信息，请参阅 [`jobs..concurrency`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idconcurrency)。 这意味着在任何时候，一个并发组中最多只能同时有一个正在运行的作业和一个待处理的作业。 当并发作业或工作流排队时，如果存储库中使用同一并发组的其他作业或工作流正在运行，则排队的作业或工作流将为 `pending`。 将取消同一并发组中的任何现有 `pending` 作业或工作流（如果存在），且新的列队作业或工作流将取代其位置。 若还要取消同一并发组中任何当前正在运行的作业或工作流，请指定 `cancel-in-progress: true`。 若要有条件地取消同一并发组中当前正在运行的作业或工作流，可以将 `cancel-in-progress` 指定为具有任何允许的表达式上下文的表达式。 > \[!NOTE] > > * 并发组名称不区分大小写。 例如，`prod` 和 `Prod` 将被视为同一个并发组。 > * 作业或工作流在同一并发组中运行时，按照每个作业开始等待该并发组的时间，以先进先出（FIFO）的顺序处理，而不是按照每个工作流的分派时间。 由于作业或运行的实际开始时间可能有所不同，因此不能保证排序。 ### 示例：使用并发和默认行为 默认情况下，GitHub Actions 允许多个作业或工作流同时运行。 使用`concurrency` 关键字可以控制工作流运行的并发性。 例如，可以在定义触发器条件以限制特定分支的整个工作流运行的并发之后立即使用 `concurrency` 关键字： ```yaml on: push: branches: - main concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true ``` 还可以通过在作业级别使用 `concurrency` 关键字来限制工作流中作业的并发性： ```yaml on: push: branches: - main jobs: job-1: runs-on: ubuntu-latest concurrency: group: example-group cancel-in-progress: true ``` ### 示例：并发组 并发组提供了一种方法，用于管理和限制共享相同并发密钥的工作流运行或作业的执行。 该 `concurrency` 密钥用于将工作流或作业组合到并发组中。 定义 `concurrency` 密钥时， GitHub Actions 请确保在任何给定时间只运行具有该密钥的一个工作流或作业。 如果新的工作流运行或作业以相同的 `concurrency` 密钥启动， GitHub Actions 将取消已使用该密钥运行的任何工作流或作业。 键 `concurrency` 可以是硬编码字符串，也可以是包含上下文变量的动态表达式。 可以在工作流中定义并发条件，以便工作流或作业是并发组的一部分。 这意味着，当工作流运行或作业启动时，GitHub 将取消同一并发组中正在进行的任何工作流运行或作业。 在想要防止对特定工作流或作业（例如用于部署到过渡环境的工作流或作业）进行并行运行的情况下，这非常有用，以防止可能导致冲突或消耗比必要资源更多的操作。 在此示例中，`job-1` 是名为 `staging_environment` 的并发组的一部分。 如果新运行的 `job-1` 被触发，那么在并发组 `staging_environment` 中已在进行的任何同一作业的运行都将被取消。 ```yaml jobs: job-1: runs-on: ubuntu-latest concurrency: group: staging_environment cancel-in-progress: true ``` 或者，在工作流中使用动态表达式 `concurrency: ci-${{ github.ref }}` 意味着工作流或作业将成为并发组 `ci-` 的一部分，后跟触发工作流的分支或标记的引用。 在此示例中，如果在上一次运行仍在进行中时将新的提交推送到主分支，则会取消上一次运行，并且新运行将启动： ```yaml on: push: branches: - main concurrency: group: ci-${{ github.ref }} cancel-in-progress: true ``` ### 示例：使用并发取消任何当前作业或运行 若要使用并发来取消任何正在进行的任务或运行，可以使用密钥`concurrency`，并将选项`cancel-in-progress`设置为`true`： ```yaml concurrency: group: ${{ github.ref }} cancel-in-progress: true ``` 请注意，在此示例中，如果不定义特定的并发组，GitHub Actions 将取消任何正在进行的\_作业或工作流\_的运行。 ### 示例：使用回退值 如果使用仅为特定事件定义的属性生成组名称，则可以使用回退值。 例如，`github.head_ref` 仅对 `pull_request` 事件定义。 如果工作流响应除了 `pull_request` 事件之外的其他事件，你将需要提供回退以避免语法错误。 以下并发组仅取消针对 `pull_request` 事件正在进行的作业或运行；如果 `github.head_ref` 未定义，并发组将回退到运行 ID，该 ID 保证是唯一的，并且是为该运行定义的。 ```yaml concurrency: group: ${{ github.head_ref || github.run_id }} cancel-in-progress: true ``` ### 示例：仅取消当前工作流中正在进行的作业或运行 如果在同一个存储库中有多个工作流，则并发组名称在工作流中必须是唯一的，以避免从其他工作流取消正在进行的作业或运行。 否则，任何先前进行中或挂起的任务都将被取消，无论工作流如何。 若要仅取消同一工作流中正在进行的运行，可以使用 `github.workflow` 属性来构建并发组。 ```yaml concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true ``` ### 示例：仅取消特定分支上正在进行的作业 如果你想取消某些分支上正在进行的作业，但不想取消其他分支上正在进行的作业，则可以将条件表达式与 `cancel-in-progress` 一起使用。 例如，如果你想取消开发分支上正在进行的作业，但不想取消发布分支上正在进行的作业，则可以执行此操作。 若要仅在未在发布分支上运行时取消同一工作流正在进行的运行，则可以设置表达式的 `cancel-in-progress`，如下所示： ```yaml concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: ${{ !contains(github.ref, 'release/')}} ``` 在此示例中，多次推送到 `release/1.2.3` 分支不会取消正在进行的运行。 推送到另一个分支（例如 `main`）将取消正在进行的运行。 ## `jobs` 工作流运行由一个或多个 `jobs` 组成，默认情况下并行运行。 若要按顺序运行作业，可以使用 `jobs..needs` 关键字定义对其他作业的依赖关系。 每个作业在 `runs-on` 指定的运行器环境中运行。 在工作流程的使用限制之内可运行无限数量的作业。 有关详细信息，请参阅 [](/zh/enterprise-server@3.22/actions/concepts/billing-and-usage) 托管运行器的 GitHub 和自托管运行器使用限制的 [Actions 限制](/zh/enterprise-server@3.22/actions/reference/limits)。 如果需要查找工作流运行中运行的作业的唯一标识符，可以使用 GitHub API。 有关详细信息，请参阅“[GitHub Actions 的 REST API 端点](/zh/enterprise-server@3.22/rest/actions#workflow-jobs)”。 ## `jobs.` 使用 `jobs.` 为作业提供唯一标识符。 键 `job_id` 是一个字符串，其值是作业配置数据的映射。 必须将 `` 替换为对于 `jobs` 对象的唯一字符串。 `` 必须以字母或 `_` 开头，并且只能包含字母数字字符、`-` 或 `_`。 ### 示例：创建作业 在此示例中，已创建两个作业，其 `job_id` 值为 `my_first_job` 和 `my_second_job`。 ```yaml jobs: my_first_job: name: My first job my_second_job: name: My second job ``` ## `jobs..name` 使用 `jobs..name` 设置作业名称，该名称显示在 GitHub UI 中。 ## `jobs..permissions` 在特定的作业中，你可以使用 `jobs..permissions` 修改授予 `GITHUB_TOKEN` 的默认权限，根据需要添加或删除访问权限，以便只授予所需的最低访问权限。 有关详细信息，请参阅“[在工作流中使用 GITHUB\_TOKEN 进行身份验证](/zh/enterprise-server@3.22/actions/tutorials/authenticate-with-github_token#modifying-the-permissions-for-the-github_token)”。 通过在作业定义中指定权限，可根据需要为每个作业的 `GITHUB_TOKEN` 配置一组不同的权限。 或者，您也可以为工作流程中的所有作业指定权限。 有关在工作流级别定义权限的信息，请参阅 [`permissions`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#permissions)。 对于下表中显示的每个可用权限，可以分配以下访问级别之一：`read`（如果适用）、`write` 或 `none`。 `write` 包括 `read`。 如果你指定其中任何权限的访问权限，则所有未指定的作用域都被设置为 `none`。 可用的权限以及每个权限允许执行的操作的详细信息： | 权限 | 允许操作使用 `GITHUB_TOKEN` | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `actions` | 使用 GitHub Actions。 例如，`actions: write` 允许操作取消工作流运行。 有关详细信息，请参阅“[GitHub应用所需的权限](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-actions)”。 | | | | | | | | `checks` | 使用检查运行和检查套件。 例如，`checks: write` 允许操作创建检查运行。 有关详细信息，请参阅“[GitHub应用所需的权限](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-checks)”。 | | | | | `contents` | 处理存储库的内容。 例如，`contents: read` 允许操作列出提交，`contents: write` 允许操作创建发布。 有关详细信息，请参阅“[GitHub应用所需的权限](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-contents)”。 | | `deployments` | 处理部署。 例如，`deployments: write` 允许操作创建新部署。 有关详细信息，请参阅“[GitHub应用所需的权限](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-deployments)”。 | | `discussions` | 使用 GitHub Discussions。 例如，`discussions: write` 允许操作关闭或删除讨论。 有关详细信息，请参阅“[使用 GraphQL API 进行讨论](/zh/enterprise-server@3.22/graphql/guides/using-the-graphql-api-for-discussions)”。 | | | | | `issues` | 处理问题。 例如，`issues: write` 允许操作向问题添加注释。 有关详细信息，请参阅“[GitHub应用所需的权限](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-issues)”。 | | `packages` | 使用 GitHub Packages。 例如，`packages: write` 允许操作在 GitHub Packages 上上传和发布包。 有关详细信息，请参阅“[关于 GitHub Packages 的权限](/zh/enterprise-server@3.22/packages/learn-github-packages/about-permissions-for-github-packages#about-scopes-and-permissions-for-package-registries)”。 | | `pages` | 使用 GitHub Pages。 例如，`pages: write` 允许操作请求 GitHub Pages 生成。 有关详细信息，请参阅“[GitHub应用所需的权限](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-pages)”。 | | `pull-requests` | 处理拉取请求。 例如，`pull-requests: write` 允许操作向拉取请求添加标签。 有关详细信息，请参阅“[GitHub应用所需的权限](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-pull-requests)”。 | | `security-events` | 处理 GitHub 代码扫描警报。 例如，`security-events: read` 允许操作列出存储库的代码扫描警报，而 `security-events: write` 允许操作更新代码扫描警报的状态。 有关详细信息，请参阅 [“代码扫描警报”的存储库权限](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-code-scanning-alerts)。

| | 。 有关详细信息，请参阅“GitHub 应用所需的权限”中的 [“Dependabot 警报”](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-dependabot-alerts) 和 [存储库权限中的“机密扫描警报](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-secret-scanning-alerts) ”。 | | | `statuses` | 处理提交状态。 例如，`statuses:read` 允许操作列出给定引用的提交状态。 有关详细信息，请参阅“[GitHub应用所需的权限](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-commit-statuses)”。 | | | | ### 为 `GITHUB_TOKEN` 范围定义访问权限 可以通过将 `GITHUB_TOKEN`、`read` 或 `write` 指定为 `none` 键中可用权限的值来定义 `permissions` 将允许的访问。 ```yaml permissions: actions: read|write|none checks: read|write|none contents: read|write|none deployments: read|write|none issues: read|write|none discussions: read|write|none packages: read|write|none pages: read|write|none pull-requests: read|write|none security-events: read|write|none statuses: read|write|none ``` 如果为其中任何权限指定了访问权限，则所有未指定的权限都将设置为 `none`。 可以使用以下语法来定义所有可用权限中的一种访问类型：`read-all` 或 `write-all` 访问。 ```yaml permissions: read-all ``` ```yaml permissions: write-all ``` 可以使用以下语法来禁用所有可用的权限： ```yaml permissions: {} ``` #### 更改分支存储库中的权限 可以使用 `permissions` 密钥添加和删除分叉存储库的读取权限，但通常不能授予其写入权限。 此行为的例外情况是，管理员用户在设置中选择了“从拉取请求发送写入令牌到工作流”选项。 有关详细信息，请参阅“[管理存储库的GitHub Actions设置](/zh/enterprise-server@3.22/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-forks-of-private-repositories)”。 #### 示例：为工作流中的一个作业设置 `GITHUB_TOKEN` 权限 本示例显示为将仅应用到作业 `stale` 的 `GITHUB_TOKEN` 设置的权限。 为 `issues` 和 `pull-requests` 权限授予写入权限。 所有其他权限均无权访问。 ```yaml jobs: stale: runs-on: ubuntu-latest permissions: issues: write pull-requests: write steps: - uses: actions/stale@v10 ``` ## `jobs..needs` 使用 `jobs..needs` 标识运行此作业之前必须成功完成的所有作业。 它可以是一个字符串，也可以是字符串数组。 如果某个作业失败或跳过，则所有需要它的作业都会被跳过，除非这些作业使用让该作业继续的条件表达式。 如果某次运行包含一系列彼此依赖的作业，那么一旦某个作业失败或被跳过，从该作业开始，依赖链中的所有后续作业都会受到影响。 如果希望某个作业在其依赖的作业未成功时也能运行，请在 `always()` 中使用 `jobs..if` 条件表达式。 ### 示例：要求成功的依赖项作业 ```yaml jobs: job1: job2: needs: job1 job3: needs: [job1, job2] ``` 在此示例中，`job1` 必须在 `job2` 开始之前成功完成，并且 `job3` 等待 `job1` 和 `job2` 完成。 此示例中的作业按顺序运行： 1. `job1` 2. `job2` 3. `job3` ### 示例：不要求成功的依赖项作业 ```yaml jobs: job1: job2: needs: job1 job3: if: ${{ always() }} needs: [job1, job2] ``` 在此示例中，`job3` 使用 `always()` 条件表达式，确保始终在 `job1` 和 `job2` 完成（无论是否成功）后运行。 有关详细信息，请参阅“[对工作流和操作中的表达式求值](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/expressions#status-check-functions)”。 ## `jobs..if` 您可以使用 `jobs..if` 条件判断来防止作业运行，除非满足某个条件。 您可以使用任何支持上下文和表达式来创建条件。 有关此键中支持哪些上下文的详细信息，请参阅“[上下文参考](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#context-availability)”。 > \[!NOTE] > `jobs..if` 条件在应用 [`jobs..strategy.matrix`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategymatrix) 之前进行评估。 在 `if` 条件中使用表达式时，可以有选择地忽略 `${{ }}` 表达式语法，因为 GitHub Actions 自动将 `if` 条件作为表达式求值。 但此例外并非适用于所有情况。 必须始终使用 `${{ }}` 表达式语法，或者当表达式以`!`开头时，必须使用 `''`、`""`、`()` 进行转义，因为 `!` 是 YAML 格式的保留表示法。 例如： ```yaml if: ${{ ! startsWith(github.ref, 'refs/tags/') }} ``` 有关详细信息，请参阅 [对工作流和操作中的表达式求值](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/expressions)。 ### 示例：仅针对特定存储库运行作业 此示例使用 `if` 控制 `production-deploy` 作业何时可以运行。 仅当存储库名为 `octo-repo-prod` 且位于 `octo-org` 组织内时，它才会运行。 否则，作业将被标记为“跳过”。 ```yaml copy name: example-workflow on: [push] jobs: production-deploy: if: github.repository == 'octo-org/octo-repo-prod' runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - uses: actions/setup-node@v7 with: node-version: '14' - run: npm install -g bats ``` ## `jobs..runs-on` 使用 `jobs..runs-on` 定义要运行作业的计算机类型。 * 目标计算机可以是一个[自托管运行器](#choosing-self-hosted-runners)。 * 你可以根据分配给运行器的标签、其组成员身份，或两者的组合来指定目标运行器。 * 您可以按以下方式提供 `runs-on`： * 单个字符串 * 包含字符串的单个变量 * 字符串数组、包含字符串的变量或两者的组合 * 使用 `key: value` 或 `group` 键的 `labels` 对 * 如果指定字符串或变量数组，工作流将在任何与所有指定的 `runs-on` 值匹配的运行器上执行。 例如，此处的作业将仅在具有标签 `linux`、`x64` 和 `gpu` 的自托管运行器上运行： ```yaml runs-on: [self-hosted, linux, x64, gpu] ``` 有关详细信息，请参阅[选择自托管运行器](#choosing-self-hosted-runners)。 * 可以在数组中混合使用字符串和变量。 例如： ```yaml on: workflow_dispatch: inputs: chosen-os: required: true type: choice options: - Ubuntu - macOS jobs: test: runs-on: [self-hosted, "${{ inputs.chosen-os }}"] steps: - run: echo Hello world! ``` * 如果要在多台计算机上运行工作流，请使用 [`jobs..strategy`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategy)。 > \[!NOTE] > 在简单字符串（如） `self-hosted`周围不需要引号，但表达式 `"${{ inputs.chosen-os }}"`需要引号。 ### 选择 GitHub-hosted runners > \[!NOTE] > GitHub Enterprise Server 目前不支持 GitHub 托管的运行器。 ### 选择自托管运行器 要为作业指定自托管运行器，请在工作流文件中使用自托管运行器标签配置 `runs-on`。 自托管运行器可能具有 `self-hosted` 标签。 设置自托管运行器时，默认情况下，我们将包含标签 `self-hosted`。 可以传递 `--no-default-labels` 标志来阻止自托管标签的应用。 标签可用于为运行器创建目标选项（例如，操作系统或体系结构），建议提供以 `self-hosted` 开头的标签数组（必须首先列出），然后根据需要包含其他标签。 在指定标签集之后，作业将在拥有你所指定所有标签的运行器上排队。 > \[!NOTE] Actions Runner Controller 不支持 `self-hosted` 标签。 #### 示例：使用标签进行运行器选择 ```yaml runs-on: [self-hosted, linux] ``` 有关详细信息，请参阅 [自托管运行程序](/zh/enterprise-server@3.22/actions/concepts/runners/self-hosted-runners) 和 [在工作流中使用自托管运行程序](/zh/enterprise-server@3.22/actions/how-tos/manage-runners/self-hosted-runners/use-in-a-workflow)。 ### 在组中选择运行器 可以使用 `runs-on` 定位运行器组，以便作业将在属于该组的任何运行器上执行。 若要进行更精细的控制，还可以将运行器组与标签组合在一起。 #### 示例：使用群组来控制作业的运行位置 在此示例中，运行器已添加到名为 `build-runners` 的组。 `runs-on` 键将作业发送到 `build-runners` 组中的任何可用运行器： ```yaml name: learn-github-actions on: [push] jobs: check-bats-version: runs-on: group: build-runners steps: - uses: actions/checkout@v6 - uses: actions/setup-node@v7 with: node-version: '14' - run: npm install -g bats - run: bats -v ``` #### 示例：将组和标签组合 组合组和标签时，运行器必须满足这两项要求才能运行作业。 在此示例中，`runs-on` 键结合了 `group` 和 `labels`，从而将该作业路由到组内任何具有匹配标签的可用运行器： ```yaml name: learn-github-actions on: [push] jobs: check-bats-version: runs-on: group: ubuntu-runners labels: ubuntu-24.04-16core steps: - uses: actions/checkout@v6 - uses: actions/setup-node@v7 with: node-version: '14' - run: npm install -g bats - run: bats -v ``` #### 示例：使用前缀区分运行器组 例如，如果组织中有一个名为 `my-group` 的运行器组，企业中有另一个名为 `my-group` 的运行器组，则可以更新工作流文件以使用 `org/my-group` 或 `ent/my-group` 来区分这两者。 使用 `org/`： ```yaml runs-on: group: org/my-group labels: [ self-hosted, label-1 ] ``` 使用 `ent/`： ```yaml runs-on: group: ent/my-group labels: [ self-hosted, label-1 ] ``` ## `jobs..environment` 使用 `jobs..environment` 定义作业引用的环境。 可以将环境仅作为环境 `name` 提供，也可以作为具有 `name` 和 `url` 的环境对象提供。 URL 将映射到部署 API 中的 `environment_url`。 有关部署 API 的详细信息，请参阅“[存储库的 REST API 终结点](/zh/enterprise-server@3.22/rest/repos#deployments)”。 > \[!NOTE] > 在将引用环境的作业发送到运行器之前，必须通过所有部署保护规则。 有关详细信息，请参阅“[管理部署环境](/zh/enterprise-server@3.22/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments)”。 ### 使用单一环境名称的示例 ```yaml environment: staging_environment ``` ### 使用环境名称和 URL 的示例 ```yaml environment: name: production_environment url: https://github.com ``` `url` 的值可以是一个表达式。 允许的表达式上下文：[`github`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#github-context)、[`inputs`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#inputs-context)、[`vars`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#vars-context)、[`needs`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#needs-context)、[`strategy`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#strategy-context)、[`matrix`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#matrix-context)、[`job`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#job-context)、[`runner`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#runner-context)、[`env`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#env-context) 和 [`steps`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#steps-context)。 有关表达式的详细信息，请参阅“[对工作流和操作中的表达式求值](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/expressions)”。 ### 将输出用作 URL 的示例 ```yaml environment: name: production_environment url: ${{ steps.step_id.outputs.url_output }} ``` `name` 的值可以是一个表达式。 允许的表达式上下文：[`github`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#github-context)、[`inputs`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#inputs-context)、[`vars`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#vars-context)、[`needs`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#needs-context)、[`strategy`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#strategy-context) 和 [`matrix`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#matrix-context)。 有关表达式的详细信息，请参阅“[对工作流和操作中的表达式求值](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/expressions)”。 ### 示例：使用表达式作为环境名称 ```yaml environment: name: ${{ github.ref_name }} ``` ## `jobs..concurrency` 可以使用 `jobs..concurrency` 确保只有使用相同并发组的单一作业或工作流才会同时运行。 并发组可以是任何字符串或表达式。 允许的表达式上下文：[`github`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#github-context)、[`inputs`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#inputs-context)、[`vars`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#vars-context)、[`needs`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#needs-context)、[`strategy`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#strategy-context) 和 [`matrix`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#matrix-context)。 有关表达式的详细信息，请参阅“[对工作流和操作中的表达式求值](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/expressions)”。 还可以在工作流级别指定 `concurrency`。 有关详细信息，请参阅 [`concurrency`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#concurrency)。 这意味着在任何时候，一个并发组中最多只能同时有一个正在运行的作业和一个待处理的作业。 当并发作业或工作流排队时，如果存储库中使用同一并发组的其他作业或工作流正在运行，则排队的作业或工作流将为 `pending`。 将取消同一并发组中的任何现有 `pending` 作业或工作流（如果存在），且新的列队作业或工作流将取代其位置。 若还要取消同一并发组中任何当前正在运行的作业或工作流，请指定 `cancel-in-progress: true`。 若要有条件地取消同一并发组中当前正在运行的作业或工作流，可以将 `cancel-in-progress` 指定为具有任何允许的表达式上下文的表达式。 > \[!NOTE] > > * 并发组名称不区分大小写。 例如，`prod` 和 `Prod` 将被视为同一个并发组。 > * 作业或工作流在同一并发组中运行时，按照每个作业开始等待该并发组的时间，以先进先出（FIFO）的顺序处理，而不是按照每个工作流的分派时间。 由于作业或运行的实际开始时间可能有所不同，因此不能保证排序。 ### 示例：使用并发和默认行为 默认情况下，GitHub Actions 允许多个作业或工作流同时运行。 使用`concurrency` 关键字可以控制工作流运行的并发性。 例如，可以在定义触发器条件以限制特定分支的整个工作流运行的并发之后立即使用 `concurrency` 关键字： ```yaml on: push: branches: - main concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true ``` 还可以通过在作业级别使用 `concurrency` 关键字来限制工作流中作业的并发性： ```yaml on: push: branches: - main jobs: job-1: runs-on: ubuntu-latest concurrency: group: example-group cancel-in-progress: true ``` ### 示例：并发组 并发组提供了一种方法，用于管理和限制共享相同并发密钥的工作流运行或作业的执行。 该 `concurrency` 密钥用于将工作流或作业组合到并发组中。 定义 `concurrency` 密钥时， GitHub Actions 请确保在任何给定时间只运行具有该密钥的一个工作流或作业。 如果新的工作流运行或作业以相同的 `concurrency` 密钥启动， GitHub Actions 将取消已使用该密钥运行的任何工作流或作业。 键 `concurrency` 可以是硬编码字符串，也可以是包含上下文变量的动态表达式。 可以在工作流中定义并发条件，以便工作流或作业是并发组的一部分。 这意味着，当工作流运行或作业启动时，GitHub 将取消同一并发组中正在进行的任何工作流运行或作业。 在想要防止对特定工作流或作业（例如用于部署到过渡环境的工作流或作业）进行并行运行的情况下，这非常有用，以防止可能导致冲突或消耗比必要资源更多的操作。 在此示例中，`job-1` 是名为 `staging_environment` 的并发组的一部分。 如果新运行的 `job-1` 被触发，那么在并发组 `staging_environment` 中已在进行的任何同一作业的运行都将被取消。 ```yaml jobs: job-1: runs-on: ubuntu-latest concurrency: group: staging_environment cancel-in-progress: true ``` 或者，在工作流中使用动态表达式 `concurrency: ci-${{ github.ref }}` 意味着工作流或作业将成为并发组 `ci-` 的一部分，后跟触发工作流的分支或标记的引用。 在此示例中，如果在上一次运行仍在进行中时将新的提交推送到主分支，则会取消上一次运行，并且新运行将启动： ```yaml on: push: branches: - main concurrency: group: ci-${{ github.ref }} cancel-in-progress: true ``` ### 示例：使用并发取消任何当前作业或运行 若要使用并发来取消任何正在进行的任务或运行，可以使用密钥`concurrency`，并将选项`cancel-in-progress`设置为`true`： ```yaml concurrency: group: ${{ github.ref }} cancel-in-progress: true ``` 请注意，在此示例中，如果不定义特定的并发组，GitHub Actions 将取消任何正在进行的\_作业或工作流\_的运行。 ### 示例：使用回退值 如果使用仅为特定事件定义的属性生成组名称，则可以使用回退值。 例如，`github.head_ref` 仅对 `pull_request` 事件定义。 如果工作流响应除了 `pull_request` 事件之外的其他事件，你将需要提供回退以避免语法错误。 以下并发组仅取消针对 `pull_request` 事件正在进行的作业或运行；如果 `github.head_ref` 未定义，并发组将回退到运行 ID，该 ID 保证是唯一的，并且是为该运行定义的。 ```yaml concurrency: group: ${{ github.head_ref || github.run_id }} cancel-in-progress: true ``` ### 示例：仅取消当前工作流中正在进行的作业或运行 如果在同一个存储库中有多个工作流，则并发组名称在工作流中必须是唯一的，以避免从其他工作流取消正在进行的作业或运行。 否则，任何先前进行中或挂起的任务都将被取消，无论工作流如何。 若要仅取消同一工作流中正在进行的运行，可以使用 `github.workflow` 属性来构建并发组。 ```yaml concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true ``` ### 示例：仅取消特定分支上正在进行的作业 如果你想取消某些分支上正在进行的作业，但不想取消其他分支上正在进行的作业，则可以将条件表达式与 `cancel-in-progress` 一起使用。 例如，如果你想取消开发分支上正在进行的作业，但不想取消发布分支上正在进行的作业，则可以执行此操作。 若要仅在未在发布分支上运行时取消同一工作流正在进行的运行，则可以设置表达式的 `cancel-in-progress`，如下所示： ```yaml concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: ${{ !contains(github.ref, 'release/')}} ``` 在此示例中，多次推送到 `release/1.2.3` 分支不会取消正在进行的运行。 推送到另一个分支（例如 `main`）将取消正在进行的运行。 ## `jobs..outputs` 可以使用 `jobs..outputs` 为作业创建输出`map`。 作业输出可用于所有依赖此作业的下游作业。 有关定义作业依赖项的详细信息，请参阅 [`jobs..needs`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idneeds)。 每个作业的输出最多可以为 1 MB。 工作流运行中所有输出的总和最大为 50 MB。 大小是基于 UTF-16 编码的近似值。 包含表达式的作业输出会在每个作业结束时由运行器进行评估。 包含机密信息的输出会在运行器上进行脱敏处理，不会发送到 GitHub Actions。 如果由于输出可能包含机密而跳过，则会看到以下警告消息：“跳过输出 `{output.Key}`，因为它可能包含机密。” 有关如何处理机密的详细信息，请参阅[示例：在作业或工作流之间屏蔽和传递机密](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-commands#example-masking-and-passing-a-secret-between-jobs-or-workflows)。 要在依赖的作业中使用作业输出, 可以使用 `needs` 上下文。 有关详细信息，请参阅“[上下文参考](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#needs-context)”。 ### 示例：定义作业的输出 ```yaml jobs: job1: runs-on: ubuntu-latest # Map a step output to a job output outputs: output1: ${{ steps.step1.outputs.test }} output2: ${{ steps.step2.outputs.test }} steps: - id: step1 run: echo "test=hello" >> "$GITHUB_OUTPUT" - id: step2 run: echo "test=world" >> "$GITHUB_OUTPUT" job2: runs-on: ubuntu-latest needs: job1 steps: - env: OUTPUT1: ${{needs.job1.outputs.output1}} OUTPUT2: ${{needs.job1.outputs.output2}} run: echo "$OUTPUT1 $OUTPUT2" ``` ### 在矩阵作业中使用作业输出 矩阵可用于生成不同名称的多个输出。 当使用矩阵时，作业输出将由矩阵内的所有作业组合而成。 ```yaml jobs: job1: runs-on: ubuntu-latest outputs: output_1: ${{ steps.gen_output.outputs.output_1 }} output_2: ${{ steps.gen_output.outputs.output_2 }} output_3: ${{ steps.gen_output.outputs.output_3 }} strategy: matrix: version: [1, 2, 3] steps: - name: Generate output id: gen_output run: | version="${{ matrix.version }}" echo "output_${version}=${version}" >> "$GITHUB_OUTPUT" job2: runs-on: ubuntu-latest needs: [job1] steps: # Will show # { # "output_1": "1", # "output_2": "2", # "output_3": "3" # } - run: echo '${{ toJSON(needs.job1.outputs) }}' ``` > \[!WARNING] > 操作不保证矩阵作业运行的顺序。 确保输出名称是唯一的，否则运行的最后一个矩阵作业将替代输出值。 ## `jobs..env` 可用于作业中所有步骤的变量的 `map`。 可以设置用于整个工作流或单个步骤的变量。 有关详细信息，请参阅 [`env`](#env) 和 [`jobs..steps[*].env`](#jobsjob_idstepsenv)。 当多个环境变量使用相同的名称定义时，GitHub 会使用最特定的变量。 例如，步骤中定义的环境变量在步骤执行时将覆盖名称相同的作业和工作流环境变量。 为作业定义的环境变量在作业执行时将覆盖名称相同的工作流变量。 ### `jobs..env` 的示例 ```yaml jobs: job1: env: FIRST_NAME: Mona ``` ## `jobs..defaults` 使用 `jobs..defaults` 创建将应用于作业中所有步骤的默认设置的 `map`。 您也可以设置整个工作流程的默认设置。 有关详细信息，请参阅 [`defaults`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#defaults)。 使用相同名称定义了多个默认设置时，GitHub 会使用最具体的默认设置。 例如，在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。 ## `jobs..defaults.run` 使用 `jobs..defaults.run` 为作业中的所有 `shell` 步骤提供默认的 `working-directory` 和 `run`。 你可以为作业中所有 `working-directory` 步骤提供默认的 `run` 和 [](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsrun) 选项。 你也可以为整个工作流的 `run` 设置默认设置。 有关详细信息，请参阅 [`defaults.run`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#defaultsrun)。 可以在 `jobs..defaults.run` 和 `jobs..steps[*].run` 级别覆盖这些值。 使用相同名称定义了多个默认设置时，GitHub 会使用最具体的默认设置。 例如，在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。 ## `jobs..defaults.run.shell` 使用 `shell` 为步骤定义 `shell`。 此关键字可以引用多个上下文。 有关详细信息，请参阅“[上下文](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#context-availability)”。 | 支持的平台 | `shell` 参数 | 说明 | 内部运行命令 | | ----------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | | Linux/macOS | unspecified | 非 Windows 平台上的默认 shell。 请注意，这与显式指定 `bash` 时运行的命令不同。 如果在路径中找不到 `bash`，则将其视为 `sh`。 | `bash -e {0}` | | All | `bash` | 非 Windows 平台上回退到 `sh` 的默认 shell。 指定 Windows 上的 bash shell 时，将使用 Git for Windows 随附的 bash shel。 | `bash --noprofile --norc -eo pipefail {0}` | | 全部 | `pwsh` | PowerShell Core。 GitHub 将扩展名 `.ps1` 追加到你的脚本名称。 | `pwsh -command ". '{0}'"` | | All | `python` | 执行 python 命令。 | `python {0}` | | Linux/macOS | `sh` | 未提供 shell 且在路径中找不到 `bash` 时的非 Windows 平台的后退行为。 | `sh -e {0}` | | Windows | `cmd` | GitHub 将扩展名 `.cmd` 追加到你的脚本名称并替换 `{0}`。 | `%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}""`。 | | Windows | `pwsh` | 这是 Windows 上使用的默认 shell。 PowerShell Core。 GitHub 将扩展名 `.ps1` 追加到你的脚本名称。 如果自承载 Windows 运行器未安装 PowerShell Core，则改用 PowerShell Desktop。 | `pwsh -command ". '{0}'"`。 | | Windows | `powershell` | PowerShell 桌面。 GitHub 将扩展名 `.ps1` 追加到你的脚本名称。 | `powershell -command ". '{0}'"`。 | 使用相同名称定义了多个默认设置时，GitHub 会使用最具体的默认设置。 例如，在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。 ## `jobs..defaults.run.working-directory` 使用 `working-directory` 为步骤定义用于 `shell` 的工作目录。 此关键字可以引用多个上下文。 有关详细信息，请参阅“[上下文](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#context-availability)”。 > \[!TIP] > 在运行 shell 之前，请确保你分配的 `working-directory` 在运行器上存在。 > 使用相同名称定义了多个默认设置时，GitHub 会使用最具体的默认设置。 例如，在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。 ### 示例：为作业设置默认 `run` 步骤选项 ```yaml jobs: job1: runs-on: ubuntu-latest defaults: run: shell: bash working-directory: ./scripts ``` ## `jobs..steps` 作业包含一系列任务，称为 `steps`。 步骤可以运行命令、运行设置任务，或者运行您的仓库、公共仓库中的操作或 Docker 注册表中发布的操作。 并非所有步骤都会执行操作，但所有操作都会作为步骤执行。 每个步骤在运行器环境中以其自己的进程运行，且可以访问工作区和文件系统。 因为步骤以自己的进程运行，所以步骤之间不会保留环境变量的更改。 GitHub 提供用于设置和完成作业的内置步骤。 GitHub 仅显示前 1,000 个检查，但是，只要处于工作流使用限制内，就可以运行无限数量的步骤。 有关详细信息，请参阅 [](/zh/enterprise-server@3.22/actions/concepts/billing-and-usage) 托管运行器的 GitHub 和自托管运行器使用限制的 [Actions 限制](/zh/enterprise-server@3.22/actions/reference/limits)。 ### `jobs..steps` 的示例 ```yaml name: Greeting from Mona on: push jobs: my-job: name: My Job runs-on: ubuntu-latest steps: - name: Print a greeting env: MY_VAR: Hi there! My name is FIRST_NAME: Mona MIDDLE_NAME: The LAST_NAME: Octocat run: | echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME. ``` ## `jobs..steps[*].id` 步骤的唯一标识符。 可以使用 `id` 在上下文中引用该步骤。 有关详细信息，请参阅“[上下文参考](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts)”。 ## `jobs..steps[*].if` 可以使用 `if` 条件来阻止步骤运行，除非满足条件。 您可以使用任何支持上下文和表达式来创建条件。 有关此键中支持哪些上下文的详细信息，请参阅“[上下文参考](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#context-availability)”。 在 `if` 条件中使用表达式时，可以有选择地忽略 `${{ }}` 表达式语法，因为 GitHub Actions 自动将 `if` 条件作为表达式求值。 但此例外并非适用于所有情况。 必须始终使用 `${{ }}` 表达式语法，或者当表达式以`!`开头时，必须使用 `''`、`""`、`()` 进行转义，因为 `!` 是 YAML 格式的保留表示法。 例如： ```yaml if: ${{ ! startsWith(github.ref, 'refs/tags/') }} ``` 有关详细信息，请参阅 [对工作流和操作中的表达式求值](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/expressions)。 ### 示例：使用上下文 此步骤仅在事件类型为 `pull_request` 且事件操作为 `unassigned` 时运行。 ```yaml steps: - name: My first step if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }} run: echo This event is a pull request that had an assignee removed. ``` ### 示例：使用状态检查功能 `my backup step` 仅在作业的上一步失败时运行。 有关详细信息，请参阅“[对工作流和操作中的表达式求值](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/expressions#status-check-functions)”。 ```yaml steps: - name: My first step uses: octo-org/action-name@main - name: My backup step if: ${{ failure() }} uses: actions/heroku@1.0.0 ``` ### 示例：使用机密 无法直接在 `if:` 条件中引用机密。 而应考虑将机密设置为作业级环境变量，然后引用环境变量以有条件地运行作业中的步骤。 如果未设置机密，则引用机密的表达式的返回值（如 `${{ secrets.SuperSecret }}` 示例中）将为空字符串。 ```yaml name: Run a step if a secret has been set on: push jobs: my-jobname: runs-on: ubuntu-latest env: super_secret: ${{ secrets.SuperSecret }} steps: - if: ${{ env.super_secret != '' }} run: echo 'This step will only run if the secret has a value set.' - if: ${{ env.super_secret == '' }} run: echo 'This step will only run if the secret does not have a value set.' ``` 有关详细信息，请参阅 [上下文参考](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#context-availability) 和 [在 GitHub Actions 中使用机密](/zh/enterprise-server@3.22/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)。 ## `jobs..steps[*].name` 在 GitHub 上显示的步骤名称。 ## `jobs..steps[*].uses` 选择要作为作业中步骤的一部分运行的操作。 操作是一种可重复使用的代码单位。 可以使用在与工作流、公共存储库或[已发布的 Docker 容器映像](https://hub.docker.com/)相同的存储库中定义的操作。 强烈建议您通过指定 Git ref、SHA 或 Docker 标签来包含您正在使用的操作版本。 如果不指定版本，在操作所有者发布更新时可能会中断您的工作流程或造成非预期的行为。 * 使用已发行操作版本的 SHA 对于稳定性和安全性是最安全的。 * 如果操作发布主版本标记，则应收到关键修补程序和安全修补程序，同时仍保持兼容性。 请注意，此行为由操作创建者决定。 * 使用操作的默认分支可能很方便，但如果有人新发布具有突破性更改的主要版本，您的工作流程可能会中断。 某些操作需要您使用 [`with`](#jobsjob_idstepswith) 关键字设置输入。 请查阅操作的自述文件，确定所需的输入。 操作为 JavaScript 文件或 Docker 容器。 如果您使用的操作是 Docker 容器，则必须在 Linux 环境中运行作业。 有关详细信息，请参阅 [`runs-on`](#jobsjob_idruns-on)。 ### 示例：使用版本化操作 ```yaml steps: # Reference a specific commit - uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3 # Reference the major version of a release - uses: actions/checkout@v6 # Reference a specific version - uses: actions/checkout@v6.2.0 # Reference a branch - uses: actions/checkout@main ``` ### 示例：使用公共操作 `{owner}/{repo}@{ref}` 可以在公共 GitHub 存储库中指定分支、ref 或 SHA。 ```yaml jobs: my_first_job: steps: - name: My first step # Uses the default branch of a public repository uses: actions/heroku@main - name: My second step # Uses a specific version tag of a public repository uses: actions/aws@v2.0.1 ``` ### 示例：在子目录中使用公共操作 `{owner}/{repo}/{path}@{ref}` 特定分支、ref 或 SHA 的公共 GitHub 存储库中的子目录。 ```yaml jobs: my_first_job: steps: - name: My first step uses: actions/aws/ec2@main ``` ### 示例：在正在运行的提交时使用与工作流相同的存储库中的操作（建议） `$/path/to/action` 前缀 `$/` 是自存储库引用。 它引用与当前正在运行的工作流或操作存储在同一存储库中的操作，并在正在运行的提交时解析为该存储库（与正在运行的工作流或操作相同的 SHA）。 无需先签出存储库，因此建议在其自己的存储库中引用操作。 语法 `$/` 在 . 中 GitHub Enterprise Server不可用。 引用 `$/` 不得包含 `@{ref}` 后缀。 ref 始终是正在运行的工作流或操作正在使用的提交，因此引用（如 `$/actions/my-action@v1` 无效）。 `$/` 始终针对其中显示的文件的存储库解析，而不是调用它的存储库。 例如，如果一个存储库中的可重用工作流由另一个存储库中的工作流调用， `$/` 则调用的工作流中的引用将解析为所调用工作流的存储库，而不是调用工作流的存储库。 `$/`这使得操作组合可靠，其中相对`./`路径会针对调用方工作区中签出的任何内容进行解析。 有关在复合操作的步骤中使用 `$/` ，请参阅 [元数据语法参考](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/metadata-syntax#runsstepsuses)。 下表比较了引用操作的方法。 | Syntax | 解析为 | 建议用于 | | ---------------------- | -------------------------------------------------- | ---------- | | `$/path/to/action` | 在正在运行的提交时，与正在运行的工作流或操作相同的存储库 | 同一存储库中的操作 | | `{owner}/{repo}@{ref}` | 指定 ref 处的指定存储库 | 另一个存储库中的操作 | | `./path/to/action` | 运行程序签出工作区中相对于默认工作目录的路径 （`${{ github.workspace }}`） | 仅边缘事例 | ```yaml on: [push] jobs: my_first_job: runs-on: ubuntu-latest steps: # References an action in the same repository at the running commit - uses: $/.github/actions/hello-world-action ``` ### 示例：使用工作流程所在仓库中操作 `./path/to/dir` 包含工作流程的仓库中操作的目录路径。 在使用操作之前，必须签出存储库，并且 `./` 路径针对运行程序的工作区而不是正在运行的工作流的存储库解析。 在大多数情况下，请改用上面所示的 `$/` 语法。 示例仓库文件结构： ```shell |-- hello-world (repository) | |__ .github | └── workflows | └── my-first-workflow.yml | └── actions | |__ hello-world-action | └── action.yml ``` 路径为相对于 (`./`) 默认工作目录（`github.workspace`、`$GITHUB_WORKSPACE`）的路径。 如果操作将存储库签出到不同于该工作流的位置，则必须更新用于本地操作的相对路径。 示例工作流程文件： ```yaml jobs: my_first_job: runs-on: ubuntu-latest steps: # This step checks out a copy of your repository. - name: My first step - check out repository uses: actions/checkout@v6 # This step references the directory that contains the action. - name: Use local hello-world-action uses: ./.github/actions/hello-world-action ``` ### 示例：使用 Docker Hub 操作 `docker://{image}:{tag}` 发布于 [Docker 中心](https://hub.docker.com/)的 Docker 映像。 ```yaml jobs: my_first_job: steps: - name: My first step uses: docker://alpine:3.8 ``` ### 示例：使用 Docker 公共注册表操作 `docker://{host}/{image}:{tag}` 公共注册表中的 Docker 映像。 此示例使用 Google Container Registry 于 `gcr.io`。 ```yaml jobs: my_first_job: steps: - name: My first step uses: docker://gcr.io/cloud-builders/gradle ``` ### 示例：在不同于工作流程的私有仓库中使用操作 如果操作位于内部存储库中，或者配置为允许从工作流存储库进行访问的专用存储库中，可以直接引用该操作。 有关详细信息，请参阅 [管理存储库的GitHub Actions设置](/zh/enterprise-server@3.22/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-an-internal-repository) 和 [管理存储库的GitHub Actions设置](/zh/enterprise-server@3.22/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-a-private-repository)。 如果该操作不在已配置为允许访问的存储库中，则需要检出该存储库并在本地引用该操作。 生成一个personal access token并将该令牌添加为密钥。 以下示例演示了用于引用操作的方法。 有关详细信息，请参阅 [管理个人访问令牌](/zh/enterprise-server@3.22/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) 和 [在 GitHub Actions 中使用机密](/zh/enterprise-server@3.22/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)。 将示例中 `PERSONAL_ACCESS_TOKEN` 替换为机密名称。 ```yaml jobs: my_first_job: steps: - name: Check out repository uses: actions/checkout@v6 with: repository: octocat/my-private-repo ref: v1.0 token: ${{ secrets.PERSONAL_ACCESS_TOKEN }} path: ./.github/actions/my-private-repo - name: Run my action uses: ./.github/actions/my-private-repo/my-action ``` 或者，使用GitHub App而不是personal access token，以确保工作流在personal access token所有者离开后仍能继续运行。 有关详细信息，请参阅“[在GitHub Actions工作流中使用GitHub应用发出经过身份验证的 API 请求](/zh/enterprise-server@3.22/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow)”。 ## `jobs..steps[*].run` 使用操作系统的 shell 运行不超过 21,000 个字符的命令行程序。 如果不提供 `name`，步骤名称将默认为 `run` 命令中指定的文本。 命令默认使用非登录 shell 运行。 您可以选择不同的 shell，也可以自定义用于运行命令的 shell。 有关详细信息，请参阅 [`jobs..steps[*].shell`](#jobsjob_idstepsshell)。 每个 `run` 关键字代表运行器环境中一个新的进程和 shell。 当您提供多行命令时，每行都在同一个 shell 中运行。 例如： * 单行命令： ```yaml - name: Install Dependencies run: npm install ``` * 多行命令： ```yaml - name: Clean install dependencies and build run: | npm ci npm run build ``` ## `jobs..steps[*].working-directory` 使用 `working-directory` 关键字，你可以指定运行命令的工作目录位置。 ```yaml - name: Clean temp directory run: rm -rf * working-directory: ./temp ``` 另外，可以为作业中的所有 `run` 步骤或整个工作流中的所有 `run` 步骤指定默认工作目录。 有关详细信息，请参阅 [`defaults.run.working-directory`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#defaultsrunworking-directory) 和 [`jobs..defaults.run.working-directory`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_iddefaultsrunworking-directory)。 还可以使用 `run` 步骤来运行脚本。 有关详细信息，请参阅“[添加脚本到工作流程](/zh/enterprise-server@3.22/actions/how-tos/write-workflows/choose-what-workflows-do/add-scripts)”。 ## `jobs..steps[*].shell` 你可以使用 `shell` 关键字，覆盖运行器操作系统中的默认 Shell 设置，以及作业的默认值。 你可以使用内置的 `shell` 关键字，也可以自定义 shell 选项集。 内部运行的 shell 命令执行一个临时文件，其中包含 `run` 关键字中指定的命令。 | 支持的平台 | `shell` 参数 | 说明 | 内部运行命令 | | ----------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | | Linux/macOS | unspecified | 非 Windows 平台上的默认 shell。 请注意，这与显式指定 `bash` 时运行的命令不同。 如果在路径中找不到 `bash`，则将其视为 `sh`。 | `bash -e {0}` | | All | `bash` | 非 Windows 平台上回退到 `sh` 的默认 shell。 指定 Windows 上的 bash shell 时，将使用 Git for Windows 随附的 bash shel。 | `bash --noprofile --norc -eo pipefail {0}` | | 全部 | `pwsh` | PowerShell Core。 GitHub 将扩展名 `.ps1` 追加到你的脚本名称。 | `pwsh -command ". '{0}'"` | | All | `python` | 执行 python 命令。 | `python {0}` | | Linux/macOS | `sh` | 未提供 shell 且在路径中找不到 `bash` 时的非 Windows 平台的后退行为。 | `sh -e {0}` | | Windows | `cmd` | GitHub 将扩展名 `.cmd` 追加到你的脚本名称并替换 `{0}`。 | `%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}""`。 | | Windows | `pwsh` | 这是 Windows 上使用的默认 shell。 PowerShell Core。 GitHub 将扩展名 `.ps1` 追加到你的脚本名称。 如果自承载 Windows 运行器未安装 PowerShell Core，则改用 PowerShell Desktop。 | `pwsh -command ". '{0}'"`。 | | Windows | `powershell` | PowerShell 桌面。 GitHub 将扩展名 `.ps1` 追加到你的脚本名称。 | `powershell -command ". '{0}'"`。 | 另外，可以为作业中的所有 `run` 步骤或整个工作流中的所有 `run` 步骤指定默认 Shell。 有关详细信息，请参阅 [`defaults.run.shell`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#defaultsrunshell) 和 [`jobs..defaults.run.shell`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_iddefaultsrunshell)。 ### 示例：使用 bash 运行命令 ```yaml steps: - name: Display the path shell: bash run: echo $PATH ``` ### 示例：使用 Windows `cmd` 运行命令 ```yaml steps: - name: Display the path shell: cmd run: echo %PATH% ``` ### 示例：使用 PowerShell Core 运行命令 ```yaml steps: - name: Display the path shell: pwsh run: echo ${env:PATH} ``` ### 示例：使用 PowerShell Desktop 运行命令 ```yaml steps: - name: Display the path shell: powershell run: echo ${env:PATH} ``` ### 示例：运行 python 内联脚本 ```yaml steps: - name: Display the path shell: python run: | import os print(os.environ['PATH']) ``` ### 自定义 shell 可以使用 `shell` 将 `command [options] {0} [more_options]` 值设置为模板字符串。 GitHub 将字符串的第一个带空格分隔的单词解释为命令，并在 处插入临时脚本 `{0}`的文件名。 例如： ```yaml steps: - name: Display the environment variables and their values shell: perl {0} run: | print %ENV ``` 此示例中使用的命令 `perl` 必须安装在运行器上。 ### 退出码和错误处理偏好 对于内置 shell 关键字，我们提供了以下由GitHub托管的运行器执行的默认值。 在运行 shell 脚本时，您应该使用这些指南。 * `bash` / `sh`： * 默认情况下，使用 `set -e` 对 `sh` 和 `bash` 强制实施快速失败行为。 指定 `shell: bash` 时，`-o pipefail` 也会被应用以强制使生成非零退出状态的管道提前退出。 * 你可以通过向 shell 选项提供模板字符串来完全控制 shell 参数。 例如，`bash {0}`。 * `sh` 类 shell 的退出代码是脚本中最后执行的命令的退出代码，这也是操作的默认行为。 运行程序将根据此退出代码将步骤的状态报告为失败/成功。 * `powershell`/`pwsh` * 可能时的快速失败行为。 对于 `pwsh` 和 `powershell` 内置 shell，我们将在脚本内容前面追加 `$ErrorActionPreference = 'stop'`。 * 我们追加 `if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE }` 到 Powershell 脚本，以便操作状态反映脚本的最后一个退出代码。 * 用户始终可以选择退出，方法是不使用内置 shell，并按需提供 `pwsh -File {0}` 或 `powershell -Command "& '{0}'"` 等自定义 shell 选项。 * `cmd` * 除了编写脚本来检查每个错误代码并相应地响应之外，似乎没有办法完全启用快速失败机制。 由于我们默认不能实际提供该行为，因此您需要将此行为写入脚本。 * `cmd.exe` 在退出时带有其执行的最后一个程序的错误等级，并且会将错误代码返回到运行器。 此行为在内部与之前的 `sh` 和 `pwsh` 默认行为一致，并且是 `cmd.exe` 默认行为，因而此行为将保持不变。 ## `jobs..steps[*].with` 由操作定义的输入参数的 `map`。 每个输入参数都是一个键/值对。 输入参数被设置为环境变量。 该变量的前缀为 `INPUT_`，并转换为大写。 为 Docker 容器定义的输入参数必须使用 `args`。 有关详细信息，请参阅 [`jobs..steps[*].with.args`](#jobsjob_idstepswithargs)。 ### `jobs..steps[*].with` 的示例 定义由 `first_name` 操作定义的三个输入参数（`middle_name`、`last_name` 和 `hello_world`）。 这些输入变量将作为 `hello-world`、`INPUT_FIRST_NAME` 和 `INPUT_MIDDLE_NAME` 环境变量由 `INPUT_LAST_NAME` 操作访问。 ```yaml jobs: my_first_job: steps: - name: My first step uses: actions/hello_world@main with: first_name: Mona middle_name: The last_name: Octocat ``` ## `jobs..steps[*].with.args` `string` 用于定义 Docker 容器的输入。 GitHub 在容器启动时将 `args` 传递给容器的 `ENTRYPOINT` 。 此参数不支持 `array of strings`。 包含空格的单个参数应该用双引号 `""` 括起来。 ### `jobs..steps[*].with.args` 的示例 ```yaml steps: - name: Explain why this job ran uses: octo-org/action-name@main with: entrypoint: /bin/echo args: The ${{ github.event_name }} event triggered this step. ``` `args` 用于代替 `CMD` 中的 `Dockerfile` 指令。 如果您在 `CMD` 中使用 `Dockerfile`，请遵循按优先顺序排列的指南： 1. 在操作的自述文件中记录必要的参数，并在 `CMD` 指令的中忽略它们。 2. 使用默认值，允许不指定任何 `args` 即可使用操作。 3. 如果操作显示 `--help` 标记或类似项，请将其用作默认值，以便操作自行记录。 ## `jobs..steps[*].with.entrypoint` 如果未指定该项，则替代 `ENTRYPOINT` 中的 Docker `Dockerfile`，否则对其进行设置。 与包含 shell 和 exec 表单的 Docker `ENTRYPOINT` 指令不同，`entrypoint` 关键字只接受定义要运行的可执行文件的单个字符串。 ### `jobs..steps[*].with.entrypoint` 的示例 ```yaml steps: - name: Run a custom command uses: octo-org/action-name@main with: entrypoint: /a/different/executable ``` `entrypoint` 关键字旨在用于 Docker 容器操作，但你也可以将其用于未定义任何输入的 JavaScript 操作。 ## `jobs..steps[*].env` 设置供步骤在运行器环境中使用的变量。 也可以设置用于整个工作流或某个作业的变量。 有关详细信息，请参阅 [`env`](#env) 和 [`jobs..env`](#jobsjob_idenv)。 当多个环境变量使用相同的名称定义时，GitHub 会使用最特定的变量。 例如，步骤中定义的环境变量在步骤执行时将覆盖名称相同的作业和工作流环境变量。 为作业定义的环境变量在作业执行时将覆盖名称相同的工作流变量。 公共动作可在 README 文件中指定预期变量。 如果要设置机密或敏感值（如密码或令牌），则必须使用 `secrets` 上下文来设置机密。 有关详细信息，请参阅“[上下文参考](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts)”。 ### `jobs..steps[*].env` 的示例 ```yaml steps: - name: My first action env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} FIRST_NAME: Mona LAST_NAME: Octocat ``` ## `jobs..steps[*].continue-on-error` 防止因某个步骤失败而导致整个作业失败。 设置为 `true` 以允许在此步骤失败时作业能够通过。 ## `jobs..steps[*].timeout-minutes` 终止进程之前运行该步骤的最大分钟数。 最大值：GitHub 托管和自托管运行器均为 360。 不支持小数值。 `timeout-minutes` 必须是正整数。 ## `jobs..timeout-minutes` 作业运行前允许的最大分钟数，之后 GitHub 会自动取消。 默认值：360 如果超时超过运行器的作业执行时限，作业将在达到执行时限时取消。 有关作业执行时间限制的详细信息，请参阅 [](/zh/enterprise-server@3.22/actions/concepts/billing-and-usage#usage-limits-and-policy) 托管运行器的 GitHub 和自托管运行器使用限制的 [Actions 限制](/zh/enterprise-server@3.22/actions/reference/limits)。 > \[!NOTE] > `GITHUB_TOKEN` 在作业完成或最多 24 小时后过期。 对于自托管运行器，如果作业超时大于 24 小时，令牌可能是限制因素。 有关 `GITHUB_TOKEN` 的详细信息，请参阅“[在工作流中使用 GITHUB\_TOKEN 进行身份验证](/zh/enterprise-server@3.22/actions/tutorials/authenticate-with-github_token)”。 ## `jobs..strategy` 使用 `jobs..strategy` 对作业使用矩阵策略。 使用矩阵策略，可以在单个作业定义中使用变量自动创建基于变量组合的多个作业运行。 例如，可以使用矩阵策略在某个语言的多个版本或多个操作系统上测试代码。 有关详细信息，请参阅 [在工作流中运行作业变体](/zh/enterprise-server@3.22/actions/how-tos/write-workflows/choose-what-workflows-do/run-job-variations)。 ## `jobs..strategy.matrix` 使用 `jobs..strategy.matrix` 定义不同作业配置的矩阵。 有关详细信息，请参阅“[在工作流中运行作业变体](/zh/enterprise-server@3.22/actions/how-tos/write-workflows/choose-what-workflows-do/run-job-variations)”。 矩阵在每次工作流运行时最多将生成 256 个作业。 此限制适用于 GitHub 托管和自托管运行器。 定义的变量将成为 `matrix` 上下文中的属性，你可以在工作流文件的其他区域中引用该属性。 在此示例中，可以使用 `matrix.version` 和 `matrix.os` 来访问作业正在使用的 `version` 和 `os` 的当前值。 有关详细信息，请参阅“[上下文参考](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts)”。 默认情况下， GitHub 将根据运行程序可用性将并行运行的作业数最大化。 矩阵中变量的顺序决定了作业的创建顺序。 定义的第一个变量将是在工作流运行中创建的第一个作业。 ### 使用单维度矩阵 以下工作流程使用值 `version` 定义变量 `[10, 12, 14]`。 工作流将运行三个作业，其中针对变量中的每个值提供一个作业。 每个作业都会通过 `version` 上下文访问 `matrix.version` 值，并此值作为 `node-version` 传递给 `actions/setup-node` 操作。 ```yaml jobs: example_matrix: strategy: matrix: version: [10, 12, 14] steps: - uses: actions/setup-node@v7 with: node-version: ${{ matrix.version }} ``` ### 使用多维矩阵 指定多个变量来创建多维矩阵。 将针对变量的每个可能组合运行作业。 例如，以下工作流指定两个变量： * `os` 变量中指定的两个操作系统 * `version` 变量中指定的三个 Node.js 版本 工作流将运行六个作业，其中针对每个 `os` 和 `version` 变量组合提供一个作业。 每个作业都会将 `runs-on` 值设置为当前的 `os` 值，并将当前的 `version` 值传递给 `actions/setup-node` 操作。 ```yaml jobs: example_matrix: strategy: matrix: os: [ubuntu-22.04, ubuntu-24.04] version: [10, 12, 14] runs-on: ${{ matrix.os }} steps: - uses: actions/setup-node@v7 with: node-version: ${{ matrix.version }} ``` 矩阵中的变量配置可以是 `array` 的 `object`。 例如，以下矩阵生成 4 个作业和相应的上下文。 ```yaml matrix: os: - ubuntu-latest - macos-latest node: - version: 14 - version: 20 env: NODE_OPTIONS=--openssl-legacy-provider ``` 矩阵中的每个作业都将具有自己的 `os` 和 `node` 值组合，如下所示。 ```yaml - matrix.os: ubuntu-latest matrix.node.version: 14 - matrix.os: ubuntu-latest matrix.node.version: 20 matrix.node.env: NODE_OPTIONS=--openssl-legacy-provider - matrix.os: macos-latest matrix.node.version: 14 - matrix.os: macos-latest matrix.node.version: 20 matrix.node.env: NODE_OPTIONS=--openssl-legacy-provider ``` ## `jobs..strategy.matrix.include` 对于 `include` 列表中的每个对象，如果对象中的键:值对不覆盖任何原始矩阵值，则会将这些键:值对添加到每个矩阵组合中。 如果对象不能添加到任何矩阵组合中，将改为创建新的矩阵组合。 请注意，原始矩阵值不会被覆盖，但添加的矩阵值可以被覆盖。 ### 示例：扩展配置 例如，以下工作流将运行四个作业，其中针对每个 `os` 和 `node` 变量组合提供一个作业。 当对应于 `windows-latest` 的 `os` 值和 `16` 的 `node` 值的作业运行时，作业中将包含一个被称为 `npm` 且值为 `6` 的其他变量。 ```yaml jobs: example_matrix: strategy: matrix: os: [windows-latest, ubuntu-latest] node: [14, 16] include: - os: windows-latest node: 16 npm: 6 runs-on: ${{ matrix.os }} steps: - uses: actions/setup-node@v7 with: node-version: ${{ matrix.node }} - if: ${{ matrix.npm }} run: npm install -g npm@${{ matrix.npm }} - run: npm --version ``` ### 示例：添加配置 例如，此矩阵将运行 10 个作业，矩阵中每个 `os` 和 `version` 的组合一个作业，再加上一个用于 `windows-latest` 的 `os` 值和 `17` 的 `version` 值的作业。 ```yaml jobs: example_matrix: strategy: matrix: os: [macos-latest, windows-latest, ubuntu-latest] version: [12, 14, 16] include: - os: windows-latest version: 17 ``` 如果未指定任何矩阵变量，则运行 `include` 下的所有配置。 例如，以下工作流将运行两个作业，每个 `include` 一个作业。 这样你可以利用矩阵策略，而无需完全填充矩阵。 ```yaml jobs: includes_only: runs-on: ubuntu-latest strategy: matrix: include: - site: "production" datacenter: "site-a" - site: "staging" datacenter: "site-b" ``` ## `jobs..strategy.matrix.exclude` 排除的配置必须是部分匹配项，才能将其排除。 所有 `include` 组合会在 `exclude` 之后处理。 这允许你使用 `include` 添加回以前排除的组合。 ## `jobs..strategy.fail-fast` 你可以使用 `jobs..strategy.fail-fast` 和 `jobs..continue-on-error` 来控制如何处理作业失败。 `jobs..strategy.fail-fast` 适用于整个矩阵。 如果 `jobs..strategy.fail-fast` 设置为 `true`，或者其表达式计算结果为 `true`，则在矩阵中的任何作业失败的情况下，GitHub 将取消矩阵中所有正在进行和在队列中的作业。 此属性的默认值为 `true`。 `jobs..continue-on-error` 适用于单个作业。 如果 `jobs..continue-on-error` 为 `true`，即使具有 `jobs..continue-on-error: true` 的作业失败，矩阵中的其他作业也将继续运行。 可以同时使用 `jobs..strategy.fail-fast` 和 `jobs..continue-on-error`。 例如，以下工作流将启动四个作业。 对于每个作业，`continue-on-error` 都由 `matrix.experimental` 的值确定。 如果任何具有 `continue-on-error: false` 的作业失败，所有正在进行或加入队列的作业都将被取消。 如果具有 `continue-on-error: true` 的作业失败，则其他作业将不会受到影响。 ```yaml jobs: test: runs-on: ubuntu-latest continue-on-error: ${{ matrix.experimental }} strategy: fail-fast: true matrix: version: [6, 7, 8] experimental: [false] include: - version: 9 experimental: true ``` ## `jobs..strategy.max-parallel` 默认情况下， GitHub 将根据运行程序可用性将并行运行的作业数最大化。 ## `jobs..continue-on-error` `jobs..continue-on-error` 适用于单个作业。 如果 `jobs..continue-on-error` 为 `true`，即使具有 `jobs..continue-on-error: true` 的作业失败，矩阵中的其他作业也将继续运行。 防止工作流程运行在作业失败时失败。 设置为 `true` 以允许工作流运行在此作业失败时通过。 ### 示例：防止特定失败的矩阵作业无法运行工作流程 您可以允许作业矩阵中的特定作业失败，但工作流程运行不会失败。 例如，工作流运行不失败的情况下只允许在 `node` 设置为 `15` 的实验性作业失败。 ```yaml runs-on: ${{ matrix.os }} continue-on-error: ${{ matrix.experimental }} strategy: fail-fast: false matrix: node: [13, 14] os: [macos-latest, ubuntu-latest] experimental: [false] include: - node: 15 os: ubuntu-latest experimental: true ``` ## `jobs..container` > \[!NOTE] > 如果工作流使用 Docker 容器操作、作业容器或服务容器，则必须使用 Linux 运行器： > > * 如果您要使用 GitHub 托管的运行器，则必须使用 Ubuntu 运行器。 > * 如果您要使用自托管运行器，则必须使用 Linux 机器作为运行器，并且必须安装 Docker。 使用 `jobs..container` 创建用于运行作业中尚未指定容器的任何步骤的容器。 如有步骤同时使用脚本和容器操作，则容器操作将运行为同一网络上使用相同卷挂载的同级容器。 若不设置 `container`，所有步骤将直接在 `runs-on` 指定的主机上运行，除非步骤引用已配置为在容器中运行的操作。 > \[!NOTE] > 用于容器中的 `run` 步骤的默认 shell 是 `sh`，而不是 `bash`。 这可以使用 [`jobs..defaults.run`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_iddefaultsrun) 或 [`jobs..steps[*].shell`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsshell) 进行替代。 ### 示例：在容器中运行作业 ```yaml copy name: CI on: push: branches: [ main ] jobs: container-test-job: runs-on: ubuntu-latest container: image: node:18 env: NODE_ENV: development ports: - 80 volumes: - my_docker_volume:/volume_mount options: --cpus 1 steps: - name: Check for dockerenv file run: (ls /.dockerenv && echo Found dockerenv) || (echo No dockerenv) ``` 只指定容器映像时，可以忽略 `image` 关键词。 ```yaml jobs: container-test-job: runs-on: ubuntu-latest container: node:18 ``` ## `jobs..container.image` 使用 `jobs..container.image` 定义要用作运行操作的容器的 Docker 映像。 值可以是 Docker Hub 映像名称或注册表名称。 > \[!NOTE] > Docker Hub 通常会对推送和拉取操作设置速率限制，这将影响自托管运行程序上的作业。 不过，根据 GitHub 和 Docker 之间的协议，GitHub 托管的运行程序不受这些限制的约束。 ## `jobs..container.credentials` 如果映像的容器注册表需要身份验证才能拉取映像，可以使用 `jobs..container.credentials` 设置 `username` 和 `password` 的 `map`。 凭据是你将提供给 [`docker login`](https://docs.docker.com/engine/reference/commandline/login/) 命令的相同值。 ### 示例：定义容器注册表的凭据 ```yaml container: image: ghcr.io/owner/image credentials: username: ${{ github.actor }} password: ${{ secrets.github_token }} ``` ## `jobs..container.env` 使用 `jobs..container.env` 以在容器中设置环境变量的 `map`。 ## `jobs..container.ports` 使用 `jobs..container.ports` 设置要在容器上显示的 `array` 个端口。 ## `jobs..container.volumes` 使用 `jobs..container.volumes` 设置容器要使用的卷 `array`。 您可以使用卷分享作业中服务或其他步骤之间的数据。 可以指定命名的 Docker 卷、匿名的 Docker 卷或主机上的绑定挂载。 要指定卷，需指定来源和目标路径： `:`。 `` 是主机上的卷名称或绝对路径，`` 是容器中的绝对路径。 ### 示例：在容器中装载卷 ```yaml volumes: - my_docker_volume:/volume_mount - /data/my_data - /source/directory:/destination/directory ``` ## `jobs..container.options` 使用 `jobs..container.options` 配置其他 Docker 容器资源选项。 有关选项列表，请参阅“[`docker create` 选项](https://docs.docker.com/engine/reference/commandline/create/#options)”。 > \[!WARNING] > 不支持 `--network` 和 `--entrypoint` 选项。 ## `jobs..services` > \[!NOTE] > 如果工作流使用 Docker 容器操作、作业容器或服务容器，则必须使用 Linux 运行器： > > * 如果您要使用 GitHub 托管的运行器，则必须使用 Ubuntu 运行器。 > * 如果您要使用自托管运行器，则必须使用 Linux 机器作为运行器，并且必须安装 Docker。 用于为工作流程中的作业托管服务容器。 服务容器可用于创建数据库或缓存服务（如 Redis）。 运行器自动创建 Docker 网络并管理服务容器的生命周期。 如果将作业配置为在容器中运行，或者步骤使用容器操作，则无需映射端口来访问服务或操作。 Docker 会自动在同一个 Docker 用户定义的桥接网络上的容器之间显示所有端口。 您可以直接引用服务容器的主机名。 主机名会自动映射到您在工作流程中为服务配置的标签名称。 如果配置作业直接在运行器机器上运行，且您的步骤不使用容器操作，则必须将任何必需的 Docker 服务容器端口映射到 Docker 主机（运行器机器）。 您可以使用 localhost 和映射的端口访问服务容器。 有关网络服务容器之间的差异的详细信息，请参阅“[与 Docker 服务容器通信](/zh/enterprise-server@3.22/actions/tutorials/use-containerized-services/use-docker-service-containers)”。 ### 示例：使用 localhost 此示例创建了两个服务：nginx 和 redis。 当指定容器端口但未指定主机端口时，容器端口将随机分配给主机上的空闲端口。 GitHub 在上下文中 `${{job.services..ports}}` 设置分配的主机端口。 在此示例中，可以使用`${{ job.services.nginx.ports['80'] }}`和`${{ job.services.redis.ports['6379'] }}`上下文访问服务主机端口。 ```yaml services: nginx: image: nginx # Map port 8080 on the Docker host to port 80 on the nginx container ports: - 8080:80 redis: image: redis # Map random free TCP port on Docker host to port 6379 on redis container ports: - 6379/tcp steps: - run: | echo "Redis available on 127.0.0.1:${{ job.services.redis.ports['6379'] }}" echo "Nginx available on 127.0.0.1:${{ job.services.nginx.ports['80'] }}" ``` ## `jobs..services..image` 用于作为服务容器来运行操作的 Docker 镜像。 值可以是 Docker Hub 映像名称或注册表名称。 如果为 `jobs..services..image` 分配了空字符串，则服务不会启动。 可以使用此选项来设置条件服务，如下所示。 ```yaml services: nginx: image: ${{ options.nginx == true && 'nginx' || '' }} ``` ## `jobs..services..credentials` 如果映像的容器注册表需要身份验证才能拉取映像，可以使用 `jobs..container.credentials` 设置 `username` 和 `password` 的 `map`。 凭据是你将提供给 [`docker login`](https://docs.docker.com/engine/reference/commandline/login/) 命令的相同值。 ### `jobs..services..credentials` 的示例 ```yaml services: myservice1: image: ghcr.io/owner/myservice1 credentials: username: ${{ github.actor }} password: ${{ secrets.github_token }} myservice2: image: dockerhub_org/myservice2 credentials: username: ${{ secrets.DOCKER_USER }} password: ${{ secrets.DOCKER_PASSWORD }} ``` ## `jobs..services..env` 在服务容器中设置环境变量 `map`。 ## `jobs..services..ports` 设置要在服务容器上显示的端口 `array`。 ## `jobs..services..volumes` 设置服务容器要使用的卷 `array`。 您可以使用卷分享作业中服务或其他步骤之间的数据。 可以指定命名的 Docker 卷、匿名的 Docker 卷或主机上的绑定挂载。 要指定卷，需指定来源和目标路径： `:`。 `` 是主机上的卷名称或绝对路径，`` 是容器中的绝对路径。 ### `jobs..services..volumes` 的示例 ```yaml volumes: - my_docker_volume:/volume_mount - /data/my_data - /source/directory:/destination/directory ``` ## `jobs..services..options` Docker 容器的附加资源选项。 有关选项列表，请参阅“[`docker create` 选项](https://docs.docker.com/engine/reference/commandline/create/#options)”。 > \[!WARNING] > `--network` 选项不受支持。 ## `jobs..uses` 要作为作业运行的可重用工作流程文件的位置和版本。 使用以下语法之一： * `$/.github/workflows/{filename}` 用于同一存储库中的可重用工作流。 这是引用同一存储库中可重用工作流的建议语法。 此语法在 . 中 GitHub Enterprise Server不可用。 * ``` 可重用工作流的 `{owner}/{repo}/.github/workflows/{filename}@{ref}`，这些工作流位于公共、内部和私有存储库中。 ``` * `./.github/workflows/{filename}` 用于同一存储库中的可重用工作流。 使用 <a0/> 引用可重用工作流时，可以是 SHA、发布标记或分支名称。 如果发布标记和分支具有相同的名称，则发布标记优先于分支名称。 出于稳定性和安全性考虑，使用提交 SHA 是最稳妥的选项。 有关详细信息，请参阅“[安全使用指南](/zh/enterprise-server@3.22/actions/reference/security/secure-use#reusing-third-party-workflows)”。 使用或`$/`（不使用）`./``{owner}/{repo}`在同一存储库`@{ref}`中引用可重用工作流时，调用的工作流与调用方工作流的提交相同。 引用 不得包含 后缀， 且在 < a0/> 中 不可用。 不允许使用 `refs/heads` 和 `refs/tags` 等引用前缀。 您不能在此关键词中使用上下文或表达式。 ### `jobs..uses` 的示例 ```yaml jobs: call-workflow-1-in-local-repo: uses: octo-org/this-repo/.github/workflows/workflow-1.yml@172239021f7ba04fe7327647b213799853a9eb89 call-workflow-2-in-local-repo: uses: ./.github/workflows/workflow-2.yml # The `$/` syntax is not available in GitHub Enterprise Server. call-workflow-in-same-repo-at-running-commit: uses: $/.github/workflows/workflow-2.yml call-workflow-in-another-repo: uses: octo-org/another-repo/.github/workflows/workflow.yml@v1 ``` 有关详细信息，请参阅“[重用工作流](/zh/enterprise-server@3.22/actions/how-tos/reuse-automations/reuse-workflows)”。 ## `jobs..with` 当作业用于调用可重用工作流时，可以使用 `with` 来提供传递到被调用工作流的输入的映射。 传递的任何输入都必须与被调用工作流程中定义的输入规范匹配。 与 [`jobs..steps[*].with`](#jobsjob_idstepswith) 不同，你使用 `jobs..with` 传递的输入不可作为环境变量用于被调用工作流中。 但你可以通过使用 `inputs` 上下文来引用输入。 ### `jobs..with` 的示例 ```yaml jobs: call-workflow: uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main with: username: mona ``` ## `jobs..with.` 由输入的字符串标识符和输入的值组成的对。 标识符必须与被调用工作流中由 [`on.workflow_call.inputs.`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/metadata-syntax#inputsinput_id) 定义的输入名称匹配。 值的数据类型必须与被调用工作流中定义的 [`on.workflow_call.inputs..type`](#onworkflow_callinputsinput_idtype) 类型匹配。 允许的表达式上下文：`github` 和 `needs`。 ## `jobs..secrets` 当作业用于调用可重用工作流时，可以使用 `secrets` 来提供传递到被调用工作流的机密的映射。 传递的任何机密都必须与被调用工作流程中定义的名称匹配。 ### `jobs..secrets` 的示例 ```yaml jobs: call-workflow: uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main secrets: access-token: ${{ secrets.PERSONAL_ACCESS_TOKEN }} ``` ## `jobs..secrets.inherit` 使用关键字 `inherit` 将所有调用工作流的机密传递给调用的工作流。 这包括调用工作流有权访问的所有机密，即组织、存储库和环境机密。 关键字 `inherit` 可用于在同一组织中跨存储库或在同一企业中跨组织传递机密。 ### `jobs..secrets.inherit` 的示例 ```yaml on: workflow_dispatch: jobs: pass-secrets-to-workflow: uses: ./.github/workflows/called-workflow.yml secrets: inherit ``` ```yaml on: workflow_call: jobs: pass-secret-to-action: runs-on: ubuntu-latest steps: - name: Use a repo or org secret from the calling workflow. run: echo ${{ secrets.CALLING_WORKFLOW_SECRET }} ``` ## `jobs..secrets.` 由机密的字符串标识符和机密的值组成的对。 标识符必须与被调用工作流中由 [`on.workflow_call.secrets.`](#onworkflow_callsecretssecret_id) 定义的机密名称匹配。 允许的表达式上下文：`github`、`needs` 和 `secrets`。 ## 筛选器模式速查表 您可以在路径、分支和标记过滤器中使用特殊字符。 * `*`：匹配零个或多个字符，但不匹配 `/` 字符。 例如，`Octo*` 匹配 `Octocat`。 * `**`：匹配零个或多个任意字符。 * `?`：匹配零个或一个前面的字符。 * `+`：匹配一个或多个前面的字符。 * `[]` 匹配列在括号中或包含在范围内的一个字母数字字符。 范围只能包括 `a-z`、`A-Z` 和 `0-9`。 例如，范围 `[0-9a-z]` 匹配任何数字或小写字母。 例如，`[CB]at` 匹配 `Cat` 或 `Bat`，而 `[1-2]00` 匹配 `100` 和 `200`。 * `!`：在模式开始时，它将否定以前的正模式。 如果不是第一个字符，它就没有特殊的意义。 字符 `*`、`[` 和 `!` 是 YAML 中的特殊字符。 如果模式以 `*`、`[` 或 `!` 开头，则必须将模式括在引号中。 此外，如果将[流序列](https://yaml.org/spec/1.2.2/#flow-sequences)与包含 `[` 和/或 `]` 的模式一起使用，则必须用引号括住该模式。 ```yaml # Valid paths: - '**/README.md' # Invalid - creates a parse error that # prevents your workflow from running. paths: - **/README.md # Valid branches: [ main, 'release/v[0-9].[0-9]' ] # Invalid - creates a parse error branches: [ main, release/v[0-9].[0-9] ] ``` 有关分支、标签和路径筛选器语法的详细信息，请参阅“[`on..`](#onpushbranchestagsbranches-ignoretags-ignore)”、“[`on..`](#onpull_requestpull_request_targetbranchesbranches-ignore)”和“[`on..paths`](#onpushpull_requestpull_request_targetpathspaths-ignore)”。 ### 匹配分支和标签的模式 | 模式 | 说明 | 示例匹配项 | | ------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------- | | `feature/*` | | | | `*` 通配符匹配任意字符，但不匹配斜杠 (`/`)。 | `feature/my-branch`

`feature/your-branch` | | | `feature/**` | | | | `**` 通配符匹配任意字符，包括分支中的斜杠 (`/`) 和标记名称。 | `feature/beta-a/my-branch`

`feature/your-branch`

`feature/mona/the/octocat` | | | `main`

`releases/mona-the-octocat` | 匹配分支或标记名称的确切名称。 | `main`

`releases/mona-the-octocat` | | `'*'` | 匹配所有不包含斜杠 (`/`) 的分支和标记名称。 | | | `*` 字符是 YAML 中的特殊字符。 当模式以 `*` 开头时，必须使用引号。 | `main`

`releases` | | | `'**'` | 匹配所有分支和标记名称。 这是不使用 `branches` 或 `tags` 筛选器时的默认行为。 | `all/the/branches`

`every/tag` | | `'*feature'` | | | | `*` 字符是 YAML 中的特殊字符。 当模式以 `*` 开头时，必须使用引号。 | `mona-feature`

`feature`

`ver-10-feature` | | | `v2*` | 匹配以 `v2` 开头的分支和标记名称。 | `v2`

`v2.0`

`v2.9` | | `v[12].[0-9]+.[0-9]+` | 将所有语义版本控制分支和标记与主要版本 1 或 2 匹配。 | `v1.10.1`

`v2.0.0` | ### 匹配文件路径的模式 路径模式必须匹配整个路径，并从仓库根开始。 | 模式 | 匹配描述 | 示例匹配项 | | --------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | `'*'` | | | | `*` 通配符匹配任意字符，但不匹配斜杠 (`/`)。 | | | | `*` 字符是 YAML 中的特殊字符。 当模式以 `*` 开头时，必须使用引号。 | `README.md`

`server.rb` | | | `'*.jsx?'` | | | | `?` 字符匹配零个或一个前面的字符。 | `page.js`

`page.jsx` | | | `'**'` | | | | `**`通配符匹配任意字符，包括斜杠 (`/`)。 这是不使用 `path` 筛选器时的默认行为。 | `all/the/files.md` | | | `'*.js'` | | | | `*` 通配符匹配任意字符，但不匹配斜杠 (`/`)。 匹配存储库根目录下的所有 `.js` 文件。 | `app.js`

`index.js` | | | `'**.js'` | 匹配存储库中的所有 `.js` 文件。 | `index.js`

`js/index.js`

`src/js/app.js` | | `docs/*` | 存储库根目录下仅 `docs` 根目录中的所有文件。 | `docs/README.md`

`docs/file.txt` | | `docs/**` | 仓库根目录下 `docs` 目录及其子目录中的任何文件。 | `docs/README.md`

`docs/mona/octocat.txt` | | `docs/**/*.md` | | | | `.md` 目录下任意位置带有 `docs` 后缀的文件。 | `docs/README.md`

`docs/mona/hello-world.md`

`docs/a/markdown/file.md` | | | `'**/docs/**'` | 存储库中任意位置 `docs` 目录下的任何文件。 | `docs/hello.md`

`dir/docs/my-file.txt`

`space/docs/plan/space.doc` | | `'**/README.md'` | 仓库中任意位置的 README.md 文件。 | `README.md`

`js/README.md` | | `'**/*src/**'` | 存储库中任意位置带有 `src` 后缀的文件夹中的任何文件。 | `a/src/app.js`

`my-src/code/js/app.js` | | `'**/*-post.md'` | 存储库中任意位置带有 `-post.md` 后缀的文件。 | `my-post.md`

`path/their-post.md` | | `'**/migrate-*.sql'` | 存储库中任意位置带有 `migrate-` 前缀和 `.sql` 后缀的文件。 | `migrate-10909.sql`

`db/migrate-v1.0.sql`

`db/sept/migrate-v1.sql` | | `'*.md'`

`'!README.md'` | 模式前使用感叹号 `!` 对其进行否定。 当文件与模式匹配并且也匹配文件后面定义的否定模式时，则不包括该文件。 | `hello.md`

| | *不匹配*

`README.md`

`docs/hello.md` | | | | `'*.md'`

`'!README.md'`

`README*` | 模式依次被检查。 否定前一个模式的模式将重新包含文件路径。 | `hello.md`

`README.md`

`README.doc` |