Docs

Stash Pull Request

Description

The stash/pullrequest action opens (or updates) a pull request on a self-managed Bitbucket Data Center / Server instance, historically named Stash, once a target linked to the same scm has changed something and the change has been pushed.

It is the second half of the Stash workflow: the stash scm commits to a working branch and pushes it, this action turns that branch into a pull request. Without it, the branch is pushed and nothing else happens.

For repositories on bitbucket.org, use bitbucket/pullrequest instead.

Requirements

An action never runs on its own: it needs an scmid pointing at an scm declared in the same manifest, and that scm must be of the matching kind. Both are checked when the manifest loads:

missing value for parameter(s) ["scmid"]
scm of kind "git" is not compatible with action of kind "github/pullrequest"

The action then reuses that scm rather than being configured twice. From it, it inherits:

FieldInherited value

sourcebranch

The working branch the scm created and pushed - the branch carrying the changes.

targetbranch

The scm’s branch - the branch the pull request is opened against.

owner, repository

The repository the scm points at.

credentials, URL

Whatever the scm was given, when the action does not set its own.

Every one of these can be overridden in the action spec, but there is rarely a good reason to: a mismatch between the branch the scm pushed and the branch the action opens the request from produces a request with no changes in it.

Where the title comes from

The title is resolved from the first of these that is set:

  1. spec.title on the action

  2. title on the action itself, one level above spec

  3. the name of the associated target, when there is exactly one

  4. the pipeline name

The second form is the usual one:

actions:
  default:
    kind: <the action kind>
    scmid: default
    title: 'deps: bump axios version'

Create or update

Updatecli looks for a request already open between the same two branches before creating one, so running the same pipeline repeatedly gives you one long-lived request per pipeline and repository rather than one per run. Whether that existing request is then refreshed with the latest title and description differs by plugin (each page says which).

Creation is also skipped, without failing the pipeline, when either branch is missing from the remote. Updatecli attempts it on every run regardless, so that a request closed by hand or lost to an earlier failure gets reopened on the next one.

Pipeline URL

When Updatecli detects that it runs inside a CI job, it appends a link to that job in the request description. Set disablepipelineurl: true on the action (next to kind and scmid, not inside spec) to leave it out.

Detection is limited to three engines, each recognised by one environment variable: Jenkins (JENKINS_URL), GitLab CI (GITLAB_CI), and GitHub Actions (GITHUB_ACTION), checked in that order. Anywhere else no link is added, whatever this setting says.

The credential comes from the scm’s token. As on the stash scm, the password field is not used (put the HTTP access token in token).

Parameters

NameTypeDescriptionRequired
bodystringBody defines the Bitbucket pullrequest body
ownerstringOwner specifies repository owner
passwordstring

“password” specifies the credential used to authenticate with Bitbucket Server API, it must be combined with “username”

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

repositorystringRepository specifies the name of a repository for a specific owner
sourcebranchstringSourceBranch specifies the pullrequest source branch
targetbranchstringTargetBranch specifies the pullrequest target branch
titlestringTitle defines the Bitbucket pullrequest title.
tokenstring

“token” specifies the credential used to authenticate with Bitbucket Server API

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

urlstring“url” specifies the default stash url in case of Bitbucket Server
usernamestring“username” specifies the username used to authenticate with Bitbucket Server API

The spec is deliberately small - title and body, on top of the identity fields inherited from the scm. Reviewers, labels, and merge automation are not exposed by this plugin.

body

Replaces the description Updatecli generates from the pipeline run.

owner

The Bitbucket Server project key, inherited from the scm.

password

Present in the table but unused, exactly as on the stash scm. Use token.

Updating an existing pull request

When a pull request is already open between the two branches, this plugin leaves it untouched - it does not refresh the title or the description with the latest run, unlike the GitHub, GitLab, Bitbucket Cloud, and Azure DevOps plugins. The report still links to it.

Cleanup

Cleanup is not implemented for this plugin. updatecli apply --clean-git-branches removes working branches that ended up with no changes, but a pull request already opened for one of them is not closed automatically (that stays a manual step).

The same goes for the options this plugin does not expose, such as reviewers and labels. If closing stale pull requests, or anything else missing here, is something you would use, say so on the Updatecli issue tracker (these gaps are unimplemented rather than deliberate, and interest is what gets them prioritised).

Example

# updatecli.yaml
# updatecli diff --config updatecli.yaml
#
name: Show Stash pipeline example

# Sources are responsible to fetch information from third location such as npm registry.
sources:
  updatecli:
    name: Get latest axios version
    kind: npm
    spec:
      name: axios

# Targets are responsible to update targeted files such as a yaml file.
targets:
  npm:
    name: Update e2e test file
    kind: yaml
    sourceid: updatecli
    scmid: stash
    spec:
      file: e2e/updatecli.d/success.d/npm.yaml
      key: conditions.axios.spec.version

### 

# Actions such as stash/pullrequest is triggered if a target is updated.
actions:
  default:
    title: Bump axios version
    kind: stash/pullrequest
    scmid: stash

scms:
  stash:
    kind: stash
    spec:
      owner: "olblak"
      repository: "updatecli"
      branch: main
      # For the change to be apply, we need to specify stash credentials
      #username: stash_username
      #token: stash_token

Links

Last updated on July 30, 2026
Prev
Gitlab Merge Request
Next
Azure DevOps