Backstage Bitbucket Cloud 集成与 Catalog Location 配置完全指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇技术指南围绕 Backstage 中 Bitbucket Cloudbitbucket.org集成展开讲解如何在 Backstage 的软件目录Software Catalog中加载存储在 Bitbucket Cloud 上的实体描述文件如catalog-info.yaml。你将掌握integrations.bitbucketCloud三种认证方式的完整配置API token、App Password、OAuth 2.0 client credentials、每个配置字段的含义与校验规则、认证背后的请求头生成原理以及如何通过静态配置或catalog-import插件把 Bitbucket Cloud 仓库注册为 Catalog Location。Bitbucket Cloud 集成在 Backstage 中的角色Bitbucket Cloud 集成负责让 Backstage 与 bitbucket.org 交互核心用途是从 Bitbucket Cloud 加载 Catalog 实体。实体可以通过两种方式加入静态 Catalog 配置在catalog.locations中声明指向 Bitbucket Cloud 上 YAML 文件的 URL参见 静态 Location 配置catalog-import 插件通过界面交互注册详见仓库中的 catalog-import 插件。从源码结构看该集成被封装在backstage/integration包的bitbucketCloud模块中config.ts、BitbucketCloudIntegration.ts、core.ts同时backstage/plugin-bitbucket-cloud-common提供了一个面向 Bitbucket Cloud REST API 的通用客户端BitbucketCloudClient.ts。Catalog 后端的UrlReaderProcessor会借助这类集成理解如何根据给定 URL 拉取远程内容。配置集成集成配置位于app-config.yaml的integrations.bitbucketCloud键下它是一个 provider 配置列表。对于 Bitbucket Cloud最多只需要一个条目。共有三种认证方式。方式一API token推荐integrations: bitbucketCloud: - username: userdomain.com # username - user email token: my-token这里username实际填写的是账号对应的用户邮箱。API token 的完整说明可参考 Atlassian 官方文档「Using API tokens」。方式二App Password旧版已弃用integrations: bitbucketCloud: - username: username appPassword: my-password需要说明的是从源码注释config.ts可以确认appPassword被标记为 Legacy 并在代码中留有TODO原因是 Bitbucket 计划在 2026 年 6 月 9 日彻底弃用 App Password。新配置请优先使用 API token 或 OAuth 2.0。方式三OAuth 2.0 client credentialsintegrations: bitbucketCloud: - clientId: client-id clientSecret: client-secret该方式使用 OAuth 2.0 的 client credentials 流程获取访问令牌。匿名访问与默认 provider:::note启动时 Backstage 会自动添加一个公开的 Bitbucket Cloud provider以便使用因此只有在需要提供凭据时才需要显式列出它。:::这一行为在 config.ts 的readBitbucketCloudIntegrationConfigs中实现如果显式配置的条目数为 0会自动注入一个只有host和apiBaseUrl的匿名条目host固定为bitbucket.orgapiBaseUrl固定为https://api.bitbucket.org/2.0。也就是说匿名读取公开仓库无需任何配置配置了凭据则替换掉匿名条目。凭据类型限制:::note该类型集成所需的凭据必须是以下三者之一API token、App Password或OAuth 2.0 client credentials。Atlassian 账号 API keyAtlassian Account API key无法用于此集成。:::配置字段详解bitbucketCloud下的单个条目包含以下元素对应 BitbucketCloudIntegrationConfig 类型定义字段类型说明备注usernamestring发起 API 请求所用的 Bitbucket Cloud 用户名实际为邮箱若未提供 username 与 token则使用匿名访问tokenstring用于认证请求的 API token与username搭配使用appPasswordstringBitbucket Cloud 用户的 App Password旧版认证方式Bitbucket 计划于 2026-06-09 弃用clientIdstringOAuth 客户端 ID需与clientSecret成对出现用于 OAuth 2.0 client credentials 流程clientSecretstringOAuth 客户端密钥需与clientId成对出现hoststring常量恒为bitbucket.org无需在 YAML 中配置由代码写入apiBaseUrlstring常量恒为https://api.bitbucket.org/2.0无需在 YAML 中配置由代码写入commitSigningKeystring用于提交签名的 PGP 私钥可选供需要签名提交的场景使用配置校验规则源码级readBitbucketCloudIntegrationConfigconfig.ts在读取配置时会执行如下校验违反即抛错username 与凭据配对若提供了username但既没有token也没有appPassword抛出Bitbucket Cloud integration must be configured with as username and either a token or an appPassword.OAuth 完整性clientId与clientSecret必须成对出现缺任一都会抛出Bitbucket Cloud integration has incomplete OAuth configuration. Both clientId and clientSecret are required.。这些规则均有对应测试覆盖见 config.test.ts。此外测试还验证了前端配置可见性token、username、appPassword、clientId、clientSecret等凭据在 frontend 可见性配置中会被隐藏前端拿到的只是host与apiBaseUrl见 config.test.ts避免把机密泄露给浏览器端。认证背后的实现原理集成如何根据配置生成认证头核心逻辑在 core.ts 的getBitbucketCloudRequestOptions与 BitbucketCloudClient.ts 的getAuthHeaders中逻辑一致按优先级分两种OAuth 2.0clientId clientSecret调用getBitbucketCloudOAuthToken向https://bitbucket.org/site/oauth2/access_token发送grant_typeclient_credentials的 POST 请求拿到的 token 以Authorization: Bearer token携带Basic 认证username token/appPassword将username:token或username:appPassword做 Base64 编码以Authorization: Basic base64携带若两者都没有则不附加任何认证头匿名请求。OAuth token 的获取还实现了缓存与并发保护core.ts令牌缓存在内存中单条缓存因为 Bitbucket Cloud 集成最多一个按expires_in默认 3600 秒计算过期时间并预留 10 分钟宽限期以抵消时钟偏差用refreshPromise跟踪正在进行的刷新请求防止并发重复获取 token。将 Bitbucket Cloud 仓库注册为 Catalog Location配置好集成后就可以把 Bitbucket Cloud 上的catalog-info.yaml加入 Catalog。静态 Location 配置在app-config.yaml中声明url类型的 location 即可参见 Catalog 配置catalog: locations: - type: url target: https://bitbucket.org/your-workspace/your-repo/src/main/catalog-info.yamlurl类型 location 由 Catalog 内置的标准处理器UrlReaderProcessor处理无需额外配置 processor但必须依赖对应的集成来解析如何拉取该 URL——这正是上文bitbucketCloud集成配置的意义所在。静态配置添加的 location 无法通过 Catalog location API 删除只能从配置中移除。若catalog-info.yaml中存在语法错误错误会被记录日志但不会中止处理当发现多个同名metadata.name相同文件时只处理其中一个其余跳过并记录日志。使用 catalog-import 插件注册也可以使用 catalog-import 插件 在界面中粘贴 Bitbucket Cloud 仓库 URL 完成注册。该插件在解析 URL 时会用到集成能力例如 LocationAnalyzer 中的相关解析逻辑。URL 拉取与路径转换集成在拉取文件时会做 URL 转换core.ts 的getBitbucketCloudFileFetchUrl从: https://bitbucket.org/orgname/reponame/src/master/file.yaml 到: https://api.bitbucket.org/2.0/repositories/orgname/reponame/src/master/file.yaml即把bitbucket.org的浏览 URL 转换为 Bitbucket Cloud REST API 的取值地址仅接受src与raw两种文件路径类型。仓库的默认分支则通过查询仓库信息mainbranch.name获得getBitbucketCloudDefaultBranch。此外集成的resolveUrl支持 Bitbucket Cloud 特有的行号语法#lines-42区别于 GitHub 的#L42resolveEditUrl会追加modeeditatref参数见 BitbucketCloudIntegration.ts。进阶Bitbucket Cloud API 客户端若需在自定义插件/处理器中直接查询 Bitbucket Cloud可复用backstage/plugin-bitbucket-cloud-common的BitbucketCloudClientBitbucketCloudClient.ts。它从集成配置构造实例BitbucketCloudClient.fromConfig(config)提供以下能力searchCode(workspace, query)在工作区中搜索代码listRepositoriesByWorkspace(workspace)列出工作区仓库listProjectsByWorkspace(workspace)列出工作区项目listWorkspaces()列出工作区listBranchesByRepository(repository, workspace)列出仓库分支。所有列表类方法都返回WithPagination分页封装pagination.ts默认每页 100 条pagelen: 100既可通过getPage()取单页也可通过iteratePages()异步迭代所有页。请求同样复用getAuthHeaders()的认证逻辑。常见问题与注意事项匿名访问公开仓库无需配置凭据Backstage 会自动注入匿名 provider凭据不生效确认username与token/appPassword成对出现否则启动时会抛出校验错误OAuth 配置不完整clientId与clientSecret必须同时配置否则抛出 incomplete OAuth 错误Atlassian 账号 API key 不可用必须使用 API token、App Password 或 OAuth 2.0 client credentialsApp Password 弃用时间线Bitbucket 计划于 2026 年 6 月 9 日弃用 App Password请尽早迁移到 API token 或 OAuth 2.0前端配置可见性凭据不会下发到浏览器端前端仅能拿到host与apiBaseUrl。总结integrations.bitbucketCloud是 Backstage 连接 bitbucket.org 的唯一入口其三种认证方式API token 推荐、App Password 旧版、OAuth 2.0 client credentials分别对应不同的请求头生成策略且配置校验、默认 provider 注入、OAuth 令牌缓存等行为均有源码与测试背书。配置好集成后通过静态catalog.locations或 catalog-import 插件 即可把 Bitbucket Cloud 仓库中的catalog-info.yaml加载为 Catalog 实体从而在 Backstage 中统一管理软件组件。相关实现可进一步阅读 config.ts、core.ts、config.test.ts 与 BitbucketCloudClient.ts。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考