Activepieces Vercel 集成 Piece 实战指南部署管理与环境变量自动化【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces本篇技术指南围绕 Activepieces 社区 Pieceactivepieces/piece-vercel展开讲解如何将 Vercel 的部署管理与环境变量操作接入 Activepieces 工作流。读完本文你将掌握该 Piece 的认证配置方式、五个内置动作列出项目、创建部署、查询部署状态、列出/写入环境变量的参数含义与调用细节并了解其底层 API 调用链与构建方法可直接用于构建代码推送后自动部署、部署完成后自动通知、批量同步环境变量等自动化场景。Piece 概览一个面向部署与配置管理的 Vercel 集成activepieces/piece-vercel是 Activepieces 社区贡献的一个有界 MVPBounded MVP版本 Vercel 集成定位明确只覆盖部署与环境变量这两条核心链路不追求穷尽 Vercel 全部 API。其入口定义位于 packages/pieces/community/vercel/src/index.tsexport const vercel createPiece({ displayName: Vercel, auth: vercelAuth, minimumSupportedRelease: 0.36.1, description: Deploy projects and manage environment variables on Vercel., categories: [PieceCategory.DEVELOPER_TOOLS], authors: [atlas-hunter], actions: [ listProjects, createDeployment, getDeploymentStatus, listEnvironmentVariables, upsertEnvironmentVariable, createCustomApiCallAction({ ... }), ], triggers: [], });从源码结构可以推断出几个关键事实最低支持版本minimumSupportedRelease: 0.36.1意味着需要 Activepieces 0.36.1 及以上版本才能加载该 Piece分类与作者归入PieceCategory.DEVELOPER_TOOLS开发者工具作者为atlas-hunter额外能力除五个固定动作外还通过createCustomApiCallAction提供了一个自定义 API 调用动作base URL 固定为https://api.vercel.com并自动注入Authorization: Bearer token请求头允许用户按需调用 Vercel 其他 REST 端点无触发器该 Piece 目前只提供动作actionstriggers为空数组适合作为流程中的执行节点而非事件源。内置动作清单动作名显示名称底层 Vercel APIlist_projectsList ProjectsGET /v10/projects带分页遍历create_deploymentCreate DeploymentPOST /v13/deploymentsget_deployment_statusGet Deployment StatusGET /v13/deployments/{id}list_environment_variablesList Environment VariablesGET /v10/projects/{projectId}/envupsert_environment_variableUpsert Environment VariablePOST /v10/projects/{projectId}/env?upserttrue认证配置Personal Access Token 与团队作用域连接 Vercel 需要先配置认证信息其定义位于 packages/pieces/community/vercel/src/lib/common/auth.ts。该 Piece 使用PieceAuth.CustomAuth自定义认证共三个字段字段类型必填说明tokenSecretText密文是Vercel Personal Access Token在 Vercel 控制台 Settings → Tokens 中创建teamIdShortText否Vercel Team ID用于操作团队Team拥有的资源slugShortText否Vercel Team Slug当未提供 Team ID 时生效值得注意的两个细节Token 以密文存储token使用PieceAuth.SecretText在 Activepieces 中会作为机密保存不会在流程编辑界面明文回显Team ID 优先级高于 Slug源码中validate逻辑与请求构造逻辑一致——若同时填写了teamId与slug只使用teamId仅当teamId为空时才回退到slug。连接校验机制配置连接时Piece 会发起一次真实的 API 探测来验证凭证有效性见 auth.tsvalidate: async ({ auth }) { const queryParams: Recordstring, string { limit: 1 }; if (auth.teamId) { queryParams[teamId] auth.teamId; } else if (auth.slug) { queryParams[slug] auth.slug; } await httpClient.sendRequest({ method: HttpMethod.GET, url: https://api.vercel.com/v10/projects, authentication: { type: AuthenticationType.BEARER_TOKEN, token: auth.token }, queryParams, }); return { valid: true }; }即连接保存时调用GET https://api.vercel.com/v10/projects?limit1附带teamId或slug请求成功则连接有效否则返回校验错误信息。因此Token 必须至少拥有读取项目列表的权限否则无法建立连接。团队作用域的自动注入认证信息中的teamId/slug会在每次 API 调用时自动作为查询参数注入其实现位于 packages/pieces/community/vercel/src/lib/common/client.tsif (auth.props.teamId) { queryParams[teamId] auth.props.teamId; } else if (auth.props.slug) { queryParams[slug] auth.props.slug; }这意味着只要在连接里配置了团队信息所有动作列表、部署、环境变量都会自动作用于该团队无需在每个动作里重复填写。对于自定义 API 调用动作官方描述也提示团队级请求仍需在 URL 或查询参数中手动补充teamId或slug。动作一List Projects列出项目定义于 packages/pieces/community/vercel/src/lib/actions/list-projects.ts用于获取当前账号或团队下的全部 Vercel 项目。参数search可选文本按项目名称过滤行为调用GET /v10/projects内部使用游标分页自动遍历所有结果单页limit: 100最多翻 10 页见 client.ts 中的MAX_PAGES 10因此最多返回约 1000 个项目幂等性只读操作aiMetadata.idempotent: true可安全重试。该动作的典型用途是发现项目 ID / 名称——在部署或管理环境变量之前先用它枚举目标项目。返回的项目结构VercelProject包含id、name、framework、latestDeployments、link关联 Git 仓库信息、updatedAt、createdAt等字段。此外项目下拉组件props.ts 中的vercelProjectDropdown也复用了同一个listAllProjects函数它支持搜索refreshOnSearch: true且未连接账号时会给出Connect your Vercel account first的禁用提示。动作二Create Deployment创建部署定义于 packages/pieces/community/vercel/src/lib/actions/create-deployment.ts这是本 Piece 最复杂的动作支持两种部署来源模式通过deployment_source下拉切换模式一Redeploy重新部署已有部署选择历史部署记录基于它重新触发部署。动态字段Property.DynamicProperties按需渲染字段类型必填说明deployment_idDropdown是从GET /v6/deployments?projectIdxxxlimit100拉取该项目的部署历史下拉标签格式为url (state · target)with_latest_commitCheckbox否勾选后使用最新提交而非原部署文件重新部署对应withLatestCommit: true请求体构造为{ name: projectId, project: projectId, deploymentId: deployment_id, withLatestCommit: true }模式二Git Source从 Git 仓库部署直接指定 Git 来源触发部署。公共字段target目标环境默认preview可选productiondeploymentTargetPropertygit_typeGit 提供商可选github、github-limited、gitlab、bitbucket默认githubgit_branch要部署的分支/ref必填git_sha可选提交 SHAgit_repo_org/git_repo_name仓库归属与仓库名GitHub 用 org/owner repoBitbucket slug 模式用 owner sluggit_repo_idGitHub repoId 或 GitLab projectId 模式git_repo_uuid/git_workspace_uuidBitbucket UUID 模式专用。不同提供商对参数的校验规则源码中均有显式错误提示GitHub提供git_repo_id或同时提供git_repo_orggit_repo_name二选一否则抛错For GitHub deployments, provide either Repository ID or both Repository Organization and Repository Name.GitLab必须提供git_repo_id作为 projectIdBitbucket提供git_repo_uuid可附加git_workspace_uuid或提供git_repo_orggit_repo_name作为 owner slug二选一。顶层通用选项force_newCheckbox默认关闭。勾选后在请求查询参数中追加forceNew1即使存在相似的旧部署也强制新建skip_auto_detection_confirmationCheckbox默认开启对应skipAutoDetectionConfirmation1自动确认框架检测而不弹出确认。最终请求为POST /v13/deploymentsname与project均取所选项目的 ID。该方法非幂等aiMetadata.idempotent: false每次调用都会启动一次独立部署不适合无谓重试。动作三Get Deployment Status获取部署状态定义于 packages/pieces/community/vercel/src/lib/actions/get-deployment-status.ts用于拉取单个部署并检查其当前状态如building、ready、error。参数project项目下拉必填deployment部署下拉基于所选项目从GET /v6/deployments动态加载必填with_git_repo_infoCheckbox默认开启请求时附带withGitRepoInfotrue以包含 Git 仓库信息底层调用GET /v13/deployments/{deploymentId}部署 ID 会经过encodeURIComponent处理幂等性只读idempotent: true。典型用法是配合 Create Deployment 使用创建部署后取出返回的uid在轮询循环或定时流程中反复调用本动作直到状态变为ready或error再触发后续通知如 Slack 消息、邮件。动作四List Environment Variables列出环境变量定义于 packages/pieces/community/vercel/src/lib/actions/list-environment-variables.ts读取指定项目已配置的环境变量。参数project项目下拉必填decryptCheckbox默认关闭。注意源码注释明确指出该参数已被 Vercel 官方标记为 deprecated——若开启Vercel 在允许的情况下会尝试返回解密后的值git_branch可选分支过滤仅对 preview 作用域的环境变量有效底层调用GET /v10/projects/{projectId}/env查询参数decrypttrue可选与gitBranch可选幂等性只读idempotent: true。动作五Upsert Environment Variable创建/更新环境变量定义于 packages/pieces/community/vercel/src/lib/actions/upsert-environment-variable.ts通过 Vercel 的 upsert API 以变量名key为键执行存在则更新、不存在则创建。字段类型必填说明projectDropdown是目标项目keyShortText是环境变量键名valueLongText是环境变量值typeStaticDropdown是变量类型plain默认/sensitive/encryptedtargetMultiSelect是作用环境production、preview、development默认三者全选git_branchShortText否可选分支仅当 target 中包含preview时允许commentShortText否变量用途备注关键行为与校验请求地址POST /v10/projects/{projectId}/env?upserttrue通过upserttrue查询参数启用覆盖语义分支校验若填写了git_branch但 target 列表不含preview源码会直接抛错Git Branch can only be used when Preview is included in Target Environments.请求体示例{ key: API_KEY, value: sk-xxx, type: sensitive, target: [production, preview, development], gitBranch: main, comment: injected by Activepieces }幂等性idempotent: true——相同 key 与值重复执行最终存储结果一致适合在流程中安全重试。底层调用链与通用客户端所有动作都通过统一的vercelApiCall客户端函数client.ts发起请求其行为归纳如下Base URLhttps://api.vercel.com认证统一使用AuthenticationType.BEARER_TOKEN请求头为Authorization: Bearer token与Content-Type: application/json团队注入自动追加teamId优先或slug查询参数空值清理query对象中undefined、null、空字符串会被剔除不会进入最终查询参数返回结构直接返回响应体response.body动作层无需再解析。该统一封装保证了五个动作以及自定义 API 调用动作的认证行为完全一致任何 Token 或团队配置的变更都会在全局生效。构建与包信息该 Piece 是独立的 npm 包包名为activepieces/piece-vercel版本0.1.0依赖activepieces/pieces-common、activepieces/pieces-framework、activepieces/core-piece-types、activepieces/core-utils均为 workspace 引用。其 package.json 位于 packages/pieces/community/vercel/package.json。原文档给出的构建命令为turbo run build --filteractivepieces/piece-vercel包内还定义了其他脚本buildtsc -p tsconfig.lib.json cp package.json dist/、bundle调用 CLI 的 pieces bundle、lintESLint 检查src/**/*.ts。目录结构与国际化Piece 源码采用清晰的分层组织packages/pieces/community/vercel/ ├── src/ │ ├── index.ts # Piece 入口createPiece 注册 │ ├── lib/ │ │ ├── actions/ # 五个动作 导出入口 │ │ │ ├── create-deployment.ts │ │ │ ├── get-deployment-status.ts │ │ │ ├── index.ts │ │ │ ├── list-environment-variables.ts │ │ │ ├── list-projects.ts │ │ │ └── upsert-environment-variable.ts │ │ └── common/ │ │ ├── auth.ts # 认证定义与连接校验 │ │ ├── client.ts # 统一 API 客户端与分页逻辑 │ │ └── props.ts # 共享属性项目下拉、target 下拉等 │ └── i18n/ # 多语言翻译de/es/fr/ja/nl/pt/zh 等 ├── README.md └── package.jsoni18n/目录提供了包括德语、西班牙语、法语、日语、荷兰语、葡萄牙语、中文在内的多语言翻译文件说明该 Piece 遵循 Activepieces 的国际化规范界面文案可随平台语言切换。典型自动化场景示例基于上述动作可以在 Activepieces 中搭建以下工作流CI/CD 后置处理Webhook 触发如 Git 推送→ Create DeploymentGit Source 模式指定分支与 GitHub 仓库→ Get Deployment Status轮询直至ready/error→ 分支判断后发送通知环境变量同步从配置源如数据库或表格读取键值 → Upsert Environment Variable批量写入多个项目→ List Environment Variables 校验结果项目巡检定时触发 List Projects → 遍历每个项目的部署状态与环境变量清单 → 汇总报告。需要注意的是部署创建动作非幂等涉及敏感值的value字段建议使用 Activepieces 的变量或连接机制管理避免明文硬编码在流程中。小结activepieces/piece-vercel以最小但完整的形态覆盖了 Vercel 最常用的部署与环境变量管理能力统一的 Bearer Token 认证、可选的团队作用域注入、带分页的项目/部署枚举、双模式部署创建redeploy 与 Git Source、以及幂等的环境变量 upsert。配合自定义 API 调用动作它既能完成高频的标准化操作也能在需要时透传访问 Vercel 的其他端点是 Activepieces 中接入 Vercel 工作流的基础组件。【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考