Bitbucket Cloud · Pipelines · Checked November 2, 2026

Bitbucket Pipelines: a variable is empty

Pipelines has several kinds of variables, and each one reaches only some places. When a step prints nothing for a variable, or a command acts as if it were not set, it is usually one of the cases below.

A deployment variable, outside its deployment step

Deployment variables belong to an environment. You set them in Repository settings, Deployments, under the environment, and they override repository and workspace variables with the same name (Atlassian's Set up and monitor deployments). A step gets them by naming that environment in deployment:

pipelines:
  branches:
    main:
      - step:
          deployment: production
          script:
            - echo "API URL: $API_URL"   # production's value

A step without deployment, or with another environment, does not see production's values. Atlassian's Variables and secrets gives the order when names collide: pipeline, then deployment, then repository, then workspace.

A secured variable is hidden, not empty

A secured variable (the padlock) is masked in the log, and so is any output that matches its value. In Atlassian's example, echo "Deploying with key $API_KEY" shows $API_KEY in the log, not the key. To see whether a value arrived without printing it, print its length:

- echo "API_KEY has ${#API_KEY} characters"

A secured variable cannot be edited, only replaced or deleted.

A variable exported in an earlier step

Each step runs in a new container, so export ends with the step. Atlassian's Variable sharing passes a value on: write KEY=VALUE to the file in $BITBUCKET_PIPELINES_VARIABLES_PATH and list the name under output-variables.

- step:
    name: Generate version
    script:
      - export VERSION=$(date +%Y%m%d)-$BITBUCKET_BUILD_NUMBER
      - echo "VERSION=$VERSION" >> $BITBUCKET_PIPELINES_VARIABLES_PATH
    output-variables:
      - VERSION
- step:
    name: Deploy
    script:
      - echo "Deploying $VERSION"

• A name written to the file but not listed under output-variables is not passed on.
• A pipeline can share 50 variables and 100 KB in total.
• The values reach the later steps that run one after another. Atlassian's page says a variable written in a parallel step reaches no other step, neither its siblings nor the steps after the parallel group.

Files go between steps as artifacts.

$VAR outside the script

$VAR is filled in by the shell when a script line runs. In other fields, such as image, a step's name, deployment or a cache path, use ${{VAR}}. Atlassian added it in May 2025 (the announcement), and YAML templating says it is filled in when the pipeline is read, before any step runs.

image: ${{NODE_IMAGE}}     # a repository variable, for example node:20

• It takes non-secured workspace and repository variables, and of the default variables only BITBUCKET_WORKSPACE, BITBUCKET_REPO_SLUG, BITBUCKET_BRANCH, BITBUCKET_COMMIT and BITBUCKET_PR_ID.
• Secured variables, deployment variables and variables shared through output-variables are not available at that point.
• A name it cannot fill in stays in the file as it is, ${{VARIABLE_NAME}}. The page says to check that it is a workspace or repository variable, not secured, and spelled the same, case included.

The exception is the build image's credentials: Atlassian's examples write username: $DOCKER_HUB_USERNAME and password: $DOCKER_HUB_PASSWORD under image.

Names, and default variables that only some builds have

• Names are case-sensitive, use letters, digits and underscores, and cannot start with a digit.
• BITBUCKET_BRANCH is set in branch builds, BITBUCKET_TAG in tag builds and BITBUCKET_PR_ID in pull request builds. A tag build has no branch name. BITBUCKET_PARALLEL_STEP and BITBUCKET_PARALLEL_STEP_COUNT exist only inside a parallel step.
• A variable called PATH replaces the build's own and breaks commands ("command not found").
• The variables of a build together are limited to 120,000 characters ("Step exceeded processing limits").

Bitbucket Pipelines in 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, with their steps, the failed step and the command it stopped at, and the step's log as Bitbucket writes it. 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). Running a custom pipeline gives a field for each variable it declares.

Get it on JetBrains Marketplace

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

More: "Host key verification failed" (SSH) · "Cannot connect to the Docker daemon" · "authorization denied by plugin pipelines" (Docker) · "Container 'docker' exceeded memory limit." · Pipelines did not run after a push · "Container 'Build' exceeded memory limit." · "Exceeded build time limit of 120 minutes" · The cache is not used · "unexpected system error" · "command not found" · Submodules not cloned · "We couldn't clone the repository" · "No online runner available" · "No space left on device" · "Step exceeded processing limits" · The artifact is missing in the next step · The build passed before and fails now · Build setup takes too long · "You've run out of build minutes" · "Permission denied to update branch" · "You have reached your pull rate limit" (Docker Hub) · "There is an error in your bitbucket-pipelines.yml" · "This pipeline was paused" (deployments) · Test results not showing · Bitbucket Pipelines plugins for IntelliJ IDEA, compared · 日本語