Gitblit devel
view | history | commit | commitdiff
lemval
2012-01-31 1c30dad2115fc513791d8a5b292ad0f7d7b85749
commit | author | age
fa5e6f 1 ## Remote Management, Administration and Integration
4cd2f6 2
JM 3 *SINCE 0.7.0*
4
5 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.
6
7     web.enableRpcServlet=true
da0c31 8     web.enableRpcManagement=false
4cd2f6 9     web.enableRpcAdministration=false
JM 10
11 **https** is strongly recommended because passwords are insecurely transmitted form your browser/rpc client using Basic authentication!
12
fa5e6f 13 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.
4cd2f6 14
fa5e6f 15 ### Gitblit Manager
JM 16
17 [Gitblit Manager](http://code.google.com/p/gitblit/downloads/detail?name=%MANAGER%) is an example Java/Swing application that allows remote management (repository and user objects) and administration (server settings) of a Gitblit server.
18   
da0c31 19 This application uses a combination of RSS feeds and the JSON RPC interface, both of which are part of the [Gitblit API](http://code.google.com/p/gitblit/downloads/detail?name=%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.
fa5e6f 20
JM 21 **NOTE:**  
22 Gitblit Manager stores your login credentials **INSECURELY** in homedir/.gitblit/config.
23
da0c31 24 ### Eclipse/EGit "Import from Gitblit" Feature (Planning)
fa5e6f 25
da0c31 26 One obvious goal of a Gitblit RPC mechanism would be to have an Eclipse/EGit Feature that allows authentication and enumeration of Gitblit repositories from the Eclipse *Import...* menu.  Batch cloning would be supported and delegated to EGit.
fa5e6f 27
JM 28 This particular project should not be difficult as the only external dependency for `com.gitblit.utils.RpcUtils` is [google-gson](http://google-gson.googlecode.com) which is already a dependency of the EGit/GitHub Mylyn feature.
29
30 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](https://bugs.eclipse.org/bugs/show_bug.cgi?id=361251).
31
32 Currently this project is in the planning stage.
33
34 ## RSS Query Interface
35
36 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.
37
38 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.
39
40 <table>
41 <tr><th>url parameter</th><th>default</th><th>description</th></tr>
42 <tr><td colspan='3'><b>standard query</b></td></tr>
43 <tr><td><em>repository</em></td><td><em>required</em></td><td>repository name is part of the url (see examples below)</td></tr>
44 <tr><td>h=</td><td><em>optional</em><br/>default: HEAD</td><td>starting branch, ref, or commit id</td></tr>
45 <tr><td>l=</td><td><em>optional</em><br/>default: web.syndicationEntries</td><td>maximum return count</td></tr>
e33b91 46 <tr><td>pg=</td><td><em>optional</em><br/>default: 0</td><td>page number for paging<br/>(offset into history = pagenumber*maximum return count)</td></tr>
fa5e6f 47 <tr><td colspan='3'><b>search query</b></td></tr>
JM 48 <tr><td>s=</td><td><em>required</em></td><td>search string</td></tr>
49 <tr><td>st=</td><td><em>optional</em><br/>default: COMMIT</td><td>search type</td></tr>
50 </table>
51
52 ### Example RSS Queries
53
54     https://localhost:8443/feed/gitblit.git?l=50&h=refs/heads/master
55     https://localhost:8443/feed/gitblit.git?l=50&h=refs/heads/master&s=documentation
e33b91 56     https://localhost:8443/feed/gitblit.git?l=50&h=refs/heads/master&s=james&st=author&pg=2
fa5e6f 57
JM 58 ## JSON Remote Procedure Call (RPC) Interface
4cd2f6 59
f08aab 60 ### RPC Protocol Versions
4cd2f6 61 <table>
f08aab 62 <tbody>
JM 63 <tr><th>Release</th><th>Protocol Version</th></tr>
64 <tr><td>Gitblit v0.7.0</td><td>1 (inferred version)</td></tr>
65 <tr><td>Gitblit v0.8.0</td><td>2</td></tr>
66 </tbody>
67 </table>
68
69 ### RPC Request and Response Types
70 <table>
71 <tr><th colspan='2'>url parameters</th><th rowspan='2'>required<br/>user<br/>permission</th><th rowspan='2'>protocol<br/>version</th><th colspan='2'>json</th></tr>
4cd2f6 72 <tr><th>req=</th><th>name=</th><th>post body</th><th>response body</th></tr>
f08aab 73 <tr><td colspan='6'><em>web.enableRpcServlet=true</em></td></tr>
JM 74 <tr><td>GET_PROTOCOL</td><td>-</td><td>-</td><td>2</td><td>-</td><td>Integer</td></tr>
75 <tr><td>LIST_REPOSITORIES</td><td>-</td><td>-</td><td>1</td><td>-</td><td>Map&lt;String, RepositoryModel&gt;</td></tr>
76 <tr><td>LIST_BRANCHES</td><td>-</td><td>-</td><td>1</td><td>-</td><td>Map&lt;String, List&lt;String&gt;&gt;</td></tr>
77 <tr><td>LIST_SETTINGS</td><td>-</td><td><em>-</em></td><td>1</td><td>-</td><td>ServerSettings (basic keys)</td></tr>
78 <tr><td colspan='6'><em>web.enableRpcManagement=true</em></td></tr>
79 <tr><td>CREATE_REPOSITORY</td><td>repository name</td><td><em>admin</em></td><td>1</td><td>RepositoryModel</td><td>-</td></tr>
80 <tr><td>EDIT_REPOSITORY</td><td>repository name</td><td><em>admin</em></td><td>1</td><td>RepositoryModel</td><td>-</td></tr>
81 <tr><td>DELETE_REPOSITORY</td><td>repository name</td><td><em>admin</em></td><td>1</td><td>-</td><td>-</td></tr>
82 <tr><td>LIST_USERS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List&lt;UserModel&gt;</td></tr>
83 <tr><td>CREATE_USER</td><td>user name</td><td><em>admin</em></td><td>1</td><td>UserModel</td><td>-</td></tr>
84 <tr><td>EDIT_USER</td><td>user name</td><td><em>admin</em></td><td>1</td><td>UserModel</td><td>-</td></tr>
85 <tr><td>DELETE_USER</td><td>user name</td><td><em>admin</em></td><td>1</td><td>-</td><td>-</td></tr>
86 <tr><td>LIST_TEAMS</td><td>-</td><td><em>admin</em></td><td>2</td><td>-</td><td>List&lt;TeamModel&gt;</td></tr>
87 <tr><td>CREATE_TEAM</td><td>team name</td><td><em>admin</em></td><td>2</td><td>TeamModel</td><td>-</td></tr>
88 <tr><td>EDIT_TEAM</td><td>team name</td><td><em>admin</em></td><td>2</td><td>TeamModel</td><td>-</td></tr>
89 <tr><td>DELETE_TEAM</td><td>team name</td><td><em>admin</em></td><td>2</td><td>-</td><td>-</td></tr>
90 <tr><td>LIST_REPOSITORY_MEMBERS</td><td>repository name</td><td><em>admin</em></td><td>1</td><td>-</td><td>List&lt;String&gt;</td></tr>
91 <tr><td>SET_REPOSITORY_MEMBERS</td><td>repository name</td><td><em>admin</em></td><td>1</td><td>List&lt;String&gt;</td><td>-</td></tr>
92 <tr><td>LIST_REPOSITORY_TEAMS</td><td>repository name</td><td><em>admin</em></td><td>2</td><td>-</td><td>List&lt;String&gt;</td></tr>
93 <tr><td>SET_REPOSITORY_TEAMS</td><td>repository name</td><td><em>admin</em></td><td>2</td><td>List&lt;String&gt;</td><td>-</td></tr>
94 <tr><td>LIST_SETTINGS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>ServerSettings (management keys)</td></tr>
95 <tr><td colspan='6'><em>web.enableRpcAdministration=true</em></td></tr>
96 <tr><td>LIST_FEDERATION_REGISTRATIONS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List&lt;FederationModel&gt;</td></tr>
97 <tr><td>LIST_FEDERATION_RESULTS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List&lt;FederationModel&gt;</td></tr>
98 <tr><td>LIST_FEDERATION_PROPOSALS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List&lt;FederationProposal&gt;</td></tr>
99 <tr><td>LIST_FEDERATION_SETS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List&lt;FederationSet&gt;</td></tr>
100 <tr><td>LIST_SETTINGS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>ServerSettings (all keys)</td></tr>
101 <tr><td>EDIT_SETTINGS</td><td>-</td><td><em>admin</em></td><td>1</td><td>Map&lt;String, String&gt;</td><td>-</td></tr>
102 <tr><td>LIST_STATUS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>ServerStatus (see example below)</td></tr>
4cd2f6 103 </table>
JM 104
b75734 105 ### RPC/HTTP Response Codes
595bbf 106 <table>
JM 107 <tr><th>code</th><th>name</th><th>description</th></tr>
108 <tr><td>200</td><td>success</td><td>Gitblit processed the request successfully</td></tr>
109 <tr><td>401</td><td>unauthorized</td><td>Gitblit requires user credentials to process the request</td></tr>
110 <tr><td>403</td><td>forbidden</td><td>Gitblit can not process the request for the supplied credentials</td></tr>
111 <tr><td>405</td><td>method not allowed</td><td>Gitblit has disallowed the processing the specified request</td></tr>
112 <tr><td>500</td><td>server error</td><td>Gitblit failed to process the request likely because the input object created a conflict</td></tr>
113 <tr><td>501</td><td>unknown request</td><td>Gitblit does not recognize the RPC request type</td></tr>
114 </table>
4cd2f6 115
JM 116 ### Example: LIST_REPOSITORIES
117
118 **url**: https://localhost/rpc?req=LIST_REPOSITORIES  
119 **response body**: Map&lt;String, RepositoryModel&gt; where the map key is the clone url of the repository
120 <pre>
121 {
122   "https://localhost/git/libraries/xmlapache.git": {
123     "name": "libraries/xmlapache.git",
124     "description": "apache xmlrpc client and server",
125     "owner": "admin",
126     "lastChange": "2010-01-28T22:12:06Z",
127     "hasCommits": true,
128     "showRemoteBranches": false,
129     "useTickets": false,
130     "useDocs": false,
131     "accessRestriction": "VIEW",
132     "isFrozen": false,
133     "showReadme": false,
134     "federationStrategy": "FEDERATE_THIS",
135     "federationSets": [
136       "libraries"
137     ],
138     "isFederated": false,
84c1d5 139     "skipSizeCalculation": false,
d40adc 140     "skipSummaryMetrics": false,
4cd2f6 141     "size": "102 KB"
JM 142   },
143   "https://localhost/git/libraries/smack.git": {
144     "name": "libraries/smack.git",
145     "description": "smack xmpp client",
146     "owner": "admin",
147     "lastChange": "2009-01-28T18:38:14Z",
148     "hasCommits": true,
149     "showRemoteBranches": false,
150     "useTickets": false,
151     "useDocs": false,
152     "accessRestriction": "VIEW",
153     "isFrozen": false,
154     "showReadme": false,
155     "federationStrategy": "FEDERATE_THIS",
156     "federationSets": [],
157     "isFederated": false,
84c1d5 158     "skipSizeCalculation": false,
d40adc 159     "skipSummaryMetrics": false,
4cd2f6 160     "size": "4.8 MB"
JM 161   }
162 }
163 </pre>
164
165 ### Example: EDIT_REPOSITORY (rename)
166
167 The original repository name is specified in the *name* url parameter.  The new name is set within the JSON object.
168
169 **url**: https://localhost/rpc?req=EDIT_REPOSITORY&name=libraries/xmlapache.git  
170 **post body**: RepositoryModel
171 <pre>
172 {
173     "name": "libraries/xmlapache-renamed.git",
174     "description": "apache xmlrpc client and server",
175     "owner": "admin",
176     "lastChange": "2010-01-28T22:12:06Z",
177     "hasCommits": true,
178     "showRemoteBranches": false,
179     "useTickets": false,
180     "useDocs": false,
181     "accessRestriction": "VIEW",
182     "isFrozen": false,
183     "showReadme": false,
184     "federationStrategy": "FEDERATE_THIS",
185     "federationSets": [
186       "libraries"
187     ],
188     "isFederated": false,
d40adc 189     "skipSizeCalculation": false,
JM 190     "skipSummaryMetrics": false,
4cd2f6 191     "size": "102 KB"
JM 192 }
193 </pre>
194
195 ### Example: LIST_USERS
196 **url**: https://localhost/rpc?req=LIST_USERS  
197 **response body**: List&lt;UserModel&gt;
198 <pre>
199 [
200   {
201     "username": "admin",
202     "password": "admin",
203     "canAdmin": true,
204     "excludeFromFederation": true,
205     "repositories": []
206   },
207   {
208     "username": "test",
209     "password": "test",
210     "canAdmin": false,
211     "excludeFromFederation": false,
212     "repositories": [
213       "libraries/xmlapache.git",
214       "libraries/smack.git"
215     ]
216   }
217 ]
b75734 218 </pre>
JM 219
220 ### Example: LIST_SETTINGS
221 **url**: https://localhost/rpc?req=LIST_SETTINGS  
84c1d5 222 **response body**: ServerSettings
b75734 223 <pre>
JM 224 {
84c1d5 225   "settings": {
JM 226       "web.siteName": {
227         "name": "web.siteName",
228         "currentValue": "",
229         "defaultValue": "",
230         "description": "Gitblit Web Settings\nIf blank Gitblit is displayed.",
231         "since": "0.5.0",
232         "caseSensitive": false,
233         "restartRequired": false,
234         "spaceDelimited": false
235       },
236       "web.summaryCommitCount": {
237         "name": "web.summaryCommitCount",
238         "currentValue": "16",
239         "defaultValue": "16",
240         "description": "The number of commits to display on the summary page\nValue must exceed 0 else default of 16 is used",
241         "since": "0.5.0",
242         "caseSensitive": false,
243         "restartRequired": false,
244         "spaceDelimited": false
245       }
b75734 246   }
JM 247 }
84c1d5 248 </pre>
JM 249
250 ### Example: LIST_STATUS
251 **url**: https://localhost/rpc?req=LIST_STATUS  
252 **response body**: ServerStatus
253 <pre>
254 {
255   "bootDate": "2011-10-22T12:13:00Z",
c75304 256   "version": "0.7.0-SNAPSHOT",
JM 257   "releaseDate": "PENDING",
258   "isGO": true,
84c1d5 259   "systemProperties": {
JM 260     "file.encoding": "Cp1252",
261     "java.home": "C:\\Program Files\\Java\\jdk1.6.0_26\\jre",
262     "java.io.tmpdir": "C:\\Users\\JAMESM~1\\AppData\\Local\\Temp\\",
263     "java.runtime.name": "Java(TM) SE Runtime Environment",
264     "java.runtime.version": "1.6.0_26-b03",
265     "java.vendor": "Sun Microsystems Inc.",
266     "java.version": "1.6.0_26",
267     "java.vm.info": "mixed mode",
268     "java.vm.name": "Java HotSpot(TM) 64-Bit Server VM",
269     "java.vm.vendor": "Sun Microsystems Inc.",
270     "java.vm.version": "20.1-b02",
271     "os.arch": "amd64",
272     "os.name": "Windows 7",
273     "os.version": "6.1"
274   },
275   "heapAllocated": 128057344,
276   "heapFree": 120399168,
c75304 277   "heapSize": 1899560960,
JM 278   "servletContainer": "jetty/7.4.3.v20110701"
84c1d5 279 }
4cd2f6 280 </pre>