Skip to content
forgit api docs

Update the branching model config for a repository

PUT
/repositories/{workspace}/{repo_slug}/branching-model/settings

Update the branching model configuration for a repository.

The development branch can be configured to a specific branch or to track the main branch. When set to a specific branch it must currently exist. Only the passed properties will be updated. The properties not passed will be left unchanged. A request without a development property will leave the development branch unchanged.

It is possible for the development branch to be invalid. This happens when it points at a specific branch that has been deleted. This is indicated in the is_valid field for the branch. It is not possible to update the settings for development if that would leave the branch in an invalid state. Such a request will be rejected.

The production branch can be a specific branch, the main branch or disabled. When set to a specific branch it must currently exist. The enabled property can be used to enable (true) or disable (false) it. Only the passed properties will be updated. The properties not passed will be left unchanged. A request without a production property will leave the production branch unchanged.

It is possible for the production branch to be invalid. This happens when it points at a specific branch that has been deleted. This is indicated in the is_valid field for the branch. A request that would leave production enabled and invalid will be rejected. It is possible to update production and make it invalid if it would also be left disabled.

The branch_types property contains the branch types to be updated. Only the branch types passed will be updated. All updates will be rejected if it would leave the branching model in an invalid state. For branch types this means that:

  1. The prefixes for all enabled branch types are valid. For example, it is not possible to use ‘*’ inside a Git prefix.
  2. A prefix of an enabled branch type must not be a prefix of another enabled branch type. This is to ensure that a branch can be easily classified by its prefix unambiguously.

It is possible to store an invalid prefix if that branch type would be left disabled. Only the passed properties will be updated. The properties not passed will be left unchanged. Each branch type must have a kind property to identify it.

The default_branch_deletion property is a string. The value of true indicates to delete branches by default. The value of false indicates that branches will not be deleted by default. A request without a default_branch_deletion property will leave it unchanged. Other values would be ignored.

There is currently a side effect when using this API endpoint. If the repository is inheriting branching model settings from its project, updating the branching model for this repository will disable the project setting inheritance.

We have deprecated this side effect and will remove it on 1 August 2022.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
repo_slug
required
string

This can either be the repository slug or the UUID of the repository, surrounded by curly-braces, for example: {repository UUID}.

workspace
required
string

This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: {workspace UUID}.

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

The updated branching model configuration

Media type application/json
object
type
required
string
links
object
self
Link

A link to a resource related to this object.

object
href
string format: uri
name
string
branch_types
Array<object>
0 <= 4 items unique items
object
enabled

Whether the branch type is enabled or not. A disabled branch type may contain an invalid prefix.

boolean
kind
required

The kind of the branch type.

string
Allowed values: feature bugfix release hotfix
prefix

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.

string
development
object
is_valid

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.

boolean
name

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.

string
use_mainbranch

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.

boolean
production
object
is_valid

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.

boolean
name

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.

string
use_mainbranch

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.

boolean
enabled

Indicates if branch is enabled or not.

boolean
Examples
Example response 
{
  "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

Section titled “ 400 ”

If the request contains invalid branching model configuration

Media type application/json
Error

Base type for most resource objects. It defines the common type element that identifies an object’s type. It also identifies the element as Swagger’s discriminator.

object
type
required
string
error
object
message
required
string
detail
string
data

Optional structured data that is endpoint-specific.

object
key
additional properties
any
key
additional properties
any
Example generated 
{
  "type": "example",
  "error": {
    "message": "example",
    "detail": "example",
    "data": {}
  }
}

401

Section titled “ 401 ”

If the request was not authenticated

Media type application/json
Error

Base type for most resource objects. It defines the common type element that identifies an object’s type. It also identifies the element as Swagger’s discriminator.

object
type
required
string
error
object
message
required
string
detail
string
data

Optional structured data that is endpoint-specific.

object
key
additional properties
any
key
additional properties
any
Example generated 
{
  "type": "example",
  "error": {
    "message": "example",
    "detail": "example",
    "data": {}
  }
}

403

Section titled “ 403 ”

If the authenticated user does not have admin access to the repository

Media type application/json
Error

Base type for most resource objects. It defines the common type element that identifies an object’s type. It also identifies the element as Swagger’s discriminator.

object
type
required
string
error
object
message
required
string
detail
string
data

Optional structured data that is endpoint-specific.

object
key
additional properties
any
key
additional properties
any
Example generated 
{
  "type": "example",
  "error": {
    "message": "example",
    "detail": "example",
    "data": {}
  }
}

404

Section titled “ 404 ”

If the repository does not exist

Media type application/json
Error

Base type for most resource objects. It defines the common type element that identifies an object’s type. It also identifies the element as Swagger’s discriminator.

object
type
required
string
error
object
message
required
string
detail
string
data

Optional structured data that is endpoint-specific.

object
key
additional properties
any
key
additional properties
any
Example generated 
{
  "type": "example",
  "error": {
    "message": "example",
    "detail": "example",
    "data": {}
  }
}