githubFork/gitblit.git - Solinfo Gitblit

Merge pull request #1073 from gitblit/1062-DocEditorUpdates

Paul Martin

2016-04-30 a502d96a860456ec5e8c96761db70f7cabb74751

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
fb289c	17	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.
fa5e6f	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
	24
	25	## RSS Query Interface
	26
	27	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.
	28
	29	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.
	30
3cc6e2	31	<table class="table">
fa5e6f	32	<tr><th>url parameter</th><th>default</th><th>description</th></tr>
JM	33	<tr><td colspan='3'><b>standard query</b></td></tr>
	34	<tr><td><em>repository</em></td><td><em>required</em></td><td>repository name is part of the url (see examples below)</td></tr>
9ff0c1	35	<tr><td>ot=</td><td><em>optional</em><br/>default: COMMIT</td><td>object type to return in results. COMMIT or TAG</td></tr>
fa5e6f	36	<tr><td>h=</td><td><em>optional</em><br/>default: HEAD</td><td>starting branch, ref, or commit id</td></tr>
JM	37	<tr><td>l=</td><td><em>optional</em><br/>default: web.syndicationEntries</td><td>maximum return count</td></tr>
e33b91	38	<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	39	<tr><td colspan='3'><b>search query</b></td></tr>
JM	40	<tr><td>s=</td><td><em>required</em></td><td>search string</td></tr>
	41	<tr><td>st=</td><td><em>optional</em><br/>default: COMMIT</td><td>search type</td></tr>
	42	</table>
	43
	44	### Example RSS Queries
	45
	46	https://localhost:8443/feed/gitblit.git?l=50&h=refs/heads/master
	47	https://localhost:8443/feed/gitblit.git?l=50&h=refs/heads/master&s=documentation
e33b91	48	https://localhost:8443/feed/gitblit.git?l=50&h=refs/heads/master&s=james&st=author&pg=2
fa5e6f	49
JM	50	## JSON Remote Procedure Call (RPC) Interface
4cd2f6	51
f08aab	52	### RPC Protocol Versions
6c4be1	53
3cc6e2	54	<table class="table">
f08aab	55	<tbody>
JM	56	<tr><th>Release</th><th>Protocol Version</th></tr>
	57	<tr><td>Gitblit v0.7.0</td><td>1 (inferred version)</td></tr>
	58	<tr><td>Gitblit v0.8.0</td><td>2</td></tr>
fee060	59	<tr><td>Gitblit v0.9.0 - v1.0.0</td><td>3</td></tr>
822dfe	60	<tr><td>Gitblit v1.1.0</td><td>4</td></tr>
813a1f	61	<tr><td>Gitblit v1.2.0</td><td>5</td></tr>
JM	62	<tr><td>Gitblit v1.3.1</td><td>6</td></tr>
	63	<tr><td>Gitblit v1.4.0</td><td>7</td></tr>
	64	<tr><td>Gitblit v1.6.0</td><td>8</td></tr>
f08aab	65	</tbody>
JM	66	</table>
822dfe	67
JM	68	#### Protocol Version 5
	69
	70	- SET_REPOSITORY_MEMBERS will reject all calls because this would elevate all discrete permissions to RW+
	71	Use SET_REPOSITORY_MEMBER_PERMISSIONS instead.
	72	- SET_REPOSITORY_TEAMS will reject all calls because this would elevate all discrete permissions to RW+
	73	Use SET_REPOSITORY_TEAM_PERMISSIONS instead.
f08aab	74
JM	75	### RPC Request and Response Types
6c4be1	76
3cc6e2	77	<table class="table">
f08aab	78	<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	79	<tr><th>req=</th><th>name=</th><th>post body</th><th>response body</th></tr>
f08aab	80	<tr><td colspan='6'><em>web.enableRpcServlet=true</em></td></tr>
JM	81	<tr><td>GET_PROTOCOL</td><td>-</td><td>-</td><td>2</td><td>-</td><td>Integer</td></tr>
	82	<tr><td>LIST_REPOSITORIES</td><td>-</td><td>-</td><td>1</td><td>-</td><td>Map<String, RepositoryModel></td></tr>
	83	<tr><td>LIST_BRANCHES</td><td>-</td><td>-</td><td>1</td><td>-</td><td>Map<String, List<String>></td></tr>
	84	<tr><td>LIST_SETTINGS</td><td>-</td><td><em>-</em></td><td>1</td><td>-</td><td>ServerSettings (basic keys)</td></tr>
