@gitkraken/integrations-tools

中文文档
0.5.0发布于 2026/11/13SEE LICENSE IN LICENSETypeScriptES Module近 30 天下载 2033

GitKraken集成:为GitHub,GitLab,Bitbucket和Azure DevOps(云和自办)启动pad优先级,git-hosting远程解析,提供者-token检索和牵引请求创建.

中文使用文档
文档目录10 节
  1. 安装
  2. 打开拉动请求
  3. resolvePullRequestTarget(config, input) 财务报告和审定财务报表 openPul…
  4. parseRemoteUrl(remoteUrl, selfHosted?)
  5. getProviderToken 财务报告和审定财务报表 refreshProviderToken
  6. createPullRequest(input, { token, request?, logger?, signal…
  7. Pull- request 细节、文件内容和问题撰写
  8. 发射纸
  9. 这是什么
  10. 使用量

@gitkraken/整合工具

运行时间不可知的 GitKraken 整合原始人 :

  • 远程解析数字 : parseRemoteUrl 将 git 远程 URL 变成 API 所需的提供者、 拥有者和仓库 .
  • 提供方令牌数字 : getProviderToken 编号 : refreshProviderToken 从 GitKraken API 获取并旋转 git 提供者连接的令牌 .
  • 提供者连接数字 : getAuthorizeUrl, (中文(简体) ), savePat, (中文(简体) ), deleteProviderToken, (中文(简体) ), getConnectionToken, (中文(简体) ), refreshConnectionToken, (中文(简体) ), deleteConnection 财务报告和审定财务报表 setPrimaryConnection 通过 GitKraken API 管理一个提供者的连接(每个提供者包含几个) .
  • 调试验证数字 : verifyProviderToken 财务报告和审定财务报表 getProviderAccountName 调查一个代币 与提供者.
  • 目录列表数字 : listProviderOrganizations, (中文(简体) ), listProviderProjects 财务报告和审定财务报表 listProviderRepositories 列出连接可看到的内容,并警告部分结果.
  • 拉请求搜索数字 : searchPullRequests 列出在每一个 git 主机上对连接的用户创建、指定或要求审查的拉动请求.
  • 问题数字 : searchIssues, (中文(简体) ), getIssue, (中文(简体) ), assignIssue 财务报告和审定财务报表 validateIssueCriteria 覆盖GitHub,GitLab,Jira,Azure DevOps,Linear和特列洛.
  • 调用目标数字 : resolvePullRequestTarget 财务报告和审定财务报表 openPullRequest 覆盖一个主机的整个“ 为这个远程打开一个 PR ” 流量: 提供者检测 , 云端/ 本地端的倒置 , 自动托管主机检查 , 并在一个被拒绝的 OAuth 令牌上刷新和重试 .
  • 拉动请求创建数字 : createPullRequest 在 GitHub, GitHub Entertainment, GitLab 上打开一个牵引请求(一个在 GitLab 上的合并请求), 自动托管的 GitLab, Bitbucket, Bitbucket 服务器, Azure DevOps 和 Azure DevOps 服务器.
  • 请求细节数字 : getPullRequest, (中文(简体) ), getPullRequestComments 财务报告和审定财务报表 createPullRequestReview 读取拉动请求(其文件已更改),读取其评论并提交对每个git主机的审查或批准.
  • 文件内容数字 : getFileContent 在每个 git 主机上读取分支、标签或承诺的寄存器文件.
  • 问题写入数字 : createIssue 财务报告和审定财务报表 addIssueComment 为 GitHub, GitLab, Jira, Azure DevOps 和 Linear (Trello 无法创建问题) 打开一个问题并评论一个问题.
  • 启动优先排序: 优先级表和纯分组/排序/建议动作功能,从 GitLens “移植 src/plus/launchpad/ (单位:千美元)origin/main) (中文(简体) ).

没错 没有 包括 GitLens 提供者抽象(packages/plus/integrations)或(或) @gitkraken/provider-apis 客户端( 服务商的电话是手写在注射器上 ) request);移动这些是gkcli # 1726 P5b,由于所有者的决定而受阻(见根) ARCHITECTURE.md) (中文(简体) ).

软件包从不拥有网络:每一次呼叫都使用(或接受)注入的网络 ApiRequest 从 @gitkraken/api-tools默认为 a fetch 请求者。 没有任何东西被隐藏或坚持,没有任何东西被推动.

安装

pnpm add @gitkraken/integrations-tools

打开拉动请求

import { IntegrationError, openPullRequest, resolvePullRequestTarget } from '@gitkraken/integrations-tools';

