Fork a repository

POST

/repositories/{workspace}/{repo_slug}/forks

Creates a new fork of the specified repository.

Forking a repository

To create a fork, specify the workspace explicitly as part of the request body:

$ curl -X POST -u jdoe https://api.bitbucket.org/2.0/repositories/atlassian/bbql/forks \
  -H 'Content-Type: application/json' -d '{
    "name": "bbql_fork",
    "workspace": {
      "slug": "atlassian"
    }
}'

To fork a repository into the same workspace, also specify a new name.

When you specify a value for name, it will also affect the slug. The slug is reflected in the repository URL of the new fork. It is derived from name by substituting non-ASCII characters, removes whitespace, and changes characters to lower case. For example, My repo would turn into my_repo.

You need contributor access to create new forks within a workspace.

Change the properties of a new fork

By default the fork inherits most of its properties from the parent. However, since the optional POST body document follows the normal repository JSON schema and you can override the new fork’s properties.

Properties that can be overridden include:

• description
• fork_policy
• language
• mainbranch
• is_private (note that a private repo’s fork_policy might prohibit the creation of public forks, in which is_private=False would fail)
• has_issues (to initialize or disable the new repo’s issue tracker – note that the actual contents of the parent repository’s issue tracker are not copied during forking)
• has_wiki (to initialize or disable the new repo’s wiki – note that the actual contents of the parent repository’s wiki are not copied during forking)
• project (when forking into a private project, the fork’s is_private must be true)

Properties that cannot be modified include:

• scm
• parent
• full_name

Authorizations

• oauth2
  repository:write
• basic
• api_key

Parameters

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}.

Request Body

A repository object. This can be left blank.

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

html

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

pullrequests

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

commits

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

forks

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

watchers

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

downloads

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

clone

Array<object>

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

hooks

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

uuid

The repository’s immutable id. This can be used as a substitute for the slug segment in URLs. Doing this guarantees your URLs will survive renaming of the repository by its owner, or even transfer of the repository to a different user.

string

full_name

The concatenation of the repository owner’s username and the slugified name, e.g. “evzijst/interruptingcow”. This is the same string used in Bitbucket URLs.

string

is_private

boolean

parent

object recursive

scm

string

Allowed values: git

owner

object

type

required

string

links

Account Links

Links related to an Account.

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

key

additional properties

any

created_on

string format: date-time

display_name

string

uuid

string

name

string

description

string

created_on

string format: date-time

updated_on

string format: date-time

size

integer

language

string

has_issues

The issue tracker for this repository is enabled. Issue Tracker features are not supported for repositories in workspaces administered through admin.atlassian.com.

boolean

has_wiki

The wiki for this repository is enabled. Wiki features are not supported for repositories in workspaces administered through admin.atlassian.com.

boolean

fork_policy

Controls the rules for forking this repository.

• allow_forks: unrestricted forking
• no_public_forks: restrict forking to private forks (forks cannot be made public later)
• no_forks: deny all forking

string

Allowed values: allow_forks no_public_forks no_forks

project

object

type

required

string

links

object

html

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

uuid

The project’s immutable id.

string

key

The project’s key.

string

owner

object

type

required

string

links

Account Links

Links related to an Account.

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

key

additional properties

any

created_on

string format: date-time

display_name

string

uuid

string

links

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

self

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

html

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

members

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

projects

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

repositories

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

name

The name of the project.

string

description

string

is_private

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.

boolean

created_on

string format: date-time

updated_on

string format: date-time

has_publicly_visible_repos

Indicates whether the project contains publicly visible repositories. Note that private projects cannot contain public repositories.

boolean

mainbranch

object

type

required

string

links

object

self

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

commits

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

html

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

name

The name of the ref.

string

target

object

type

required

string

hash

string

/[0-9a-f]{7,}?/

date

string format: date-time

author

object

type

required

string

raw

The raw author value from the repository. This may be the only value available if the author does not match a user in Bitbucket.

string

user

object

type

required

string

links

Account Links

Links related to an Account.

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

key

additional properties

any

created_on

string format: date-time

display_name

string

uuid

string

committer

object

type

required

string

raw

The raw committer value from the repository. This may be the only value available if the committer does not match a user in Bitbucket.

string

user

object

type

required

string

links

Account Links

Links related to an Account.

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

key

additional properties

any

created_on

string format: date-time

display_name

string

uuid

string

message

string

summary

object

raw

The text as it was typed by a user.

string

markup

The type of markup language the raw content is to be interpreted in.

string

Allowed values: markdown creole plaintext

html

The user’s content rendered as HTML.

string

parents

Array<object> recursive

repository

object recursive

participants

Array

0

object

type

required

string

user

object

type

required

string

links

Account Links

Links related to an Account.

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

key

additional properties

any

created_on

string format: date-time

display_name

string

