Bitbucket Cloud

Description

The bitbucket scm plugin clones a repository hosted on Bitbucket Cloud (bitbucket.org) and pushes changes back to it. It is referenced by a resource through its scmid, as described on the "SCM" page.

For a self-hosted Bitbucket Data Center or Server instance, use the stash plugin instead (this one always talks to https://bitbucket.org and has no url parameter).

Its behavior depends on the stage referencing it:

source and condition: The repository is cloned and the resource works on the files from the branch defined by branch. Nothing is pushed.
target: Updatecli creates a working branch based on branch, commits the changes to it, and pushes that branch. The branch value itself is left untouched.

Important

This plugin does not open pull requests. Pushing a working branch and opening a pull request are two distinct steps: the pull request comes from an actions block of kind bitbucket/pullrequest, documented on the "Bitbucket Cloud Pull Request" page. Without such an action, the branch is pushed and nothing else happens.

Parameters

Name	Type	Description
branch	string	“branch” defines the git branch to work on. compatible: scm default: main remark: depending on which resource references the Bitbucket Cloud scm, the behavior will be different. If the scm is linked to a source or a condition (using scmid), the branch will be used to retrieve file(s) from that branch. If the scm is linked to target then Updatecli creates a new “working branch” based on the branch value. The working branch created by Updatecli looks like “updatecli_”. The working branch can be disabled using the “workingBranch” parameter set to false.
commitmessage	object	“commitMessage” is used to generate the final commit message. compatible: scm remark: it’s worth mentioning that the commit message settings is applied to all targets linked to the same scm.
body	string	body defines the commit body of the commit message as defined by the conventional commit specification. More information on -> https://www.conventionalcommits.org/en/ default: none
deprecatedtitle	string	DeprecatedTitle is deprecated and will be ignored. The commit title is now always generated from the target name or description.
footers	string	footers defines the footer of the commit message as defined by the conventional commit specification. More information on -> https://www.conventionalcommits.org/en/ default: none
hidecredit	boolean	hideCredit defines if updatecli credits should be displayed inside commit message body please consider sponsoring the Updatecli project if you want to disable credits. -> https://github.com/updatecli/updatecli default: false
scope	string	scope defines the scope of the commit message as defined by the conventional commit specification. More information on -> https://www.conventionalcommits.org/en/ default: none
squash	boolean	squash defines if the commit should be squashed default: false important: if squash is set to true, then it’s highly recommended to set the commit body to a meaningful value as all other commit information will be lost during the squash operation. if body is not set, then the commit title/message will be generated based on the most recent commit message of the squashed commits. The commit title is always generated from the target name or description.
title	string	Title is the parsed commit message title (not configurable via YAML). The title is automatically generated from the target name or description.
type	string	type defines the type of commit message such as “chore”, “fix”, “feat”, etc. as defined by the conventional commit specification. More information on -> https://www.conventionalcommits.org/en/ default: chore
depth	integer	Depth defines the depth used when cloning the git repository. Default: disabled (full clone) Remark: When using a shallow clone (depth greater than 0), Updatecli is not able to retrieve the full git history. This may cause some issues when Updatecli tries to push changes to the remote repository. In that case, you may need to set the force option to true to force push changes to the remote repository.
directory	string	“directory” defines the local path where the git repository is cloned. compatible: scm remark: Unless you know what you are doing, it is recommended to use the default value. The reason is that Updatecli may automatically clean up the directory after a pipeline execution. default: The default value is based on your local temporary directory like: (on Linux) /tmp/updatecli/bitbucket//
email	string	“email” defines the email used to commit changes. compatible: scm default: default set to your global git configuration
force	boolean	“force” is used during the git push phase to run `git push --force`. compatible: scm default: true remark: When force is set to true, Updatecli also recreate the working branches that diverged from their base branch.
gpg	object	“gpg” specifies the GPG key and passphrased used for commit signing compatible: * scm
passphrase	string	passphrase defines the gpg passphrase used to sign the commit message
signingkey	string	signingKey defines the gpg key used to sign the commit message default: none
owner	string	“owner” defines the owner of a repository. compatible: * scm
password	string	“password” specifies the credential used to authenticate with Bitbucket Cloud API, it must be combined with “username” The “password” should be app password with “pullrequest:write” scope. “token” and “password” are mutually exclusive remark: A password is a sensitive information, it’s recommended to not set this value directly in the configuration file but to use an environment variable or a SOPS file. The value can be set to `{{ requiredEnv "BITBUCKET_PASSWORD"}}` to retrieve the token from the environment variable `BITBUCKET_PASSWORD` or `{{ .bitbucket.password }}` to retrieve the token from a SOPS file. For more information, about a SOPS file, please refer to the following documentation: https://github.com/getsops/sops
repository	string	repository specifies the name of a repository for a specific owner. compatible: * scm
submodules	boolean	“submodules” defines if Updatecli should checkout submodules. compatible: * scm default: true
token	string	“token” specifies the credential used to authenticate with Bitbucket Cloud API The “token” is a repository or project access token with “pullrequest:write” scope. “token” and “password” are mutually exclusive remark: A token is a sensitive information, it’s recommended to not set this value directly in the configuration file but to use an environment variable or a SOPS file. The value can be set to `{{ requiredEnv "BITBUCKET_TOKEN"}}` to retrieve the token from the environment variable `BITBUCKET_TOKEN` or `{{ .bitbucket.token }}` to retrieve the token from a SOPS file. For more information, about a SOPS file, please refer to the following documentation: https://github.com/getsops/sops
user	string	“user” specifies the user associated with new git commit messages created by Updatecli compatible: * scm
username	string	“username” specifies the username used to authenticate with Bitbucket Cloud API
workingbranch	boolean	“workingBranch” defines if Updatecli should use a temporary branch to work on. If set to `true`, Updatecli create a temporary branch to work on, based on the branch value. compatible: * scm default: true
workingbranchprefix	string	WorkingBranchPrefix defines the prefix used to create a working branch. compatible: scm default: updatecli remark: A working branch is composed of three components: WorkingBranchPrefix Target Branch PipelineID If WorkingBranchPrefix is set to ‘’, then the working branch will look like “_”.
workingbranchseparator	string	WorkingBranchSeparator defines the separator used to create a working branch. compatible: scm default: “_”

owner and repository identify the repository, https://bitbucket.org/<owner>/<repository>;.

Note	The table is generated from the Updatecli JSON schema, refreshed by a bot after each release. A recently added parameter (currently `singleBranch`, which restricts clone and fetch to the configured branch) may work in the binary before it appears there.

Authentication

Two mutually exclusive credentials are supported, and token wins when both are given.

token

A repository or project access token, needing the pullrequest:write scope when an action opens pull requests. Updatecli sends it as a bearer token to the API, and for git operations it authenticates as the literal user x-token-auth with the token as password (you do not set username alongside it).

token: '{{ requiredEnv "BITBUCKET_TOKEN" }}'

username + password

An account name together with an app password, again with the pullrequest:write scope for actions. Your real account password will not work.

username: '{{ requiredEnv "BITBUCKET_USER" }}'
password: '{{ requiredEnv "BITBUCKET_APP_PASSWORD" }}'

Reading from a public repository works without any credential; a target always needs write access.

Working branch

For a target, the working branch is derived from three components joined by a separator:

<workingBranchPrefix><workingBranchSeparator><branch><workingBranchSeparator><pipelineID>

With the defaults (updatecli and ), a pipeline based on main produces updatecli_main<pipelineID>, where pipelineID is a hash derived from the manifest - so the same pipeline reuses the same branch instead of piling up new ones. Characters git refuses in a ref are stripped, and the name is truncated to 255 characters. Setting workingBranchPrefix: "" gives <branch>_<pipelineID>.

branch defaults to main, with a warning in the logs when it is left unset.

Disabling the working branch

workingBranch: false makes Updatecli commit and push straight to branch. Since force defaults to true (meaning git push --force), that combination is refused unless force is also set explicitly:

Better safe than sorry.

Updatecli may be pushing unwanted changes to the branch "main".

Set force: false to push without forcing, or force: true to acknowledge the force push. When force is true, Updatecli also recreates working branches that diverged from their base branch.

Tip	`updatecli apply --clean-git-branches` deletes, at the end of a run, the working branches that ended up identical to their base branch (those left behind by pipelines that had nothing to change).

Commit message

Updatecli generates conventional commits. The commitMessage parameters (type, scope, body, footers, hideCredit, squash) shape the result.

The commit title always comes from the target’s name, or from its description when name is unset. It is capped at 72 characters minus the room taken by type and scope; the overflow moves into the body. With the default type chore:

Author: updatecli-bot <updatecli-bot@updatecli.io>
Date:   Tue May 4 15:41:44 2021 +0200

    chore: Update key "dependencies[0].version" from file "charts/jenkins/r...

    ... equirements.yaml"

    Made with ❤️️  by updatecli

Setting body replaces the generated body entirely, including that overflow. hideCredit: true drops the credit line. squash: true collapses the commits of the working branch into one (set body when you use it, since the individual messages are lost).

Warning

commitMessage.title is deprecated and ignored. Rename the target instead; Updatecli logs a warning when the field is present.

Note	`commitMessage` applies to every target linked to the same scm.

Commit signing and identity

gpg.signingkey takes an armored private GPG key and gpg.passphrase its passphrase. Both are secrets:

gpg:
  signingkey: '{{ requiredEnv "GPG_SIGNING_KEY" }}'
  passphrase: '{{ requiredEnv "GPG_PASSPHRASE" }}'

user and email name the commit author, defaulting to updatecli-bot and updatecli-bot@updatecli.io. Set email to an address attached to your Bitbucket account if you want the commits attributed to it.

Clone behavior

Left unset, directory defaults to <tmp>/updatecli/bitbucket/<owner>/<repository> on your system temporary directory. Overriding it is rarely useful, as Updatecli may clean that directory up after a run.

submodules: Defaults to true; set it to false to skip submodule checkout.
depth: Number of commits to fetch. Unset means a full clone. A shallow clone leaves an incomplete history, which can break pushes; force: true is often needed alongside.
singleBranch: Defaults to false, meaning every branch, tag, and ref is fetched. true fetches only branch (much faster on repositories with many refs, at the cost of Updatecli sometimes failing to notice an already published working branch and opening a duplicate pull request).

Example

The manifest below picks whichever credential is available in the environment, thanks to the Go template guards around the two blocks.

# updatecli.yaml
name: "Example with Bitbucket Cloud SCM"
pipelineid: bitbucket/scm

scms:
  bitbucket:
    kind: bitbucket
    spec:
      owner: "updatecli"
      repository: "updatecli"
      branch: main
      # {{ if (env "BITBUCKET_TOKEN") }}
      token: '{{ env "BITBUCKET_TOKEN" }}'
      # {{ else if (and (env "BITBUCKET_USER") (env "BITBUCKET_APP_PASSWORD")) }}
      username: '{{ env "BITBUCKET_USER" }}'
      password: '{{ env "BITBUCKET_APP_PASSWORD" }}'
      # {{ end }}

sources:
  source-1:
    name: "Source 1"
    kind: file
    scmid: bitbucket
    spec:
      file: README.md

conditions:
  condition-1:
    name: "Condition 1"
    kind: file
    scmid: bitbucket
    spec:
      file: README.md

targets:
  target-1:
    name: "Target 1"
    kind: file
    scmid: bitbucket
    spec:
      file: README.md

Last updated on July 30, 2026

Azure DevOps Search

Gitea Pull Request

Docs

Title here

Bitbucket Cloud

Description

Parameters

Authentication

Working branch

Disabling the working branch

Commit message

Commit signing and identity

Clone behavior

Example

Bitbucket Cloud

Description#

Parameters#

Authentication#

Working branch#

Disabling the working branch#

Commit message#

Commit signing and identity#

Clone behavior#

Example#

Description

Parameters

Authentication

Working branch

Disabling the working branch

Commit message

Commit signing and identity

Clone behavior

Example