const config = { apiBaseUrl: 'https://api.gitkraken.com/', getToken: async () => gitkrakenToken };

const draft = false;

try {
  const target = await resolvePullRequestTarget(config, {
    remoteUrl: '[email protected]:group/sub/repo.git',
    selfHosted, // the servers the user connected to GitKraken: [{ provider, url }]
    draft,
  });
  // target.repository -> { provider: 'gitlab', owner: 'group/sub', name: 'repo', host: 'gitlab.com' }
  const pr = await openPullRequest(config, target, {
    base: 'main',
    head: 'my-branch',
    title: 'Add the thing',
    body: 'Why the thing is needed.',
    draft,
  });
  console.log(pr.url);
} catch (error) {
  if (error instanceof IntegrationError) console.error(error.code, error.message, error.retryable);
}

config 结构满足于帐号工具 AccountClientConfig。 。 。 .

resolvePullRequestTarget(config, input) 财务报告和审定财务报表 openPullRequest(config, target, input, options?)

resolvePullRequestTarget 返回时 { repository, token, refreshable }。 。 。 . input 拿着 remoteUrl,链接 selfHosted 服务器,可选择:

  • reloadSelfHosted(): 当没有提供者拥有远程时调用一次, 可重读自主机上次同步以来连接的服务器 .
  • localTokens数字 : [{ provider, accessToken, isPat, domain?, username? }],当云对提供者没有连接时使用(例如离线的 PATs)。 这些从不刷新.
  • username: Bitbucket Cloud App-password登录,当符号没有.
  • draft: 提供者无法打开的草稿 unsupported 在任何请求之前 只是这个预检,通过 draft 改为 openPullRequest 或打开非草稿拉动请求.

对于自我托管的提供者来说,符号必须是远程服务器的:其域名必须是远程主机,对于Azure DevOps Server来说,其收藏(另一个服务器或不可分割域名是) invalid_request)),并且该匹配选择了本地的符号,因此一个连接的符号从未被发送到另一个服务器. 一个未知的远程器是 invalid_request,在信件中从 URL 中删除证书。 哪里都没有任何标志的提供商 not_connected。 。 。 .

