---
title: "Create repository runner"
method: POST
path: "/repositories/{workspace}/{repo_slug}/pipelines-config/runners"
tags: ["Pipelines"]
---

# Create repository runner

`POST /repositories/{workspace}/{repo_slug}/pipelines-config/runners`

## Request

- Base URL: `https://api.bitbucket.org/2.0`
- URL: `https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/pipelines-config/runners`
- Auth: one of:
  - OAuth 2
    - Authorization code: `https://bitbucket.org/site/oauth2/authorize`
    - Token URL: `https://bitbucket.org/site/oauth2/access_token` scopes: `runner:write`
  - HTTP basic
  - API key in header `Authorization`

Create repository runner.

## Path parameters

- `workspace` string, required
- `repo_slug` string, required

## Response `200`

The repository runner.

- PipelineRunner: A Bitbucket Pipelines runner for self-hosted builds.
  - `type` string, required
  - `uuid` string: The UUID identifying the runner.
  - `name` string: The name of the runner.
  - `labels` string[]: Labels assigned to the runner for identification and routing.
  - `state` PipelineRunnerState: The state information of a runner.
    - `type` string, required
    - `status` 'UNREGISTERED' | 'ONLINE' | 'OFFLINE' | 'DISABLED' | 'ENABLED' | 'UNHEALTHY': The current status of the runner.
    - `version` PipelineRunnerVersion: Version information for a runner.
      - `type` string, required
      - `version` string: The currently installed version of the runner.
      - `current` string: The current recommended version of the runner.
    - `updated_on` string, date-time: The timestamp when the runner state was last updated.
    - `cordoned` boolean: Whether the runner is cordoned (prevented from accepting new steps).
  - `created_on` string, date-time: The timestamp when the runner was created.
  - `updated_on` string, date-time: The timestamp when the runner was last updated.
  - `oauth_client` PipelineRunnerOauthClient: OAuth client configuration for runner authentication.
    - `type` string, required
    - `id` string: The OAuth client ID.
    - `secret` string: The OAuth client secret. This is an optional element that is only provided once.
    - `token_endpoint` string, uri: The OAuth token endpoint URL.
    - `audience` string: The intended audience for the OAuth token.

## Other responses

- `400`: The request body contained invalid properties or runner limit exceeded.
- `409`: The repository runner with the provided UUID already exists.

## Changes

- **2026-07-13** `d344164ecb11`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/atlassian/apis/bitbucket-api/changes/repositories/:workspace/:repo_slug/pipelines-config/runners/post.md)

---

[API](https://skmtc.dev/atlassian/apis/bitbucket-api.md) - [All operations](https://skmtc.dev/atlassian/apis/bitbucket-api/llms.txt) - [OpenAPI document](https://skmtc.dev/atlassian/apis/bitbucket-api/revisions/6ae783fa75da?raw)