uuid

string

role

string

Allowed values: PARTICIPANT REVIEWER

approved

boolean

state

string

Allowed values: approved changes_requested

participated_on

The ISO8601 timestamp of the participant’s action. For approvers, this is the time of their approval. For commenters and pull request reviewers who are not approvers, this is the time they last commented, or null if they have not commented.

string format: date-time

merge_strategies

Available merge strategies for pull requests targeting this branch.

Array<string>

Allowed values: merge_commit squash fast_forward squash_fast_forward rebase_fast_forward rebase_merge

default_merge_strategy

The default merge strategy for pull requests targeting this branch.

string

Responses

201

The newly created fork.

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

html

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

pullrequests

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

commits

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

forks

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

watchers

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

downloads

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

clone

Array<object>

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

hooks

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

uuid

The repository’s immutable id. This can be used as a substitute for the slug segment in URLs. Doing this guarantees your URLs will survive renaming of the repository by its owner, or even transfer of the repository to a different user.

string

full_name

The concatenation of the repository owner’s username and the slugified name, e.g. “evzijst/interruptingcow”. This is the same string used in Bitbucket URLs.

string

is_private

boolean

parent

object recursive

scm

string

Allowed values: git

owner

object

type

required

string

links

Account Links

Links related to an Account.

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

key

additional properties

any

created_on

string format: date-time

display_name

string

uuid

string

name

string

description

string

created_on

string format: date-time

updated_on

string format: date-time

size

integer

language

string

has_issues

The issue tracker for this repository is enabled. Issue Tracker features are not supported for repositories in workspaces administered through admin.atlassian.com.

boolean

has_wiki

The wiki for this repository is enabled. Wiki features are not supported for repositories in workspaces administered through admin.atlassian.com.

boolean

fork_policy

Controls the rules for forking this repository.

• allow_forks: unrestricted forking
• no_public_forks: restrict forking to private forks (forks cannot be made public later)
• no_forks: deny all forking

string

Allowed values: allow_forks no_public_forks no_forks

project

object

type

required

string

links

object

html

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

uuid

The project’s immutable id.

string

key

The project’s key.

string

owner

object

type

required

string

links

Account Links

Links related to an Account.

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

key

additional properties

any

created_on

string format: date-time

display_name

string

uuid

string

links

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

self

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

html

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

members

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

projects

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

repositories

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

name

The name of the project.

string

description

string

is_private

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.

boolean

created_on

string format: date-time

updated_on

string format: date-time

has_publicly_visible_repos

Indicates whether the project contains publicly visible repositories. Note that private projects cannot contain public repositories.

boolean

mainbranch

object

type

required

string

links

object

self

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

commits

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

html

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

name

The name of the ref.

string

target

object

type

required

string

hash

string

/[0-9a-f]{7,}?/

date

string format: date-time

author

object

type

required

string

raw

The raw author value from the repository. This may be the only value available if the author does not match a user in Bitbucket.

string

user

object

type

required

string

links

Account Links

Links related to an Account.

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

key

additional properties

any

created_on

string format: date-time

display_name

string

uuid

string

committer

object

type

required

string

raw

The raw committer value from the repository. This may be the only value available if the committer does not match a user in Bitbucket.

string

user

object

type

required

string

links

Account Links

Links related to an Account.

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

key

additional properties

any

created_on

string format: date-time

display_name

string

uuid

string

message

string

summary

object

raw

The text as it was typed by a user.

string

markup

The type of markup language the raw content is to be interpreted in.

string

Allowed values: markdown creole plaintext

html

The user’s content rendered as HTML.

string

parents

Array<object> recursive

repository

object recursive

participants

Array

0

object

type

required

string

user

object

type

required

string

links

Account Links

Links related to an Account.

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

key

additional properties

any

created_on

string format: date-time

display_name

string

uuid

string

role

string

Allowed values: PARTICIPANT REVIEWER

approved

boolean

state

string

Allowed values: approved changes_requested

participated_on

The ISO8601 timestamp of the participant’s action. For approvers, this is the time of their approval. For commenters and pull request reviewers who are not approvers, this is the time they last commented, or null if they have not commented.

string format: date-time

merge_strategies

Available merge strategies for pull requests targeting this branch.

Array<string>

Allowed values: merge_commit squash fast_forward squash_fast_forward rebase_fast_forward rebase_merge

default_merge_strategy

The default merge strategy for pull requests targeting this branch.

string

Example

{
  "scm": "git",
  "fork_policy": "allow_forks",
  "mainbranch": {
    "target": {
      "summary": {
        "markup": "markdown"
      },
      "participants": [
        {
          "role": "PARTICIPANT",
          "state": "approved"
        }
      ]
    },
    "merge_strategies": [
      "merge_commit"
    ]
  }
}

Headers

Location

string

The URL of the newly created fork