How to Run a Step in a Specific Container Image in Bitbucket Pipelines

The image: keyword sets the Docker image a step runs in, globally or overridden per step.

Set a top-level image: for the default, and override it on any step: that needs a different one. For private images, use the object form with username/password.

Global image with a per-step override

The pipeline defaults to node:20; the lint step overrides to a custom private image.

image: node:20

pipelines:
  default:
    - step:
        name: Test
        script:
          - npm ci && npm test
    - step:
        name: Lint
        image:
          name: myregistry.example.com/ci-lint:1
          username: $REGISTRY_USER
          password: $REGISTRY_PASSWORD
        script:
          - npm run lint

Gotchas

• A step-level image: overrides the global one only for that step.
• For a private image, use the object form with username/password from repository variables - a bare image string cannot authenticate.
• The image must have a shell (/bin/sh); a scratch/distroless image cannot run the step script.

Related guides