Backstage Bitbucket Cloud 集成与 Catalog Location 配置完全指南

Backstage Bitbucket Cloud 集成与 Catalog Location 配置完全指南

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage

本篇技术指南围绕 Backstage 中 Bitbucket Cloud（bitbucket.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: user@domain.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 credentials

integrations: 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.org，apiBaseUrl固定为https://api.bitbucket.org/2.0）。也就是说，匿名读取公开仓库无需任何配置；配置了凭据则替换掉匿名条目。

凭据类型限制

:::note

该类型集成所需的凭据必须是以下三者之一：API token、App Password或OAuth 2.0 client credentials。Atlassian 账号 API key（Atlassian Account API key）无法用于此集成。

:::

配置字段详解

bitbucketCloud下的单个条目包含以下元素（对应 BitbucketCloudIntegrationConfig 类型定义）：

配置校验规则（源码级）

readBitbucketCloudIntegrationConfig（config.ts）在读取配置时会执行如下校验，违反即抛错：

1. username 与凭据配对：若提供了username但既没有token也没有appPassword，抛出Bitbucket Cloud integration must be configured with as username and either a token or an appPassword.；
2. 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中，逻辑一致，按优先级分两种：

1. OAuth 2.0（clientId + clientSecret）：调用getBitbucketCloudOAuthToken向https://bitbucket.org/site/oauth2/access_token发送grant_type=client_credentials的 POST 请求，拿到的 token 以Authorization: Bearer <token>携带；
2. Basic 认证（username + token/appPassword）：将username:token（或username:appPassword）做 Base64 编码，以Authorization: Basic <base64>携带；
3. 若两者都没有，则不附加任何认证头（匿名请求）。

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.yaml

url类型 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 的#L42），resolveEditUrl会追加mode=edit&at=<ref>参数，见 BitbucketCloudIntegration.ts。

进阶：Bitbucket Cloud API 客户端

若需在自定义插件/处理器中直接查询 Bitbucket Cloud，可复用@backstage/plugin-bitbucket-cloud-common的BitbucketCloudClient（BitbucketCloudClient.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 credentials；
• App 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