ToolJet GitHub Marketplace 插件使用指南：连接 GitHub 数据源与执行仓库查询

ToolJet GitHub Marketplace 插件使用指南：连接 GitHub 数据源与执行仓库查询

【免费下载链接】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 通过官方 Marketplace 提供了 GitHub 数据源插件，允许你在应用构建器中直接对接 GitHub，读取用户信息、仓库详情、Issue 与 Pull Request 列表，并将结果绑定到表格、图表等组件上，快速搭建开发运维类内部工具。本文基于 GitHub 插件官方文档 与仓库中该插件的完整源码，讲解连接配置、四种内置查询的参数细节，以及底层基于 Octokit 的实现原理，读完即可独立完成数据源接入与查询调优。

插件概览：从文档到源码

GitHub 插件是 ToolJet Marketplace 生态中的一个type: api类型数据源插件，完整的插件包位于 marketplace/plugins/github，其核心结构如下：

• lib/index.ts：插件入口，Github类实现QueryService接口，负责建立连接、分发操作与测试连接；
• lib/query_operations.ts：四种查询操作的具体实现，全部基于octokit客户端调用 GitHub REST API；
• lib/manifest.json：数据源级配置 Schema，定义认证方式与凭据字段；
• lib/operations.json：查询操作级 Schema，定义操作下拉列表与各操作的参数表单；
• lib/types.ts：SourceOptions、QueryOptions与Operation枚举等类型定义；
• package.json：插件元信息，核心运行时依赖为octokit ^4.0.2与@tooljet-marketplace/common ^1.0.0。

插件对外暴露四种查询能力，与文档中的 Supported Queries 一一对应：

操作标识（Operation）	对应 REST 端点
get_user_info	GET /users/{username}
get_repo	GET /repos/{owner}/{repo}
get_repo_issues	GET /repos/{owner}/{repo}/issues
get_repo_pull_requests	GET /repos/{owner}/{repo}/pulls

建立连接：Personal Access Token 认证

凭据要求

要连接 GitHub 数据源，你只需要一种凭据：

• Personal Access Token（个人访问令牌）：可通过 GitHub 账号设置页面生成。生成令牌时，请根据后续要执行的查询勾选合适的权限范围——仅读取公开数据时使用无权限的令牌即可，访问私有仓库数据则需为令牌授予repo相关的读取权限。

关于令牌的适用边界，官方文档明确说明：

访问私有仓库的数据必须提供 Personal Access Token；公开仓库的数据无需令牌即可访问。

也就是说，即使不配置令牌，你依然可以查询公开仓库的信息，但查询私有仓库时会因凭据不足而失败。

凭据字段与加密存储

从 manifest.json 可以看到数据源配置层的定义：

"source": { "name": "GitHub", "kind": "github", "exposedVariables": { "isLoading": false, "data": {}, "rawData": {} }, "options": { "auth_type": { "type": "string" }, "personal_token": { "type": "string", "encrypted": true } } }

关键点：

• auth_type：认证类型标识，默认值为personal_access_token（当前仅支持这一种认证方式），在界面中表现为"Use Personal Access Token"单选下拉；
• personal_token：令牌字段，标记为encrypted: true，意味着令牌会以加密形式存储，界面输入框类型为password；
• required: ["personal_token"]：令牌是必填项；
• 数据源还对外暴露isLoading、data、rawData三个变量，供查询运行时在应用内引用（如表格加载态）。

底层连接与测试逻辑

连接与测试逻辑实现在 lib/index.ts：

async testConnection(sourceOptions: SourceOptions): Promise<ConnectionTestResult> { const octokit = await this.getConnection(sourceOptions); try { const { status } = await octokit.rest.users.getAuthenticated(); if (status) { return { status: 'ok' }; } } catch (error) { return { status: 'failed', message: 'Invalid credentials' }; } } async getConnection(sourceOptions: SourceOptions): Promise<any> { const octokitClient = new Octokit({ auth: sourceOptions.personal_token, }); return octokitClient; }

• getConnection使用personal_token创建Octokit实例；
• testConnection调用 GitHub 的GET /user（octokit.rest.users.getAuthenticated()）校验令牌有效性，成功后返回status: 'ok'，令牌非法时返回status: 'failed'与Invalid credentials提示。

在界面上的操作路径为：数据源 → 添加数据源 → 选择 GitHub → 粘贴 Personal Access Token → 点击测试连接 → 保存。下图展示了文档中的连接界面截图：

支持的四类查询操作详解

以下四个查询即为该插件当前支持的全部操作。除Get User Info外，其余三个操作共享"Owner + Repository"的组合参数模式，可配合状态过滤与分页参数灵活取数。

Get User Info：获取用户信息

该操作用于获取指定 GitHub 用户或组织的详细信息（如登录名、名称、头像、公共仓库数、粉丝数、个人主页、所在地、创建时间等）。

必填参数

• Username：GitHub 用户名或组织名。

底层调用 query_operations.ts 中的getUserInfo：

export async function getUserInfo(octokit: Octokit, options: QueryOptions): Promise<object> { const { data } = await octokit.request('GET /users/{username}', { username: options.username, }); return data; }

对应 REST 端点为GET /users/{username}，该端点支持匿名访问，因此即使未配置令牌也能查询公开用户信息。界面截图参考文档配图：

Get Repository：获取仓库详情

获取指定仓库的详细元数据，包括仓库描述、默认分支、Star 数、Fork 数、语言、许可证、是否私有、最近更新时间等。

必填参数

• Owner：仓库所有者名称，可以是 GitHub 用户或组织；
• Repository：仓库的准确名称。

底层调用getRepo：

