gitblit/docs/02_rpc.mkd

JSON Remote Procedure Call (RPC) Interface

SINCE 0.7.0

Gitblit optionally allows a remote client to administer the Gitblit server. This client could be a Java-based tool or perhaps a tool written in another language.

web.enableRpcServlet=true
web.enableRpcAdministration=false

https is strongly recommended because passwords are insecurely transmitted form your browser/rpc client using Basic authentication!

The Gitblit RPC mechanism, like the Gitblit JGit servlet, syndication/feed servlet, etc, supports request-based authentication. Making an admin request will trigger Gitblit’s basic authentication mechanism. Listing of repositories, generally, will not trigger this authentication mechanism unless web.authenticateViewPages=true. That means its possible to allow anonymous enumeration of repositories that are not view restricted or clone restricted. Of course, if credentials are provided then all private repositories that are available to the user account will be enumerated in the JSON response.

RPC Requests

url parameters		required permission	json
req=	name=		post body	response body
LIST_REPOSITORIES	-	-	-	Map<String, RepositoryModel>
CREATE_REPOSITORY	repository name	admin	RepositoryModel	-
EDIT_REPOSITORY	repository name	admin	RepositoryModel	-
DELETE_REPOSITORY	repository name	admin	-	-
LIST_USERS	-	admin	-	List<UserModel>
CREATE_USER	user name	admin	UserModel	-
EDIT_USER	user name	admin	UserModel	-
DELETE_USER	user name	admin	-	-
LIST_REPOSITORY_MEMBERS	repository name	admin	-	List<String>
SET_REPOSITORY_MEMBERS	repository name	admin	List<String>	-
LIST_FEDERATION_REGISTRATIONS	-	admin	-	List<FederationModel>
LIST_FEDERATION_RESULTS	-	admin	-	List<FederationModel>
LIST_FEDERATION_PROPOSALS	-	admin	-	List<FederationProposal>
LIST_FEDERATION_SETS	-	admin	-	List<FederationSet>
LIST_SETTINGS	-	admin	-	ServerSettings (see example below)
EDIT_SETTINGS	-	admin	Map<String, String>	-
LIST_STATUS	-	admin	-	ServerStatus (see example below)

RPC/HTTP Response Codes

code	name	description
200	success	Gitblit processed the request successfully
401	unauthorized	Gitblit requires user credentials to process the request
403	forbidden	Gitblit can not process the request for the supplied credentials
405	method not allowed	Gitblit has disallowed the processing the specified request
500	server error	Gitblit failed to process the request likely because the input object created a conflict
501	unknown request	Gitblit does not recognize the RPC request type

Gitblit Manager

Gitblit Manager is an example Java/Swing application that allows remote administration of a Gitblit server.
This application exercises many, but not all, methods from the utility class com.gitblit.utils.RpcUtils.

EGit “Import from Gitblit” Feature (Planning)

One obvious goal of a Gitblit RPC mechanism would be to have an EGit Feature that allows authentication and enumeration of Gitblit repositories from the Eclipse Import… menu. Cloning (hopefully batch) would be delegated to EGit.

This particular project should not be difficult as the only external dependency for com.gitblit.utils.RpcUtils is google-gson which is already a dependency of the EGit/GitHub Mylyn feature.

One proposal from the EGit team is to define a common JSON RPC method for enumeration of repositories which can be implemented by Git hosts. The EGit team would then implement the UI and the client-side enumeration code. This idea was raised as part of this feature request for EGit.

Currently this project is in the planning stage.

Example: LIST_REPOSITORIES

url: https://localhost/rpc?req=LIST_REPOSITORIES
response body: Map<String, RepositoryModel> where the map key is the clone url of the repository

{
  “https://localhost/git/libraries/xmlapache.git”: {


"name": "libraries/xmlapache.git",
"description": "apache xmlrpc client and server",
"owner": "admin",
"lastChange": "2010-01-28T22:12:06Z",
"hasCommits": true,
"showRemoteBranches": false,
"useTickets": false,
"useDocs": false,
"accessRestriction": "VIEW",
"isFrozen": false,
"showReadme": false,
"federationStrategy": "FEDERATE_THIS",
"federationSets": [
  "libraries"
],
"isFederated": false,
"skipSizeCalculation": false,
"skipSummaryMetrics": false,
"size": "102 KB"


},
  “https://localhost/git/libraries/smack.git”: {

