|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301 |
- ## 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
-
- [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.
-
- 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.
-
- **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.
-
- <table class="table">
- <tr><th>url parameter</th><th>default</th><th>description</th></tr>
- <tr><td colspan='3'><b>standard query</b></td></tr>
- <tr><td><em>repository</em></td><td><em>required</em></td><td>repository name is part of the url (see examples below)</td></tr>
- <tr><td>ot=</td><td><em>optional</em><br/>default: COMMIT</td><td>object type to return in results. COMMIT or TAG</td></tr>
- <tr><td>h=</td><td><em>optional</em><br/>default: HEAD</td><td>starting branch, ref, or commit id</td></tr>
- <tr><td>l=</td><td><em>optional</em><br/>default: web.syndicationEntries</td><td>maximum return count</td></tr>
- <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>
- <tr><td colspan='3'><b>search query</b></td></tr>
- <tr><td>s=</td><td><em>required</em></td><td>search string</td></tr>
- <tr><td>st=</td><td><em>optional</em><br/>default: COMMIT</td><td>search type</td></tr>
- </table>
-
- ### 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
-
- <table class="table">
- <tbody>
- <tr><th>Release</th><th>Protocol Version</th></tr>
- <tr><td>Gitblit v0.7.0</td><td>1 (inferred version)</td></tr>
- <tr><td>Gitblit v0.8.0</td><td>2</td></tr>
- <tr><td>Gitblit v0.9.0 - v1.0.0</td><td>3</td></tr>
- <tr><td>Gitblit v1.1.0</td><td>4</td></tr>
- <tr><td>Gitblit v1.2.0</td><td>5</td></tr>
- <tr><td>Gitblit v1.3.1</td><td>6</td></tr>
- <tr><td>Gitblit v1.4.0</td><td>7</td></tr>
- <tr><td>Gitblit v1.6.0</td><td>8</td></tr>
- </tbody>
- </table>
-
- #### Protocol Version 5
-
- - *SET_REPOSITORY_MEMBERS* will reject all calls because this would elevate all discrete permissions to RW+
- Use *SET_REPOSITORY_MEMBER_PERMISSIONS* instead.
- - *SET_REPOSITORY_TEAMS* will reject all calls because this would elevate all discrete permissions to RW+
- Use *SET_REPOSITORY_TEAM_PERMISSIONS* instead.
-
- ### RPC Request and Response Types
-
- <table class="table">
- <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>
- <tr><th>req=</th><th>name=</th><th>post body</th><th>response body</th></tr>
- <tr><td colspan='6'><em>web.enableRpcServlet=true</em></td></tr>
- <tr><td>GET_PROTOCOL</td><td>-</td><td>-</td><td>2</td><td>-</td><td>Integer</td></tr>
- <tr><td>LIST_REPOSITORIES</td><td>-</td><td>-</td><td>1</td><td>-</td><td>Map<String, RepositoryModel></td></tr>
- <tr><td>LIST_BRANCHES</td><td>-</td><td>-</td><td>1</td><td>-</td><td>Map<String, List<String>></td></tr>
- <tr><td>LIST_SETTINGS</td><td>-</td><td><em>-</em></td><td>1</td><td>-</td><td>ServerSettings (basic keys)</td></tr>
- <tr><td>GET_USER</td><td>user name</td><td>-</td><td>6</td><td>-</td><td>UserModel</td></tr>
- <tr><td>FORK_REPOSITORY</td><td>repository name</td><td><em>-</em></td><td>8</td><td>-</td><td>-</td></tr>
- <tr><td colspan='6'><em>web.enableRpcManagement=true</em></td></tr>
- <tr><td>CREATE_REPOSITORY</td><td>repository name</td><td><em>admin</em></td><td>1</td><td>RepositoryModel</td><td>-</td></tr>
- <tr><td>EDIT_REPOSITORY</td><td>repository name</td><td><em>admin</em></td><td>1</td><td>RepositoryModel</td><td>-</td></tr>
- <tr><td>DELETE_REPOSITORY</td><td>repository name</td><td><em>admin</em></td><td>1</td><td>RepositoryModel</td><td>-</td></tr>
- <tr><td>LIST_USERS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List<UserModel></td></tr>
- <tr><td>CREATE_USER</td><td>user name</td><td><em>admin</em></td><td>1</td><td>UserModel</td><td>-</td></tr>
- <tr><td>EDIT_USER</td><td>user name</td><td><em>admin</em></td><td>1</td><td>UserModel</td><td>-</td></tr>
- <tr><td>DELETE_USER</td><td>user name</td><td><em>admin</em></td><td>1</td><td>UserModel</td><td>-</td></tr>
- <tr><td>LIST_TEAMS</td><td>-</td><td><em>admin</em></td><td>2</td><td>-</td><td>List<TeamModel></td></tr>
- <tr><td>CREATE_TEAM</td><td>team name</td><td><em>admin</em></td><td>2</td><td>TeamModel</td><td>-</td></tr>
- <tr><td>EDIT_TEAM</td><td>team name</td><td><em>admin</em></td><td>2</td><td>TeamModel</td><td>-</td></tr>
- <tr><td>DELETE_TEAM</td><td>team name</td><td><em>admin</em></td><td>2</td><td>TeamModel</td><td>-</td></tr>
- <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>
- <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>
- <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>
- <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>
- <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>
- <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>
- <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>
- <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>
- <tr><td>LIST_SETTINGS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>ServerSettings (management keys)</td></tr>
- <tr><td>CLEAR_REPOSITORY_CACHE</td><td>-</td><td><em>-</em></td><td>4</td><td>-</td><td>-</td></tr>
- <tr><td>REINDEX_TICKETS</td><td>repository name</td><td><em>-</em></td><td>7</td><td>-</td><td>-</td></tr>
- <tr><td colspan='6'><em>web.enableRpcAdministration=true</em></td></tr>
- <tr><td>LIST_FEDERATION_REGISTRATIONS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List<FederationModel></td></tr>
- <tr><td>LIST_FEDERATION_RESULTS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List<FederationModel></td></tr>
- <tr><td>LIST_FEDERATION_PROPOSALS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List<FederationProposal></td></tr>
- <tr><td>LIST_FEDERATION_SETS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List<FederationSet></td></tr>
- <tr><td>LIST_SETTINGS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>ServerSettings (all keys)</td></tr>
- <tr><td>EDIT_SETTINGS</td><td>-</td><td><em>admin</em></td><td>1</td><td>Map<String, String></td><td>-</td></tr>
- <tr><td>LIST_STATUS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>ServerStatus (see example below)</td></tr>
- </table>
-
- ### RPC/HTTP Response Codes
-
- <table class="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>
-
- ### 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
-
- ```json
- {
- "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
-
- ```json
- {
- "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>
-
- ```json
- [
- {
- "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
-
- ```json
- {
- "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
-
- ```json
- {
- "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"
- }
- ```
|