How to Set a Custom Docker Image in Bitbucket Pipelines

The image: key chooses the Docker image your steps run in - set it globally or override it per step.

Set a top-level image: as the default and override it on individual steps. For private registries, supply credentials in the image object.

Global default with a per-step override

Most steps use node:20; the deploy step uses a different image.

image: node:20
pipelines:
  default:
    - step:
        name: Test
        script: [npm ci, npm test]
    - step:
        name: Deploy
        image:
          name: my-registry.example.com/deployer:1.2
          username: ${REGISTRY_USER}
          password: ${REGISTRY_PASS}
        script:
          - ./deploy.sh

Gotchas

• Use a tagged image (node:20), never latest, so builds are reproducible.
• Private images take an object with name, username, and password (use Secured variables).
• The image must include the tools your scripts call; otherwise add an install step.

Related guides