Publish To Bitbucket Cloud

Property	Type	Description
token	string	The token to use for authorization to BitBucket Cloud
repoUrl	string	Repository Location
signCommit	boolean	Sign commit with configured PGP private key
sourcePath	string	Path within the workspace that will be used as the repository root. If omitted, the entire workspace will be published as the repository.
description	string	Repository Description
defaultBranch	string	-
repoVisibility	string	-
gitCommitMessage	string	-

Property	Type	Description
remoteUrl	string	A URL to the repository with the provider
commitHash	string	The git commit hash of the initial commit
repoContentsUrl	string	A URL to the root of the repository

Publish a private service repository to a Bitbucket Cloud workspace

Publishes the generated service to a new private repository in a Bitbucket Cloud workspace. Use this after fetching a template with fetch:template, then register it with catalog:register.

Copy

steps:
  - id: fetch-template
    action: fetch:template
    name: Fetch project template
    input:
      url: ./skeleton
      targetPath: ./
      values:
        name: ${{ parameters.component_id }}
        owner: ${{ parameters.owner }}
        description: ${{ parameters.description }}

  - id: publish-repo
    action: publish:bitbucketCloud
    name: Publish to Bitbucket Cloud
    input:
      repoUrl: bitbucket.org?workspace=acme-ws&repo=${{ parameters.component_id }}
      description: ${{ parameters.description }}
      defaultBranch: main
      repoVisibility: private
      gitCommitMessage: "chore: scaffold ${{ parameters.component_id }}"

  - id: register
    action: catalog:register
    name: Register in Backstage catalog
    input:
      repoContentsUrl: ${{ steps.publish-repo.output.repoContentsUrl }}
      catalogInfoPath: /catalog-info.yaml

Publish only a subdirectory to a new repository

Publishes a specific subdirectory of the workspace as the repository root. Use this when your template creates multiple packages and you want only one to be a separate repo.

Copy

steps:
  - id: fetch-monorepo
    action: fetch:template
    name: Generate monorepo
    input:
      url: ./monorepo-template
      targetPath: ./
      values:
        rootName: ${{ parameters.component_id }}
        generateApi: true
        generateWeb: true

  - id: publish-api
    action: publish:bitbucketCloud
    name: Publish API package
    input:
      repoUrl: bitbucket.org?workspace=acme-ws&repo=${{ parameters.component_id }}-api
      description: "API service for ${{ parameters.component_id }}"
      defaultBranch: main
      repoVisibility: private
      sourcePath: packages/api
      gitCommitMessage: "feat: bootstrap API package from template"

  - id: register-api
    action: catalog:register
    name: Register API in catalog
    input:
      repoContentsUrl: ${{ steps.publish-api.output.repoContentsUrl }}
      catalogInfoPath: /catalog-info.yaml

Publish a public repo with a custom default branch and signed commit

Creates a public repository with a nonstandard default branch and signs the initial commit. Provide a Bitbucket Cloud app password or OAuth token via the action input.

Copy

steps:
  - id: fetch-template
    action: fetch:template
    name: Materialize template
    input:
      url: ./skeleton
      values:
        name: ${{ parameters.component_id }}

  - id: publish-public
    action: publish:bitbucketCloud
    name: Publish public repo with signed commit
    input:
      repoUrl: bitbucket.org?workspace=oss-ws&repo=${{ parameters.component_id }}
      description: "Open source library ${{ parameters.component_id }}"
      defaultBranch: develop
      repoVisibility: public
      gitCommitMessage: "init: open source initial commit"
      signCommit: true
      token: ${{ secrets.bitbucketCloudToken }}

Publish into a specific Bitbucket Cloud project within a workspace

Targets a project within the workspace to group related repositories. Use this when your organization enforces project keys in Bitbucket Cloud.

Copy

steps:
  - id: fetch-template
    action: fetch:template
    name: Fetch service template
    input:
      url: ./service-template
      values:
        name: ${{ parameters.component_id }}
        description: ${{ parameters.description }}

  - id: publish-to-project
    action: publish:bitbucketCloud
    name: Publish to workspace project
    input:
      repoUrl: bitbucket.org?workspace=acme-ws&project=ENG&repo=${{ parameters.component_id }}
      description: ${{ parameters.description }}
      defaultBranch: main
      repoVisibility: private
      gitCommitMessage: "chore: scaffold ${{ parameters.component_id }} in ENG project"

Publish and use outputs for follow-up steps

Publishes the repo and then uses the outputs to log the created repository and commit hash. This is useful for audit or for passing metadata to later steps like catalog:register or other automation.

Copy

steps:
  - id: fetch
    action: fetch:template
    name: Prepare workspace
    input:
      url: ./template
      values:
        name: ${{ parameters.component_id }}

  - id: publish
    action: publish:bitbucketCloud
    name: Publish repository
    input:
      repoUrl: bitbucket.org?workspace=platform-ws&repo=${{ parameters.component_id }}
      description: "Service ${{ parameters.component_id }}"
      defaultBranch: main
      repoVisibility: private
      gitCommitMessage: "build: initial scaffold for ${{ parameters.component_id }}"

  - id: announce
    action: debug:log
    name: Log publish details
    input:
      message: >
        Created repo at ${{ steps.publish.output.remoteUrl }},
        root contents at ${{ steps.publish.output.repoContentsUrl }},
        initial commit ${{ steps.publish.output.commitHash }}

Input Schema

Output Schema

Usage Examples

Publish a private service repository to a Bitbucket Cloud workspace

Publish only a subdirectory to a new repository

Publish a public repo with a custom default branch and signed commit

Publish into a specific Bitbucket Cloud project within a workspace

Publish and use outputs for follow-up steps

Other actions in @backstage/plugin-scaffolder-backend-module-bitbucket-cloud

Publish Bitbucket Pull Request

Create Bitbucket Branch Restrictions

Run Bitbucket Cloud Pipeline