a5ae3d	85	<tr><td>GET_USER</td><td>user name</td><td>-</td><td>6</td><td>-</td><td>UserModel</td></tr>
813a1f	86	<tr><td>FORK_REPOSITORY</td><td>repository name</td><td><em>-</em></td><td>8</td><td>-</td><td>-</td></tr>
f08aab	87	<tr><td colspan='6'><em>web.enableRpcManagement=true</em></td></tr>
JM	88	<tr><td>CREATE_REPOSITORY</td><td>repository name</td><td><em>admin</em></td><td>1</td><td>RepositoryModel</td><td>-</td></tr>
	89	<tr><td>EDIT_REPOSITORY</td><td>repository name</td><td><em>admin</em></td><td>1</td><td>RepositoryModel</td><td>-</td></tr>
bd8ec5	90	<tr><td>DELETE_REPOSITORY</td><td>repository name</td><td><em>admin</em></td><td>1</td><td>RepositoryModel</td><td>-</td></tr>
f08aab	91	<tr><td>LIST_USERS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List<UserModel></td></tr>
JM	92	<tr><td>CREATE_USER</td><td>user name</td><td><em>admin</em></td><td>1</td><td>UserModel</td><td>-</td></tr>
	93	<tr><td>EDIT_USER</td><td>user name</td><td><em>admin</em></td><td>1</td><td>UserModel</td><td>-</td></tr>
bd8ec5	94	<tr><td>DELETE_USER</td><td>user name</td><td><em>admin</em></td><td>1</td><td>UserModel</td><td>-</td></tr>
f08aab	95	<tr><td>LIST_TEAMS</td><td>-</td><td><em>admin</em></td><td>2</td><td>-</td><td>List<TeamModel></td></tr>
JM	96	<tr><td>CREATE_TEAM</td><td>team name</td><td><em>admin</em></td><td>2</td><td>TeamModel</td><td>-</td></tr>
	97	<tr><td>EDIT_TEAM</td><td>team name</td><td><em>admin</em></td><td>2</td><td>TeamModel</td><td>-</td></tr>
bd8ec5	98	<tr><td>DELETE_TEAM</td><td>team name</td><td><em>admin</em></td><td>2</td><td>TeamModel</td><td>-</td></tr>
f08aab	99	<tr><td>LIST_REPOSITORY_MEMBERS</td><td>repository name</td><td><em>admin</em></td><td>1</td><td>-</td><td>List<String></td></tr>
822dfe	100	<tr><td><s>SET_REPOSITORY_MEMBERS</s></td><td><s>repository name</s></td><td><em><s>admin</s></em></td><td><s>1</s></td><td><s>List<String></s></td><td>-</td></tr>
JM	101	<tr><td>LIST_REPOSITORY_MEMBER_PERMISSIONS</td><td>repository name</td><td><em>admin</em></td><td>5</td><td>-</td><td>List<String></td></tr>
	102	<tr><td>SET_REPOSITORY_MEMBER_PERMISSIONS</td><td>repository name</td><td><em>admin</em></td><td>5</td><td>List<String></td><td>-</td></tr>
f08aab	103	<tr><td>LIST_REPOSITORY_TEAMS</td><td>repository name</td><td><em>admin</em></td><td>2</td><td>-</td><td>List<String></td></tr>
822dfe	104	<tr><td><s>SET_REPOSITORY_TEAMS</s></td><td><s>repository name</s></td><td><em><s>admin</s></em></td><td><s>2</s></td><td><s>List<String></s></td><td>-</td></tr>
JM	105	<tr><td>LIST_REPOSITORY_TEAM_PERMISSIONS</td><td>repository name</td><td><em>admin</em></td><td>5</td><td>-</td><td>List<String></td></tr>
	106	<tr><td>SET_REPOSITORY_TEAM_PERMISSIONS</td><td>repository name</td><td><em>admin</em></td><td>5</td><td>List<String></td><td>-</td></tr>