"name": "libraries/smack.git",
"description": "smack xmpp client",
"owner": "admin",
"lastChange": "2009-01-28T18:38:14Z",
"hasCommits": true,
"showRemoteBranches": false,
"useTickets": false,
"useDocs": false,
"accessRestriction": "VIEW",
"isFrozen": false,
"showReadme": false,
"federationStrategy": "FEDERATE_THIS",
"federationSets": [],
"isFederated": false,
"skipSizeCalculation": false,
"skipSummaryMetrics": false,
"size": "4.8 MB"


}
}

Example: EDIT_REPOSITORY (rename)

The original repository name is specified in the name url parameter. The new name is set within the JSON object.

url: https://localhost/rpc?req=EDIT_REPOSITORY&name=libraries/xmlapache.git
post body: RepositoryModel

{


"name": "libraries/xmlapache-renamed.git",
"description": "apache xmlrpc client and server",
"owner": "admin",
"lastChange": "2010-01-28T22:12:06Z",
"hasCommits": true,
"showRemoteBranches": false,
"useTickets": false,
"useDocs": false,
"accessRestriction": "VIEW",
"isFrozen": false,
"showReadme": false,
"federationStrategy": "FEDERATE_THIS",
"federationSets": [
  "libraries"
],
"isFederated": false,
"skipSizeCalculation": false,
"skipSummaryMetrics": false,
"size": "102 KB"


}

Example: LIST_USERS

url: https://localhost/rpc?req=LIST_USERS
response body: List<UserModel>

[
  {


"username": "admin",
"password": "admin",
"canAdmin": true,
"excludeFromFederation": true,
"repositories": []


},
  {

"username": "test",
"password": "test",
"canAdmin": false,
"excludeFromFederation": false,
"repositories": [
  "libraries/xmlapache.git",
  "libraries/smack.git"
]


}
]

Example: LIST_SETTINGS

url: https://localhost/rpc?req=LIST_SETTINGS
response body: ServerSettings

{
  “settings”: {


  "web.siteName": {
    "name": "web.siteName",
    "currentValue": "",
    "defaultValue": "",
    "description": "Gitblit Web Settings\nIf blank Gitblit is displayed.",
    "since": "0.5.0",
    "caseSensitive": false,
    "restartRequired": false,
    "spaceDelimited": false
  },
  "web.summaryCommitCount": {
    "name": "web.summaryCommitCount",
    "currentValue": "16",
    "defaultValue": "16",
    "description": "The number of commits to display on the summary page\nValue must exceed 0 else default of 16 is used",
    "since": "0.5.0",
    "caseSensitive": false,
    "restartRequired": false,
    "spaceDelimited": false
  }


}
}

Example: LIST_STATUS

url: https://localhost/rpc?req=LIST_STATUS
response body: ServerStatus

{
  “bootDate”: “2011-10-22T12:13:00Z”,
  “systemProperties”: {


"file.encoding": "Cp1252",
"java.home": "C:\\Program Files\\Java\\jdk1.6.0_26\\jre",
"java.io.tmpdir": "C:\\Users\\JAMESM~1\\AppData\\Local\\Temp\\",
"java.runtime.name": "Java(TM) SE Runtime Environment",
"java.runtime.version": "1.6.0_26-b03",
"java.vendor": "Sun Microsystems Inc.",
"java.version": "1.6.0_26",
"java.vm.info": "mixed mode",
"java.vm.name": "Java HotSpot(TM) 64-Bit Server VM",
"java.vm.vendor": "Sun Microsystems Inc.",
"java.vm.version": "20.1-b02",
"os.arch": "amd64",
"os.name": "Windows 7",
"os.version": "6.1"


},
  “heapAllocated”: 128057344,
  “heapFree”: 120399168,
  “heapSize”: 1899560960
}