openPullRequest 电话 createPullRequest 并增加两件事。 打开 provider_auth页:1 refreshable 目标(在 GitLab 、 Bitbucket 或 Azure DevOps 上的云 OAuth 令牌) 被刷新一次, 并重试一次 。 用400或403来刷新吉特克赖肯拒绝 provider_auth5xx, 网络故障, 或中断或超时 signal 当创建请求在飞行中时 没有 可重试,因为提供方可能已经打开了拉出请求,消息中说(cause 保留原始错误。 在创建请求发出之前中止, 包括一个在令牌刷新时, 重排不变 .

createPullRequest 和下面的符号函数保留给需要单独步骤的主机.

parseRemoteUrl(remoteUrl, selfHosted?)

回返 { provider, owner, name, azureProject?, host },或 undefined。 。 。 .

  • 匹配由精确的主机名进行,从不通过子字符串进行(notgithub.example.com 这不是 GitHub 。 连接的自托管服务器首先按阵列顺序检查(一个条目可能包含路径,如 https://host/gitlab,或 Azure DevOps 服务器收藏 https://host/tfs/DefaultCollection然后云宿主 github.com, (中文(简体) ), gitlab.com, (中文(简体) ), bitbucket.org编号 :bitbucket.com,以及 dev.azure.com编号 :ssh.dev.azure.com编号 :*.visualstudio.com。 。 。 .
  • https, (中文(简体) ), http, (中文(简体) ), ssh 财务报告和审定财务报表 git URL 和 scp 格式 (git@host:path)被支持;用户info和端口被忽略.
  • 布局: GitLab owner 是全名空间( y)group/sub; Bitbucket 服务器 owner 是工程密钥,大写,除非是 ~user 个人项目,一个领先 scm/ 被丢弃; Azure DevOps owner 是组织(云)或收藏名称(服务器)和 azureProject 项目(以其项目命名的存储器可能在URL中省略).

getProviderToken 财务报告和审定财务报表 refreshProviderToken

getProviderToken(config, provider, signal?) 电话 GET v1/provider-tokens/{id} 返回 a ProviderToken (单位:千美元)accessToken, (中文(简体) ), type, (中文(简体) ), isPat,以及 domain编号 :tokenId编号 :isPrimary编号 :expiresIn (如果有的话) 对于一个 Bitbucket Cloud 应用程序,主机的密码 username 以物配主,云不还. refreshProviderToken(config, provider, accessToken, signal?) 旋转已到期的 OAuth 令牌并返回新的访问令牌(不针对 PAT 或自托管服务器) 。 打电话者出错 signal 中止的重排不变 。 呼叫者决定何时刷新: a provider_auth 错误来自 createPullRequest复试一次.

createPullRequest(input, { token, request?, logger?, signal? })

提供者草案
github, (中文(简体) ), githubEnterprisedraft 字段
gitlab, (中文(简体) ), gitlabSelfHosted无创建时旗:标题前缀为 Draft: (除非它已经开始) Draft:, (中文(简体) ), [Draft] 或者说 (Draft)(中文(简体) )
bitbucketdraft 字段
bitbucketServer不支持 : draft: true 掷出 unsupported 而不寄出任何邮件supportsDraft 实值 false(中文(简体) )
azure, (中文(简体) ), azureDevopsServerisDraft 字段

自托管提供者从服务器 URL 中获取 token.domain;没有一个人的呼叫 invalid_request 却一无所获 Azure DevOps 服务器需要它的收藏 URL 。 Bitbucket Cloud 应用程序密码需要 token.username (Bitbucket 用户名,而不是电子邮件). 不同供应商的代号 input.provider 被拒绝,所以从未向错误的主机发送过一个符号.

失败的是 IntegrationError有马厩的 code, (中文(简体) ), status, (中文(简体) ), retryable 财务报告和审定财务报表 provider数字 :

code何时
not_logged_ingitKraken API 拒绝了调用者自己的代号( 调用函数)
not_connected提供者未连接到 GitKraken 账户( token 函数)
unsupported提供者无法按要求行事( Bitbucket 服务器上的草稿)
provider_auth提供商拒绝了连接的代号: HTTP 401 403 或 Azure 的 203 登录页
rate_limitedHTTP 429,或已用完的GitHub 403 x-ratelimit-remaining 或一个 retry-after 页眉( 可重试)
invalid_request任何其它 4xx , 并带有提供者的电文( 例如“ 已存在拉动请求 ” ) , 或在任何请求之前拒绝输入
provider_error5xx 或网络失败( 可在读取和浏览上重试; 无法在创建请求上重试 ) openPullRequest, (中文(简体) ), createIssue 或者说 addIssueComment,它可能已经着陆),或者没有所创建的资源或无效的正文的 2xx(不可重试:拉出请求,问题或注释可能已经创建)

Pull- request 细节、文件内容和问题撰写

全部六条 (options, input) 与 options (单位:千美元) ProviderCallOptions (单位:千美元)token, (中文(简体) ), request?, (中文(简体) ), logger?, (中文(简体) ), signal?, (中文(简体) ), refresh?) (中文(简体) ).

  • getPullRequest(options, { id, owner, repo, azureProject?, files? }) 返回时 { pullRequest, warnings }与 files: true 更改后的文件在 gkcli 的限度内列出( GitHub 和 GitLab : 20页的 100 个文件, 512 KB 的 diffs 和 45 s 的行走 ; 预算过后的文件保留其名称并丢失其补丁 , diffOmitted; GitLab 也标记了提供者省略的补丁). Bitbucket Cloud 在相同的512 KB补丁预算, Bitbucket 服务器页面中列出其 diff 的每个文件 changes 最多可有10页,两者都在同一45s的截止日期之内(后来的Bitbucket Server一页失败或出错保存了更早的文件并添加了警告;Bitbucket Cloud diff是一个单项请求,因此一个失败或出错的diff没有部分列表的完整呼叫失败),Azure DevOps没有列出.
  • getPullRequestComments(options, input) 返回时 { prComments, reviewComments }:谈话和内置评论. GitHub 将两者都输入 prComments 并审查 reviewComments; 其他提供者将内置注释输入 reviewComments。每个页面都读取;系统注释和被删除的评论被忽略.
  • createPullRequestReview(options, { id, owner, repo, azureProject?, review, approve? }) 员额 review 文本作为评论,并 approve,在一次GitHub审查呼叫中批准,或单独呼叫其他提供者。 它返回"你的审查已经提交",并链接到提供方给出一个的评论或审查. 一个空的 review 无 approve 是一个 invalid_request。当评论发布后批准失败时,错误是不可重复的,并说评论发布。 第一次写作前的读取( Azure DevOps 身份查询以获得批准) 失败, 因为没有提交文件 .
  • getFileContent(options, { owner, repo, ref, filePath, azureProject?, maxBytes? }) 返回文件的文本。 一个文件结束 maxBytes (默认 1 MiB) 失败 invalid_request。限制会限制返回的内容,而不是内存或下载:只有 GitLab(一种最佳效果) HEAD 页:1 X-Gitlab-Size; 失败 HEAD 坠入深渊 GETBitbucket Cloud (路径元数据) size)在下载前拒绝文件. GitHub (英语) size 与内含内容相同 原始反应 content-length 与它的躯体,所以那些在下载后但解码前就被拒绝了 request 在检查前读取整个身体. owner 不需要在 Azure DevOps 服务器上使用,该令牌的收藏 URL 替换它 .
  • createIssue(options, { title, body?, org?, repo?, labels?, assignees?, issueType?, azureOrg?, azureProject? }) 返回创建的 Issue 包含创建响应给出的字段. issueType 仅为 Jira( 默认) Task中,项目密钥 repo) (中文(简体) ). 特雷洛抛出 unsupported。 。 。 .
  • addIssueComment(options, { id, comment, org?, repo?, azureOrg?, azureProject? }) 在 Jira (已转换) 和 Azure DevOps 上取出 Markdown 。 Jira 的 Markdown 转换不支持引用式链接([text][ref] 带有 [ref]: url 定义).

