How Backstage reads catalog files from Bitbucket
Platform teams that keep services in Bitbucket need Backstage to find those services without a manual import for every repository. Backstage handles this with separate integration and catalog discovery modules for Bitbucket Cloud and Bitbucket Server, so the first decision is which product your organization runs. The core repository ships a catalog module for each product, named catalog-backend-module-bitbucket-cloud and catalog-backend-module-bitbucket-server, and an auth provider for each as well. Pick the pair that matches your deployment and do not try to point one module at the other product, because the API endpoints and credential model differ.
The catalog reads catalog-info.yaml files from repositories, and the discovery module decides which projects, repositories and branches it scans. Before you configure anything, list the Bitbucket projects that hold services and confirm that the service account or token you plan to use can read every one of them. Missing read access usually shows up as entities that silently never appear, so verify it with a test repository first. On the publishing side, scaffolder actions for Bitbucket come from @backstage/plugin-scaffolder-backend-module-bitbucket-cloud or @backstage/plugin-scaffolder-backend-module-bitbucket-server, so the template side must match the same product as the catalog side. Confirm with your Bitbucket administrators which version and hosting model applies before you install either module, and check the Backstage integrations documentation for the current configuration keys.
What you need before configuring Bitbucket in Backstage
Most Bitbucket integration problems trace back to decisions made before any configuration file is touched. Settle the deployment type, the credential model, network paths and the discovery scope first, then the catalog module and auth configuration follow from those choices.
A running Backstage instance
Confirm you have a working Backstage app with the Software Catalog enabled and a backend that starts cleanly. The Software Catalog, Software Templates and TechDocs are core built-in features, so catalog discovery and publishing both depend on this base being stable. Note which Backstage release line you run, because the module versions you install must match it. Check the versioning policy before you pick any package versions, and do not mix module releases from different lines.
Confirm Cloud or Server deployment
Decide whether your code lives in Bitbucket Cloud or in a self-hosted Bitbucket Server (Data Center) instance. The two use separate integration settings, separate catalog modules, separate auth providers and separate scaffolder publish modules, so a Cloud setup will not work against a Server host. If you run both, plan two integration blocks and two sets of modules from the start, with a clear owner for each.
Read-only credentials for target repositories
Create the account or app credential that Backstage will use, scoped to the projects and repositories it must read. Discovery needs read access to catalog files, while scaffolder publishing needs write access to create repositories, so treat these as separate credentials when possible. Record who owns the credential, when it expires and how it is rotated, because a silently expired token stops discovery without an obvious error.
Network path from the backend
Verify that the machine running the Backstage backend, not your browser, can reach the Bitbucket host over HTTPS. This matters most for self-hosted Bitbucket Server behind a corporate proxy, VPN or private DNS, and for egress rules on Kubernetes clusters. Test the path with the same runtime and proxy settings the backend uses. Also confirm certificate trust for any internal certificate authority, since a failed TLS handshake looks like a credential problem.
A discovery scope decision
Decide which projects, repositories and branches Backstage should scan for catalog files, and which path or file name marks an entity. Broad scans increase load and the number of entities you must later review, while narrow scopes miss services owned by teams outside the pilot group. Write the scope down with the owning team, so the first import produces entities people recognize and can correct.
Module versions confirmed for your release
Plan a check of the catalog and scaffolder module versions against your Backstage release line before adding them, and record the result in your change ticket. The core repository's plugins directory lists the packages that ship with the project. Confirm the exact versions with your team's upgrade owner rather than copying package names from older examples, since Backstage upgrades move all @backstage packages together.
Configure the Bitbucket integration in order
This sequence connects Backstage to one Bitbucket host, loads catalog files from the repositories you choose, and optionally lets Software Templates publish new repositories. Each step ends with a check so you can confirm the previous layer works before adding the next.
Add the Bitbucket integration entry
The platform team adds a Bitbucket integration block to app-config.yaml for the exact host in use, either bitbucket.org for Cloud or the base URL of your self-hosted Bitbucket Server or Data Center instance. Keep the Cloud and Server entries separate if you run both, since each has its own credential format and API base. Confirm the entry is present by starting the backend and checking that it loads without integration configuration errors in the logs.
Store credentials in secrets
Create the access credential for a dedicated service account in Bitbucket, scoped to read the projects and repositories you plan to catalog. Place the token or app password in your secrets store or an environment variable, and reference it from the integration config instead of writing it into plain app-config files. Confirm the setup by making a read call with the credential against one known repository from the Backstage host, outside the portal.
Install the matching catalog module
Add the catalog module for your platform, @backstage/plugin-catalog-backend-module-bitbucket-cloud or @backstage/plugin-catalog-backend-module-bitbucket-server, to the catalog backend and register it in the backend index. Do not install both unless you run both platforms. Confirm the install by restarting the backend and checking that the module initializes without errors in the startup log.
Configure discovery with filters
Add a Bitbucket discovery provider under the catalog configuration, setting the host, the project and repository filters, and the catalog file path, commonly catalog-info.yaml at the repository root. Narrow the filters to the projects that own services, because broad patterns increase the number of entities and the refresh load on the host. Confirm the configuration by triggering a catalog refresh and checking that the expected repositories appear as entities in the Catalog view, with unmatched repositories absent.
Verify entities and ownership fields
Open a sample of the discovered entities and check that their kind, owner, and lifecycle fields match the descriptors in the repositories. Entities that fail validation or lack an owner will show errors in the catalog processing view, so resolve those in the source repositories before expanding the filters. Confirm the step by reviewing that a representative set of services from different projects shows the correct owner and system.
Install the scaffolder publish module
If Software Templates will create repositories in Bitbucket, install the matching publish module, @backstage/plugin-scaffolder-backend-module-bitbucket-cloud or @backstage/plugin-scaffolder-backend-module-bitbucket-server, and grant the service account permission to create repositories in the target projects. Keep this separate from read access, and review which projects the template actions can write to. Confirm the install by checking that the Bitbucket publish action appears in the available actions list.
Dry-run a template publish
Run one non-production template that publishes to a test project in Bitbucket, and confirm the repository is created with the expected content and that the catalog descriptor is discovered on the next refresh. Use a sandbox project so a failed attempt does not leave repositories in production projects. Confirm the result by checking the new repository in Bitbucket and the matching entity in the catalog before enabling the template for teams.
Bitbucket Cloud or Bitbucket Server: which path to configure
Bitbucket Cloud is hosted by Atlassian at bitbucket.org, so the Backstage backend connects outward to a public endpoint. Your decisions focus on which credential the backend holds and which workspaces and projects that credential can read. Backstage documents a Cloud integration separately from Server, and the core repository ships its own catalog module and auth provider for it.
- Host and integration block: Configure the Bitbucket Cloud integration with the host
bitbucket.organd the credential your chosen method requires, so the catalog, readers and scaffolder all use the same settings. - Catalog module: Install
catalog-backend-module-bitbucket-cloudto discovercatalog-info.yamlfiles in the repositories your credential can read. - Auth provider: Enable the Bitbucket Cloud sign-in provider as its own step, and make its sign-in resolver map to the same user identity your catalog uses.
- Scaffolder publish: Add
@backstage/plugin-scaffolder-backend-module-bitbucket-cloudonly when templates must create repositories in Bitbucket Cloud. - Network: The backend needs outbound HTTPS access to the Cloud endpoints, and nothing inbound from Atlassian is required for scheduled discovery.
Before go-live, confirm that the backend's egress policy allows the Cloud host and that the credential's scopes cover every workspace you intend to discover.
Self-hosted Bitbucket Server, which Atlassian also refers to as Data Center, runs on your hostnames and your certificate chain. The integration therefore depends on what the Backstage backend can reach and what it trusts. Backstage ships separate Server modules for catalog discovery, sign-in and scaffolder publishing, so each one needs its own configuration.
- Hostnames: Set the Bitbucket Server integration host to the exact name in your server certificate, and set the API base URL to the address your instance exposes to the backend.
- Certificate trust: If an internal certificate authority signs the server certificate, the backend's Node.js process must trust that authority. Confirm with your platform team how your Backstage image or deployment supplies the CA bundle.
- Catalog module: Install
catalog-backend-module-bitbucket-serverand scope discovery to named projects so the scan stays bounded on a large instance. - Auth provider and scaffolder: Pair the Bitbucket Server sign-in provider with its own resolver, and add
@backstage/plugin-scaffolder-backend-module-bitbucket-serveronly if templates publish repositories there. - Service credential: Use a dedicated service account with a personal access token limited to read access, plus write access where publishing is enabled, and store it in your secrets process.
From the Backstage backend host, not a workstation, confirm that the hostname resolves, the TLS handshake succeeds and the token reads one known repository.
Many estates run Cloud and Server side by side, or move repositories from one to the other during a transition. Each host is configured separately, so catalog identity and sign-in must stay consistent while both are active. Illustrative example: a team migrates a service from a self-hosted project to a Cloud workspace and must keep one catalog entity for it.
- Separate integration entries: Keep the Cloud and Server hosts in their own integration blocks, since one host value cannot describe both.
- Stable source location: Use a source location annotation that points to the repository's current home, and update it during the move so the entity is not created twice.
- Shared sign-in identity: Two sign-in providers can resolve to one user when the resolver matches on a shared attribute such as email. Confirm which attribute your directory supplies for both.
- Per-host secrets: Give each host its own credential so a rotation on one host does not break discovery on the other.
- Duplicate detection: Discovery runs per provider, so a repository visible through both hosts can produce two entities. Check the catalog for duplicates after each discovery run during the transition.
Before retiring the old host, test sign-in with one user on each provider and confirm that each migrated entity appears once.
How Bitbucket projects, repositories and users map to Backstage
This table compares how each Bitbucket object (workspace or project, repository, branch, user) lands in the Backstage catalog and sign-in model, for both Bitbucket Cloud and Bitbucket Server. Read each row as a design decision to settle before discovery runs, because the mapping determines ownership, entity names and who can sign in. The main takeaway is that catalog ownership and sign-in identity are configured separately and must be reconciled through a single sign-in resolver.
| Bitbucket object | Bitbucket Cloud | Bitbucket Server (Data Center) | What to confirm |
|---|---|---|---|
| Top-level container | Workspace, read through the Bitbucket Cloud integration and discovery module | Project key and server URL, read through the Bitbucket Server integration and discovery module | Which workspaces or projects hold catalog files and which credentials can read them |
| Group or owner | Workspace or team mapped to a catalog Group or owner reference in entity metadata | Project mapped to a catalog Group or owner reference in entity metadata | Whether ownership follows the Bitbucket structure or your identity directory groups |
| Repository to entity | Repository catalog-info file read and turned into a Component or other entity | Repository catalog-info file read and turned into a Component or other entity | Entity kind chosen per repository and how the file location is matched |
| Repository name and branch | Repository slug and configured branch become entity source location and naming | Repository slug and configured branch become entity source location and naming | Default branch handling and whether forks or archived repositories are included |
| Bitbucket user to sign-in | User signs in through the Bitbucket auth provider | User signs in through the Bitbucket Server auth provider where your version supports it | Which OAuth application or credential the sign-in flow uses in your environment |
| Sign-in resolver | Resolver maps the Bitbucket identity to the same user entity as other providers | Resolver maps the Bitbucket Server identity to the same user entity as other providers | Every provider resolves to one identity, and guest access is disabled in production |
| Catalog user and group entities | Users and groups come from a separate org data source, not from sign-in alone | Users and groups come from a separate org data source, not from sign-in alone | Which directory is the source of truth for people and team membership |
Securing the Bitbucket credentials and the scaffolder
Bitbucket access in Backstage has two directions: the catalog reads repositories, and the scaffolder writes new ones. The controls below keep both narrow, and they tie sign-in and identity mapping to the same portal boundary that the Backstage authentication guidance describes.
Use read-only, scoped credentials
Give the catalog module a Bitbucket credential that can only read the repositories it needs to discover. Keep discovery credentials separate from the credentials the scaffolder uses to create repositories, so a leaked read token cannot write code. Confirm with your Bitbucket administrator which token type your Cloud or Server version supports for read-only access, and record the owning service account, its scopes and its expiry date.
Store tokens in secrets
Reference Bitbucket tokens through environment variables or your secret manager rather than writing them into app-config.yaml or the Git repository that holds it. Backstage reads these values at startup, so rotation means updating the secret and restarting the backend. Check that the backend logs and the frontend configuration never echo the token, and that your deployment pipeline masks it.
Limit discovery to approved projects
Point the Bitbucket catalog provider at specific projects and repository patterns instead of the whole workspace or server. Each catalog file that is discovered becomes a published entity, so an overly broad filter can register repositories that teams never meant to expose in the portal. Ask the platform owner to review the filter list whenever a new project is added to Bitbucket, and to document which projects are in scope.
Avoid guest access in production
The Backstage authentication guidance advises against offering guest access in production. Users who sign in through Bitbucket or your central identity provider should resolve to one catalog identity, and that identity should decide what they see. Configure sign-in resolvers so each Bitbucket login maps to the same user entity as the same person in other providers, and test that an unmapped account is refused rather than admitted as a generic user.
Restrict which templates publish where
Scaffolder publish actions create repositories in Bitbucket, so each template should only be allowed to write to the Bitbucket projects its owning team uses. Enforce this with the permission framework and with the Bitbucket permissions on the target projects, and review the template's publish step during authoring. Ask the implementation team to show, in writing, which templates can reach which projects and who approves changes to that mapping.
How to test discovery and publishing before rollout
Test discovery and publishing in a sandbox before any production workspace or project is connected to Backstage. Start with a sandbox Bitbucket Cloud workspace or a test project on Bitbucket Server (Data Center) that mirrors the access model you plan to use in production, including the same project permissions and branch settings. Place one known catalog file, a catalog-info.yaml with a single Component entity, in one test repository. Then configure only the matching catalog module (catalog-backend-module-bitbucket-cloud or catalog-backend-module-bitbucket-server) and the matching integration entry, so a failure points to one component. Confirm the entity appears in the catalog with the expected name, namespace, and spec.owner, and that the owner resolves to an existing user or group. Check relationships such as dependsOn or partOf against the entities you expect to exist, because a missing target usually shows up as an unresolved reference rather than an error in the discovery log. Confirm the owner and relationships on the entity page, not only in the API response.
Next, test the failure path on purpose. Revoke or disable the service credential you plan to use, then trigger a refresh of the same entity and confirm that Backstage reports a read error and does not silently drop the entity or keep stale data as healthy. Restore the credential and confirm that discovery recovers without a restart. Repeat this with a credential that has read access to one project but not another, so you know exactly which repositories a narrowed token can see. Record the error text and the timestamp, because your operations team will need them when a real token expires.
Finally, run a scaffolder publish into a test project using the matching publish module, @backstage/plugin-scaffolder-backend-module-bitbucket-cloud or @backstage/plugin-scaffolder-backend-module-bitbucket-server. Confirm that the new repository lands in the intended project, that the generated catalog-info.yaml is discovered on the next run, and that the repository has the branch and access settings your template promises. Keep the evidence from each step: the configuration version tested, the sandbox identifiers, screenshots or exports of the entity pages, the refresh logs for the good and revoked-credential runs, the publish output, and the name of the person who approved the test. Give the platform team and security team the same package, so they can confirm that the credential scope, the owner mapping, and the publish permissions match what was approved.
Why Bitbucket entities fail to appear in the catalog
This table lists the failures teams hit most often when Bitbucket repositories do not show up in the Backstage catalog or when a scaffolder publish step fails. Read each row by matching the symptom to the likely cause, then apply the fix and confirm the exact error text in your own running environment.
| Failure | Likely cause | Fix |
|---|---|---|
| Repositories never appear after discovery runs | Wrong host or base URL in the Bitbucket integration config, for example a Cloud URL set for a Server instance or a missing context path | Set the host and apiBaseUrl to match the instance type, then confirm the integration matches the Cloud or Server module you installed |
| Discovery finds the project but not the catalog file | Catalog file path in the provider config does not match where the descriptor sits in the repository | Align the catalog path pattern with the real file location, and check the default branch or branch filter the provider reads |
| Repositories missing from a large project | Project or repository filter in the provider config excludes them | Review the project key and repository patterns, widen them temporarily to test, then narrow them again |
| Authentication errors when reading repositories | Credential lacks read permission on the target repositories or projects | Grant the service account read access to the projects in scope, and confirm the token or app password is not expired |
| TLS or certificate errors against self-hosted Server or Data Center | Internal certificate authority is not trusted by the Backstage backend process | Add the internal CA to the backend trust store used by Node.js, then restart and retest; confirm the exact error text in your logs |
| Scaffolder publish step fails to create a repository | Credential lacks write or create permission in the target project or workspace | Grant project-level create and write rights to the publishing identity and verify it with a test publish in a sandbox project |
| Publish succeeds but the catalog entry is absent | Generated repository lacks the catalog descriptor, or discovery has not run since creation | Confirm the template commits the descriptor to the new repository and let the next discovery cycle run before troubleshooting further |
Questions buyers ask before connecting Bitbucket to Backstage
Can our team connect Backstage to Bitbucket without outside help?
Yes, if your team already runs Backstage and has engineers who know its configuration and Bitbucket's access model. The work is configuration plus a few code-level decisions: choosing Cloud or Server modules, creating credentials, deciding which projects and repositories are scanned, and adding publish actions for templates. Teams without a Backstage owner, or without anyone who has worked with the catalog processors before, usually find the first integration takes longer than expected because of how catalog locations are defined and refreshed. Ask yourself whether someone can own the configuration after the first release, since the catalog only stays accurate if the descriptor files are kept current.
What drives the effort of a Bitbucket integration?
Effort rises with the number of Bitbucket projects and repositories you want discovered, how inconsistent your catalog-info files are today, and whether you need both Cloud and Server connected. Sign-in design matters too, because identities from Bitbucket sign-in must resolve to the same users your catalog uses. Template publishing adds work if you want Software Templates to create repositories in Bitbucket, since each publish action needs its own credentials and tests. Ask any partner to list these drivers in the written scope so each one has a stated boundary.
What do we need to provide before the work starts?
You need to provide the Bitbucket credentials the integration will use, network access from the Backstage backend to your Bitbucket endpoint, and a named owner for each catalog file or team that will maintain it. For Bitbucket Server, the Backstage backend must reach your self-hosted server, which often means firewall rules or proxy changes inside your network. For Bitbucket Cloud, outbound access to the Bitbucket service is required. Confirm with your Bitbucket administrators which account type the integration may use and who approves its access scope.
How long does a Bitbucket integration take under a fixed-scope agreement?
Duration is set in the written scope, not by a general rule. Under a fixed-scope agreement, the timeline follows the agreed list of projects, repositories, sign-in work and publish actions, and the deliverables and dates are confirmed before work starts. Your readiness drives much of the schedule: credentials, network changes and owner reviews of catalog files often take longer than the code itself. Ask for the milestones, the acceptance checks for each one, and which client tasks sit on the critical path.
Does Bitbucket Server need different modules than Bitbucket Cloud?
Yes. Backstage documents separate integrations for Bitbucket Cloud and Bitbucket Server, and the core repository ships separate catalog modules for each: catalog-backend-module-bitbucket-cloud and catalog-backend-module-bitbucket-server. Authentication providers are also separate for each. On the scaffolder side, publish actions come from @backstage/plugin-scaffolder-backend-module-bitbucket-cloud and @backstage/plugin-scaffolder-backend-module-bitbucket-server. Mixing the two in one configuration is a common source of errors, so confirm which deployment you run before choosing modules and credentials.
What happens to the Bitbucket integration when we upgrade Backstage?
Backstage upgrades move all @backstage packages together, typically with yarn backstage-cli versions:bump, and the Backstage Upgrade Helper shows template changes between versions. Your Bitbucket modules are versioned with those packages, so they move with the rest of the portal, but configuration keys and module behavior can change between releases. The release policy also sets a monthly main line and a weekly next line, and high and critical vulnerabilities are backported to releases from the last six months where feasible. Plan a regular upgrade window, test discovery and publish actions in a non-production instance, and confirm your own support horizon with your partner.
Will the catalog stay accurate after the first Bitbucket discovery run?
Only if the catalog-info files have owners who update them when services change. Discovery finds files that exist in the scanned repositories, so repositories without descriptors will not appear, and descriptors that point to retired services will remain until someone removes them. Decide which repositories are in scope, define a minimum descriptor standard, and assign a review path for orphaned entities before the first full run. Ask for the expected ownership model in the written scope so accuracy has a named responsibility.
How DeployOpen works on this
DeployOpen plans, implements, tests, documents and supports self-hosted open-source platforms inside your own infrastructure, so the Backstage Bitbucket integration runs on your accounts and networks. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we scope
- Confirm whether your repositories live in Bitbucket Cloud, Bitbucket Server or Data Center, or both.
- Inventory the workspaces, projects and repositories that should be discovered for catalog files.
- Agree which scaffolder publish actions are in scope and which Bitbucket credentials each will use.
- Record the written scope, deliverables and timeline before any configuration begins.
How we build
- Configure the Bitbucket integration and catalog discovery modules that match your hosting model.
- Set up credentials with least-privilege access, stored in your own secret management.
- Test discovery against sample repositories and confirm catalog entities appear as expected.
- Validate scaffolder publish actions against a test project before enabling them for teams.
How we hand over
- Document the integration configuration, credential ownership and discovery filters for your team.
- Walk your engineers through how catalog files are discovered and how to troubleshoot gaps.
- Provide a runbook for rotating Bitbucket credentials and updating the integration on upgrades.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover.
- Plan Backstage version bumps together with the Bitbucket modules so both move in step.
- Re-check discovery and publish behavior after changes to repositories, projects or access policies.
