管理自动化

• 一个已连接到 GitHub 或 GitLab 仓库的 Mintlify 项目
• 对于 GitHub：在你计划用于自动化的每个仓库上都安装 Mintlify GitHub 应用
• 对于 GitLab：已连接的 GitLab 账户（请参见下方GitLab 设置）

1. 在控制台中打开 Automations 页面。

2. 点击自动化旁边的开关以启用它。

   

   如果自动化可以使用默认设置运行，它会立即激活。否则，该自动化的配置页面会打开，让你填写任何必需的配置。

3. 如果配置页面打开，请填写必填字段并点击 Save。

要更改已激活自动化的设置，点击其卡片上的 设置按钮以打开其配置页面。使用页面头部的开关可以启用或禁用自动化，然后点击 Save 应用你的更改。

每个自动化的配置页面将设置分为 Trigger、Scope 和 Advanced options 三个部分。

每个自动化都有一个默认触发器来控制运行时机。要更改触发器，在自动化的配置页面上选择不同的触发器类型。

• 内容更新（Content update）：每当你向项目仓库推送内容时运行，包括 pull request 合并和直接推送。
• 代码变更（Code change）：当已连接的源代码仓库中有 pull request 合并时运行。你必须至少指定一个源仓库。点击 Add repo 可让来自多个仓库的 pull request 触发该自动化。对于每个仓库，你可以选择设置 Exclude author 来忽略来自特定作者的 pull request，以及 Listening to changes in 仅在特定路径下有变更的 pull request 时触发。
• 自定义计划（Custom schedule）：按你定义的周期性计划运行。选择一个预设（Daily、Every Monday、Every Friday 或 Twice weekly）以及起始小时，或选择 Custom cron 并输入标准的 5 段式 cron 表达式（minute hour day month weekday）。cron 值以 UTC 存储；控制台会在你的本地时区与预设小时之间进行转换。自动化会在预定时间的 10 分钟内进入队列。
• 集成（Integration）：当已连接的共享集成中发生所选事件时运行，或当在所选 Slack 频道中发布新的顶层消息时运行。此选项适用于自定义自动化。请选择集成和事件，并填写出现的任何其他事件字段。对于 Slack 触发器，请选择一个或多个已添加 Mintlify Slack 应用的频道。
• Webhook：当一个已认证的 POST 请求命中自动化的 webhook 端点时运行。仅适用于自定义自动化。先保存自动化；触发器卡片随后会显示 webhook URL 和用于 Authorization: Bearer <api-key> 请求头的 Copy auth header 操作。在 API keys 页面提供一个具有写入权限且未过期的组织 API 密钥。可用于从 CI/CD 流水线、发布脚本或内部工具触发运行。有关端点和速率限制，请参见触发自动化 webhook。

对于在 GitHub 上使用**代码变更（Code change）**触发器的自动化，每个源代码仓库在配置页面上都会显示为独立的卡片。每个自动化最多可添加 50 个仓库。在每张卡片的 Show advanced options 中，你可以缩小该仓库触发自动化的范围：

• Listening to changes in：添加 pull request 必须涉及的路径，自动化才会运行。路径可以是文件、文件夹或 glob 模式（例如 docs/**/*.mdx）。建议来自仓库中被跟踪的文件；你也可以输入自定义路径。
• Excluding PRs from：添加不应触发自动化的 GitHub 用户名或机器人账户。适合跳过自动化账户的合并操作。建议来自近期的贡献者；你也可以输入自定义用户名。

每个仓库最多支持 20 条路径和 20 个被排除的作者。在卡片上更换仓库会清除其过滤器。GitLab 源代码仓库不支持按仓库过滤，仍使用单一的仓库选择器。

每个自动化都有一种默认的更新方式：要么直接将更改合并到你的内容仓库，要么打开一个 pull request 以供审查。

在自动化配置页面的 After automation runs 部分选择更新模式。选择 Update and merge changes 可自动合并更改。选择 Modify and wait for review 则要求在更改上线前进行审查。

