Use a repository runner when only one repository should reach a host, such as one with production network access. Use a workspace runner when many repositories share the same build host. A workspace runner can run builds for any repository in the workspace, so treat everything it runs as sharing one trust level.
The two scopes
Bitbucket's runner setup page says a repository runner is scoped to one repository, and a workspace runner is available to every repository in the workspace. Each repository supports up to 100 runners, and so does each workspace. Repository runners are added under the repository's Settings, Runners, and workspace runners under Workspace settings, Workspace runners. The page does not state which roles can add them, so check your own permissions.
| Question | Repository runner | Workspace runner |
|---|---|---|
| Who can send jobs to it | One repository | Any repository in the workspace |
| Good for | Deploy hosts, sensitive networks | Shared build capacity |
| Main risk | More hosts to maintain | One repository's job can run beside another's |
How a step finds a runner
A step targets self-hosted runners with runs-on. It runs on the next available runner that has all the required labels. Bitbucket says the self.hosted label must be in runs-on, and each runner type needs its platform label such as linux.shell, linux.arm64, windows or macos, or the scheduler treats the step as Linux Docker. Custom labels narrow the choice, up to 10 per runner, lowercase and alphanumeric with dots.
- step:
runs-on:
- self.hosted
- linux
- prod.deploy
script:
- ./deploy.sh
Steps without runs-on run in Atlassian's cloud. If no online runner in your repository has every label, the step fails. If matching runners are busy, it queues. Each step has a 120 minute maximum.
The token and the host
The generated install command contains a token that authenticates the host with Bitbucket, and it displays once. Store it carefully, and if it leaks, delete the runner and create a new one. The Linux Docker command pulls the latest runner image by default, and can be changed to pull a specific version listed in the runner changelog. Pin one, as with any container image in a pipeline.
Steps to choose and secure
- List which repositories need this host. One repository means a repository runner.
- Give deploy runners a distinct label and put that label only on deploy steps.
- Keep production credentials out of the host image and in secured deployment variables or OIDC.
- Rebuild hosts on a schedule, and prefer a fresh host per job where you can. See ephemeral versus persistent runners.
- Wait for the runner to show online before relying on it.
- Restrict who can change
bitbucket-pipelines.yml, since it chooses the runner.
A runner executes code from your repositories on your machine, a point made in self-hosted runners execute strangers' code.
Safeguard's asset discovery can help you find the repositories in play, and you can try a free scan at https://gold.safeguard.sh/scan.
Quick check
What happens if my labels do not match?
The step fails if no online runner has every label. It queues if matching runners are busy.
Can I read the runner token again?
No. The install command shows once, so create a new runner if it is lost.
Sources
- Atlassian: Adding a new runner in Bitbucket, fetched 19 October 2026.
- Atlassian: Configure your runner in bitbucket-pipelines.yml, fetched 19 October 2026.
Last reviewed: 19 October 2026.