export async function getRepo(octokit: Octokit, options: QueryOptions): Promise<object> { const { data } = await octokit.request('GET /repos/{owner}/{repo}', { owner: options.owner, repo: options.repo, }); return data; }

Get Repository Issues：获取仓库 Issue 列表

生成指定仓库的 Issue 列表，并支持按状态过滤。

必填参数

• Owner：仓库所有者名称（用户或组织）；
• Repository：要检索 Issue 的仓库名称；
• State：按状态过滤 Issue，可选All（全部）/ Open（打开）/ Closed（已关闭）。

可选参数

• Page size：每页返回的 Issue 数量，默认 30；
• Page number：要获取的页码，默认 1。

底层实现（query_operations.ts）：

export async function getRepoIssues(octokit: Octokit, options: QueryOptions): Promise<object> { const { data } = await octokit.request('GET /repos/{owner}/{repo}/issues', { owner: options.owner, repo: options.repo, state: options.state || 'all', ...(options.page && validateNumber('The value must be greater than 1.', 'page', options.page, 1) && { page: parseInt(options.page, 10), }), ...(options.page_size && validateNumber('The value must be in the range of 1 to 100', 'page size', options.page_size, 1, 100) && { per_page: parseInt(options.page_size, 10), }), }); return data; }

需要注意的几个实现细节：

• state缺省值为all：不填写状态时按全部状态查询；
• 分页参数仅在显式提供时才会传给 GitHub，不传则使用 GitHub REST API 的默认分页行为；
• 参数校验：page必须大于等于 1；page_size（对应 GitHub 的per_page）必须在 1 到 100 之间，超出范围会抛出形如Invalid page size: The value must be in the range of 1 to 100的校验错误——这也解释了为什么界面占位提示中把 100 作为上限。

Get Repository Pull Requests：获取仓库 Pull Request 列表

生成指定仓库的 Pull Request 列表，支持按状态过滤。

必填参数

• Owner：仓库所有者名称（用户或组织）；
• Repository：要检索 PR 的仓库名称；
• State：按状态过滤 PR，可选All / Open / Closed。

可选参数

• Page size：每页返回的 PR 数量，默认 30；
• Page number：要获取的页码，默认 1。

底层实现为getRepoPullRequests，调用GET /repos/{owner}/{repo}/pulls，其参数处理、缺省值与校验规则与getRepoIssues完全一致（query_operations.ts）。

运行机制：从操作分发到结果返回

在 ToolJet 中执行一条 GitHub 查询时，请求会进入 lib/index.ts 的run方法：

async run(sourceOptions: SourceOptions, queryOptions: QueryOptions, dataSourceId: string): Promise<QueryResult> { const operation: Operation = queryOptions.operation; const octokit: Octokit = await this.getConnection(sourceOptions); let result = {}; try { switch (operation) { case Operation.GetUserInfo: result = await getUserInfo(octokit, queryOptions); break; case Operation.GetRepo: result = await getRepo(octokit, queryOptions); break; case Operation.GetRepoIssues: result = await getRepoIssues(octokit, queryOptions); break; case Operation.GetRepoPullRequests: result = await getRepoPullRequests(octokit, queryOptions); break; default: throw new QueryError('Query could not be completed', 'Invalid operation', {}); } } catch (error) { throw new QueryError('Query could not be completed', error.message, {}); } return { status: 'ok', data: result }; }

整个执行链路可以概括为三步：

1. 建立客户端：getConnection用令牌初始化 Octokit；
2. 操作分发：根据queryOptions.operation（枚举定义见 lib/types.ts）匹配四种操作之一，未知操作会抛出Invalid operation；
3. 统一封装结果：成功时返回{ status: 'ok', data: result }，失败时以QueryError包装错误信息，方便在应用编辑器中定位问题。

在应用中使用查询结果

在 ToolJet 应用构建器中，将 GitHub 数据源添加到应用后，即可创建查询并选用上述四种操作。操作表单由 operations.json 驱动：

• 参数输入框类型为codehinter，支持输入静态值，也支持写表达式引用应用内其他组件/查询的返回值（例如把表格选中行中的owner、repo动态传入查询参数）；
• state为下拉选择，取值open/closed/all；
• 查询创建完成后，可将其绑定到 Table、Listview 等展示组件（data数组型结果按行渲染），或用于触发后续查询（如选中某条 Issue 后再查询其评论）。

以"仓库 Issue 看板"为例的典型用法：Get repository issues查询传入固定的owner/repo，state绑定下拉组件值，page_size填 30；结果绑定到表格组件，即可在几分钟内搭出一个可筛选、可翻页的 Issue 列表视图。

验证与扩展

插件自带的测试入口位于tests/index.js，目前为it.todo('needs tests')占位状态，尚未补充针对run分发与参数校验的断言用例——若你打算为插件贡献测试，validateNumber的边界条件（page < 1、page_size > 100）与state缺省值逻辑都是值得优先覆盖的路径。

从扩展角度看，该插件的操作集合固定为文档列出的四类。若需要读取 Issue 评论、仓库提交记录或触发 GitHub Actions 等更丰富的交互，可在Operation枚举与run的switch分支中新增对应操作（参照现有getRepoIssues的写法调用octokit.request），并在 operations.json 中补充表单 Schema，即可在界面上使用。

小结

GitHub 插件以极低的接入成本，为 ToolJet 应用提供了访问 GitHub 数据的标准通道：一个 Personal Access Token 即可建立连接，四类内置查询覆盖了用户信息、仓库详情、Issue 与 PR 列表等高频场景，且分页与状态过滤参数在源码层面有明确的缺省值与校验边界。本文所涉及的源码均可直接在仓库中查阅：插件入口、查询操作实现、数据源 Schema 与 操作表单 Schema。

【免费下载链接】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