对于自定义自动化和部分预定义自动化，你可以添加上下文仓库——自动化运行时 agent 读取的额外源代码仓库。这在你的自动化提示词引用了项目仓库之外的代码、API 或其他内容时很有用。

每个自动化最多可添加 10 个上下文仓库。对于每个 GitHub 仓库，请安装 Mintlify GitHub 应用。在 GitHub App settings 页面添加仓库。

对于自定义自动化和其他受支持的预定义自动化，你可以启用集成，让 agent 在运行时从 Notion、Jira 或 Linear 等共享工具获取上下文。

要为某个自动化启用集成，打开其配置页面，展开 Advanced options，然后在 Integrations 中选择你想使用的集成。

如果选择 集成（Integration） 作为触发器，触发该自动化的集成会自动添加为工具。有关连接范围、支持的事件和权限，请参见集成。

在自动化运行时向一个或多个频道发送 Slack 消息。

要启用 Slack 通知：

1. 在你的工作区安装 Mintlify Slack 应用。
2. 在控制台的 Automations 页面点击 Configure Slack。
3. 选择一个或多个用于接收通知的频道。
4. 点击 Save changes。

启用后，Mintlify 会在以下情况下向所选频道发送消息：

• 自动化打开了 pull request 等待审查。
• 自动化的 pull request 已等待审查三天。
• 自动化合并了 pull request 或未能完成。

若要在自动化运行成功或失败时收到电子邮件，请在控制台的通知页面开启自动化运行邮件。

在配置页面的 Scope 部分添加可选指令。对于预定义自动化，此字段名为 Additional prompts，会在每次运行时附加到自动化的基础提示词。对于自定义自动化，此字段名为 Prompt，是该自动化的完整指令集。使用它来调整风格、语气或其他项目特有的行为，而无需更改核心自动化逻辑。

启用 Translate content 自动化时，选择一种或多种语言以与你的源内容保持同步。

• Mintlify 会读取你 docs.json 中定义的languages以识别默认语言，并预选已配置的目标语言。
• 你必须至少选择一个目标语言才能保存自动化。
• 你无法选择源语言作为目标。

随时可通过打开自动化的配置页面并编辑 Translate to 字段来添加目标语言。

GitLab 设置

要在自动化中使用 GitLab 仓库，请通过 GitLab OAuth 设置页面连接每个项目。请连接自动化涉及的所有仓库——你的文档仓库以及任何触发或上下文仓库。你必须在每个项目中至少具有 Maintainer 角色。

1. 进入控制台中的 Automations 页面。
2. 点击自动化旁边的开关以禁用它。

当你重新启用一个计划自动化或更改其计划时，Mintlify 会从当前时间重新计算下次运行时间。已禁用的自动化不会保留待运行时间。

你可以在控制台中删除自定义自动化。预定义自动化无法从控制台删除。请改为禁用它们，或使用 CLI 来移除。

1. 在控制台中打开 Automations 页面。
2. 点击自定义自动化卡片上的 设置按钮以打开其配置页面。
3. 点击页面底部的 Delete automation 并确认。

要在终端中删除任意自动化，请使用 mint automations。删除操作是永久性的，无法撤销。

你可以按需触发自动化，而无需等待其下一次预定或事件触发的运行。

1. 在控制台中打开 Automations 页面。
2. 点击自动化卡片上的 设置按钮以打开其配置页面。
3. 点击运行按钮（根据自动化不同，为 Test run 或 Run now）。
4. 选择运行范围。
   • Since a date：审查从所选日期到当前时间的更改。日期默认为该自动化的上次运行时间；如果从未运行过，则默认为七天前。
   • Everything：审查整个站点或仓库历史。此范围通常比定向运行耗时更长。
   • Specific pull request：将运行限制为所选仓库中的一个 pull request。
5. 点击 Run now。

