Configure GitSyncToolJet 工作区 Git 同步配置【免费下载链接】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 应用与 Git 仓库连接起来为内部工具、仪表盘和业务应用带来可靠的版本控制、跨环境迁移与自动备份能力。本文聚焦 GitSync 的配置环节以一个 GitHub 仓库为示例逐步讲解从创建仓库、生成 SSH 密钥、部署 Deploy Key 到完成连接验证的完整流程并说明如何通过环境变量把 GitSync 切换到自定义分支。ToolJet 的工作区应用、数据源与查询定义都保存在服务端数据库中。GitSync 的本质是将一个工作区配置同步到某个 Git 仓库把应用的定义definition以文本形式落盘到 Git从而实现版本追踪、跨实例迁移例如从开发环境推到仓库、再在预发/生产实例上拉回以及应用备份。GitSync 的更多用途可参考 GitSync Overview。GitSync 是 ToolJet 的付费功能在 ToolJet Cloud 与 EE 自托管版本中可用。本节所讲解的“Configure GitSync”指工作区级别的仓库连接配置其对应的源码位于 server/src/modules/git-sync 模块涉及的数据库实体为organization_git_ssh每工作区一条 SSH 仓库配置记录与organization_git_sync。配置前的准备在开始配置之前先确认你已具备以下条件管理员Admin角色GitSync 的配置入口位于 Workspace settings只有管理员可以操作。一个 Git 仓库可以是 GitHub、GitLab、Gitea 等遵循标准 Git 协议的平台云托管或自托管均可。支持的其他仓库管理器配置方式见 SSH Configuration for Git Repo Manager。自托管实例的 .env 可访问权限仅当你要配置 GitSync 使用非默认分支时需要见本文「配置自定义分支」一节。ToolJet 与仓库之间的通信使用SSH 协议ToolJet 服务端生成一对 SSH 密钥你把公钥以 Deploy Key 的形式部署到 Git 仓库中随后 ToolJet 通过 SSH URL 对仓库进行读写。从源码结构看Git 同步模块按 Provider 拆分实现见 server/src/modules/git-sync/AGENTS.mdproviders/github-ssh、providers/github-https、providers/gitlab各自承担配置的 CRUD 与连接测试其中 SSH 方式的 Provider 内部使用ssh-keygen生成 ed25519/rsa 密钥。在 ToolJet 中配置 GitSync以 GitHub 为例完整流程分为“准备仓库 → 生成 SSH 密钥 → 部署公钥 → 完成连接”四个阶段下面按官方推荐的执行顺序逐步展开。第 1 步创建一个新仓库或使用已有仓库在 GitHub 上创建一个新的仓库公开或私有均可也可以直接使用已有仓库。有一个关键要求仓库应为空empty且默认分支名最好为master。ToolJet 的 GitSync 默认与 master 分支同步如果仓库默认分支不是 master请按本文「配置自定义分支」一节处理。提示为什么要求 master这与 ToolJet 服务端的默认分支约定有关在迁移脚本 server/data-migrations/1754048735123-MigrateSSHBranchColumnData.ts 中可以看到未显式配置自定义分支时organization_git_ssh表的git_branch字段会被统一回填为master。因此让仓库默认分支与 master 保持一致可以避免后续 Pull/Push 时出现分支不匹配。新建仓库后 GitHub 会展示一个包含 SSH URL 的引导界面。第 2 步获取仓库的 SSH URL新建仓库仓库创建完成后GitHub 展示的界面中直接提供 SSH URL。已有仓库点击仓库页面的Code按钮切换到SSH标签页即可复制 SSH URL。SSH URL 形如gitgithub.com:your-org/your-repo.git。这个 URL 与 HTTPS URL 不同它专用于 SSH 认证下一步配置中需要将完整的 SSH URL而非https://github.com/...填入 ToolJet。如果是 GitLab / Gitea 等其他仓库管理器SSH URL 的获取方式不同详见 SSH Configuration for Git Repo ManagerGitLab 通过Clone → SSH、Gitea 在仓库创建后的界面直接展示。第 3 步进入 ToolJet 的 Configure git 页面在 ToolJet 中进入Workspace settings点击左侧的Configure git标签页。对于自托管部署该页面的 URL 通常形如https://app.corp.com/nexus/workspace-settings/configure-git其中app.corp.com是你自托管 ToolJet 的域名。Configure git 页面即 GitSync 连接配置的 UI 入口对应服务端OrganizationGitCreateDto等配置 DTO见 server/src/dto/organization_git.dto.ts后端会接收并校验gitUrl与gitType等字段。第 4 步填写 Git repo URL在Git repo URL字段中粘贴第 2 步获取到的 SSH URL。例如gitgithub.com:example-org/tooljet-apps.git第 5 步生成 SSH 密钥点击Generate SSH key按钮ToolJet 会为你生成一对新的 SSH 密钥并展示需要部署到 Git 仓库的公钥。请复制这份公钥——它会用于 ToolJet 与仓库之间的认证。ToolJet 支持生成两种类型的 SSH 密钥密钥类型算法说明推荐场景ED25519安全且高效的现代算法GitHub、GitLab 官方推荐使用大多数场景下的首选RSA相对较老的算法个别对 RSA 有强制要求的平台例如 Bitbucket 官方推荐使用从服务端校验逻辑看keyType仅允许取值ed25519或rsa见 server/src/modules/git-sync/dto/index.ts 与 server/src/dto/organization_git.dto.ts与界面上的两个选项一一对应仓库侧 Provider 实现github-ssh会用ssh-keygen以所选类型生成密钥对。第 610 步在 GitHub 上部署 SSH 公钥Deploy Key拿到 ToolJet 生成的公钥后回到 GitHub 仓库完成部署进入该仓库的Settings标签页点击左侧Deploy keys再点击Add deploy key。在Title字段为该密钥起一个便于识别的标题例如tooljet-gitsync。将第 5 步复制的 SSH 公钥粘贴到Key字段。勾选Allow write access复选框——当你要用 GitSync向 Git 推送Push变更时必须勾选如果只打算用于从 Git 拉取Pull变更则可以不勾选。推、拉两种工作方式的详细说明分别见 push changes to Git 与 pulling changes from Git。点击Add key完成部署。GitLab / Gitea 上部署密钥的方式不同GitLab 既支持在用户级添加 SSH Key对所有仓库生效也支持在指定仓库添加 Deploy KeyGitea 则在仓库Settings → Deploy keys中操作。具体步骤见 SSH Configuration for Git Repo Manager。第 11 步Finalize setup 验证连接公钥部署完成后回到 ToolJet 的Configure git页面点击Finalize setup按钮。此时 ToolJet 会使用配置的 SSH URL 与部署的密钥对仓库发起一次连接测试如果 SSH 密钥配置正确页面会显示成功信息表明 ToolJet 已能与该仓库建立 SSH 通信。如果提示失败请依次检查SSH URL 是否为正确的 SSH而非 HTTPS格式、公钥是否完整粘贴、是否勾选了合适的写权限、仓库是否为空/分支名是否符合预期。该“测试连接”行为在服务端由各 Provider 的testConnection实现通过 simple-git 执行真实的 SSH 操作配置完成后 ToolJet 对仓库的读写如 pull.md 的拉取与 push.md 的提交推送都会复用同一组 SSH 凭据。在自定义分支上配置 GitSync默认情况下GitSync 面向仓库的master分支工作。但从v3.5.3-ee-lts版本开始ToolJet 支持为 GitSync 配置自定义分支。使用该能力前需要了解以下限制与约定仅自托管版本可用自定义分支功能只在 ToolJet Self-Hosted 版本中提供Cloud 版不支持。实例级配置自定义分支通过实例的环境变量配置而不是在工作区 UI 中逐工作区选择。所有工作区共享同一分支不同工作区可以连接不同的仓库但.env中设置的自定义分支必须存在于所有已配置的仓库中否则相应工作区的 GitSync 无法正常工作。也就是说.env里指定的分支会对实例内所有启用 GitSync 的工作区生效。设置方法在 ToolJet 实例的.env文件中加入以下环境变量GITSYNC_TARGET_BRANCHbranch-name将branch-name替换为你希望 GitSync 使用的目标分支名。配置完成后重启 ToolJet 服务使环境变量生效。服务端如何读取该变量GITSYNC_TARGET_BRANCH的读取逻辑体现在迁移脚本 server/data-migrations/1754048735123-MigrateSSHBranchColumnData.ts 中其行为可以归纳为脚本会同时读取进程环境变量与该实例的.env文件内容通过dotenv解析NODE_ENV决定配置文件路径。若GITSYNC_TARGET_BRANCH存在且不等于master则把实例内所有工作区的organization_git_ssh.git_branch更新为该分支名。否则未配置或配置为master全部回填为master——这也与“默认使用 master 分支”的行为一致。也就是说该环境变量决定的是 GitSync 仓库连接的目标分支它会被写入工作区的 Git 配置中供后续 Pull/Push 使用。对已有 GitSync 用户的建议已经在使用 GitSync 的用户如果希望切换到自定义 Git 分支请按以下顺序操作确保一切顺畅先在 Git 仓库管理器中从 master 分支新建一个自定义分支保证历史与现有 master 内容一致。再把该分支名配置到.env文件的GITSYNC_TARGET_BRANCH中并重启服务。之后 GitSync 的 Pull / Push 操作都会以该自定义分支为目标工作。这样做可以避免分支缺失或内容不一致导致的同步失败。相关文档GitSync OverviewGitSync 的总体能力、适用场景应用迁移与备份SSH Configuration for Git Repo ManagerGitLab、Gitea 等其他仓库管理器的 SSH URL 获取与密钥部署push changes to Git把应用变更推送到 Git 仓库pulling changes from Git从 Git 仓库拉取应用变更delete GitSync移除已有 GitSync 连接配置相关源码git-sync 模块、Git 配置 DTO、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考