{"meta":{"title":"在工作流中使用预编写的构建基块","intro":"可以使用和自定义预先编写的操作来为工作流提供支持。","product":"GitHub Actions","breadcrumbs":[{"href":"/zh/actions","title":"GitHub Actions"},{"href":"/zh/actions/how-tos","title":"操作方法"},{"href":"/zh/actions/how-tos/write-workflows","title":"编写工作流"},{"href":"/zh/actions/how-tos/write-workflows/choose-what-workflows-do","title":"选择工作流执行的操作"},{"href":"/zh/actions/how-tos/write-workflows/choose-what-workflows-do/find-and-customize-actions","title":"查找和自定义操作"}],"documentType":"article"},"body":"# 在工作流中使用预编写的构建基块\n\n可以使用和自定义预先编写的操作来为工作流提供支持。\n\n## 在工作流程编辑器中浏览 Marketplace 操作\n\n您可以直接在仓库的工作流程编辑器中搜索和浏览操作。 从边栏可以搜索特定的操作、查看特色操作和浏览特色类别。 您还可以查看某项操作从 GitHub 社区获得的星标数。\n\n1. 在代码库中，浏览至要编辑的工作流程文件。\n2. 在文件视图的右上角，若要打开工作流编辑器，请单击 。\n\n\n\n1. 在编辑器右侧，使用 GitHub Marketplace 边栏浏览操作。 带有 徽章的操作表明，GitHub 已将该操作的创建者验证为合作伙伴组织。\n\n!\\[文件编辑器中的工作流的屏幕截图。 侧边栏显示市场操作。 “由 GitHub 验证的创建者”徽章以橙色标出。\n\n## 添加操作到工作流程\n\n您可以通过在工作流程文件中引用操作来向工作流程添加操作。 在工作流程中使用的操作可以定义于：\n\n* 与工作流文件相同的存储库\n* 任何公共仓库\n* Docker Hub上已发布的 Docker 容器映像\n\n可以在包含工作流的存储库的依赖项关系图中查看工作流中 GitHub Actions 引用的操作。 有关详细信息，请参阅“[依赖项关系图](/zh/code-security/concepts/supply-chain-security/dependency-graph)”。\n\n> \\[!NOTE]\n> 为了增强安全性，GitHub Actions 不支持对操作或可重用工作流进行重定向。 这意味着，当所有者、操作存储库的名称或操作名称发生更改时，使用该操作并具有先前名称的任何工作流都将失败。\n\n### 从 GitHub Marketplace 中添加操作\n\n操作的列表页包括操作的版本以及使用操作所需的工作流程语法。 为使工作流程在操作有更新时也保持稳定，您可以在工作流程文件中指定 Git 或 Docker 标记号以引用所用操作的版本。\n\n1. 导航到要在工作流程中使用的操作。\n2. 点击查看该操作的完整市场清单。\n3. 在“安装”下，单击 以复制工作流语法。\n\n\n\n1. 将语法粘贴为工作流程中的新步骤。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idsteps)”。\n2. 如果操作要求您提供输入，请将其设置在工作流程中。 有关操作可能需要的输入的信息，请参阅“[在工作流中使用预编写的构建基块](/zh/actions/how-tos/write-workflows/choose-what-workflows-do/find-and-customize-actions#using-inputs-and-outputs-with-an-action)”。\n\n您还可以为添加到工作流中的操作启用 Dependabot version updates。 有关详细信息，请参阅“[使用 Dependabot 保持操作的最新状态](/zh/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/auto-update-actions)”。\n\n### 从相同仓库添加操作\n\n如果在工作流文件使用该操作的同一存储库中定义操作，则可以使用 `$/path/to/dir` 自存储库引用或工作流文件中的 `{owner}/{repo}@{ref}` 语法 `./path/to/dir` 引用操作。 语法 `$/` 在 . 中 GitHub Enterprise Server不可用。\n\n示例仓库文件结构：\n\n```shell\n|-- hello-world (repository)\n| |__ .github\n| └── workflows\n| └── my-first-workflow.yml\n| └── actions\n| |__ hello-world-action\n| └── action.yml\n```\n\n建议使用 `$/path/to/dir` 自存储库引用来引用操作。 这会在正在运行的提交时解析为同一存储库，因此无需先签出存储库。 有关如何`$/`比较和`{owner}/{repo}@{ref}`的详细信息`./`，请参阅 [GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#example-using-an-action-in-the-same-repository-as-the-workflow-at-the-running-commit-recommended)。\n\n使用 `$/`： 的示例工作流文件\n\n```yaml\njobs:\n my_first_job:\n runs-on: ubuntu-latest\n steps:\n # This step references an action in the same repository at the\n # running commit. No repository checkout is required.\n - name: Use hello-world-action\n uses: $/.github/actions/hello-world-action\n```\n\n还可以使用相对 `./path/to/dir` 语法引用操作，但它更容易出错。 该路径是默认工作目录的相对（`./``github.workspace`），`$GITHUB_WORKSPACE`因此它需要签出步骤，如果操作签出存储库的位置与工作流不同，则必须更新相对路径。\n\n使用 `./`： 的示例工作流文件\n\n```yaml\njobs:\n my_first_job:\n runs-on: ubuntu-latest\n steps:\n # This step checks out a copy of your repository.\n - name: My first step - check out repository\n uses: actions/checkout@v6\n # This step references the directory that contains the action.\n - name: Use local hello-world-action\n uses: ./.github/actions/hello-world-action\n```\n\n`action.yml` 文件用于提供操作的元数据。 在“[元数据语法参考](/zh/actions/reference/workflows-and-actions/metadata-syntax)”中了解此文件的内容。\n\n### 从不同仓库添加操作项\n\n如果操作在与工作流文件不同的存储库中定义，可在工作流文件中通过 `{owner}/{repo}@{ref}` 语法引用该操作。\n\n该操作必须存储在公共存储库。\n\n```yaml\njobs:\n my_first_job:\n steps:\n - name: My first step\n uses: actions/setup-node@v7\n```\n\n### 在 Docker Hub 上引用容器\n\n如果在 Docker Hub 上发布的 Docker 容器镜像中定义了的操作，则必须在工作流文件中使用 `docker://{image}:{tag}` 语法引用该操作。 为了保护您的代码和数据，我们强烈建议在将 Docker 容器映像用于工作流程之前，先验证从 Docker Hub 获取的映像的完整性。\n\n```yaml\njobs:\n my_first_job:\n steps:\n - name: My first step\n uses: docker://alpine:3.8\n```\n\n有关 Docker 操作的一些示例，请参阅“[Docker-image.yml 工作流](https://github.com/actions/starter-workflows/blob/main/ci/docker-image.yml)”和“[创建 Docker 容器操作](/zh/actions/tutorials/use-containerized-services/create-a-docker-container-action)”。\n\n### 使用工作流中操作的安全性强化\n\nGitHub 提供可用于提高工作流安全性的安全功能。 可以使用 GitHub“内置功能”确保收到有关所用操作中的漏洞的通知，或自动执行使工作流中的操作保持最新状态的过程。 有关详细信息，请参阅“[安全使用指南](/zh/actions/reference/security/secure-use)”。\n\n## 为自定义操作使用发布管理\n\n社区操作的创建者可以选择使用标记、分支或 SHA 值来管理操作的版本。 与任何依赖项类似，您应该根据自动接受操作更新的舒适程度来指示要使用的操作版本。\n\n您将在工作流程文件中指定操作的版本。 查阅该操作的文档，以了解其发行管理方法的信息，并查看可使用的标签、分支或 SHA 值。\n\n> \\[!NOTE]\n> 建议在使用第三方操作时使用 SHA 值。 但是，请务必注意，Dependabot 只会为使用语义版本控制的易受攻击的 Dependabot alerts 创建 GitHub Actions。 有关详细信息，请参阅 [安全使用指南](/zh/actions/reference/security/secure-use#using-third-party-actions) 和 [Dependabot 警报](/zh/code-security/concepts/supply-chain-security/dependabot-alerts)。\n\n### 使用标记\n\n标记可用于让您决定何时在主要版本和次要版本之间切换，但这只是临时的，可能被维护员移动或删除。 此示例演示如何定位已标记为 `v1.0.1` 的操作：\n\n```yaml\nsteps:\n - uses: actions/javascript-action@v1.0.1\n```\n\n### 使用 SHA 算法\n\n如果需要更可靠的版本控制，应使用与操作版本关联的 SHA 值。 SHA 是不可变的，因此比标记或分支更可靠。 但是，此方法意味着你不会自动接收操作的更新，包括重要的 Bug 修复和安全更新。 必须使用提交的完整 SHA 值，而不是缩写值。\n选择 SHA 时，应验证它是否来自操作的存储库，而不是存储库分支。 此示例针对操作的 SHA：\n\n```yaml\nsteps:\n - uses: actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f\n```\n\n### 使用分支\n\n为操作指定目标分支意味着它将始终在该分支上运行当前的版本。 如果对分支的更新包含重大更改，此方法可能会造成问题。 此示例针对名为 `@main` 的分支：\n\n```yaml\nsteps:\n - uses: actions/javascript-action@main\n```\n\n有关详细信息，请参阅“[管理自定义操作](/zh/actions/how-tos/create-and-publish-actions/manage-custom-actions#using-release-management-for-actions)”。\n\n## 对操作使用输入和输出\n\n操作通常接受或需要输入并生成可以使用的输出。 例如，操作可能要求您指定文件的路径、标签的名称或它将用作操作处理一部分的其他数据。\n\n若要查看操作的输入和输出，请检查存储库根目录中的 `action.yml`。\n\n在示例 `action.yml` 中，`inputs` 关键字定义名为 `file-path` 的必需输入，并且包括在未指定任何输入时使用的默认值。\n`outputs` 关键字定义名为 `results-file` 的输出，指示在何处查找结果。\n\n```yaml\nname: \"Example\"\ndescription: \"Receives file and generates output\"\ninputs:\n file-path: # id of input\n description: \"Path to test script\"\n required: true\n default: \"test-file.js\"\noutputs:\n results-file: # id of output\n description: \"Path to results file\"\n```"}