Remote Management, Administration and Integration

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.enableRpcManagement=false
web.enableRpcAdministration=false

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

The Gitblit JSON 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.

Gitblit Manager

The Gitblit Manager is an example Java/Swing application that allows remote management (repository and user objects) and administration (server settings) of a Gitblit server.

This application uses a combination of RSS feeds and the JSON RPC interface, both of which are part of the Gitblit API library, to present live information from a Gitblit server. Some JSON RPC methods from the utility class com.gitblit.utils.RpcUtils are not currently used by the Gitblit Manager.

NOTE:
Gitblit Manager stores your login credentials INSECURELY in homedir/.gitblit/config.

RSS Query Interface

At present, Gitblit does not yet support retrieving Git objects (commits, etc) via the JSON RPC mechanism. However, the repository/branch RSS feeds can be used to extract log/history information from a repository branch.

The Gitblit API includes methods for retrieving and interpreting RSS feeds. The Gitblit Manager uses these methods to allow branch activity monitoring and repository searching.

url parameterdefaultdescription
standard query
repositoryrequiredrepository name is part of the url (see examples below)
ot=optional
default: COMMIT
object type to return in results. COMMIT or TAG
h=optional
default: HEAD
starting branch, ref, or commit id
l=optional
default: web.syndicationEntries
maximum return count
pg=optional
default: 0
page number for paging
(offset into history = pagenumber*maximum return count)
search query
s=requiredsearch string
st=optional
default: COMMIT
search type

Example RSS Queries

https://localhost:8443/feed/gitblit.git?l=50&h=refs/heads/master
https://localhost:8443/feed/gitblit.git?l=50&h=refs/heads/master&s=documentation
https://localhost:8443/feed/gitblit.git?l=50&h=refs/heads/master&s=james&st=author&pg=2

JSON Remote Procedure Call (RPC) Interface

RPC Protocol Versions

ReleaseProtocol Version
Gitblit v0.7.01 (inferred version)
Gitblit v0.8.02
Gitblit v0.9.0 - v1.0.03
Gitblit v1.1.04
Gitblit v1.2.05
Gitblit v1.3.16
Gitblit v1.4.07
Gitblit v1.6.08
Gitblit v1.9.09

Protocol Version 5

RPC Request and Response Types

url parametersrequired
user
permission
protocol
version
json
req=name=post bodyresponse body
web.enableRpcServlet=true
GET_PROTOCOL--2-Integer
LIST_REPOSITORIES--1-Map<String, RepositoryModel>
LIST_BRANCHES[repository name]-9-Map<String, List<String>>
LIST_SETTINGS--1-ServerSettings (basic keys)
GET_USERuser name-6-UserModel
FORK_REPOSITORYrepository name-8--
web.enableRpcManagement=true
CREATE_REPOSITORYrepository nameadmin1RepositoryModel-
EDIT_REPOSITORYrepository nameadmin1RepositoryModel-
DELETE_REPOSITORYrepository nameadmin1RepositoryModel-
LIST_USERS-admin1-List<UserModel>
CREATE_USERuser nameadmin1UserModel-
EDIT_USERuser nameadmin1UserModel-
DELETE_USERuser nameadmin1UserModel-
LIST_TEAMS-admin2-List<TeamModel>
CREATE_TEAMteam nameadmin2TeamModel-
EDIT_TEAMteam nameadmin2TeamModel-
DELETE_TEAMteam nameadmin2TeamModel-
LIST_REPOSITORY_MEMBERSrepository nameadmin1-List<String>
SET_REPOSITORY_MEMBERSrepository nameadmin1List<String>-
LIST_REPOSITORY_MEMBER_PERMISSIONSrepository nameadmin5-List<String>
SET_REPOSITORY_MEMBER_PERMISSIONSrepository nameadmin5List<String>-
LIST_REPOSITORY_TEAMSrepository nameadmin2-List<String>
SET_REPOSITORY_TEAMSrepository nameadmin2List<String>-
LIST_REPOSITORY_TEAM_PERMISSIONSrepository nameadmin5-List<String>
SET_REPOSITORY_TEAM_PERMISSIONSrepository nameadmin5List<String>-
LIST_SETTINGS-admin1-ServerSettings (management keys)
CLEAR_REPOSITORY_CACHE--4--
REINDEX_TICKETSrepository name-7--
web.enableRpcAdministration=true
LIST_FEDERATION_REGISTRATIONS-admin1-List<FederationModel>
LIST_FEDERATION_RESULTS-admin1-List<FederationModel>
LIST_FEDERATION_PROPOSALS-admin1-List<FederationProposal>
LIST_FEDERATION_SETS-admin1-List<FederationSet>
LIST_SETTINGS-admin1-ServerSettings (all keys)
EDIT_SETTINGS-admin1Map<String, String>-
LIST_STATUS-admin1-ServerStatus (see example below)

RPC/HTTP Response Codes

codenamedescription
200successGitblit processed the request successfully
401unauthorizedGitblit requires user credentials to process the request
403forbiddenGitblit can not process the request for the supplied credentials
405method not allowedGitblit has disallowed the processing the specified request
500server errorGitblit failed to process the request likely because the input object created a conflict
501unknown requestGitblit does not recognize the RPC request type

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",
  "version": "0.7.0-SNAPSHOT",
  "releaseDate": "PENDING",
  "isGO": true,
  "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,
  "servletContainer": "jetty/7.4.3.v20110701"
}