f08aab	107	<tr><td>LIST_SETTINGS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>ServerSettings (management keys)</td></tr>
4ebaf6	108	<tr><td>CLEAR_REPOSITORY_CACHE</td><td>-</td><td><em>-</em></td><td>4</td><td>-</td><td>-</td></tr>
88693e	109	<tr><td>REINDEX_TICKETS</td><td>repository name</td><td><em>-</em></td><td>7</td><td>-</td><td>-</td></tr>
f08aab	110	<tr><td colspan='6'><em>web.enableRpcAdministration=true</em></td></tr>
JM	111	<tr><td>LIST_FEDERATION_REGISTRATIONS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List<FederationModel></td></tr>
	112	<tr><td>LIST_FEDERATION_RESULTS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List<FederationModel></td></tr>
	113	<tr><td>LIST_FEDERATION_PROPOSALS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List<FederationProposal></td></tr>
	114	<tr><td>LIST_FEDERATION_SETS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List<FederationSet></td></tr>
	115	<tr><td>LIST_SETTINGS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>ServerSettings (all keys)</td></tr>
	116	<tr><td>EDIT_SETTINGS</td><td>-</td><td><em>admin</em></td><td>1</td><td>Map<String, String></td><td>-</td></tr>
	117	<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	118	</table>
JM	119
b75734	120	### RPC/HTTP Response Codes
6c4be1	121
3cc6e2	122	<table class="table">
595bbf	123	<tr><th>code</th><th>name</th><th>description</th></tr>
JM	124	<tr><td>200</td><td>success</td><td>Gitblit processed the request successfully</td></tr>
	125	<tr><td>401</td><td>unauthorized</td><td>Gitblit requires user credentials to process the request</td></tr>
	126	<tr><td>403</td><td>forbidden</td><td>Gitblit can not process the request for the supplied credentials</td></tr>
	127	<tr><td>405</td><td>method not allowed</td><td>Gitblit has disallowed the processing the specified request</td></tr>
	128	<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>
	129	<tr><td>501</td><td>unknown request</td><td>Gitblit does not recognize the RPC request type</td></tr>
	130	</table>
4cd2f6	131
JM	132	### Example: LIST_REPOSITORIES
	133
234572	134	url: https://localhost/rpc/?req=LIST_REPOSITORIES
4cd2f6	135	response body: Map<String, RepositoryModel> where the map key is the clone url of the repository
6c4be1	136
JM	137	```json
4cd2f6	138	{
JM	139	"https://localhost/git/libraries/xmlapache.git": {
	140	"name": "libraries/xmlapache.git",
	141	"description": "apache xmlrpc client and server",
	142	"owner": "admin",
	143	"lastChange": "2010-01-28T22:12:06Z",
	144	"hasCommits": true,
	145	"showRemoteBranches": false,
	146	"useTickets": false,
	147	"useDocs": false,
	148	"accessRestriction": "VIEW",
	149	"isFrozen": false,
	150	"showReadme": false,
	151	"federationStrategy": "FEDERATE_THIS",
	152	"federationSets": [
	153	"libraries"
	154	],
	155	"isFederated": false,
84c1d5	156	"skipSizeCalculation": false,
d40adc	157	"skipSummaryMetrics": false,
4cd2f6	158	"size": "102 KB"
JM	159	},
	160	"https://localhost/git/libraries/smack.git": {
	161	"name": "libraries/smack.git",
	162	"description": "smack xmpp client",
	163	"owner": "admin",
	164	"lastChange": "2009-01-28T18:38:14Z",
	165	"hasCommits": true,
	166	"showRemoteBranches": false,
	167	"useTickets": false,
	168	"useDocs": false,
	169	"accessRestriction": "VIEW",
	170	"isFrozen": false,
	171	"showReadme": false,
	172	"federationStrategy": "FEDERATE_THIS",
	173	"federationSets": [],
	174	"isFederated": false,
84c1d5	175	"skipSizeCalculation": false,
d40adc	176	"skipSummaryMetrics": false,
4cd2f6	177	"size": "4.8 MB"
JM	178	}
	179	}
6c4be1	180	```
4cd2f6	181
JM	182	### Example: EDIT_REPOSITORY (rename)
	183
	184	The original repository name is specified in the name url parameter. The new name is set within the JSON object.
	185
