The branching model resource is used to modify the branching model for a repository. You can use the branching model to define a branch based workflow for your repositories. When you map your workflow to branch types, you can ensure that branches are named consistently by configuring which branch types to make available.
swagger: '2.0'
info:
title: Bitbucket Addon Branching model API
description: Code against the Bitbucket API to automate simple tasks, embed Bitbucket data into your own site, build mobile or desktop apps, or even add custom UI add-ons into Bitbucket itself using the Connect framework.
version: '2.0'
termsOfService: https://www.atlassian.com/legal/customer-agreement
contact:
name: Bitbucket Support
url: https://support.atlassian.com/bitbucket-cloud/
email: support@bitbucket.org
host: api.bitbucket.org
basePath: /2.0
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: Branching model
description: 'The branching model resource is used to modify the branching model
for a repository.
You can use the branching model to define a branch based workflow
for your repositories. When you map your workflow to branch types,
you can ensure that branches are named consistently by configuring
which branch types to make available.
'
paths:
/repositories/{workspace}/{repo_slug}/branching-model:
parameters:
- name: repo_slug
in: path
description: 'This can either be the repository slug or the UUID of the repository,
surrounded by curly-braces, for example: `{repository UUID}`.
'
required: true
type: string
- name: workspace
in: path
description: 'This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
'
required: true
type: string
get:
tags:
- Branching model
description: "Return the branching model as applied to the repository. This view is\nread-only. The branching model settings can be changed using the\n[settings](#api-repositories-workspace-repo-slug-branching-model-settings-get) API.\n\nThe returned object:\n\n1. Always has a `development` property. `development.branch` contains\n the actual repository branch object that is considered to be the\n `development` branch. `development.branch` will not be present\n if it does not exist.\n2. Might have a `production` property. `production` will not\n be present when `production` is disabled.\n `production.branch` contains the actual branch object that is\n considered to be the `production` branch. `production.branch` will\n not be present if it does not exist.\n3. Always has a `branch_types` array which contains all enabled branch\n types."
summary: Get the branching model for a repository
responses:
'200':
description: The branching model object
schema:
$ref: '#/definitions/branching_model'
examples:
application/json:
development:
name: master
branch:
type: branch
name: master
target:
hash: 16dffcb0de1b22e249db6799532074cf32efe80f
use_mainbranch: true
production:
name: production
branch:
type: branch
name: production
target:
hash: 16dffcb0de1b22e249db6799532074cf32efe80f
use_mainbranch: false
branch_types:
- kind: release
prefix: release/
- kind: hotfix
prefix: hotfix/
- kind: feature
prefix: feature/
- kind: bugfix
prefix: bugfix/
type: branching_model
links:
self:
href: https://api.bitbucket.org/.../branching-model
'401':
description: If the request was not authenticated
schema:
$ref: '#/definitions/error'
'403':
description: If the authenticated user does not have read access to the repository
schema:
$ref: '#/definitions/error'
'404':
description: If the repository does not exist
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- repository
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:repository:bitbucket
x-atlassian-auth-types:
- forge-oauth2
- api-token
/repositories/{workspace}/{repo_slug}/branching-model/settings:
parameters:
- name: repo_slug
in: path
description: 'This can either be the repository slug or the UUID of the repository,
surrounded by curly-braces, for example: `{repository UUID}`.
'
required: true
type: string
- name: workspace
in: path
description: 'This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
'
required: true
type: string
get:
tags:
- Branching model
description: "Return the branching model configuration for a repository. The returned\nobject:\n\n1. Always has a `development` property for the development branch.\n2. Always a `production` property for the production branch. The\n production branch can be disabled.\n3. The `branch_types` contains all the branch types.\n4. `default_branch_deletion` indicates whether branches will be\n deleted by default on merge.\n\nThis is the raw configuration for the branching model. A client\nwishing to see the branching model with its actual current branches may\nfind the [active model API](/cloud/bitbucket/rest/api-group-branching-model/#api-repositories-workspace-repo-slug-branching-model-get) more useful."
summary: Get the branching model config for a repository
responses:
'200':
description: The branching model configuration
schema:
$ref: '#/definitions/branching_model_settings'
examples:
application/json:
development:
is_valid: true
name: 'null'
use_mainbranch: true
production:
is_valid: true
name: production
use_mainbranch: false
enabled: false
branch_types:
- kind: release
enabled: true
prefix: release/
- kind: hotfix
enabled: true
prefix: hotfix/
- kind: feature
enabled: true
prefix: feature/
- kind: bugfix
enabled: false
prefix: bugfix/
type: branching_model_settings
links:
self:
href: https://api.bitbucket.org/.../branching-model/settings
default_branch_deletion: 'false'
'401':
description: If the request was not authenticated
schema:
$ref: '#/definitions/error'
'403':
description: If the authenticated user does not have admin access to the repository
schema:
$ref: '#/definitions/error'
'404':
description: If the repository does not exist
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- repository:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:repository:bitbucket
x-atlassian-auth-types:
- forge-oauth2
- api-token
put:
tags:
- Branching model
description: "Update the branching model configuration for a repository.\n\nThe `development` branch can be configured to a specific branch or to\ntrack the main branch. When set to a specific branch it must\ncurrently exist. Only the passed properties will be updated. The\nproperties not passed will be left unchanged. A request without a\n`development` property will leave the development branch unchanged.\n\nIt is possible for the `development` branch to be invalid. This\nhappens when it points at a specific branch that has been\ndeleted. This is indicated in the `is_valid` field for the branch. It is\nnot possible to update the settings for `development` if that\nwould leave the branch in an invalid state. Such a request will be\nrejected.\n\nThe `production` branch can be a specific branch, the main\nbranch or disabled. When set to a specific branch it must currently\nexist. The `enabled` property can be used to enable (`true`) or\ndisable (`false`) it. Only the passed properties will be updated. The\nproperties not passed will be left unchanged. A request without a\n`production` property will leave the production branch unchanged.\n\nIt is possible for the `production` branch to be invalid. This\nhappens when it points at a specific branch that has been\ndeleted. This is indicated in the `is_valid` field for the branch. A\nrequest that would leave `production` enabled and invalid will be\nrejected. It is possible to update `production` and make it invalid if\nit would also be left disabled.\n\nThe `branch_types` property contains the branch types to be updated.\nOnly the branch types passed will be updated. All updates will be\nrejected if it would leave the branching model in an invalid state.\nFor branch types this means that:\n\n1. The prefixes for all enabled branch types are valid. For example,\n it is not possible to use '*' inside a Git prefix.\n2. A prefix of an enabled branch type must not be a prefix of another\n enabled branch type. This is to ensure that a branch can be easily\n classified by its prefix unambiguously.\n\nIt is possible to store an invalid prefix if that branch type would be\nleft disabled. Only the passed properties will be updated. The\nproperties not passed will be left unchanged. Each branch type must\nhave a `kind` property to identify it.\n\nThe `default_branch_deletion` property is a string. The value of `true`\nindicates to delete branches by default. The value of `false` indicates\nthat branches will not be deleted by default. A request without a\n`default_branch_deletion` property will leave it unchanged. Other values\nwould be ignored.\n\nThere is currently a side effect when using this API endpoint. If the\nrepository is inheriting branching model settings from its project,\nupdating the branching model for this repository will disable the\nproject setting inheritance.\n\n\nWe have deprecated this side effect and will remove it on 1 August 2022."
summary: Update the branching model config for a repository
responses:
'200':
description: The updated branching model configuration
schema:
$ref: '#/definitions/branching_model_settings'
examples:
application/json:
development:
use_mainbranch: true
production:
enabled: true
use_mainbranch: false
name: production
branch_types:
- kind: bugfix
enabled: true
prefix: bugfix/
- kind: feature
enabled: true
prefix: feature/
- kind: hotfix
prefix: hotfix/
- kind: release
enabled: false
default_branch_deletion: 'true'
'400':
description: If the request contains invalid branching model configuration
schema:
$ref: '#/definitions/error'
'401':
description: If the request was not authenticated
schema:
$ref: '#/definitions/error'
'403':
description: If the authenticated user does not have admin access to the repository
schema:
$ref: '#/definitions/error'
'404':
description: If the repository does not exist
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- repository:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:repository:bitbucket
x-atlassian-auth-types:
- forge-oauth2
- api-token
/repositories/{workspace}/{repo_slug}/effective-branching-model:
parameters:
- name: repo_slug
in: path
description: 'This can either be the repository slug or the UUID of the repository,
surrounded by curly-braces, for example: `{repository UUID}`.
'
required: true
type: string
- name: workspace
in: path
description: 'This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
'
required: true
type: string
get:
tags:
- Branching model
description: ''
summary: Get the effective, or currently applied, branching model for a repository
responses:
'200':
description: The effective branching model object
schema:
$ref: '#/definitions/effective_repo_branching_model'
'401':
description: If the request was not authenticated
schema:
$ref: '#/definitions/error'
'403':
description: If the authenticated user does not have read access to the repository
schema:
$ref: '#/definitions/error'
'404':
description: If the repository does not exist
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- repository
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:repository:bitbucket
x-atlassian-auth-types:
- forge-oauth2
- api-token
/workspaces/{workspace}/projects/{project_key}/branching-model:
parameters:
- name: project_key
in: path
description: 'The project in question. This is the actual `key` assigned
to the project.
'
required: true
type: string
- name: workspace
in: path
description: 'This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
'
required: true
type: string
get:
tags:
- Branching model
description: "Return the branching model set at the project level. This view is\nread-only. The branching model settings can be changed using the\n[settings](#api-workspaces-workspace-projects-project-key-branching-model-settings-get)\nAPI.\n\nThe returned object:\n\n1. Always has a `development` property. `development.name` is\n the user-specified branch that can be inherited by an individual repository's\n branching model.\n2. Might have a `production` property. `production` will not\n be present when `production` is disabled.\n `production.name` is the user-specified branch that can be\n inherited by an individual repository's branching model.\n3. Always has a `branch_types` array which contains all enabled branch\n types."
summary: Get the branching model for a project
responses:
'200':
description: The branching model object
schema:
$ref: '#/definitions/project_branching_model'
examples:
application/json:
development:
name: master
use_mainbranch: true
production:
name: production
use_mainbranch: false
branch_types:
- kind: release
prefix: release/
- kind: hotfix
prefix: hotfix/
- kind: feature
prefix: feature/
- kind: bugfix
prefix: bugfix/
type: project_branching_model
links:
self:
href: https://api.bitbucket.org/.../branching-model
'401':
description: If the request was not authenticated
schema:
$ref: '#/definitions/error'
'403':
description: If the authenticated user does not have read access to the project
schema:
$ref: '#/definitions/error'
'404':
description: If the project does not exist
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- project:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:repository:bitbucket
x-atlassian-auth-types:
- forge-oauth2
- api-token
/workspaces/{workspace}/projects/{project_key}/branching-model/settings:
parameters:
- name: project_key
in: path
description: 'The project in question. This is the actual `key` assigned
to the project.
'
required: true
type: string
- name: workspace
in: path
description: 'This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
'
required: true
type: string
get:
tags:
- Branching model
description: "Return the branching model configuration for a project. The returned\nobject:\n\n1. Always has a `development` property for the development branch.\n2. Always a `production` property for the production branch. The\n production branch can be disabled.\n3. The `branch_types` contains all the branch types.\n4. `default_branch_deletion` indicates whether branches will be\n deleted by default on merge.\n\n\nThis is the raw configuration for the branching model. A client\nwishing to see the branching model with its actual current branches may find the\n[active model API](#api-workspaces-workspace-projects-project-key-branching-model-get)\nmore useful."
summary: Get the branching model config for a project
responses:
'200':
description: The branching model configuration
schema:
$ref: '#/definitions/branching_model_settings'
examples:
application/json:
development:
name: 'null'
use_mainbranch: true
production:
name: production
use_mainbranch: false
enabled: false
branch_types:
- kind: release
enabled: true
prefix: release/
- kind: hotfix
enabled: true
prefix: hotfix/
- kind: feature
enabled: true
prefix: feature/
- kind: bugfix
enabled: false
prefix: bugfix/
type: branching_model_settings
links:
self:
href: https://api.bitbucket.org/.../branching-model/settings
default_branch_deletion: 'false'
'401':
description: If the request was not authenticated
schema:
$ref: '#/definitions/error'
'403':
description: If the authenticated user does not have admin access to the project
schema:
$ref: '#/definitions/error'
'404':
description: If the project does not exist
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- project:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:project:bitbucket
x-atlassian-auth-types:
- forge-oauth2
- api-token
put:
tags:
- Branching model
description: "Update the branching model configuration for a project.\n\nThe `development` branch can be configured to a specific branch or to\ntrack the main branch. Any branch name can be supplied, but will only\nsuccessfully be applied to a repository via inheritance if that branch\nexists for that repository. Only the passed properties will be updated. The\nproperties not passed will be left unchanged. A request without a\n`development` property will leave the development branch unchanged.\n\nThe `production` branch can be a specific branch, the main\nbranch or disabled. Any branch name can be supplied, but will only\nsuccessfully be applied to a repository via inheritance if that branch\nexists for that repository. The `enabled` property can be used to enable (`true`)\nor disable (`false`) it. Only the passed properties will be updated. The\nproperties not passed will be left unchanged. A request without a\n`production` property will leave the production branch unchanged.\n\nThe `branch_types` property contains the branch types to be updated.\nOnly the branch types passed will be updated. All updates will be\nrejected if it would leave the branching model in an invalid state.\nFor branch types this means that:\n\n1. The prefixes for all enabled branch types are valid. For example,\n it is not possible to use '*' inside a Git prefix.\n2. A prefix of an enabled branch type must not be a prefix of another\n enabled branch type. This is to ensure that a branch can be easily\n classified by its prefix unambiguously.\n\nIt is possible to store an invalid prefix if that branch type would be\nleft disabled. Only the passed properties will be updated. The\nproperties not passed will be left unchanged. Each branch type must\nhave a `kind` property to identify it.\n\nThe `default_branch_deletion` property is a string. The value of `true`\nindicates to delete branches by default. The value of `false` indicates\nthat branches will not be deleted by default. A request without a\n`default_branch_deletion` property will leave it unchanged. Other values\nwould be ignored."
summary: Update the branching model config for a project
responses:
'200':
description: The updated branching model configuration
schema:
$ref: '#/definitions/branching_model_settings'
examples:
application/json:
development:
use_mainbranch: true
production:
enabled: true
use_mainbranch: false
name: production
branch_types:
- kind: bugfix
enabled: true
prefix: bugfix/
- kind: feature
enabled: true
prefix: feature/
- kind: hotfix
prefix: hotfix/
- kind: release
enabled: false
default_branch_deletion: 'false'
'400':
description: If the request contains an invalid branching model configuration
schema:
$ref: '#/definitions/error'
'401':
description: If the request was not authenticated
schema:
$ref: '#/definitions/error'
'403':
description: If the authenticated user does not have admin access to the project
schema:
$ref: '#/definitions/error'
'404':
description: If the project does not exist
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- project:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:project:bitbucket
x-atlassian-auth-types:
- forge-oauth2
- api-token
definitions:
project:
allOf:
- $ref: '#/definitions/object'
- type: object
title: Project
description: "A Bitbucket project.\n Projects are used by teams to organize repositories."
properties:
links:
type: object
properties:
html:
type: object
title: Link
description: A link to a resource related to this object.
properties:
href:
type: string
format: uri
name:
type: string
additionalProperties: false
avatar:
type: object
title: Link
description: A link to a resource related to this object.
properties:
href:
type: string
format: uri
name:
type: string
additionalProperties: false
additionalProperties: false
uuid:
type: string
description: The project's immutable id.
key:
type: string
description: The project's key.
owner:
$ref: '#/definitions/team'
name:
type: string
description: The name of the project.
description:
type: string
is_private:
type: boolean
description: '
Indicates whether the project is publicly accessible, or whether it is
private to the team and consequently only visible to team members.
Note that private projects cannot contain public repositories.'
created_on:
type: string
format: date-time
updated_on:
type: string
format: date-time
has_publicly_visible_repos:
type: boolean
description: '
Indicates whether the project contains publicly visible repositories.
Note that private projects cannot contain public repositories.'
additionalProperties: true
branching_model_settings:
allOf:
- $ref: '#/definitions/object'
- type: object
title: Branching Model Settings
description: A repository's branching model settings
properties:
links:
type: object
properties:
self:
type: object
title: Link
description: A link to a resource related to this object.
properties:
href:
type: string
format: uri
name:
type: string
additionalProperties: false
additionalProperties: false
branch_types:
type: array
items:
type: object
properties:
enabled:
type: boolean
description: Whether the branch type is enabled or not. A disabled branch type may contain an invalid `prefix`.
kind:
type: string
description: The kind of the branch type.
enum:
- feature
- bugfix
- release
- hotfix
prefix:
type: string
description: The prefix for this branch type. A branch with this prefix will be classified as per `kind`. The `prefix` of an enabled branch type must be a valid branch prefix.Additionally, it cannot be blank, empty or `null`. The `prefix` for a disabled branch type can be empty or invalid.
required:
- kind
additionalProperties: false
minItems: 0
maxItems: 4
uniqueItems: true
development:
type: object
properties:
is_valid:
type: boolean
description: Indicates if the configured branch is valid, that is, if the configured branch actually exists currently. Is always `true` when `use_mainbranch` is `true` (even if the main branch does not exist). This field is read-only. This field is ignored when updating/creating settings.
name:
type: string
description: The configured branch. It must be `null` when `use_mainbranch` is `true`. Otherwise it must be a non-empty value. It is possible for the configured branch to not exist (e.g. it was deleted after the settings are set). In this case `is_valid` will be `false`. The branch must exist when updating/setting the `name` or an error will occur.
use_mainbranch:
type: boolean
description: Indicates if the setting points at an explicit branch (`false`) or tracks the main branch (`true`). When `true` the `name` must be `null` or not provided. When `false` the `name` must contain a non-empty branch name.
additionalProperties: false
production:
type: object
properties:
is_valid:
type: boolean
description: Indicates if the configured branch is valid, that is, if the configured branch actually exists currently. Is always `true` when `use_mainbranch` is `true` (even if the main branch does not exist). This field is read-only. This field is ignored when updating/creating settings.
name:
type: string
description: The configured branch. It must be `null` when `use_mainbranch` is `true`. Otherwise it must be a non-empty value. It is possible for the configured branch to not exist (e.g. it was deleted after the settings are set). In this case `is_valid` will be `false`. The branch must exist when updating/setting the `name` or an error will occur.
use_mainbranch:
type: boolean
description: Indicates if the setting points at an explicit branch (`false`) or tracks the main branch (`true`). When `true` the `name` must be `null` or not provided. When `false` the `name` must contain a non-empty branch name.
enabled:
type: boolean
description: Indicates if branch is enabled or not.
additionalProperties: false
additionalProperties: true
base_commit:
allOf:
- $ref: '#/definitions/object'
- type: object
title: Base Commit
description: The common base type for both repository and snippet commits.
properties:
hash:
type: string
pattern: '[0-9a-f]{7,}?'
date:
type: string
format: date-time
author:
$ref: '#/definitions/author'
committer:
$ref: '#/definitions/committer'
message:
type: string
summary:
type: object
properties:
raw:
type: string
description: The text as it was typed by a user.
markup:
type: string
description: The type of markup language the raw content is to be interpreted in.
enum:
- markdown
- creole
- plaintext
html:
type: string
description: The user's content rendered as HTML.
additionalProperties: false
parents:
type: array
items:
$ref: '#/definitions/base_commit'
minItems: 0
additionalProperties: true
account:
allOf:
- $ref: '#/definitions/object'
- type: object
title: Account
description: An account object.
properties:
links:
$ref: '#/definitions/account_links'
created_on:
type: string
format: date-time
display_name:
type: string
uuid:
type: string
additionalProperties: true
branch:
allOf:
- $ref: '#/definitions/ref'
- type: object
title: Branch
description: A branch object, representing a branch in a repository.
properties:
merge_strategies:
type: array
description: Available merge strategies for pull requests targeting this branch.
items:
type: string
enum:
- merge_commit
- squash
- fast_forward
- squash_fast_forward
- rebase_fast_forward
- rebase_merge
default_merge_strategy:
type: string
description: The default merge strategy for pull requests targeting this branch.
additionalProperties: true
project_branching_model:
allOf:
- $ref: '#
# --- truncated at 32 KB (162 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bitbucket-pipelines/refs/heads/main/openapi/bitbucket-pipelines-branching-model-api-openapi.yml