{ "openapi": "3.0.0", "info": { "title": "n8n 公共 API", "version": "1.1.1" }, "tags": [ { "name": "Promotions", "description": "晋升提供方、环境及包操作相关操作" } ], "servers": [ { "url": "/api/v1", "description": "当前 n8n 实例（自托管版本的内置测试台）" }, { "url": "{url}/api/v1", "description": "自托管 n8n 实例", "variables": { "url": { "default": "https://example.com" } } } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, { "CookieAuth": [] } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-N8N-API-KEY" }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "CookieAuth": { "type": "apiKey", "in": "cookie", "name": "n8n-auth" } }, "schemas": { "promotionEnvironmentPublicDto.generated": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 36 }, "name": { "type": "string" }, "scope": { "type": "string", "enum": [ "instance", "projects" ] }, "remote": { "type": "object", "properties": { "schemaVersion": { "type": "number", "enum": [ 1 ] }, "remoteUrl": { "type": "string", "minLength": 1 }, "repositoryPath": { "type": "string", "description": "Git 主机远程地址所存储的仓库路径。将其用作 repositoryId 列出分支前，请进行 URL 编码。请求不接受此字段。" } }, "required": [ "schemaVersion", "remoteUrl" ], "additionalProperties": false }, "provider": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 36 }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "git", "gitlab" ] }, "authType": { "type": "string", "enum": [ "ssh-key", "token" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "type", "authType", "createdAt", "updatedAt" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "direction": { "type": "string", "enum": [ "apply" ] }, "settings": { "type": "object", "properties": { "schemaVersion": { "type": "number", "enum": [ 1 ] }, "branchName": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "schemaVersion", "branchName" ], "additionalProperties": false }, "checkout": { "type": "object", "properties": { "hasCheckout": { "type": "boolean" }, "matchesEnvironment": { "type": "boolean" } }, "required": [ "hasCheckout", "matchesEnvironment" ] } }, "required": [ "id", "name", "scope", "remote", "provider", "createdAt", "updatedAt", "direction", "settings", "checkout" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 36 }, "name": { "type": "string" }, "scope": { "type": "string", "enum": [ "instance", "projects" ] }, "remote": { "type": "object", "properties": { "schemaVersion": { "type": "number", "enum": [ 1 ] }, "remoteUrl": { "type": "string", "minLength": 1 }, "repositoryPath": { "type": "string", "description": "Git 主机远程地址所存储的仓库路径。将其用作 repositoryId 列出分支前，请进行 URL 编码。请求不接受此字段。" } }, "required": [ "schemaVersion", "remoteUrl" ], "additionalProperties": false }, "provider": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 36 }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "git", "gitlab" ] }, "authType": { "type": "string", "enum": [ "ssh-key", "token" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "type", "authType", "createdAt", "updatedAt" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "direction": { "type": "string", "enum": [ "promote" ] }, "settings": { "type": "object", "properties": { "schemaVersion": { "type": "number", "enum": [ 1 ] }, "baseBranchName": { "type": "string", "minLength": 1, "maxLength": 255 }, "createBranchOnPromotion": { "type": "boolean" } }, "required": [ "schemaVersion", "baseBranchName", "createBranchOnPromotion" ], "additionalProperties": false }, "checkout": { "type": "object", "properties": { "hasCheckout": { "type": "boolean" }, "matchesEnvironment": { "type": "boolean" } }, "required": [ "hasCheckout", "matchesEnvironment" ] } }, "required": [ "id", "name", "scope", "remote", "provider", "createdAt", "updatedAt", "direction", "settings", "checkout" ] } ], "type": "object" } }, "responses": { "badRequest": { "description": "请求无效，或提供的数据格式错误。" }, "unauthorized": { "description": "未授权" }, "forbidden": { "description": "禁止访问" }, "notFound": { "description": "未找到指定资源。" }, "conflict": { "description": "冲突" }, "unsupportedMediaType": { "description": "不支持的媒体类型。" }, "serviceUnavailable": { "description": "所请求的服务暂时不可用。" } } }, "paths": { "/promotions/environments/{promotionEnvironmentId}": { "put": { "operationId": "updatePromotionEnvironment", "tags": [ "Promotions" ], "summary": "更新晋升环境", "description": "更新名称、提供方、远程地址或设置。远程地址会整体替换已保存的远程配置，设置也会整体替换已保存设置。设置必须与环境方向匹配，因此 Promote 始终要求 `createBranchOnPromotion`。GitLab 环境存储仓库路径，并根据提供方推导 remoteUrl；普通 Git 环境保留完整远程 URL。更新期间提供方发生变化时，返回 409，请重新加载环境后重试。方向和作用域不能更改。", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "晋升环境的 ID。", "name": "promotionEnvironmentId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "providerId": { "type": "string", "minLength": 1, "maxLength": 36 }, "remote": { "type": "object", "properties": { "schemaVersion": { "type": "number", "enum": [ 1 ] }, "remoteUrl": { "type": "string", "minLength": 1 } }, "required": [ "schemaVersion", "remoteUrl" ], "additionalProperties": false }, "settings": { "anyOf": [ { "type": "object", "properties": { "schemaVersion": { "type": "number", "enum": [ 1 ] }, "branchName": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "schemaVersion", "branchName" ], "additionalProperties": false }, { "type": "object", "properties": { "schemaVersion": { "type": "number", "enum": [ 1 ] }, "baseBranchName": { "type": "string", "minLength": 1, "maxLength": 255 }, "createBranchOnPromotion": { "type": "boolean" } }, "required": [ "schemaVersion", "baseBranchName", "createBranchOnPromotion" ], "additionalProperties": false } ] } }, "additionalProperties": false, "minProperties": 1 } } } }, "responses": { "200": { "description": "操作成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/promotionEnvironmentPublicDto.generated" } } } }, "400": { "$ref": "#/components/responses/badRequest" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/notFound" }, "409": { "$ref": "#/components/responses/conflict" }, "415": { "$ref": "#/components/responses/unsupportedMediaType" }, "503": { "$ref": "#/components/responses/serviceUnavailable" } } } } } }