通过公共 API 以编程方式使用环境
你可以使用公共 API,通过脚本和流水线管理 n8n 环境,无需打开 n8n UI。这样便可自动在实例之间推进更改,例如按计划或在 CI/CD 流水线中将开发实例上的工作移至生产环境。
本页介绍源代码管理 API 端点如何协同工作。本文假设你已将实例连接到 Git,并了解 UI 中的推送和拉取行为。如需了解相关背景,请阅读推送和拉取更改以及在环境之间移动工作。
提示
Feature availability 功能可用性
源代码管理的 status 和 push 端点自 n8n 2.39.0 版本起可用。
* GET /api/v1/source-control/status
* POST /api/v1/source-control/push
环境是 Enterprise 功能。
端点
公共 API 提供三种源代码管理操作:
| 端点 | 方法 | 功能 |
|---|---|---|
/source-control/status |
GET |
预览实例与 Git 之间任一方向的待处理更改。 |
/source-control/push |
POST |
提交本地更改并将其推送到已连接的 Git 分支。 |
/source-control/pull |
POST |
从已连接的 Git 分支获取更改并应用到实例。 |
push 和 pull 与源代码管理菜单中的 Push 推送和 Pull 拉取按钮执行相同的操作。status 对应 UI 在确认前于推送和拉取弹窗中显示的文件列表。API 将其作为独立端点提供,以便脚本执行与 UI 内联审查相同的操作。
如需完整的请求和响应模式,请参阅端点参考。
身份验证和作用域
每个请求都需要在 X-N8N-API-KEY 标头中发送 API key。在 Enterprise 计划中,你可以将每个 key 的作用域限制到所需的最低权限:
| 作用域 | 授予的权限 |
|---|---|
sourceControl:pull |
将更改拉取到实例。 |
sourceControl:push |
将本地更改推送到 Git。 |
sourceControl:read |
读取待处理更改的状态。 |
通过这种方式设置 key 的作用域,可以强制限定同步方向。对于只能接收更改的生产实例,请为其 key 授予 sourceControl:pull,使其无法推送。如果还希望该 key 在拉取前通过 status 预览传入的更改,请同时添加 sourceControl:read。
先检查状态,再执行操作
不要在不了解更改内容的情况下直接推送。push 需要一个 fileNames 数组,并且只提交其中列出的文件,因此应先调用 status 查看哪些文件符合条件。
步骤如下:
- 调用
status查看符合条件的文件。 - 确定要包含的内容:包含所有文件以推送全部更改,或选择部分文件以仅推送部分更改。
- 根据所选文件构建
fileNames,仅保留每个文件的id和type。 - 使用该数组调用
push。
调用 status 时使用 direction 查询参数,选择要预览的方向:
curl --request GET \
--location '<YOUR-INSTANCE-URL>/api/v1/source-control/status?direction=push' \
--header 'X-N8N-API-KEY: <YOUR-API-KEY>'
响应中的每个文件都包含其 id、name、type(例如 workflow 或 credential)和 status(例如 modified 或 new):
{
"data": [
{
"id": "1a2b3c",
"name": "Daily sales report",
"type": "workflow",
"status": "modified",
"file": "workflows/1a2b3c.json"
}
]
}
从开发环境推进到只读生产环境
这是一种常见设置:在开发实例上进行更改,然后将其推进到只接收更新的生产实例。本例让两个实例共享一个 Git 分支。
为每个实例提供具有相应作用域的 API key:
- 开发实例的 API key 具有
sourceControl:read和sourceControl:push。 - 生产实例的 API key 具有
sourceControl:read和sourceControl:pull。
1. 预览开发环境中的更改。 使用 direction=push 调用 status,查看 n8n 将提交的内容:
curl --request GET \
--location '<DEV-INSTANCE-URL>/api/v1/source-control/status?direction=push' \
--header 'X-N8N-API-KEY: <DEV-API-KEY>'
2. 从开发环境推送到 Git。 发送提交消息和要推进的文件,并在 fileNames 中以 id/type 对的形式列出。若要推进全部更改,请包含步骤 1 的 status 响应中的每个文件;若只推进部分更改,则包含文件子集:
curl --request POST \
--location '<DEV-INSTANCE-URL>/api/v1/source-control/push' \
--header 'Content-Type: application/json' \
--header 'X-N8N-API-KEY: <DEV-API-KEY>' \
--data '{
"commitMessage": "Promote sales reporting workflows",
"fileNames": [
{
"id": "1a2b3c",
"type": "workflow"
}
]
}'
3. 预览生产环境中的更改。 在应用任何更改前,使用 direction=pull 调用 status,查看 n8n 将应用的内容:
curl --request GET \
--location '<PROD-INSTANCE-URL>/api/v1/source-control/status?direction=pull' \
--header 'X-N8N-API-KEY: <PROD-API-KEY>'
4. 拉取到生产环境。 生产实例读取同一分支并应用更改。使用 force 接受传入版本,并设置 autoPublish 以在工作流到达时发布它们:
curl --request POST \
--location '<PROD-INSTANCE-URL>/api/v1/source-control/pull' \
--header 'Content-Type: application/json' \
--header 'X-N8N-API-KEY: <PROD-API-KEY>' \
--data '{
"force": true,
"autoPublish": "published"
}'
autoPublish 参数接受 none(默认值)、published(仅重新发布已在生产环境中发布的工作流)或 all(发布所有拉取的工作流)。有关各模式的更多详情,请参阅推送和拉取更改。
提示
使用多个分支
如果实例使用不同的 Git 分支,则无法直接推进更改。请从开发环境推送到其分支,在 Git 提供商中将该分支合并到生产分支,然后在生产环境中拉取。有关分支模式,请参阅在环境之间移动工作。
定时备份流程
若要定期在 Git 中对实例进行版本管理,请获取所有符合条件的文件,并按计划推送全部内容。可以从 cron 作业、CI 流水线,或使用 Schedule Trigger 的 n8n 工作流运行此流程。
1. 获取所有符合条件的文件。 使用 direction=push 调用 status:
curl --request GET \
--location '<YOUR-INSTANCE-URL>/api/v1/source-control/status?direction=push' \
--header 'X-N8N-API-KEY: <YOUR-API-KEY>'
2. 推送完整列表。 将 status 响应返回的每个文件映射为其 id 和 type,并作为 fileNames 传递。与推进流程不同,此作业无人值守,并将 force 设置为 true。这样会跳过冲突检查,并始终以实例的当前状态覆盖分支。每次定时运行前,请确保实例保存的是你需要的版本,否则可能会覆盖 Git 中较新的更改。
curl --request POST \
--location '<YOUR-INSTANCE-URL>/api/v1/source-control/push' \
--header 'Content-Type: application/json' \
--header 'X-N8N-API-KEY: <YOUR-API-KEY>' \
--data '{
"commitMessage": "Scheduled backup",
"force": true,
"fileNames": [
{
"id": "1a2b3c",
"type": "workflow"
},
{
"id": "4d5e6f",
"type": "workflow"
},
...
]
}'
处理推送冲突
如果自上次同步以来实例和 Git 都更改了同一个文件,该文件便处于冲突状态。status 会使用 "conflict": true 标记这些文件。如果在未设置 force 的情况下调用 push,且所选文件中有任何文件存在冲突,n8n 会拒绝整个推送并返回 409 响应:
{
"message": "Push blocked by conflicting files. Pass `force: true` to push anyway.",
"conflicts": [
{
"id": "1a2b3c",
"name": "Daily sales report",
"type": "workflow",
"status": "modified",
"file": "workflows/1a2b3c.json",
"conflict": true
}
]
}
若仍要推送,并使用实例版本覆盖 Git 中存在冲突的文件,请将 force 设置为 true:
curl --request POST \
--location '<YOUR-INSTANCE-URL>/api/v1/source-control/push' \
--header 'Content-Type: application/json' \
--header 'X-N8N-API-KEY: <YOUR-API-KEY>' \
--data '{
"commitMessage": "Push reviewed workflows only",
"force": true,
"fileNames": [
{
"id": "1a2b3c",
"type": "workflow"
}
]
}'
推送和拉取的内容
API 提交和应用的资源与 UI 相同:工作流、凭证存根、变量存根、数据表模式、项目、文件夹和标签。如需完整列表以及每种资源类型的合并行为,请参阅推送和拉取更改。
相关资源
- 使用源代码控制和环境
- 了解源代码控制
- 使用环境
- 在 n8n 中使用 Git
- 选择分支模式
- 设置源代码控制
- 推拉变化
- 比较版本
- 在环境之间移动工作
- 教程:使用源代码管理创建环境
- 源代码控制:源代码控制端点的请求和响应模式。
- 端点参考:完整的公共 API 模式。