Caches

Overview

Bitbucket Pipelines enables teams to cache external build dependencies and directories between builds, significantly reducing build times and minimizing resource consumption.

Key Benefits

Speed Improvements - Store dependencies between builds rather than downloading them fresh each time, drastically reducing build duration
Resource Optimization - Eliminate repeated downloads, conserving allocated build minutes
Developer Productivity - Faster pipelines mean quicker feedback and more rapid iteration cycles
Consistency - Ensures that the same versions of dependencies are used across different builds
Cost Efficiency - Optimized builds translate to reduced expenses for teams relying heavily on CI/CD

How Caching Works

Instead of downloading dependencies repeatedly, cache them once for reuse. Most builds start by running commands that download dependencies from the internet, which can take a lot of time for each build.

On first run, dependencies download normally. Subsequent builds retrieve cached versions, improving speed.

Basic Cache Configuration

Add a caches section to your pipeline step:

pipelines:
  default:
    - step:
        caches:
          - node
        script:
          - npm install
          - npm test

Pre-defined Caches

Pipelines provides built-in cache support for popular tools:

Node.js

- step:
    caches:
      - node
    script:
      - npm install

Caches: node_modules/

Composer (PHP)

- step:
    caches:
      - composer
    script:
      - composer install

Caches: ~/.composer/cache

Maven

- step:
    caches:
      - maven
    script:
      - mvn install

Caches: ~/.m2/repository

Gradle

- step:
    caches:
      - gradle
    script:
      - ./gradlew build

Caches: ~/.gradle/caches

pip (Python)

- step:
    caches:
      - pip
    script:
      - pip install -r requirements.txt

Caches: ~/.cache/pip

Docker

- step:
    caches:
      - docker
    services:
      - docker
    script:
      - docker build -t myapp .

Caches: /var/lib/docker

.NET Core

- step:
    caches:
      - dotnetcore
    script:
      - dotnet restore
      - dotnet build

Caches: ~/.nuget/packages

Ivy2

- step:
    caches:
      - ivy2
    script:
      - sbt compile

Caches: ~/.ivy2/cache

Custom Caches

For unsupported tools, define custom caches in the definitions section:

definitions:
  caches:
    npm-global: ~/.npm
    cypress: ~/.cache/Cypress
    gradle-wrapper: ~/.gradle/wrapper
pipelines:
  default:
    - step:
        caches:
          - npm-global
          - cypress
        script:
          - npm install
          - npm run test:e2e

File-Based Cache Keys

Automatically invalidate caches when dependency files change:

definitions:
  caches:
    npm-cache:
      key:
        files:
          - package-lock.json
      path: node_modules
pipelines:
  default:
    - step:
        caches:
          - npm-cache
        script:
          - npm install

When package-lock.json changes, the cache is automatically regenerated.

Multiple Cache Keys

definitions:
  caches:
    node-and-python:
      key:
        files:
          - package-lock.json
          - requirements.txt
      path: ~/.cache
pipelines:
  default:
    - step:
        caches:
          - node-and-python
        script:
          - npm install
          - pip install -r requirements.txt

Multiple Caches

Use multiple caches in a single step:

pipelines:
  default:
    - step:
        caches:
          - node
          - docker
          - composer
        script:
          - npm install
          - composer install
          - docker build -t myapp .

Cache Scope

Caches are shared across:

All branches in the same repository
All pipelines in the same repository
Workspace and repository level

Cache Limitations

Important Constraints

Maximum size: 1 GB once compressed
Retention: Caches expire after 7 days of inactivity
No guarantees: Caches may be cleared at any time
Read-only in parallel steps: Parallel steps can read but not write to caches

Clear Cache

To clear a cache, change the cache key or wait for automatic expiration:

definitions:
  caches:
    npm-v2:  # Changed from npm-v1
      key:
        files:
          - package-lock.json
      path: node_modules

Or clear manually from the Bitbucket UI: Repository Settings → Pipelines → Caches → Clear cache

Best Practices

Cache language dependencies - node_modules, vendor/, .m2/, etc.
Don't cache build outputs - Use artifacts instead
Avoid sensitive data - Never cache passwords or keys
Use file-based keys - Automatically invalidate when dependencies change
Monitor cache effectiveness - Check build times before and after caching
Keep caches under 1GB - Compress or split if needed

Example: Multi-Language Project

image: node:18
definitions:
  caches:
    npm-cache:
      key:
        files:
          - package-lock.json
      path: node_modules
    pip-cache:
      key:
        files:
          - requirements.txt
      path: ~/.cache/pip
pipelines:
  default:
    - step:
        name: Build and Test
        caches:
          - npm-cache
          - pip-cache
        script:
          - npm install
          - pip install -r requirements.txt
          - npm run build
          - python manage.py test

Example: Docker Layer Caching

options:
  docker: true
pipelines:
  default:
    - step:
        name: Build Docker Image
        caches:
          - docker
        services:
          - docker
        script:
          - docker build -t myapp:$BITBUCKET_BUILD_NUMBER .
          - docker push myapp:$BITBUCKET_BUILD_NUMBER

Debugging Cache Issues

If caches aren't working:

Check cache size - Must be under 1GB compressed
Verify path - Ensure the cached path exists after your install command
Check expiration - Caches expire after 7 days
Review logs - Look for cache upload/download messages
Test locally - Verify the path contains what you expect

Next Steps

Learn about Artifacts to share build outputs
Configure Docker Images for faster builds
Set up Service Containers for testing

Was this helpful?

It wasn't accurateIt wasn't clearIt wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community