Skip to content
forgit api docs

Update the branching model config for a project

PUT
/workspaces/{workspace}/projects/{project_key}/branching-model/settings

Update the branching model configuration for a project.

The development branch can be configured to a specific branch or to track the main branch. Any branch name can be supplied, but will only successfully be applied to a repository via inheritance if that branch exists for that repository. 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.

The production branch can be a specific branch, the main branch or disabled. Any branch name can be supplied, but will only successfully be applied to a repository via inheritance if that branch exists for that repository. 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.

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.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
project_key
required
string

The project in question. This is the actual key assigned to the project.

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": "false"
}

400

Section titled “ 400 ”

If the request contains an 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 project

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 project 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": {}
  }
}