How Backstage publishes new repositories to Bitbucket Cloud or Server
A platform team that wants a Backstage template to create a Bitbucket repository, register it in the software catalog and hand the developer a link on success is describing a chain of work that runs in the Backstage backend. The template's steps are scaffolder actions, and a Bitbucket publishing action is one of them. The backend executes that action with a credential it holds, calls Bitbucket, writes the new repository, and then the register step adds a catalog entry that points back to it. Nothing in this chain runs in the browser, so the developer never sees the Bitbucket credential, but the platform team owns every decision about it.
Bitbucket Cloud and Bitbucket Server are different products with different APIs, so Backstage ships separate action modules for each. Choosing the wrong one is an early failure that shows up as a template that cannot authenticate or cannot find the project. Module package names and action IDs change between release lines, so confirm the exact names against the Backstage documentation for the release you run before you write a single step. The scaffolder reference and the release notes for your version are the sources to check, and a dry run against a test workspace will catch a mismatch quickly.
This page covers three decisions that shape every Bitbucket template: which action module and action ID to use for your deployment, where the repository lands (workspace or project, and the repository slug rules that apply there), and which credential the backend holds and what that credential is allowed to do. Ask your Bitbucket administrator which authentication method your site supports for applications and what scopes or permissions it grants, because those answers determine what a template can create and who can be blamed when it fails.
What you need before the first Bitbucket publish run
Five things must be in place before a template can create a Bitbucket repository: a supported Backstage instance, reachable Bitbucket, a dedicated integration account, agreed placement, and a safe place to dry run. Each card is a decision or check to close before the first live run.
Backstage on a supported release line
Run Backstage on a release line that the versioning policy still supports, and confirm which Node.js versions it accepts. Backstage 1.46.0 supports Node.js 22 and 24, so check the release you deploy against that policy before you install the Bitbucket modules. Plan to move to the monthly main release line, since security fixes are backported to recent releases only when feasible.
Reachable Bitbucket endpoint
The Backstage backend, not the browser, calls Bitbucket, so the backend host must reach the Bitbucket Cloud API or your Server or Data Center base URL. Confirm the network path from the backend's runtime environment, including any proxies, egress filters and firewall rules that apply to that workload. Test the call from the same host and network zone that will run the scaffolder.
Dedicated integration account
Create a named service account owned by the platform team for scaffolder writes, not a personal developer login. Decide whether it authenticates with an app password, access token or personal access token, depending on your Bitbucket edition and policy, and confirm which token type your edition supports. Record who owns the credential, where it is stored and when it expires.
Agreed workspace and project keys
Settle the target placement before the first run: the Bitbucket Cloud workspace or the Server or Data Center project key that each template may write to. Agree naming rules for repository slugs and who approves new projects. Changing placement later means changing template defaults and moving repositories, so write the list down before you author the first template.
Test location for dry runs
Provide a sandbox workspace or project where test runs can create throwaway repositories without touching production teams. Use it with dry run mode first, then with a live run that you delete afterward. Keep the integration account's permissions identical between the test and production locations so the test proves what production will do.
TLS trust and network rules
If your self-hosted Bitbucket uses a private or internal certificate authority, add that root certificate to the Backstage backend's trust store and confirm the chain validates from the backend host. Confirm with your network team any outbound rules that apply to the backend, and record the exceptions they approve. A failed certificate check often looks like a generic publish error, so test it before the first run.
Choosing the Bitbucket Cloud or Bitbucket Server action
Bitbucket Cloud is hosted by Atlassian, so your platform team installs the scaffolder action module built for Cloud and the action calls the Atlassian API. Workspaces are the top-level grouping, so the workspace identifier becomes the first placement decision in your template.
- Module: install the Bitbucket Cloud scaffolder action module in the scaffolder backend, using the package name listed in the docs for your Backstage release.
- Reference: call the action by its ID in the
stepslist oftemplate.yaml, taking the ID and its options from the docs for your version. - Parameters: expose the repository name as a form field, and either fix the
workspacevalue in the template or make it a parameter if several workspaces are in use. - Credentials: use the Atlassian credential type your account supports, scoped to the repository permissions the action needs, and store it as a backend secret.
- Placement: confirm how the action assigns new repositories to projects inside a workspace, since Cloud project handling can differ from self-hosted behavior.
Check the Cloud action documentation for your exact release before copying any step, including the auth configuration keys and option names.
Bitbucket Server and Data Center run on infrastructure your organization controls, so the instance URL, TLS trust and token lifecycle are yours to configure. Repositories sit inside projects identified by a project key, which makes the key the main placement parameter for templates that publish here.
- Module: install the Bitbucket Server action module, which targets the self-hosted REST API and is separate from the Cloud module.
- Host configuration: set the base URL of your instance in the backend integrations config, and confirm the backend container trusts your internal certificate authority.
- Parameters: expose the project key and repository slug as form fields, and validate the project key with a pattern so a typo is caught in the form before the run starts.
- Credentials: use a personal access token or service account token limited to creating repositories in the target projects, stored as a backend secret and rotated on your own schedule.
- Versions: confirm which Bitbucket Server or Data Center versions the module documents as supported for your instance.
Confirm the supported Bitbucket versions and integration config keys in the docs for your Backstage release, then test the project key validation with a dry run. The Keeping Backstage updated guide explains how to check module changes during upgrades.
A single template should target one Bitbucket host, because its parameters, credentials and base URL all describe one system. A portal that serves both Bitbucket Cloud and self-hosted Bitbucket registers one action per host, and each action needs a distinct name so template authors choose the right one. Keeping the two hosts separate also keeps the catalog and publishing settings easy to audit.
- One host per template: make each template's publish step call one Bitbucket action, so its parameters and secrets match a single system.
- Distinct names: give each host's action its own identity and document it in the template description, so authors can see which system they are publishing to.
- Separate credentials: store Cloud and Server tokens under separate secret keys, so rotating one set does not change the other.
- Separate integration entries: configure each host with its own base URL in the integrations section, so discovery and publishing settings stay independent.
- Visible target: name the host in template tags or titles so teams can tell which Bitbucket a template creates repositories in.
Before adding a second host, confirm in your Backstage version's docs that both action modules can be registered in the same backend without conflicting.
Placing projects and repositories in Bitbucket
The template decides where a new repository lands, so this is the first control to design. Bitbucket Cloud places repositories inside a workspace and a project, while Bitbucket Server and Data Center place them inside a project key on your own instance. The template parameters that carry the workspace or project, the repository slug, visibility and default branch should map directly to the naming rules your organization already enforces. Write those rules down before the template is built: which slugs are allowed, which prefixes or team codes a project must use, whether repositories are private by default, and which branch name is the default. Then confirm with your Bitbucket administrator that the account running the scaffolder can create repositories in the target workspace or project and that the default branch setting in your instance matches what the template sets. Validate these fields in the template form so an invalid slug fails before any repository is created, not after.
Letting developers pick a project from a list is faster for teams that span several business units, but it moves placement decisions to the requester. Fixing the project in the template keeps every repository in a known location and makes the audit trail simpler, because the template name, its owner and the project all point to one approved path. A middle option is to offer a short, curated list of projects that the template owner maintains, and to restrict who may run templates that create repositories in sensitive projects. Whichever you choose, record the decision in the template documentation. Permissions in Bitbucket follow the workspace or project, so the account the scaffolder uses needs only the rights it needs in each project it can reach. Confirm with your Bitbucket administrator how repository creation events are logged in your edition, because the audit evidence you show later depends on that answer and on the identity recorded for each run.
Credentials for Bitbucket Cloud and Bitbucket Server
Each Bitbucket deployment model accepts a different credential, and the account behind that credential decides what templates can create and where. The cards below cover the choices that connect the publishing action to a secure, auditable setup. Confirm the exact auth mechanism your chosen action module accepts before issuing anything.
Integration account for Bitbucket Cloud
Create a dedicated integration account in your Atlassian organization rather than reusing a developer's login, so repository creation is not tied to one person's employment. Ask Atlassian or your Bitbucket admin which token type the module accepts for Cloud, which scopes it needs to create repositories and manage project placement, and whether the token can be limited to specific workspaces. Test with a sandbox workspace first, because a broad scope on a production workspace is hard to walk back.
Personal access token for Bitbucket Server
For self-hosted Bitbucket, confirm with the Bitbucket administrator whether the action module authenticates with a personal access token, HTTP access token or another mechanism, and which global or project permissions that identity needs. Ask who will be the owner of record for the token, since repositories created by the template will show that account as their creator. Record the token's creation date and its owning team in your secrets inventory so the first renewal is not discovered during an outage.
Separate service user per environment
Use one service user for development or staging and another for production, each with its own credential and permission set. A template run against a test Bitbucket instance should never hold a production write scope, even by accident. Ask your Bitbucket admin whether the instances share a directory or identity provider, because that affects how quickly one account can be disabled without disrupting the other.
Secrets in backend configuration
Store the credential in the Backstage backend secrets configuration, referenced by an environment variable or secret store, and never in template.yaml, skeleton files or the catalog repository. Template authors can then use the action without seeing the token. Confirm with your platform team how the backend loads these values in your deployment, and whether values are masked in task logs for the publishing step.
Rotation ownership and expiry
Name one owner for each Bitbucket credential, along with a backup, and write down the rotation procedure before go-live. Ask Atlassian or your Bitbucket admin for the expiry rules that apply to the token type you chose, and set calendar reminders ahead of that date. Include the rotation step in your incident runbook, because a failed publish caused by an expired token looks like a template bug to most developers.
Configuring the Bitbucket publish step in order
This sequence takes a Backstage instance from a Bitbucket decision to a template that creates repositories in the right project, registers them in the catalog, and shows a working link to the developer. Each step ends with a check you can run before moving on.
Choose the hosting model and action module
Decide whether your repositories live in Bitbucket Cloud or Bitbucket Server or Data Center, because the two use different APIs, authentication methods and host settings. Your platform engineer then installs the matching scaffolder action module into the Backstage backend package, using the module that corresponds to your hosting model. Confirm the exact package names and their supported Backstage versions in the Backstage plugin repositories before you install, since they change over time. Done means the package appears in the backend dependencies and the backend builds without errors.
Register the action module in the scaffolder backend
Add the installed module to the backend entry point so the scaffolder can discover its publish actions when the backend starts. The platform engineer restarts the backend in a development environment and confirms the new Bitbucket actions appear in the actions list served by the scaffolder. If the action does not appear, check the module import order and the backend build output. Done means the action is listed and the backend starts with no registration warnings.
Add the Bitbucket host and credential from a secret
Add the Bitbucket integration block to the backend configuration, naming the host and pointing the credential fields at environment variables that are injected from your secret store, not written into a config file in source control. Use a dedicated service account or app credential with only the repository creation rights your templates need, and confirm the token scopes or app permissions with Atlassian's documentation for your hosting model. Done means the backend reads the integration at startup and a test call with the credential returns the expected workspace or project data.
Define project, repository name and visibility parameters
In the template's parameters section, add fields for the Bitbucket project key, the repository name and the visibility setting, with validation rules that reject empty values and names your Bitbucket instance would refuse. Restrict the project field to a list of allowed projects where possible, so teams cannot create repositories in arbitrary locations. Keep the parameter names aligned with the action input names so the form values pass straight through. Done means the form renders in the Backstage UI and rejects an invalid repository name before any step runs.
Add the publish step
Add a publish step that uses the Bitbucket action for your hosting model, passing the project, repository name and visibility from the parameters and pointing the repository URL at the host from your integration configuration. Include a description and the source skeleton fetch step before it, and confirm the action's input names against its documentation for the version you run. Done means a dry run reports the publish step as completed and the logged repository URL uses the host and project you chose.
Add the catalog registration step
Add a catalog registration step after the publish step that writes a catalog-info.yaml file into the new repository and registers its location with the catalog, so the component appears without a manual import. Set the catalog info path and the registration flag, and make the step depend on the repository URL output of the publish step. Done means a dry run completes registration and the output shows a Location entity reference that points at the new repository file.
Run a dry run against a test project and confirm the output
Run the template in dry-run mode against a Bitbucket test project that your team controls, and read the task log from start to finish, checking each step's output. Then run it without dry-run mode in that test project, confirm the repository exists with the expected visibility, confirm the Location entity appears in the catalog, and confirm the success page shows a link to the repository. Only after these checks should you point the template at a production project. Done means the repository, catalog entry and success link all match what the parameters requested.
Mapping template parameters to Bitbucket fields
This table maps each template parameter to the Bitbucket field it feeds, where the value comes from, and the check it should pass before the action runs. Use it as a review checklist when you write the template, then confirm each field name against the Bitbucket action module release your instance runs, since names change between versions.
| Template parameter | Bitbucket field | Source of the value | Validation rule |
|---|---|---|---|
| Project or workspace key | Project key (Server) or workspace slug (Cloud) | Form field chosen by the developer or fixed by the template | Match the key format Bitbucket accepts and restrict choices to workspaces the team may create in |
| Repository slug | Repository name and slug | Derived from the component name or entered by the developer | Lowercase, hyphen-separated, unique in the target project, and free of characters Bitbucket rejects |
| Visibility | Repository private or public flag | Dropdown with a default set by the template owner | Allow only private by default; restrict public options to approved teams |
| Default branch | Main branch name in repository settings | Template parameter with a fixed default such as main | Must match the branch the initial commit creates and the branch rules applied later |
| Description | Repository description | Free text entered by the developer | Short, single-line text with a maximum length you set in the parameter schema |
| Catalog owner annotation | Written into catalog-info.yaml in the new repository, not a Bitbucket field | Owner entity reference selected from the catalog | Must reference an existing Group or User entity so the component has a valid owner |
| Git author for the initial commit | Commit author name and email in the first commit | Service account or the signed-in user, set in the action input | Use a dedicated automation identity with a real mailbox so commits trace back to the template run |
Securing Bitbucket publishing in production
A template that creates Bitbucket repositories holds write access to your code platform, so the controls around it matter as much as the template itself. The five controls below work together: they limit what the integration can touch, who can trigger it, and what evidence and secrets it leaves behind. Each depends on the sign-in model, so every provider should resolve to one identity and guest access should stay off in production.
Least-privilege integration account
Create a dedicated Bitbucket account or app credential for the scaffolder and grant it write access only to the projects your templates target. Confirm with Bitbucket how its workspace and project permissions map to the scopes your chosen action module needs. Review the grants whenever a new template targets a new project, since a broad grant quietly widens what every template run can do. A compromised scaffolder token should reach only the projects it was built to populate.
Separate development and production credentials
Run development and production Backstage instances with different Bitbucket credentials and different target workspaces or projects. A test template run in development should never be able to create repositories in production projects, even by mistake. Keep the two credential sets in separate secret stores, and confirm that a development instance cannot read production secrets through its configuration. Rotate each set on its own schedule.
Restrict who runs repository templates
Templates that create repositories should not be open to every signed-in user. Limit them to the teams that own those projects, and restrict who can register new Template entities, since a registered template runs with the integration's rights. Follow the Backstage permission framework guidance for templates and actions, and test the restriction with a user outside the allowed group before go-live. Confirm that the sign-in resolver maps each person to one catalog identity so group membership is reliable.
Audit created repositories
Check every repository a template creates against two records: the Bitbucket audit log for the creation event and the Backstage task list for the run that requested it. The task list shows who started the run and which parameters were used, while the Bitbucket log shows the account that made the change. Compare the two regularly, and confirm your Bitbucket plan includes the audit log features you need. A mismatch between them is a signal to investigate the credential or the template.
Keep secrets out of logs and outputs
Scaffolder logs and output parameters are visible to anyone who can view the task, so tokens, app passwords and private keys must never be written into them. Pass credentials only through configured integration settings, and review custom actions for any logging of request headers or raw API responses. Output links should point to the new repository, not carry credentials. Test a sample run and search its task log for token-like strings before publishing the template.
Bitbucket publish failures and how to fix them
This table maps the failures teams most often hit when a Backstage template publishes to Bitbucket Cloud or Bitbucket Server, with the likely cause and a fix for each. Start from the symptom shown in the task log, then check the cause column against your Bitbucket deployment type and credentials. Most failures trace back to credentials, permissions or a mismatch between the dry run and the real target.
| Symptom | Likely cause | Fix |
|---|---|---|
| Publish step fails with 401 or authentication rejected | Token or app password is expired, revoked, or belongs to the wrong Bitbucket host or deployment type | Reissue the credential for the correct deployment, confirm the host in the integration config matches Cloud or Server, and restart the backend to load the new secret |
| Publish step fails with 403 in the target project | The service account can authenticate but lacks create-repository rights in that project or workspace | Grant the service account project-level permission to create repositories, then rerun the task from the task list |
| Publish fails because the repository already exists | The chosen repository slug was used by an earlier run, a manual repo, or a previously deleted repo still in recovery | Change the repository name parameter or remove the stale repository after confirming with its owner, then run again |
| Self-hosted Bitbucket call fails with a certificate or TLS error | The backend does not trust the internal certificate authority that issued the Bitbucket Server certificate | Add the internal CA to the backend trust store in its runtime image, verify the TLS connection from the backend host, and avoid disabling verification |
| Template shows no Bitbucket publish action after an upgrade | The action module was not added to the backend after the upgrade, or the package versions were bumped unevenly | Confirm the Bitbucket scaffolder module is listed in the backend, align all @backstage packages with the version bump, and restart the backend |
| Catalog registration step fails after a template change | The catalog-info file path in the published repository differs from the path the registration step expects | Make the path in the template's skeleton and the register step identical, then test with a throwaway repository in the target project |
| Dry run succeeds but the real run fails | Dry run used a placeholder project, a different workspace, or credentials that differ from the live run | Compare the target project, workspace and credential used in each run, and make the dry-run configuration point at the same placement as production |
Questions teams ask before publishing to Bitbucket from Backstage
How much effort is the Bitbucket publish step compared with the rest of a template?
The publish step is usually one action among several in a template, so it takes a smaller share of build time than the parameter form, the skeleton and the catalog registration. Its effort sits in decisions made before any code is written: which Bitbucket host receives each repository, which project it belongs to, and which credential the action uses. Those choices depend on your Bitbucket administrators, so they often take longer than the code itself. Ask any partner to show how much of the scope is decision work and how much is implementation, and confirm the split against your own templates.
What drives the cost of a Bitbucket publishing engagement?
Cost follows the written scope, and four factors move it most:
- The number of Bitbucket hosts, since Bitbucket Cloud and each self-hosted Bitbucket Server or Data Center instance need their own configuration and testing.
- The number of templates that publish, and how many of them create repositories in several projects.
- The credential model, including how tokens or app credentials are scoped, stored and rotated.
- Custom parameters, custom actions and the testing required before templates reach developers.
DeployOpen does not publish a price list. A quote follows from the written scope, so list each factor explicitly when you request one.
What recurs after go-live for Bitbucket publishing?
Three things recur after go-live. Credentials need rotation on a schedule your security policy sets, and each rotation must be tested against every template that publishes. Backstage itself moves on a monthly main release line and a weekly next release line, so the portal needs periodic upgrades, typically with yarn backstage-cli versions:bump and the Backstage Upgrade Helper. Backstage's versioning policy says high and critical vulnerabilities will always be backported to releases from the last 6 months if feasible, so staying within that window matters. Finally, the Bitbucket action module must be kept compatible with your Backstage version. Ask whether your quote includes these tasks or a separate support retainer.
How long does Bitbucket publishing take, and what does the timeline depend on?
No duration applies until the scope is written, so treat any number you hear before that as a guess. The timeline depends on how many Bitbucket hosts are involved, how many templates publish to them, whether a working Backstage instance and sign-in already exist, and how quickly your Bitbucket administrators can approve projects, service accounts and permissions. A test location that mirrors production also changes the schedule. Ask for the timeline as a list of milestones with the dependencies that each one waits on, and ask which of those dependencies sit with your team.
What must our internal team provide before the engagement starts?
Your team needs to provide the following before work begins:
- Bitbucket administrator access in each Cloud workspace or Server instance, sufficient to create projects, repositories and service credentials.
- Naming standards for projects, repository slugs and default branches, so templates produce consistent output.
- A test workspace or project where templates can publish without touching production repositories.
- Named sign-off owners for each template and for the credential model.
- Access to the running Backstage deployment and its identity provider, so the team can confirm sign-in and catalog registration.
Missing any of these usually delays the work more than the technical build does.
Can our platform team publish to Bitbucket from Backstage without outside help?
A platform team can do this in-house if it already runs Backstage, writes TypeScript, and has Bitbucket administrator access for each host. Backstage's authentication documentation is a useful reference for sign-in resolvers and for avoiding guest access in production, and the upgrade guide covers version changes. The harder parts are scoping credentials narrowly, testing templates without creating live repositories, and keeping the module current through upgrades. Many teams keep the build in-house and bring in a partner for a security review or a fixed-scope rollout. Decide based on who will own the module in two years.
What should we ask for in a written quote for this work?
A useful quote lists what is in and out of scope. Ask for:
- Each Bitbucket host, its deployment type and the templates that publish to it.
- The credential model, who creates each credential, and how rotation is handled.
- The test location and how dry-run testing will be verified before go-live.
- Documentation and handover, including who maintains the action module afterward.
- Acceptance criteria for each template.
- Exclusions such as Backstage upgrades, other Git platforms or retainers.
- The timeline with the dependencies that each milestone waits on.
Fixed-scope agreements make these items easier to compare across quotes.
Which Bitbucket action module do we need for Cloud and for Server?
Choose the module by where the repositories live, not by which team requests them. Cloud and self-hosted Bitbucket instances have different endpoints and credential types, so a template that targets both usually needs one configuration per host. Check the module name, its supported options and its compatibility with your Backstage release in the Backstage documentation and the module's own repository before you write any template steps. Confirm whether your self-hosted instance is reachable from the Backstage backend network, since that affects both the module choice and the test plan.
How DeployOpen scopes and delivers Bitbucket publishing
DeployOpen starts with a written scope that names your Bitbucket deployment type, your project and repository layout, and the credentials the Backstage backend will hold. We then build, test and document the publishing path inside infrastructure you control, and hand it over with the runbooks your team needs to operate it.
How we scope
- Confirm whether you run Bitbucket Cloud or a self-hosted Bitbucket Server or Data Center instance before choosing an action module.
- Map which Bitbucket projects and workspaces new repositories should land in, and who may create them.
- Agree credential types, secret storage and the templates in scope in a written scope before work starts.
How we build
- Configure the Bitbucket integration in the Backstage backend and wire the publishing step into your software templates.
- Test each template with dry runs and review the repository settings, branch defaults and catalog registration it produces.
- Scope tokens or app credentials to the minimum permissions the publishing steps need, and verify them against a test project.
How we hand over
- Document the configuration keys, credential rotation steps and project placement rules your platform team will maintain.
- Walk your engineers through a template run from parameter form to the new repository and catalog entry.
- Provide a written record of what was built, tested and deployed so your team can extend it without us.
How we support
- Engagements are fixed-scope, and any changes to templates or Bitbucket settings are agreed in writing before work begins.
- Ongoing support, upgrades and continuous testing are available as a retainer that covers Backstage and Bitbucket changes.
- Confirm with your Bitbucket administrators which API and token behaviors apply to your deployment before scoping support hours.
