How to Deploy With a Self-Hosted Runner in Bitbucket Pipelines

Target a step at your own runner with runs-on labels so the deploy runs inside your network, with direct access to private databases and internal hosts.

A self-hosted runner lets a deploy step reach resources that Atlassian-hosted runners cannot, like a private VPC database or an on-prem host. Register the runner with labels, then select it on the deploy step with runs-on.

Steps

• Register a runner in Repository settings to Runners and note its labels.
• Start the runner on a host inside your network.
• Add runs-on: [self.hosted, linux, deploy] to the deploy step.
• The step is picked up only by a matching online runner.

Pipeline

pipelines:
  branches:
    main:
      - step:
          name: Build (hosted)
          script:
            - npm ci && npm run build
          artifacts:
            - dist/**
      - step:
          name: Deploy from private network
          deployment: production
          runs-on:
            - self.hosted
            - linux
            - deploy
          script:
            - ./deploy.sh --internal-db $INTERNAL_DB_HOST dist/

Gotchas

• A step waits (and can time out) if no online runner matches every runs-on label.
• The implicit self.hosted label distinguishes your runners from Atlassian-hosted ones.
• Self-hosted runners are not isolated like hosted ones; secure the host and clean the workspace.

Related guides