> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.another-horizon.eu/llms.txt
> Use this file to discover all available pages before exploring further.
# 教程：代码变更时自动更新文档
> 使用代理 API 自动更新文档。
## 你将构建的内容
一个自动化流程：当代码推送到主 branch 时自动更新文档。该工作流可在多个平台上搭建，包括 GitHub Actions 和 n8n。它会监控你的代码存储库，然后调用代理 API，在单独的文档存储库中更新文档。
此工作流连接两个独立的存储库：
* **代码存储库**：用于存放应用程序代码。你将在此存储库上设置自动化触发器。示例包括后端 API、前端应用、SDK，或命令行界面（CLI）工具。
* **文档存储库**：用于存放文档并连接到你的 Mintlify 项目。代理会在此存储库中创建包含文档更新的拉取请求（PR；亦称“合并请求”/Merge Request）。
本教程假设你的文档与应用程序代码位于不同的存储库中。如果你使用 monorepo，请修改工作流以定位存放文档的目录。
### 工作流概览
1. 有人将代码推送到你的主分支。
2. 工作流被触发。
3. 工作流调用代理的 API 来更新你的文档。
4. 代理在你的文档存储库中创建一个包含文档更新的拉取请求（PR）。
## 选择你的平台
如果您的代码已在 GitHub 上,GitHub Actions 是最简单的选择。无需额外服务。
## 前提条件
* 已在代码和文档仓库中启用 GitHub Actions
* 已在代码和文档仓库中安装 [Mintlify GitHub 应用](/zh/deploy/github)
* [Mintlify 管理 API 密钥](https://dashboard.mintlify.com/settings/organization/api-keys)
* [Mintlify 项目 ID](https://dashboard.mintlify.com/settings/organization/api-keys)
* [Mintlify Pro 或 Custom 方案](https://mintlify.com/pricing)
* 对存放您代码和文档的 GitHub 仓库拥有管理员权限
### 在代码仓库中安装 Mintlify 应用
必须在您的代码存储库中安装 Mintlify 应用,以便 agent 能够从代码库获取上下文信息。要将应用添加到新存储库:
1. 在 Mintlify 控制台中打开 agent 面板。
2. 点击 **Settings** 按钮。
3. 点击 **Add to New Organization**。这会打开 GitHub 上的应用安装页面。
4. 从列表中选择要授予访问权限的仓库。
5. 保存更改。
### 获取管理员 API 密钥
1. 在仪表盘中前往 [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) 页面。
2. 选择 **Create Admin API Key**。
3. 将该密钥复制并妥善保存。
## 构建工作流
### 创建工作流文件
1. 在代码仓库中创建一个新文件：`.github/workflows/update-docs.yml`
2. 添加以下工作流：
```yaml theme={null}
name: 更新文档
on:
push:
branches:
- main
jobs:
update-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v8
env:
MINTLIFY_API_KEY: ${{ secrets.MINTLIFY_API_KEY }}
PROJECT_ID: ${{ secrets.MINTLIFY_PROJECT_ID }}
with:
script: |
const { owner, repo } = context.repo;
const projectId = process.env.PROJECT_ID;
const apiKey = process.env.MINTLIFY_API_KEY;
if (!projectId || !apiKey) {
core.setFailed('缺少 MINTLIFY_PROJECT_ID 或 MINTLIFY_API_KEY 密钥');
return;
}
const url = `https://api.mintlify.com/v1/agent/${projectId}/job`;
const payload = {
branch: `mintlify/docs-update-${Date.now()}`,
messages: [
{
role: 'system',
content: '你是一个根据代码变更自动更新文档的操作执行器。你不应该提出任何问题。如果无法访问代码仓库,请报告错误并退出。'
},
{
role: 'user',
content: `更新我们最近推送到 main 分支的文档:\n\n代码仓库: ${owner}/${repo}`
}
],
asDraft: false
};
try {
const response = await fetch(url, {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(payload)
});
if (!response.ok) {
throw new Error(`API 请求失败,状态码为 ${response.status}: ${await response.text()}`);
}
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';
while (true) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
const lines = buffer.split('\n');
buffer = lines.pop() || '';
for (const line of lines) {
if (line.trim()) {
console.log(line);
}
}
}
if (buffer.trim()) {
console.log(buffer);
}
core.notice(`已为 ${owner}/${repo} 触发文档更新任务`);
} catch (error) {
core.setFailed(`创建文档更新任务失败: ${error.message}`);
}
```
### 添加密钥
1. 在代码仓库中，依次点击 **Settings** → **Secrets and variables** → **Actions**。
2. 点击 **New repository secret**。
3. 添加以下机密：
* 名称：`MINTLIFY_API_KEY`，Secret：您的 Mintlify 管理员 API 密钥
* 名称：`MINTLIFY_PROJECT_ID`，Secret：您的 Mintlify 项目 ID（可在仪表盘的 [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) 页面找到）
更多信息请参阅 GitHub 文档中的[在 GitHub Actions 中使用密钥](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)。
## 测试自动化
1. 在你的代码仓库中做一个小改动，并推送到 main 分支：
```bash theme={null}
git add .
git commit -m "测试：触发文档自动化"
git push origin main
```
2. 在代码仓库中打开 **Actions** 选项卡，查看工作流的运行情况。
3. 工作流运行完成后，查看你的文档仓库中是否已创建包含文档更新的新分支和拉取请求（pull request）。
## 故障排除
### 工作流未运行
* 请确认已在代码仓库中启用 GitHub Actions。
* 在 **Actions** 选项卡中查看错误信息。
* 确保工作流文件位于 `.github/workflows/` 目录下，并使用 `.yml` 扩展名。
### 代理 API 返回 401 错误
* 请确认你的 API 密钥是否以 `mint_` 开头。
* 检查 Authorization 请求头的格式是否为 `Bearer mint_yourkey`。
* 确认该 API 密钥对应的是正确的 Mintlify 组织。
### 文档更新未显示
* 确认文档仓库已连接到你的 Mintlify 项目。
* 确认代理对文档仓库有写入权限。
* 查看工作流日志中代理返回的错误信息。
n8n 提供可视化工作流编辑器,并可与多种服务集成。
## 前提条件
* n8n 工作区
* [Mintlify Pro 或 Custom 方案](https://mintlify.com/pricing)
* 已在你的代码仓库中安装 Mintlify 应用
* Mintlify 管理 API 密钥
* 对存放您代码和文档的 GitHub 仓库的管理员访问权限
* GitHub 个人访问令牌
### 在代码仓库中安装 Mintlify 应用
必须在您的代码存储库中安装 Mintlify 应用,以便 agent 能够从代码库获取上下文信息。要将应用添加到新存储库:
1. 在 Mintlify 控制台中打开 agent 面板。
2. 点击 **Settings** 按钮。
3. 点击 **Add to New Organization**。这会带你前往 GitHub 上的应用安装页面。
4. 从列表中选择要授予访问权限的仓库。
5. 保存更改。
### 获取管理员 API 密钥
1. 在仪表盘中前往 [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) 页面。
2. 选择 **Create Admin API Key**。
3. 将该密钥复制并妥善保存。
### 获取 GitHub 个人访问令牌
1. 在 GitHub 中，转到 **Settings**。
2. 点击 **Developer settings**。
3. 点击 **Personal access tokens**（个人访问令牌）。
4. 点击 **Tokens (classic)**。
5. 单击 **Generate new token (classic)**。
6. 选择以下权限范围：
* `repo`（对私有仓库拥有完全控制权限）
* `admin:repo_hook`（如果你希望由 n8n 创建 webhooks）
7. 生成令牌并妥善保存。
更多信息请参阅 GitHub 文档中的[创建个人访问令牌(经典版)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens?versionId=free-pro-team%40latest\&productId=account-and-profile#creating-a-personal-access-token-classic)。
## 构建工作流
### 创建 webhook 触发器
1. 在 n8n 中创建一个新工作流。
2. 添加一个 Webhook 节点。
3. 配置 Webhook：
* HTTP 方法：`POST`
* 路径：`auto-update-documentation`（或任何唯一路径）
* 认证：无
* 响应：立即
4. 保存工作流。
5. 复制该 webhook 的生产环境 URL，类似于：`https://your-n8n-instance.app.n8n.cloud/webhook/auto-update-documentation`
### 设置 GitHub webhook
1. 前往你在 GitHub 上的代码仓库。
2. 点击 **Settings**。
3. 点击 **Webhooks**。
4. 点击 **Add webhook**.
5. 配置 Webhook：
* Payload URL：粘贴你的 n8n webhook URL
* Content type：`application/json`
* Which events would you like to trigger this webhook?
* 选择 **Let me select individual events.**
* 只选择 **Push events**。
* 勾选 **Active**
6. 点击 **Add webhook**。
### 筛选主分支推送
在 webhook 之后添加代码节点,以筛选推送到 main 分支的事件并提取相关信息。
1. 添加一个代码节点。
2. 将其命名为“Filter main pushes.”。
3. 将模式设置为 **Run Once for All Items**（对所有项目仅运行一次）。
4. 添加以下 JavaScript 代码：
```javascript theme={null}
const webhookData = $input.first().json.body;
// 仅在推送到 main 分支时继续执行
if (webhookData.ref !== "refs/heads/main") {
return [];
}
// 提取信息
const repository = webhookData.repository;
const pusher = webhookData.pusher;
// 构建 agent 消息
const agentMessage = `更新 ${repository.name} 中推送到 main 分支的变更文档。始终编辑文件并创建拉取请求（PR；亦称"合并请求"/Merge Request）。`;
return {
json: {
codeRepoName: repository.full_name,
codeRepoShortName: repository.name,
agentMessage: agentMessage
}
};
```
此代码会在推送不是到 main 分支时停止工作流,从 GitHub webhook 中提取所有相关信息,并为 agent API 创建消息。
### 调用 Agent API
添加 HTTP 请求节点以创建文档任务。
1. 添加一个 HTTP 请求节点。
2. 将其命名为 "Create agent job."
3. 配置请求：
* 方法：`POST`
* URL：`https://api.mintlify.com/v1/agent/YOUR_PROJECT_ID/job`（将 `YOUR_PROJECT_ID` 替换为你在 [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) 页面中看到的项目 ID）
* 认证方式：Generic Credential Type → Header Auth
* 创建一个新的凭证：
* Name：`Authorization`
* Value：`Bearer mint_YOUR_API_KEY`（替换为你的 API 密钥）
* Send Body：On（发送请求体）
* Body Content Type：JSON（请求体内容类型）
* Specify Body：Using JSON（使用 JSON 指定请求体）
* 添加以下 JSON：
```json theme={null}
{
"branch": "docs-update-from-{{ $json.codeRepoShortName }}-{{ $now.toISOString() }}",
"messages": [
{
"role": "system",
"content": "{{ $json.agentMessage }}"
}
],
"asDraft": false
}
```
代理会在您的文档存储库中创建一个拉取请求（PR；亦称"合并请求"/Merge Request），使用包含源存储库名称和时间戳的描述性 branch 名称。
### 激活工作流
1. 保存该工作流。
2. 将其启用。
您的工作流现在正在监控代码仓库向 main 分支的推送。
## 测试自动化
1. 在代码仓库中创建测试分支：
```bash theme={null}
git checkout -b test-docs-automation
```
2. 进行一个小改动并提交：
```bash theme={null}
git add .
git commit -m "测试：触发文档自动化"
git push origin test-docs-automation
```
3. 在 GitHub 上发起一个 Pull Request。
4. 合并拉取请求。
### 验证自动化
您应该会看到一个新的 n8n 执行记录,其中所有节点都已成功完成,同时在您的文档存储库中会创建一个新 branch 和拉取请求（PR；亦称"合并请求"/Merge Request）。
## 故障排除
### Webhook 未触发
* 确认该工作流在 n8n 中处于激活状态。
* 在 GitHub 仓库的“Settings → Webhooks → Recent Deliveries”中查看响应状态码。
* 确保 webhook URL 与你的 n8n webhook URL 完全一致。
### 代理 API 返回 401 错误
* 请确认你的 API 密钥是否以 `mint_` 开头。
* 检查 Authorization 请求头的格式是否为 `Bearer mint_yourkey`。
* 确认该 API 密钥属于正确的 Mintlify 组织。
### GitHub 401 错误
* 确认你的令牌具有 `repo` 权限范围。
* 确认该 token 尚未过期。
* 请确认你在 GitHub 请求中包含了 `User-Agent` 请求头。