@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财务报告和审定财务报表gitURL 和 scp 格式 (git@host:path)被支持;用户info和端口被忽略.- 布局: GitLab
owner是全名空间( y)group/sub; Bitbucket 服务器owner是工程密钥,大写,除非是~user个人项目,一个领先scm/被丢弃; Azure DevOpsowner是组织(云)或收藏名称(服务器)和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, (中文(简体) ), githubEnterprise | draft 字段 |
gitlab, (中文(简体) ), gitlabSelfHosted | 无创建时旗:标题前缀为 Draft: (除非它已经开始) Draft:, (中文(简体) ), [Draft] 或者说 (Draft)(中文(简体) ) |
bitbucket | draft 字段 |
bitbucketServer | 不支持 : draft: true 掷出 unsupported 而不寄出任何邮件supportsDraft 实值 false(中文(简体) ) |
azure, (中文(简体) ), azureDevopsServer | isDraft 字段 |
自托管提供者从服务器 URL 中获取 token.domain;没有一个人的呼叫 invalid_request 却一无所获 Azure DevOps 服务器需要它的收藏 URL 。 Bitbucket Cloud 应用程序密码需要 token.username (Bitbucket 用户名,而不是电子邮件). 不同供应商的代号 input.provider 被拒绝,所以从未向错误的主机发送过一个符号.
失败的是 IntegrationError有马厩的 code, (中文(简体) ), status, (中文(简体) ), retryable 财务报告和审定财务报表 provider数字 :
code | 何时 |
|---|---|
not_logged_in | gitKraken API 拒绝了调用者自己的代号( 调用函数) |
not_connected | 提供者未连接到 GitKraken 账户( token 函数) |
unsupported | 提供者无法按要求行事( Bitbucket 服务器上的草稿) |
provider_auth | 提供商拒绝了连接的代号: HTTP 401 403 或 Azure 的 203 登录页 |
rate_limited | HTTP 429,或已用完的GitHub 403 x-ratelimit-remaining 或一个 retry-after 页眉( 可重试) |
invalid_request | 任何其它 4xx , 并带有提供者的电文( 例如“ 已存在拉动请求 ” ) , 或在任何请求之前拒绝输入 |
provider_error | 5xx 或网络失败( 可在读取和浏览上重试; 无法在创建请求上重试 ) 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页:1X-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 远程到 aRemoteRepository(单位:千美元){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。 。 。 .