Beanstalk

Repository Resource

Readable attributes

id integer Unique ID.
account_id integer ID of the associated account.
title string Human-readable name.
name string File-system name.
color_label string Name of the specified color label. See a list of available labels below.
default_branch string Branch that is used by default when creating a new clone. Git only.
type string Type of the repository. See a list of available types below.
vcs string Name of a version control system the repoistory is using. See a list of available types below.
repository_url string A URL that can be used to checkout or clone the repository.
last_commit_at datetime Time of the last commit.
public_key string Repository-wide deployment key. Add this key to your server to make all ReleaseServers from this repository to be able to deploy to it.
updated_at datetime Time when the repository was last updated.
created_at datetime Time when the repository was first added to the system.

Writable attributes

title string Required on create.
name string Required on create. Only writable on create and rename. Must be unique in account.
color_label string White by default. See list of available labels below.
default_branch string Git only. “master” by default.
type_id string Type of repository. See a list of available types below.
create_structure boolean Subversion only. Determines if you want to create “trunk”, “branches” and “tags” directories in your new repository. If true, Beanstalk will create those directories for you.

Available repository types

The type_id attribute accepts one of the following values:

  • subversion
  • git

type_id is a write-only attribute, you will never receive it when fetching a repository. Instead there will be a vcs attribute that will contain the same value.

In addition there’s a read-only attribute called type that will contain a repository class name. One of the following:

  • SubversionRepository
  • GitRepository

Available color labels

  • label-white
  • label-pink
  • label-red
  • label-red-orange
  • label-orange
  • label-yellow
  • label-yellow-green
  • label-aqua-green
  • label-green
  • label-green-blue
  • label-sky-blue
  • label-light-blue
  • label-blue
  • label-orchid
  • label-violet
  • label-brown
  • label-black
  • label-grey

Find All Repositories

This method support optional pagination that is disabled by default. Simply pass the page parameter to turn it on.

Optional GET parameters:

  • page (integer) — page number for pagination;
  • per_page (integer) — number of elements per page (default 30, maximum 50).
json http-request
GET /api/repositories.json

Click to expand…

json http-response
[
  {
    "repository": {
      "name": "beanstalk",
      "created_at": "2011/09/23 11:53:46 +0800",
      "title": "beanstalk",
      "storage_used_bytes": 0,
      "default_branch": "master",
      "updated_at": "2011/09/23 11:53:46 +0800",
      "color_label": "label-white",
      "account_id": 2,
      "id": 13,
      "type": "GitRepository",
      "last_commit_at": null,
      "vcs": "git",
      "repository_url": "git@account.beanstalkapp.com:/beanstalk.git",
      "public_key": "ssh-rsa ..."
    }
  }
]
xml http-request
GET /api/repositories.xml

Click to expand…

xml http-response
<?xml version="1.0" encoding="UTF-8"?>
<repositories type="array">
  <repository>
    <account-id type="integer">9247</account-id>
    <anonymous type="boolean">false</anonymous>
    <color-label>label-blue</color-label>
    <created-at type="datetime">
      2007-06-14T22:15:37Z
    </created-at>
    <id type="integer">82346</id>
    <type>SubversionRepository</id>
    <last-commit-at type="datetime">
      2009-11-18T13:21:24Z
    </last-commit-at>
    <name>ProjectAlpha</name>
    <revision type="integer">36</revision>
    <storage-used-bytes type="integer">
      151130112
    </storage-used-bytes>
    <title>Beanstalk</title>
    <updated-at type="datetime">
      2009-11-18T13:21:42Z
    </updated-at>
    <repository-url>https://account.svn.beanstalkapp.com/ProjectAlpha</repository-url>
    <public-key>ssh-rsa ...</public-key>
  </repository>

  <repository>
    <account-id type="integer">7334</account-id>
    <anonymous type="boolean">false</anonymous>
    <color-label>label-</color-label>
    <created-at type="datetime">
      2007-07-23T06:59:15Z
    </created-at>
    <id type="integer">63722</id>
    <type>SubversionRepository</id>
    <last-commit-at type="datetime">
      2007-07-23T08:11:13Z
    </last-commit-at>
    <name>mt</name>
    <revision type="integer">2</revision>
    <storage-used-bytes type="integer">
      180224
    </storage-used-bytes>
    <title>Super Repository</title>
    <updated-at type="datetime">
      2009-08-10T06:05:39Z
    </updated-at>
    <repository-url>https://account.svn.beanstalkapp.com/mt</repository-url>
    <public-key>ssh-rsa ...</public-key>
  </repository>
