Bitbucket Cloud · Pipelines · Checked October 31, 2026

Bitbucket Pipelines: "Permission denied to update branch" when the pipeline pushes

A step that pushes back to the repository, to bump a version, write a changelog or push a tag, stops at:

+ git push origin HEAD:master
remote: Permission denied to update branch master.
 ! [remote rejected] HEAD -> master (pre-receive hook declined)
error: failed to push some refs to ...

The branch has branch restrictions, and they do not let this push write to it (Atlassian's article, Pipelines error: remote rejected HEAD -> master (pre-receive hook declined)).

Why it passes for one person and fails for another

Pipelines sets the HTTP origin of the clone for you, so a plain git push works without credentials (Push back to your repository). Atlassian's article on this error says that push is checked against the user who started the pipeline: by pushing a commit, by opening a pull request, or by running it by hand. If that user has write access to the branch in its branch restriction, the push passes; when a teammate without it starts the same pipeline, it fails.

Pipelines itself cannot be added to the restriction. That is asked for in BCLOUD-19136 "Expose bitbucket-pipelines user in Bitbucket branch permissions", open since July 2019, with 258 votes and the status Reviewing.

Since September 15, 2026: push with a repository access token

Bitbucket's changelog of September 15, 2026: branch restrictions now take repository, project and workspace access tokens in Write access and Merge access. The request, BCLOUD-22400 (427 votes), was closed as fixed the same day. Atlassian's article Unable to push to repository - "pre-receive hook declined" error, last updated in September 2025, still says access tokens are not supported.

In the repository: Repository settings, Access tokens under Security, Create access token, with the permission Repositories: Write. A token for a repository reaches only that repository. It is shown once.
Repository settings, Branch restrictions: edit the branch's rule and add the token under Write access.
Repository settings, Repository variables under Pipelines: a variable PUSH_URL, Secured, with the address and the token, the user name being x-token-auth (Using access tokens): https://x-token-auth:<token>@bitbucket.org/<workspace>/<repository>.git
In the step's script:

script:
  - git remote set-url origin "$PUSH_URL"
  - git commit -am "[skip ci] Release ${BITBUCKET_BUILD_NUMBER}"
  - git push origin HEAD:master

Now the push no longer depends on who started the pipeline, and needs no bot account. [skip ci] in the message keeps the new commit from starting the pipeline again, which Atlassian's push-back article recommends against an endless loop.

The older ways: a person's SSH key or API token

Atlassian's push-back article has the push authenticate as someone on the restriction list:

SSH key pair managed by Pipelines: Repository settings, SSH Keys under Pipelines, Generate keys; add the public key to that person's Personal Bitbucket settings, SSH Keys; in the script, git remote set-url origin ${BITBUCKET_GIT_SSH_ORIGIN}.
API token of that person with the scopes read:repository:bitbucket and write:repository:bitbucket, in a secured variable, in the remote URL with their Bitbucket username.
OAuth consumer credentials cannot push to branches that have branch restrictions.

The article warns that credentials set up for an account cannot be limited to some repositories. Atlassian's article on this error says the same of the personal key, and does not recommend it. A key added to the workspace instead of a person's own SSH keys is refused too: move it to the person's settings (the "pre-receive hook declined" article).

The same rejection for other reasons

Force push or rebase: the rule must also allow Allow rewriting branch history.
Signed commits required (Premium): with Require all commits to have a verified signature under Repository details, Advanced, a commit the pipeline makes without a signature is rejected.

See the failed push from IntelliJ IDEA

Pipeline Inbox for Bitbucket Pipelines, a plugin by Lesstep for JetBrains IDEs 2024.1 or later, lists the pipelines of all your Bitbucket Cloud repositories in an IDE tool window. For a failed pipeline it shows the command the step failed at and that command's last lines, such as the git push and Bitbucket's "Permission denied to update branch". After you change the restriction there is no new commit to push: with Pro, Run again builds the same commit once more from the IDE. The list, steps and logs are free; running, re-running and stopping pipelines are Pro (US$1.50 a month, with a 30-day trial).

Get it on JetBrains Marketplace

Atlassian, Bitbucket and Bitbucket Pipelines are trademarks of Atlassian; Git is a trademark of Software Freedom Conservancy; IntelliJ IDEA is a trademark of JetBrains s.r.o. This page is not affiliated with or endorsed by any of them.

More: "pre-receive hook declined" when you push from your own machine · Git submodules are not cloned · "We couldn't clone the repository" · Pipelines did not run after a push · Re-running a failed pipeline · SSH moves to ssh.bitbucket.org · "You have reached your pull rate limit" (Docker Hub) · "There is an error in your bitbucket-pipelines.yml" · "This pipeline was paused" (deployments) · Bitbucket Pipelines plugins for IntelliJ IDEA, compared · 日本語