getFileContent是因为 ref 是除Azure DevOps以外的每个供应商的分支、标记或承诺SHA, 它无法从分支中分辨出一个赤裸的标记: 完整的承诺SHA在该承诺中读取, refs/tags/<name> 在标签,和 refs/heads/<name> 或任何其他赤名被读作分行. 在 Bitbucket Cloud 上,分支名称可能包含 /。文件查找首先读取路径元数据,拒绝目录,并在元数据返回的承诺取取文件.

对于 getFileContent 主持人的 request 必须返回响应正文为文本(或字节,解码为UTF-8). 预paras JSON 失败的不可重试请求 provider_error。Bitbucket 和 Azure DevOps 即使主机给它贴上标签, 也可以逐字返回身体 application/json,所以JSONC或者其他畸形的JSON作为文字回来.

3个读了一次刷新符号 provider_auth (当 refresh 已设定). 这三人写道:createPullRequestReview, (中文(简体) ), createIssue, (中文(简体) ), addIssueComment从不刷新符号,所以 provider_auth 拨打者未受影响。 他们只在提供商的运输时重新尝试过一次受压请求:GitHub和GitHub Entertainment在429上(在它之后) Retry-After,5秒无一秒)或403个带一秒 Retry-After- Bitbucket Cloud and Server, Jira (Cloud and Server) 和 Azure DevOps (Cloud and server) 上的429号卫星。 GitLab, Linear和Trello从不重试. 5xx, 运输失败, 或中止或超时 signal 当创建、评论或审查请求正在飞行中时,则不可重复 provider_error 表示问题或评论可能已经存在或可能已提交审查(cause 保留原始错误。 中止或超时 signal 在发出书面请求之前,包括在其之前的一次检索中,不作更改;这种查询的5xx或运输失败(线性团队、标签或用户、Jira Cloud站点、Azure DevOps 身份以获得批准)仍然可以进行再试。 在贴出评论后,一个失败的审批是不可重复的,并称评论是贴出. 该变异上的线性图形QL 验证错误是 invalid_request 只有在反应对突变无结果时(data 或编号 issueCreate编号 :commentCreate 因此,线性拒绝了它;如果结果出现,它可能是写作的 provider_error。错误使用上表的代码: unsupported 对于一个没有能力的供应商, invalid_request 缺少输入或4xx, provider_auth, (中文(简体) ), rate_limited 财务报告和审定财务报表 provider_error; 无法读取的一写为 2xx 不可重录 provider_error (审查、问题或评论可能存在)。 Jira Cloud在这样的回复后从不重复在另一个站点上写作,在5xx,超时或运输失败后从不重复创建或评论(它可能在第一个站点上存在). 缺少的文件或参考文献是 invalid_request 与 status: 404。 GitHub 和 GitLab 也失败了 invalid_request 没有 status 当一个 2xx 机构没有可用的文件 content (例如GitHub上的目录).

文件内容限制 :

  • maxBytes 盖上返回的内容, 而不是内存: 只有 GitLab( 最优) HEAD)和Bitbucket Cloud(元数据)在下载前检查大小. GitHub (英语) size 和原始反应 content-length 在下载后但解码前检查;否则主机的 request 在检查前读取整个身体.
  • 二进制文件被丢失解码:无效的UTF-8字节成为了U+FFFD. 一个领先的UTF-8 BOM被放弃.
  • GitHub 的内容 API 不在 1 MB 上内入文件; 失败的文件 invalid_request。 。 。 .

发射纸

这是什么

  • models/launchpad.ts:优先表格 -- -- launchpadActionCategories, (中文(简体) ), launchpadGroups, (中文(简体) ), launchpadCategoryToGroupMap, (中文(简体) ), sharedCategoryToLaunchpadActionCategoryMap, (中文(简体) ), prActionsMap, (中文(简体) ), launchpadPriorityGroups (显示优先级顺序 : mergeable, (中文(简体) ), blocked, (中文(简体) ), follow-up, (中文(简体) ), needs-review),以及 launchpadGroupLabelMap编号 :actionGroupMap (平面英语字符串; GitLens' VS 代码图标映射和 @vscode/l10n 电话 被丢弃,而不是移植).
  • launchpad.ts数字 : getLaunchpadItemGroups, (中文(简体) ), groupAndSortLaunchpadItems, (中文(简体) ), countLaunchpadItemGroups, (中文(简体) ), sortLaunchpadItems, (中文(简体) ), getSuggestedActions - 移植 从 launchpadProvider.ts,在最小值上运行 LaunchpadItemInput 输入类型而不是 GitLens 的全 LaunchpadItem (无) vscode,没有 openRepository(原始内容存档于2019-10-21) (中文(简体) ). groupAndSortLaunchpadItems编号 :countLaunchpadItemGroups 从不包含 current-branch 键; sortLaunchpadItems 保持链接输入顺序.
  • providers.ts数字 : GitHostingProviderId (八克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克. github, (中文(简体) ), gitlabSelfHosted, (中文(简体) ), azureDevopsServer, (中文(简体) ), normalizeProviderId (存储密钥, CLI) 名称和云 id 到 id,或 undefined, (中文(简体) ), providerDisplayName, (中文(简体) ), isSelfHosted。 。 。 .
  • remotes.ts数字 : parseRemoteUrl 解析 git 远程到 a RemoteRepository (单位:千美元){provider, owner, name, azureProject?, host}(三); SelfHostedProvider 描述 a 已连接的自托管服务器( e){provider, url}) (中文(简体) ).

使用量

import {
  getLaunchpadItemGroups,
  getSuggestedActions,
  type LaunchpadItemInput,
  sortLaunchpadItems,
} from '@gitkraken/integrations-tools';

const items: LaunchpadItemInput[] = [...];
const aiReviewAllowed = hostAiEnabled; // org + user AI setting; required so a missing flag cannot fail open
sortLaunchpadItems(items);
for (const item of items) {
  const groups = getLaunchpadItemGroups(item);
  const actions = getSuggestedActions(item.actionableCategory, false, aiReviewAllowed);
}

sortLaunchpadItems 重新排序并返回相同的数组; groupAndSortLaunchpadItems 还将其输入数组排序到位。 下表未解析的项目草稿 needs-my-review 类别均出现在 draft 财务报告和审定财务报表 needs-review 团体,但 countLaunchpadItemGroups 数起来 draft 并把它排除在 needs-review。 。 。 .

版本与发布记录

@gitkraken/integrations-tools 共发布 5 个版本,首次发布于 2026/10/27;过去 12 个月发布了 5 个版本。

版本发布日期距今
0.5.0latest2026/11/133 天前
0.4.02026/11/0313 天前
0.3.02026/10/2819 天前
0.2.02026/10/2720 天前
0.0.0-stage2026/10/2720 天前

关于 @gitkraken/integrations-tools 的常见问题

@gitkraken/integrations-tools 是什么?

GitKraken集成:为GitHub,GitLab,Bitbucket和Azure DevOps(云和自办)启动pad优先级,git-hosting远程解析,提供者-token检索和牵引请求创建.

如何安装 @gitkraken/integrations-tools?

在项目目录运行 npm install @gitkraken/integrations-tools,或使用 pnpm add / yarn add / bun add。

@gitkraken/integrations-tools 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gitkraken/integrations-tools 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gitkraken/integrations-tools 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >= 22。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gitkraken/integrations-tools 可以商用吗?

@gitkraken/integrations-tools 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中,请阅读该文件确认可否商用。以上为概括,不构成法律意见,请以许可原文为准。

@gitkraken/integrations-tools 的下载量有多少?

根据 npm 官方下载统计,@gitkraken/integrations-tools 在 2026/10/17 – 2026/11/15 这 30 天内被下载 2,033 次,日均约 68 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gitkraken/integrations-tools 还在维护吗?

最新版本 0.5.0 发布于 2026/11/13(3 天前);至今共发布 5 个版本,其中过去 12 个月发布了 5 个;首次发布于 2026/10/27。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。