</repositories>

Find Repository

json http-request
GET /api/repositories/{REPOSITORY_ID}.json

Click to expand…

json http-response
{
  "repository": {
    "name": "beanstalk",
    "created_at": "2011/09/23 11:53:46 +0800",
    "title": "beanstalk",
    "storage_used_bytes": 0,
    "default_branch": "master",
    "updated_at": "2011/09/23 11:53:46 +0800",
    "color_label": "label-white",
    "account_id": 2,
    "id": 13,
    "type": "GitRepository",
    "last_commit_at": null,
    "vcs": "git",
    "repository_url": "git@account.beanstalkapp.com:/beanstalk.git",
    "public_key": "ssh-rsa ..."
  }
}
xml http-request
GET /api/repositories/{REPOSITORY_ID}.xml

Click to expand…

xml http-response
<?xml version="1.0" encoding="UTF-8"?>
<repository>
  <account-id type="integer">9247</account-id>
  <anonymous type="boolean">false</anonymous>
  <color-label>label-blue</color-label>
  <created-at type="datetime">
    2007-06-14T22:15:37Z
  </created-at>
  <id type="integer">82346</id>
  <type>SubversionRepository</id>
  <last-commit-at type="datetime">
    2009-11-18T13:21:24Z
  </last-commit-at>
  <name>ProjectAlpha</name>
  <revision type="integer">36</revision>
  <storage-used-bytes type="integer">
    151130112
  </storage-used-bytes>
  <title>Beanstalk</title>
  <updated-at type="datetime">
    2009-11-18T13:21:42Z
  </updated-at>
  <repository-url>https://account.svn.beanstalkapp.com/ProjectAlpha</repository-url>
  <public-key>ssh-rsa ...</public-key>
</repository>

Find Branches

Returns an array of repository’s branches. For Subversion always returns an empty array.

json http-request
GET /api/repositories/{REPOSITORY_ID}/branches.json

Click to expand…

json http-response
[
  {"branch": "master"},
  {"branch": "new-feature"}
]
xml http-request
GET /api/repositories/{REPOSITORY_ID}/branches.xml

Click to expand…

xml http-response
<?xml version="1.0" encoding="UTF-8"?>
<branches>
  <branch>master</branch>
  <branch>new-feature</branch>
</branches>

Find Tags

Returns an array of repository’s tags. For Subversion always returns an empty array.

json http-request
GET /api/repositories/{REPOSITORY_ID}/tags.json

Click to expand…

json http-response
[
  {"tag": "0.9"},
  {"tag": "1.0"},
  {"tag": "1.1"}
]
xml http-request
GET /api/repositories/{REPOSITORY_ID}/tags.xml

Click to expand…

xml http-response
<?xml version="1.0" encoding="UTF-8"?>
<tags>
  <tag>0.9</tag>
  <tag>1.0</tag>
  <tag>1.1</tag>
</tags>

Create Repository

Admin privileges required for this API method.

See a list of writable attributes at the top of the page.

json http-request
POST /api/repositories.json
{
  "repository": {
    "type_id": "git",
    "name": "project-beta",
    "title": "Project Beta",
    "color_label": "label-blue"
  }
}

Click to expand…

json http-response
{
  "repository": {
    "name": "project-beta",
    "created_at": "2011/09/23 11:53:46 +0800",
    "title": "Project Beta",
    "storage_used_bytes": 0,
    "updated_at": "2011/09/23 11:53:46 +0800",
    "color_label": "label-blue",
    "account_id": 2,
    "id": 13,
    "type": "GitRepository",
    "last_commit_at": null,
    "vcs": "git",
    "repository_url": "git@account.beanstalkapp.com:/project-beta",
    "public_key": "ssh-rsa ..."
  }
}
xml http-request
POST /api/repositories.xml
<?xml version="1.0" encoding="UTF-8"?>
<repository>
  <name>shiny_new_repo</name>
  <title>Bubblegum</title>
  <color_label>label-pink</color_label>
</repository>

Click to expand…

