Configure GitSync（ToolJet 工作区 Git 同步配置）-平芜编程栈

Configure GitSync（ToolJet 工作区 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.md：providers/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 形如git@github.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 Manager（GitLab 通过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。例如：

git@github.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以所选类型生成密钥对。

第 6～10 步：在 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 Key；Gitea 则在仓库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_BRANCH=branch-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 使用。