ToolJet GitSync SSH 配置实战在 GitHub、GitLab 与 Gitea 上部署 ToolJet 生成的 SSH 密钥【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet本文围绕 ToolJet 3.0.0-LTS 版本文档中的 GitSync SSH 配置指南展开先用 GitHub、GitLab、Gitea 三种 Git 平台各走一遍「获取 SSH URL」的完整流程再逐一部署 ToolJet 自动生成的 SSH 公钥并结合服务端源码剖析 ToolJet 是如何使用这把密钥完成连接测试与 push/pull 的。读完本文你可以独立完成工作区 Git 同步的 SSH 通道搭建并理解密钥权限只读拉取 vs 读写推送对 GitSync 功能边界的直接影响。一、配置总览SSH 通道的两个输入使用 GitSync 把 ToolJet 工作区接入 Git 仓库时需要两类输入Git 仓库的 SSH URL——从你的 Git 管理器云端或自建获取任何遵循标准 Git 协议的仓库均可ToolJet 生成的 SSH 密钥——在 ToolJet 的 Configure Git 流程中生成需要你把公钥部署到 Git 平台Deploy Key 或用户级 SSH Key。一个关键前提三个平台通用仓库必须为空且默认分支名必须是master。这一点在 GitHub、GitLab、Gitea 的说明中都重复强调了是连接测试能通过的基础条件之一。二、生成 SSH URL各平台操作步骤2.1 GitHub创建新仓库在 GitHub 上新建仓库公开或私有均可也可以复用已有仓库。但必须保证仓库为空、默认分支名为master。获取 SSH URL仓库创建完成后GitHub 会直接展示该仓库的 SSH URL如果使用的是已有仓库则点击仓库页面的Code按钮切换到 SSH 方式查看。2.2 GitLab创建新仓库同样要求仓库为空、默认分支名为master公开私有均可也可复用已有仓库。获取 SSH URL在仓库页面点击Clone按钮再选择SSH选项即可看到地址。2.3 Gitea创建新仓库要求同样是空仓库 默认分支master。获取 SSH URL仓库创建后 Gitea 会直接展示 SSH URL已有仓库则通过克隆入口查看。三、部署 SSH 密钥Deploy Key拿到 ToolJet 生成的公钥后按平台分别部署。权限要求的差异值得特别注意只读拉取pull场景无需勾选写权限需要推送push场景必须赋予写权限。3.1 GitHub仓库级 Deploy Key进入 GitHub 仓库的Settings页点击Deploy keys子页再点击Add deploy key在Title字段为这把密钥填写一个标题粘贴 ToolJet 生成的 SSH 公钥勾选 Allow write access——配置 GitSync 推送push能力时这是必须的而仅配置从 Git 拉取pull时可以不勾选点击Add key完成添加。3.2 GitLab两种部署方式任选GitLab 支持把密钥加到全局访问该账号下所有仓库或加到单个仓库方式一用户级 SSH Key访问该用户全部仓库点击左上角头像选择Edit Profile进入SSH Keys页签点击Add new key在Key字段粘贴 ToolJet 生成的 SSH 公钥填写描述性标题Usage type选择Authentication signing可选设置过期时间点击Add key保存。方式二仓库级 Deploy Key仅访问指定仓库进入目标仓库点击Settings页签选择Repository在 Repository Settings 中展开Deploy Keys区域点击Add new deploy key填写描述性标题在Key字段粘贴 ToolJet 在 Configure Git 步骤中生成的公钥勾选 Grant write permissions to this key——这是推送变更回仓库所必需的权限点击Add key保存。3.3 Gitea仓库级 Deploy Key进入 Gitea 仓库的Settings页点击Deploy keys页签点击Add deploy key在Title字段填写标题粘贴 ToolJet 生成的 SSH 公钥Allow write access复选框配置 push 功能时必须勾选仅配置 pull 功能 时非必须push 参见 推送变更到 Git点击Add Deploy key完成。四、源码视角ToolJet 服务端如何消费这把密钥文档描述的是「平台侧操作」而服务端如何把这些配置串起来可以从 git-sync 模块说明 中得到印证。4.1 两步式配置流程save finalize从模块文档看工作区 Git 连接采用两步式设置先POST /git-sync/configs保存 provider 配置连接测试通过后再由PUT /git-sync/finalize/:id将该配置标记为可用。这解释了为什么在界面上必须先「测试连接」成功、再完成最终保存——你部署到 GitHub/GitLab/Gitea 的那把 Deploy Key正是在test-connection环节被实际使用服务端向仓库发起一次 SSH 握手来验证密钥有效。4.2 三种 Provider 的策略选择服务端为每个组织维护OrganizationGitSync实体含autoCommit、isBranchingEnabled、useEnvConfig等开关并以一对一关系挂载三种 provider 行OrganizationGitSsh、OrganizationGitHttps、OrganizationGitLab实体定义位于server/src/entities/gitsync_entities/。运行时由SourceControlProviderService.getSourceControlService()选择具体实现优先级为显式传入的gitType参数useEnvConfig开启时取环境变量envGitProvider第一个处于启用状态的 provider 行兜底默认走 SSH provider。也就是说只要按本文第三节的流程把 SSH 密钥部署好即使不显式指定 providerSSH 也是默认选择——这与文档把它作为主推配置路径是一致的。4.3 密钥的生成与使用位置从模块文档看github-ssh provider 的testConnection使用 simple-git 驱动并在需要时执行 SSH 密钥生成ed25519/rsa。而本文档中「ToolJet 生成的 SSH 密钥」正是这条链路里产生的产物ToolJet 负责生成密钥对你负责把公钥部署到 Git 平台私钥留在 ToolJet 服务端用于后续 push/pull 的鉴权。4.4 适用前提CE 与 EE 的差异需要注意一个重要的适用边界GitSync 的完整能力configure、test、finalize、delete 以及应用序列化为仓库文件树的机制属于 EE 功能真实逻辑位于server/ee/git-sync/社区版CE在 git-sync 模块 中只保留路由与桩实现例如 HTTPSGitSyncService 就是一个空壳继承自 BaseGitSyncService。因此本文的 SSH 配置流程适用于具备 EE 能力的 ToolJet 部署在纯 CE 版本上完成上述平台侧配置也不会触发真实的 Git 连接。五、实战要点核对清单检查项要求说明仓库状态空仓库三个平台的共同前置条件默认分支master与 ToolJet 侧分支约定一致密钥标题描述性标题便于在平台上识别来源写权限push 必须开启GitHub/Gitea 的 Allow write access、GitLab 的 Grant write permissions只读拉取可不勾选写权限仅 pull 场景下最小化密钥权限GitLab 部署粒度用户级或仓库级二选一用户级覆盖全部仓库Deploy Key 仅覆盖单仓库ToolJet 侧确认测试连接后 finalize服务端两步式流程见 配置说明六、小结ToolJet GitSync 的 SSH 配置本质上是一条「ToolJet 生成密钥 → 平台部署公钥 → 服务端测试并 finalize」的闭环GitHub 与 Gitea 使用仓库级 Deploy KeyGitLab 则额外提供用户级密钥这一更宽泛的选项权限最小化原则下仅 pull 的场景无需授予写权限而 push 能力则依赖写权限勾选。配合服务端server/ee/git-sync/中的 provider 策略选择与两步式连接确认机制这套流程在标准 Git 协议范围内对云端与自托管 Git 管理器均适用。参考文档SSH 配置指南3.0.0-LTS 版本【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考