手动运行会在开始前保存自动化的当前配置并激活该自动化。这些运行会计入你的积分使用量，并与自动触发的运行一起出现在运行历史中。

你可以手动运行使用计划、内容更新或代码变更触发器的自动化。由集成或 webhook 触发的自动化仅在其触发器触发时运行，因此其运行按钮不可用。Translate content 自动化始终可以手动运行。

对于使用自定义计划触发器的自动化，你可以从自己的工具中启动一次运行，而无需等待下一次计划时间。使用 Trigger automation 端点，可以从 CI/CD 流水线、发布脚本或任何可以发起经过身份验证的 HTTP 请求的服务触发一次运行。

通过 API 触发的运行与计划运行的行为完全相同：它们会处理上次完成运行以来发生的所有变更，会计入积分使用量，并出现在运行历史中。

具有 Webhook 触发器的自定义自动化会在已认证的 POST 请求到达其 webhook 端点时运行。保存自动化后，打开其配置页面即可复制 webhook URL 并查看 Authorization: Bearer <api-key> 请求头模板。将 <api-key> 替换为在 API keys 页面创建的、具有写入权限且未过期的组织 API 密钥。自动化不会为你创建、存储或轮换密钥。

通过 webhook 触发的运行使用自动化保存的提示词，读取完整的仓库历史，并在运行历史中以 Webhook request 标签显示。有关请求格式、响应代码和速率限制，请参见触发自动化 webhook。

自动化页面上的 Runs 标签页会显示所有自动化的全部运行列表。

一次运行是自动化的一次执行。一次运行可以创建新的 pull request、更新现有的 pull request、运行失败，或未发现需要更改的内容。

1. 进入控制台中的 Automations 页面。
2. 使用下拉菜单按特定自动化或状态进行过滤。

每个结果会显示以下状态之一：

• Review needed：agent 已完成运行，但更改需要你团队中的成员审查并合并。
• Running：agent 正在执行该自动化任务。
• Accepted：agent 已完成运行，更改已合并到你的仓库。
• Closed：agent 已完成运行，但有人拒绝了这些更改。
• Failed：agent 无法完成运行。
• No action needed：agent 完成了运行，但未发现需要更新的内容。
• Modified PR：该结果将更改追加到了先前运行打开的 pull request 中。

你可以直接在列表中对结果执行操作。对于等待审查的运行，点击 Accept 合并更改，或点击 Preview 打开该运行分支的 preview deployment。要在编辑器中打开该运行的分支，请点击 View changes，或打开 菜单并点击 Open in editor。对于失败的结果，点击 Re-trigger 重新开始运行。

只有当运行关联了 preview deployment 时，才会显示 Preview 按钮。preview deployment 在闲置一段时间后会过期；过期后该按钮将被禁用。

如果某次运行的 pull request 与你的部署分支存在冲突，点击 Accept 会打开一个对话框，提供为你解决冲突的选项。点击 Resolve and merge，agent 会将部署分支的最新更改合并到 pull request 分支、解决冲突并自动合并该 pull request。agent 工作期间，运行显示为 Running；pull request 合并后变为 Accepted。如果 agent 无法解决冲突，请在你的仓库中手动解决冲突，然后再次点击 Accept。

要查看某次运行的提示词、读取或更改的文件，以及任何 pull request，请点击该运行的 操作菜单，然后点击 View run details。

当自动化完成并在分支上创建更改后，你可以直接在编辑器中打开这些更改，进行查看、调整或发布。

1. 在控制台中打开 Automations 页面。
2. 在 Runs 标签页中，点击该运行上的 View changes，或打开 操作菜单并点击 Open in editor。这两个选项仅在该运行的 pull request 仍然开启时可用。

编辑器会打开到该自动化的分支。你可以让编辑器中的 agent 继续优化或扩展这些更改；agent 拥有该自动化的完整上下文，包括自动化的提示词、所做更改的摘要，以及修改了哪些页面，因此无需你重新解释背景。