234572	186	url: https://localhost/rpc/?req=EDIT_REPOSITORY&name=libraries/xmlapache.git
4cd2f6	187	post body: RepositoryModel
6c4be1	188
JM	189	```json
4cd2f6	190	{
JM	191	"name": "libraries/xmlapache-renamed.git",
	192	"description": "apache xmlrpc client and server",
	193	"owner": "admin",
	194	"lastChange": "2010-01-28T22:12:06Z",
	195	"hasCommits": true,
	196	"showRemoteBranches": false,
	197	"useTickets": false,
	198	"useDocs": false,
	199	"accessRestriction": "VIEW",
	200	"isFrozen": false,
	201	"showReadme": false,
	202	"federationStrategy": "FEDERATE_THIS",
	203	"federationSets": [
	204	"libraries"
	205	],
	206	"isFederated": false,
d40adc	207	"skipSizeCalculation": false,
JM	208	"skipSummaryMetrics": false,
4cd2f6	209	"size": "102 KB"
JM	210	}
6c4be1	211	```
4cd2f6	212
JM	213	### Example: LIST_USERS
234572	214	url: https://localhost/rpc/?req=LIST_USERS
4cd2f6	215	response body: List<UserModel>
6c4be1	216
JM	217	```json
4cd2f6	218	[
JM	219	{
	220	"username": "admin",
	221	"password": "admin",
	222	"canAdmin": true,
	223	"excludeFromFederation": true,
	224	"repositories": []
	225	},
	226	{
	227	"username": "test",
	228	"password": "test",
	229	"canAdmin": false,
	230	"excludeFromFederation": false,
	231	"repositories": [
	232	"libraries/xmlapache.git",
	233	"libraries/smack.git"
	234	]
	235	}
	236	]
6c4be1	237	```
b75734	238
JM	239	### Example: LIST_SETTINGS
234572	240	url: https://localhost/rpc/?req=LIST_SETTINGS
84c1d5	241	response body: ServerSettings
6c4be1	242
JM	243	```json
b75734	244	{
84c1d5	245	"settings": {
JM	246	"web.siteName": {
	247	"name": "web.siteName",
	248	"currentValue": "",
	249	"defaultValue": "",
	250	"description": "Gitblit Web Settings\nIf blank Gitblit is displayed.",
	251	"since": "0.5.0",
	252	"caseSensitive": false,
	253	"restartRequired": false,
	254	"spaceDelimited": false
	255	},
	256	"web.summaryCommitCount": {
	257	"name": "web.summaryCommitCount",
	258	"currentValue": "16",
	259	"defaultValue": "16",
	260	"description": "The number of commits to display on the summary page\nValue must exceed 0 else default of 16 is used",
	261	"since": "0.5.0",
	262	"caseSensitive": false,
	263	"restartRequired": false,
	264	"spaceDelimited": false
	265	}
b75734	266	}
JM	267	}
6c4be1	268	```
84c1d5	269
JM	270	### Example: LIST_STATUS
234572	271	url: https://localhost/rpc/?req=LIST_STATUS
84c1d5	272	response body: ServerStatus
6c4be1	273
JM	274	```json
84c1d5	275	{
JM	276	"bootDate": "2011-10-22T12:13:00Z",
c75304	277	"version": "0.7.0-SNAPSHOT",
JM	278	"releaseDate": "PENDING",
	279	"isGO": true,
84c1d5	280	"systemProperties": {
JM	281	"file.encoding": "Cp1252",
	282	"java.home": "C:\\Program Files\\Java\\jdk1.6.0_26\\jre",
	283	"java.io.tmpdir": "C:\\Users\\JAMESM~1\\AppData\\Local\\Temp\\",
	284	"java.runtime.name": "Java(TM) SE Runtime Environment",
	285	"java.runtime.version": "1.6.0_26-b03",
	286	"java.vendor": "Sun Microsystems Inc.",
	287	"java.version": "1.6.0_26",
	288	"java.vm.info": "mixed mode",
	289	"java.vm.name": "Java HotSpot(TM) 64-Bit Server VM",
	290	"java.vm.vendor": "Sun Microsystems Inc.",
	291	"java.vm.version": "20.1-b02",
	292	"os.arch": "amd64",
	293	"os.name": "Windows 7",
	294	"os.version": "6.1"
	295	},
	296	"heapAllocated": 128057344,
	297	"heapFree": 120399168,
c75304	298	"heapSize": 1899560960,
JM	299	"servletContainer": "jetty/7.4.3.v20110701"
84c1d5	300	}
d02011	301	```