xml http-response
<?xml version="1.0" encoding="UTF-8"?>
<repository>
  <account-id type="integer">9247</account-id>
  <anonymous type="boolean">false</anonymous>
  <color-label>label-pink</color-label>
  <created-at type="datetime">
    2007-06-14T22:15:37Z
  </created-at>
  <id type="integer">82346</id>
  <type>SubversionRepository</id>
  <last-commit-at type="datetime">
    2009-11-18T13:21:24Z
  </last-commit-at>
  <name>ProjectAlpha</name>
  <revision type="integer">36</revision>
  <storage-used-bytes type="integer">
    151130112
  </storage-used-bytes>
  <title>Beanstalk</title>
  <updated-at type="datetime">
    2009-11-18T13:21:42Z
  </updated-at>
  <repository-url>https://account.svn.beanstalkapp.com/ProjectAlpha</repository-url>
  <public-key>ssh-rsa ...</public-key>
</repository>

--OR IF INVALID--

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Name can't be blank</error>
</errors>

Update Repository

Admin privileges required for this API method.

See a list of writable attributes at the top of the page. You only need to pass the attributes that you want to change.

json http-request
PUT /api/repositories/{REPOSITORY_ID}.json
{
  "repository": {
    "title": "New Project"
  }
}

Click to expand…

json http-response
{
  "repository": {
    "name": "project-beta",
    "created_at": "2011/09/23 11:53:46 +0800",
    "title": "New Project",
    "storage_used_bytes": 0,
    "updated_at": "2011/09/23 11:53:46 +0800",
    "color_label": "label-white",
    "account_id": 2,
    "id": 13,
    "type": "GitRepository",
    "last_commit_at": null,
    "vcs": "git",
    "repository_url": "git@account.beanstalkapp.com:/project-beta",
    "public_key": "ssh-rsa ..."
  }
}
xml http-request
PUT /api/repositories/{REPOSITORY_ID}.xml
<?xml version="1.0" encoding="UTF-8"?>
<repository>
  <name>bahroma_tunec</name>
  <title>bla</title>
  <color_label>label-red</color_label>
</repository>

Click to expand…

xml http-response
HEAD 200 OK

--OR IF INVALID--

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Name can't be blank</error>
</errors>

Rename Repository

Admin privileges required for this API method.

json http-request
PUT /api/repositories/{REPOSITORY_ID}/rename.json
{
  "repository": {
    "name": "new-project"
  }
}

Click to expand…

json http-response
{
  "repository": {
    "name": "new-project",
    "created_at": "2011/09/23 11:53:46 +0800",
    "title": "Project Beta",
    "storage_used_bytes": 2621440,
    "updated_at": "2014/05/15 10:23:45 +0800",
    "color_label": "label-white",
    "account_id": 2,
    "id": 13,
    "type": "GitRepository",
    "last_commit_at": "2014/05/14 11:53:46 +0800",
    "vcs": "git",
    "repository_url": "git@account.beanstalkapp.com:/new-project",
    "public_key": "ssh-rsa ..."
  }
}
--OR IF INVALID--

{
  "errors": ["Error message"]
}
xml http-request
PUT /api/repositories/{REPOSITORY_ID}/rename.xml
<?xml version="1.0" encoding="UTF-8"?>
<repository>
  <name>new-project</name>
</repository>

Click to expand…

xml http-response
<?xml version="1.0" encoding="UTF-8"?>
<repository>
  <account-id type="integer">2</account-id>
  <color-label>label-white</color-label>
  <created-at type="datetime">
    2007-06-14T22:15:37Z
  </created-at>
  <id type="integer">13</id>
  <type>GitRepository</id>
  <last-commit-at type="datetime">
    2014-05-14T13:21:24Z
  </last-commit-at>
  <name>new-project</name>
  <revision type="integer">36</revision>
  <storage-used-bytes type="integer">
    2621440
  </storage-used-bytes>
  <title>Project Beta</title>
  <updated-at type="datetime">
    2014-05-15T13:21:42Z
  </updated-at>
  <repository-url>git@account.beanstalkapp.com:/new-project</repository-url>
  <public-key>ssh-rsa ...</public-key>
  <vcs>git</vcs>
</repository>

--OR IF INVALID--

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Name can't be blank</error>
</errors>

Delete Repository

Account owner privileges required for this API method.

This method submits a request for repository deletion. If request was successfully submitted HTTP 202 will be returned with no response body. If previously submitted request is still in progress HTTP 304 will be returned with no response body. It is safe to call this method more than once as Beanstalk will make sure that only one request can be submitted.

Repository deletion requests can take several seconds to finish for smaller repositories and hours for extremely big repos.

json http-request
DELETE /api/repositories/{REPOSITORY_ID}.json

Click to expand…

json http-response
HEAD 202 OR HEAD 304
xml http-request
DELETE /api/repositories/{REPOSITORY_ID}.xml

Click to expand…

xml http-response
HEAD 202 OR HEAD 304