1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
|
## 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
<table>
<tr><th colspan='2'>url parameters</th><th rowspan='2'>required<br/>permission</th><th colspan='2'>json</th></tr>
<tr><th>req=</th><th>name=</th><th>post body</th><th>response body</th></tr>
<tr><td>LIST_REPOSITORIES</td><td>-</td><td>-</td><td>-</td><td>Map<String, RepositoryModel></td></tr>
<tr><td>CREATE_REPOSITORY</td><td>repository name</td><td><em>admin</em></td><td>RepositoryModel</td><td>-</td></tr>
<tr><td>EDIT_REPOSITORY</td><td>repository name</td><td><em>admin</em></td><td>RepositoryModel</td><td>-</td></tr>
<tr><td>DELETE_REPOSITORY</td><td>repository name</td><td><em>admin</em></td><td>-</td><td>-</td></tr>
<tr><td>LIST_USERS</td><td>-</td><td><em>admin</em></td><td>-</td><td>List<UserModel></td></tr>
<tr><td>CREATE_USER</td><td>user name</td><td><em>admin</em></td><td>UserModel</td><td>-</td></tr>
<tr><td>EDIT_USER</td><td>user name</td><td><em>admin</em></td><td>UserModel</td><td>-</td></tr>
<tr><td>DELETE_USER</td><td>user name</td><td><em>admin</em></td><td>-</td><td>-</td></tr>
<tr><td>LIST_REPOSITORY_MEMBERS</td><td>repository name</td><td><em>admin</em></td><td>-</td><td>List<String></td></tr>
<tr><td>SET_REPOSITORY_MEMBERS</td><td>repository name</td><td><em>admin</em></td><td>List<String></td><td>-</td></tr>
<tr><td>LIST_FEDERATION_REGISTRATIONS</td><td>-</td><td><em>admin</em></td><td>-</td><td>List<FederationModel></td></tr>
<tr><td>LIST_FEDERATION_RESULTS</td><td>-</td><td><em>admin</em></td><td>-</td><td>List<FederationModel></td></tr>
<tr><td>LIST_FEDERATION_PROPOSALS</td><td>-</td><td><em>admin</em></td><td>-</td><td>List<FederationProposal></td></tr>
<tr><td>LIST_FEDERATION_SETS</td><td>-</td><td><em>admin</em></td><td>-</td><td>List<FederationSet></td></tr>
<tr><td>LIST_SETTINGS</td><td>-</td><td><em>admin</em></td><td>-</td><td>ServerSettings (see example below)</td></tr>
<tr><td>LIST_STATUS</td><td>-</td><td><em>admin</em></td><td>-</td><td>ServerStatus (see example below)</td></tr>
</table>
### RPC/HTTP Response Codes
<table>
<tr><th>code</th><th>name</th><th>description</th></tr>
<tr><td>200</td><td>success</td><td>Gitblit processed the request successfully</td></tr>
<tr><td>401</td><td>unauthorized</td><td>Gitblit requires user credentials to process the request</td></tr>
<tr><td>403</td><td>forbidden</td><td>Gitblit can not process the request for the supplied credentials</td></tr>
<tr><td>405</td><td>method not allowed</td><td>Gitblit has disallowed the processing the specified request</td></tr>
<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>
<tr><td>501</td><td>unknown request</td><td>Gitblit does not recognize the RPC request type</td></tr>
</table>
### Gitblit Manager
[Gitblit Manager](http://code.google.com/p/gitblit/downloads/detail?name=%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](http://google-gson.googlecode.com) 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](https://bugs.eclipse.org/bugs/show_bug.cgi?id=361251).
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
<pre>
{
"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"
}
}
</pre>
### 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
<pre>
{
"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"
}
</pre>
### Example: LIST_USERS
**url**: https://localhost/rpc?req=LIST_USERS
**response body**: List<UserModel>
<pre>
[
{
"username": "admin",
"password": "admin",
"canAdmin": true,
"excludeFromFederation": true,
"repositories": []
},
{
"username": "test",
"password": "test",
"canAdmin": false,
"excludeFromFederation": false,
"repositories": [
"libraries/xmlapache.git",
"libraries/smack.git"
]
}
]
</pre>
### Example: LIST_SETTINGS
**url**: https://localhost/rpc?req=LIST_SETTINGS
**response body**: ServerSettings
<pre>
{
"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
}
}
}
</pre>
### Example: LIST_STATUS
**url**: https://localhost/rpc?req=LIST_STATUS
**response body**: ServerStatus
<pre>
{
"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
}
</pre>
|
