ToolJet GitSync SSH 配置完全指南为 GitHub、GitLab 与 Gitea 部署 SSH Key【免费下载链接】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/ToolJetToolJet 的 GitSync 功能允许将工作区中的应用与 Git 仓库双向同步用于版本控制、跨实例应用迁移如 Development → Staging → Production与应用备份。在使用 GitSync 之前管理员必须先完成两个动作获取 Git 仓库的 SSH URL以及将 ToolJet 生成的 SSH Key 部署到 Git 仓库。本文以 ToolJet 仓库中 ssh-config.md 为骨架结合后端git-sync-configs模块源码逐步讲解 GitHub、GitLab、Gitea 三种平台下 SSH URL 的获取方式与 SSH Key 的部署细节读完即可独立完成 GitSync 的 SSH 认证配置。GitSync 与 SSH 认证前置背景GitSync 是 ToolJet 的付费Paid功能支持云端与自托管两种形态的 Git 提供商只要其遵循标准 Git 协议即可接入。要启用 GitSync核心认证链路为在 ToolJet 的Workspace settings → Configure git页面填入仓库的SSH URLToolJet 据此生成一对 SSH 公钥/私钥私钥留存在服务端公钥展示给你复制你将该公钥以Deploy Key或用户级 SSH Key的形式部署到 Git 仓库授权 ToolJet 对仓库执行 pull/push回到 ToolJet 点击Finalize setup校验握手成功即完成配置。从后端源码看GitSync 的组织级配置被抽象为一组按提供商注册的“描述符”集中维护在 provider-descriptors.ts。该文件是提供商级配置字段映射的单一注册点每个描述符声明了gitType、仓库 URL 字段、分支字段与密钥字段注释中明确指出新增提供商只需添加一个描述符条目而无需改动消费这些描述符的代码。因此无论使用哪种 Git 管理器前端呈现的“填入 SSH URL / 部署 SSH Key / Finalize”三步流程是一致的。下文从“获取 SSH URL”开始逐步说明。前置角色要求配置 GitSync 需要Admin角色。第一步生成并获取 SSH URLGitSync 通过 SSH 协议访问仓库因此需要的是形如githost:owner/repo.git的SSH URL而非 HTTPS URL。默认情况下GitSync 面向master分支工作因此建议仓库的默认分支命名为masterToolJet 也支持通过环境变量自定义分支详见本文最后一节。仓库本身可为空仓库推荐或已有内容推荐为空仓库以避免历史内容干扰同步。GitHub创建新仓库在你的 GitHub 账号下创建仓库公开或私有均可也可以直接复用一个既有仓库。若新建请确保仓库为空且默认分支名为master。获取 SSH URL新仓库创建完成后GitHub 会在完成页直接展示该仓库的 SSH URL。或者如果使用的是既有仓库点击页面上的Code按钮切换至SSH标签页即可复制同一份 SSH URL。GitLab创建新仓库在 GitLab 上新建仓库公开或私有均可或复用既有仓库同样建议仓库为空、默认分支名为master。获取 SSH URL进入仓库主页点击Clone按钮并选择SSH选项即可看到并复制 SSH URL。Gitea创建新仓库在自托管的 Gitea 上新建或复用仓库保持空仓库且默认分支为master。获取 SSH URLGitea 在仓库创建完成页会直接显示 SSH URL对既有仓库也可在仓库首页的克隆信息中找到。第二步在 ToolJet 中生成 SSH Key拿到 SSH URL 后进入 ToolJet 工作区设置示例路径为https://app.corp.com/nexus/workspace-settings/configure-git的Configure git标签页将上一步复制的 SSH URL 粘贴到Git repo URL输入框点击Generate SSH key按钮ToolJet 会生成一对用于与仓库鉴权的 SSH 密钥随后复制页面展示的公钥内容。ToolJet 支持生成两种类型的 SSH 密钥密钥类型说明推荐场景ED25519安全且高效的现代算法ToolJet 默认推荐GitHub、GitLab 等多数现代 VCS 提供商推荐使用RSA较老的传统算法仅当提供商强制要求时使用如 Bitbucket 等仍推荐 RSA 的场景不同 Git 管理器的“Generate SSH key / 部署密钥”操作入口一致完整对照步骤见 gitsync-config.md 中“Setting up GitSync in ToolJet”一节。该密钥属于公开密钥可以放心粘贴到 Git 仓库的部署密钥配置中私钥由 ToolJet 服务端保管用于之后的 git 操作。第三步将 SSH Key 部署到 GitHubGitHub 通过Deploy Keys机制授权单个仓库的访问。步骤如下打开目标 GitHub 仓库的Settings标签页进入侧栏Deploy keys点击Add deploy key按钮。在Title字段为该密钥起一个可辨识的名称例如ToolJet GitSync。将 ToolJet 生成的 SSH 公钥粘贴到Key文本框。勾选 Allow write access当你要启用 推送变更到 Git 时此选项为必需若仅用于从 Git 拉取变更可以不勾选。点击Add key保存。GitHub 部署小结Push 场景必须勾选Allow write access否则 ToolJet 只能读仓库、无法把应用变更写回。Pull 场景只读 Deploy Key 即可满足安全性更高。是否勾选写权限取决于你的 GitSync 使用模式——若同时启用 push 与 pull应保持勾选。第四步将 SSH Key 部署到 GitLabGitLab 提供两种部署层级可按需二选一方案 A添加为“用户级”SSH Key可访问你的所有仓库适用于希望一个 key 覆盖名下所有项目例如多应用仓库迁移场景的情况点击 GitLab 页面左上角头像选择Edit Profile。进入SSH Keys标签页点击Add new key按钮。在Key字段粘贴 ToolJet 生成的 SSH 公钥。填写描述性Title。将Usage type设为Authentication signing。可选设置过期时间。点击Add key保存。方案 B添加为仓库级 Deploy Key仅限单个仓库适用于只为某一个仓库授权 GitSync 的情况进入目标仓库。点击Settings标签页并选择Repository。在Repository Settings中展开Deploy Keys区段。点击Add new deploy key。填写描述性Title。在Key字段粘贴 ToolJet 的 Configure git 页面生成的公钥。勾选Grant write permissions to this key推送变更到仓库需要该权限。点击Add key保存。选型建议若 GitLab 实例中每个 ToolJet 工作区都对应独立仓库方案 B 权限粒度最细、更安全若存在大量仓库迁移方案 A 可减少重复维护成本。第五步将 SSH Key 部署到 GiteaGitea自托管轻量 Git 服务的 Deploy Key 机制与 GitHub 基本一致进入 Gitea 仓库的Settings标签页点击Deploy keys再点击Add deploy key。在Title字段输入密钥名称。粘贴 ToolJet 生成的 SSH 公钥。勾选 Allow write access启用推送变更到 Git时为必需仅从 Git 拉取时可留空。点击Add Deploy key完成。部署完成后的收尾与分支策略完成收尾验证SSH Key 部署完成后回到 ToolJet 的Configure git标签页点击Finalize setup。若密钥与仓库 URL 均配置正确ToolJet 会返回成功提示随后即可在应用编辑器的 GitSync 按钮中发起首次提交。详细流程可参考 push.md手动提交、应用创建/改名/版本更新的自动提交与 pull.md从仓库拉取变更。若不再需要同步可参考 delete-gitsync.md 删除配置。默认 master 分支与自定义分支GitSync 默认面向master分支。自版本v3.5.3-ee-lts起自托管版支持通过实例级环境变量配置自定义分支GITSYNC_TARGET_BRANCHbranch-name该环境变量写入.env文件对所有启用 GitSync 的工作区生效。因此如果不同工作区分别对接了不同仓库自定义分支必须预先在所有已配置仓库中创建否则同步会中断。对于既有 GitSync 用户升级到自定义分支的正确顺序是先在 Git 仓库中基于 master 创建新分支再于.env中填入该分支名并重启服务。这一机制在后端有数据迁移佐证迁移 1754048735123-MigrateSSHBranchColumnData.ts 会为历史用户读取实例上配置的GITSYNC_TARGET_BRANCH环境变量并将分支名回填到各个工作区的 Git 配置中该迁移注释明确指出“如果配置了GITSYNC_TARGET_BRANCH环境变量则在实例的所有工作区中使用.env中的分支”可见分支是 GitSync 组织级配置的一部分。源码中的配置模型从源码结构看组织级 GitSync 配置以OrganizationGitSync实体为中心Git 提供商的连接类型由GITConnectionType枚举约束见 organization_git_sync.entity.ts而各提供商的字段映射统一收敛在 provider-descriptors.ts 的GIT_PROVIDER_CONFIG_DESCRIPTORS数组中代码注释还指出该文件被 CE 仓库与 EE 服务共同引用。这意味着无论你在 UI 上选择哪类 Git 管理器GitHub、GitLab、Gitea 或其他遵循标准 Git 协议的自托管服务其“SSH URL SSH Key 目标分支”的配置模型是一致的——这也是本文三步式配置方法可复用的根本原因。常见要点速查操作GitHubGitLabGiteaSSH URL 获取位置新仓库完成页 /Code → SSHClone → SSH仓库完成页 / 仓库首页密钥部署入口Settings →Deploy keys用户级Edit Profile → SSH Keys或仓库级Settings → Repository → Deploy KeysSettings →Deploy keysPush 必需项勾选Allow write access勾选Grant write permissions勾选Allow write access仅 Pull 时可只读授权可只读授权可只读授权两条最重要的实践结论权限最小化如果只用 GitSync 做“从 Git 拉取到 ToolJet”的同步就不要给 Deploy Key 写权限把仓库写入口收窄到最小写权限是双向同步的前提只要计划把应用从 ToolJet 推回 Git提交、版本发布、应用改名等自动提交均依赖写权限就必须在 Deploy Key 上开启 write access再执行Finalize setup验证握手。【免费下载链接】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），仅供参考 ToolJet GitSync SSH 配置完全指南：为 GitHub、GitLab 与 Gitea 部署 SSH Key
ToolJet GitSync SSH 配置完全指南为 GitHub、GitLab 与 Gitea 部署 SSH Key【免费下载链接】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/ToolJetToolJet 的 GitSync 功能允许将工作区中的应用与 Git 仓库双向同步用于版本控制、跨实例应用迁移如 Development → Staging → Production与应用备份。在使用 GitSync 之前管理员必须先完成两个动作获取 Git 仓库的 SSH URL以及将 ToolJet 生成的 SSH Key 部署到 Git 仓库。本文以 ToolJet 仓库中 ssh-config.md 为骨架结合后端git-sync-configs模块源码逐步讲解 GitHub、GitLab、Gitea 三种平台下 SSH URL 的获取方式与 SSH Key 的部署细节读完即可独立完成 GitSync 的 SSH 认证配置。GitSync 与 SSH 认证前置背景GitSync 是 ToolJet 的付费Paid功能支持云端与自托管两种形态的 Git 提供商只要其遵循标准 Git 协议即可接入。要启用 GitSync核心认证链路为在 ToolJet 的Workspace settings → Configure git页面填入仓库的SSH URLToolJet 据此生成一对 SSH 公钥/私钥私钥留存在服务端公钥展示给你复制你将该公钥以Deploy Key或用户级 SSH Key的形式部署到 Git 仓库授权 ToolJet 对仓库执行 pull/push回到 ToolJet 点击Finalize setup校验握手成功即完成配置。从后端源码看GitSync 的组织级配置被抽象为一组按提供商注册的“描述符”集中维护在 provider-descriptors.ts。该文件是提供商级配置字段映射的单一注册点每个描述符声明了gitType、仓库 URL 字段、分支字段与密钥字段注释中明确指出新增提供商只需添加一个描述符条目而无需改动消费这些描述符的代码。因此无论使用哪种 Git 管理器前端呈现的“填入 SSH URL / 部署 SSH Key / Finalize”三步流程是一致的。下文从“获取 SSH URL”开始逐步说明。前置角色要求配置 GitSync 需要Admin角色。第一步生成并获取 SSH URLGitSync 通过 SSH 协议访问仓库因此需要的是形如githost:owner/repo.git的SSH URL而非 HTTPS URL。默认情况下GitSync 面向master分支工作因此建议仓库的默认分支命名为masterToolJet 也支持通过环境变量自定义分支详见本文最后一节。仓库本身可为空仓库推荐或已有内容推荐为空仓库以避免历史内容干扰同步。GitHub创建新仓库在你的 GitHub 账号下创建仓库公开或私有均可也可以直接复用一个既有仓库。若新建请确保仓库为空且默认分支名为master。获取 SSH URL新仓库创建完成后GitHub 会在完成页直接展示该仓库的 SSH URL。或者如果使用的是既有仓库点击页面上的Code按钮切换至SSH标签页即可复制同一份 SSH URL。GitLab创建新仓库在 GitLab 上新建仓库公开或私有均可或复用既有仓库同样建议仓库为空、默认分支名为master。获取 SSH URL进入仓库主页点击Clone按钮并选择SSH选项即可看到并复制 SSH URL。Gitea创建新仓库在自托管的 Gitea 上新建或复用仓库保持空仓库且默认分支为master。获取 SSH URLGitea 在仓库创建完成页会直接显示 SSH URL对既有仓库也可在仓库首页的克隆信息中找到。第二步在 ToolJet 中生成 SSH Key拿到 SSH URL 后进入 ToolJet 工作区设置示例路径为https://app.corp.com/nexus/workspace-settings/configure-git的Configure git标签页将上一步复制的 SSH URL 粘贴到Git repo URL输入框点击Generate SSH key按钮ToolJet 会生成一对用于与仓库鉴权的 SSH 密钥随后复制页面展示的公钥内容。ToolJet 支持生成两种类型的 SSH 密钥密钥类型说明推荐场景ED25519安全且高效的现代算法ToolJet 默认推荐GitHub、GitLab 等多数现代 VCS 提供商推荐使用RSA较老的传统算法仅当提供商强制要求时使用如 Bitbucket 等仍推荐 RSA 的场景不同 Git 管理器的“Generate SSH key / 部署密钥”操作入口一致完整对照步骤见 gitsync-config.md 中“Setting up GitSync in ToolJet”一节。该密钥属于公开密钥可以放心粘贴到 Git 仓库的部署密钥配置中私钥由 ToolJet 服务端保管用于之后的 git 操作。第三步将 SSH Key 部署到 GitHubGitHub 通过Deploy Keys机制授权单个仓库的访问。步骤如下打开目标 GitHub 仓库的Settings标签页进入侧栏Deploy keys点击Add deploy key按钮。在Title字段为该密钥起一个可辨识的名称例如ToolJet GitSync。将 ToolJet 生成的 SSH 公钥粘贴到Key文本框。勾选 Allow write access当你要启用 推送变更到 Git 时此选项为必需若仅用于从 Git 拉取变更可以不勾选。点击Add key保存。GitHub 部署小结Push 场景必须勾选Allow write access否则 ToolJet 只能读仓库、无法把应用变更写回。Pull 场景只读 Deploy Key 即可满足安全性更高。是否勾选写权限取决于你的 GitSync 使用模式——若同时启用 push 与 pull应保持勾选。第四步将 SSH Key 部署到 GitLabGitLab 提供两种部署层级可按需二选一方案 A添加为“用户级”SSH Key可访问你的所有仓库适用于希望一个 key 覆盖名下所有项目例如多应用仓库迁移场景的情况点击 GitLab 页面左上角头像选择Edit Profile。进入SSH Keys标签页点击Add new key按钮。在Key字段粘贴 ToolJet 生成的 SSH 公钥。填写描述性Title。将Usage type设为Authentication signing。可选设置过期时间。点击Add key保存。方案 B添加为仓库级 Deploy Key仅限单个仓库适用于只为某一个仓库授权 GitSync 的情况进入目标仓库。点击Settings标签页并选择Repository。在Repository Settings中展开Deploy Keys区段。点击Add new deploy key。填写描述性Title。在Key字段粘贴 ToolJet 的 Configure git 页面生成的公钥。勾选Grant write permissions to this key推送变更到仓库需要该权限。点击Add key保存。选型建议若 GitLab 实例中每个 ToolJet 工作区都对应独立仓库方案 B 权限粒度最细、更安全若存在大量仓库迁移方案 A 可减少重复维护成本。第五步将 SSH Key 部署到 GiteaGitea自托管轻量 Git 服务的 Deploy Key 机制与 GitHub 基本一致进入 Gitea 仓库的Settings标签页点击Deploy keys再点击Add deploy key。在Title字段输入密钥名称。粘贴 ToolJet 生成的 SSH 公钥。勾选 Allow write access启用推送变更到 Git时为必需仅从 Git 拉取时可留空。点击Add Deploy key完成。部署完成后的收尾与分支策略完成收尾验证SSH Key 部署完成后回到 ToolJet 的Configure git标签页点击Finalize setup。若密钥与仓库 URL 均配置正确ToolJet 会返回成功提示随后即可在应用编辑器的 GitSync 按钮中发起首次提交。详细流程可参考 push.md手动提交、应用创建/改名/版本更新的自动提交与 pull.md从仓库拉取变更。若不再需要同步可参考 delete-gitsync.md 删除配置。默认 master 分支与自定义分支GitSync 默认面向master分支。自版本v3.5.3-ee-lts起自托管版支持通过实例级环境变量配置自定义分支GITSYNC_TARGET_BRANCHbranch-name该环境变量写入.env文件对所有启用 GitSync 的工作区生效。因此如果不同工作区分别对接了不同仓库自定义分支必须预先在所有已配置仓库中创建否则同步会中断。对于既有 GitSync 用户升级到自定义分支的正确顺序是先在 Git 仓库中基于 master 创建新分支再于.env中填入该分支名并重启服务。这一机制在后端有数据迁移佐证迁移 1754048735123-MigrateSSHBranchColumnData.ts 会为历史用户读取实例上配置的GITSYNC_TARGET_BRANCH环境变量并将分支名回填到各个工作区的 Git 配置中该迁移注释明确指出“如果配置了GITSYNC_TARGET_BRANCH环境变量则在实例的所有工作区中使用.env中的分支”可见分支是 GitSync 组织级配置的一部分。源码中的配置模型从源码结构看组织级 GitSync 配置以OrganizationGitSync实体为中心Git 提供商的连接类型由GITConnectionType枚举约束见 organization_git_sync.entity.ts而各提供商的字段映射统一收敛在 provider-descriptors.ts 的GIT_PROVIDER_CONFIG_DESCRIPTORS数组中代码注释还指出该文件被 CE 仓库与 EE 服务共同引用。这意味着无论你在 UI 上选择哪类 Git 管理器GitHub、GitLab、Gitea 或其他遵循标准 Git 协议的自托管服务其“SSH URL SSH Key 目标分支”的配置模型是一致的——这也是本文三步式配置方法可复用的根本原因。常见要点速查操作GitHubGitLabGiteaSSH URL 获取位置新仓库完成页 /Code → SSHClone → SSH仓库完成页 / 仓库首页密钥部署入口Settings →Deploy keys用户级Edit Profile → SSH Keys或仓库级Settings → Repository → Deploy KeysSettings →Deploy keysPush 必需项勾选Allow write access勾选Grant write permissions勾选Allow write access仅 Pull 时可只读授权可只读授权可只读授权两条最重要的实践结论权限最小化如果只用 GitSync 做“从 Git 拉取到 ToolJet”的同步就不要给 Deploy Key 写权限把仓库写入口收窄到最小写权限是双向同步的前提只要计划把应用从 ToolJet 推回 Git提交、版本发布、应用改名等自动提交均依赖写权限就必须在 Deploy Key 上开启 write access再执行Finalize setup验证握手。【免费下载链接】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），仅供参考