##// END OF EJS Templates
docs: update api docs
dan -
r618:fadf8638 default
parent child Browse files
Show More
@@ -0,0 +1,77 b''
1 .. _deprecated-methods-ref:
2
3 deprecated methods
4 =================
5
6 changeset_comment
7 -----------------
8
9 .. py:function:: changeset_comment(apiuser, repoid, revision, message, userid=<Optional:<OptionalAttr:apiuser>>, status=<Optional:None>)
10
11 .. deprecated:: 3.4.0
12
13 Please use method `comment_commit` instead.
14
15
16 Set a changeset comment, and optionally change the status of the
17 changeset.
18
19 This command can only be run using an |authtoken| with admin
20 permissions on the |repo|.
21
22 :param apiuser: This is filled automatically from the |authtoken|.
23 :type apiuser: AuthUser
24 :param repoid: Set the repository name or repository ID.
25 :type repoid: str or int
26 :param revision: Specify the revision for which to set a comment.
27 :type revision: str
28 :param message: The comment text.
29 :type message: str
30 :param userid: Set the user name of the comment creator.
31 :type userid: Optional(str or int)
32 :param status: Set the comment status. The following are valid options:
33 * not_reviewed
34 * approved
35 * rejected
36 * under_review
37 :type status: str
38
39 Example error output:
40
41 .. code-block:: json
42
43 {
44 "id" : <id_given_in_input>,
45 "result" : {
46 "msg": "Commented on commit `<revision>` for repository `<repoid>`",
47 "status_change": null or <status>,
48 "success": true
49 },
50 "error" : null
51 }
52
53
54 get_locks
55 ---------
56
57 .. py:function:: get_locks(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)
58
59 .. deprecated:: 4.0.0
60
61 Please use method `get_user_locks` instead.
62
63 None
64
65
66 show_ip
67 -------
68
69 .. py:function:: show_ip(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)
70
71 .. deprecated:: 4.0.0
72
73 Please use method `get_ip` instead.
74
75 None
76
77
@@ -0,0 +1,121 b''
1 .. _gist-methods-ref:
2
3 gist methods
4 =================
5
6 create_gist
7 -----------
8
9 .. py:function:: create_gist(apiuser, files, gistid=<Optional:None>, owner=<Optional:<OptionalAttr:apiuser>>, gist_type=<Optional:u'public'>, lifetime=<Optional:-1>, acl_level=<Optional:u'acl_public'>, description=<Optional:''>)
10
11 Creates a new Gist.
12
13 :param apiuser: This is filled automatically from the |authtoken|.
14 :type apiuser: AuthUser
15 :param files: files to be added to the gist. The data structure has
16 to match the following example::
17
18 {'filename1': {'content':'...'}, 'filename2': {'content':'...'}}
19
20 :type files: dict
21 :param gistid: Set a custom id for the gist
22 :type gistid: Optional(str)
23 :param owner: Set the gist owner, defaults to api method caller
24 :type owner: Optional(str or int)
25 :param gist_type: type of gist ``public`` or ``private``
26 :type gist_type: Optional(str)
27 :param lifetime: time in minutes of gist lifetime
28 :type lifetime: Optional(int)
29 :param acl_level: acl level for this gist, can be
30 ``acl_public`` or ``acl_private`` If the value is set to
31 ``acl_private`` only logged in users are able to access this gist.
32 If not set it defaults to ``acl_public``.
33 :type acl_level: Optional(str)
34 :param description: gist description
35 :type description: Optional(str)
36
37 Example output:
38
39 .. code-block:: bash
40
41 id : <id_given_in_input>
42 result : {
43 "msg": "created new gist",
44 "gist": {}
45 }
46 error : null
47
48 Example error output:
49
50 .. code-block:: bash
51
52 id : <id_given_in_input>
53 result : null
54 error : {
55 "failed to create gist"
56 }
57
58
59 delete_gist
60 -----------
61
62 .. py:function:: delete_gist(apiuser, gistid)
63
64 Deletes existing gist
65
66 :param apiuser: filled automatically from apikey
67 :type apiuser: AuthUser
68 :param gistid: id of gist to delete
69 :type gistid: str
70
71 Example output:
72
73 .. code-block:: bash
74
75 id : <id_given_in_input>
76 result : {
77 "deleted gist ID: <gist_id>",
78 "gist": null
79 }
80 error : null
81
82 Example error output:
83
84 .. code-block:: bash
85
86 id : <id_given_in_input>
87 result : null
88 error : {
89 "failed to delete gist ID:<gist_id>"
90 }
91
92
93 get_gist
94 --------
95
96 .. py:function:: get_gist(apiuser, gistid, content=<Optional:False>)
97
98 Get the specified gist, based on the gist ID.
99
100 :param apiuser: This is filled automatically from the |authtoken|.
101 :type apiuser: AuthUser
102 :param gistid: Set the id of the private or public gist
103 :type gistid: str
104 :param content: Return the gist content. Default is false.
105 :type content: Optional(bool)
106
107
108 get_gists
109 ---------
110
111 .. py:function:: get_gists(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)
112
113 Get all gists for given user. If userid is empty returned gists
114 are for user who called the api
115
116 :param apiuser: This is filled automatically from the |authtoken|.
117 :type apiuser: AuthUser
118 :param userid: user to get gists for
119 :type userid: Optional(str or int)
120
121
@@ -0,0 +1,71 b''
1 .. _license-methods-ref:
2
3 license methods
4 =================
5
6 get_license_info (EE only)
7 ----------------
8
9 .. py:function:: get_license_info(apiuser)
10
11 Returns the |RCE| license information.
12
13 :param apiuser: This is filled automatically from the |authtoken|.
14 :type apiuser: AuthUser
15
16 Example output:
17
18 .. code-block:: bash
19
20 id : <id_given_in_input>
21 result : {
22 'rhodecode_version': <rhodecode version>,
23 'token': <license token>,
24 'issued_to': <license owner>,
25 'issued_on': <license issue date>,
26 'expires_on': <license expiration date>,
27 'type': <license type>,
28 'users_limit': <license users limit>,
29 'key': <license key>
30 }
31 error : null
32
33
34 set_license_key (EE only)
35 ---------------
36
37 .. py:function:: set_license_key(apiuser, key)
38
39 Sets the |RCE| license key.
40
41 :param apiuser: This is filled automatically from the |authtoken|.
42 :type apiuser: AuthUser
43 :param key: This is the license key to be set.
44 :type key: str
45
46 Example output:
47
48 .. code-block:: bash
49
50 id : <id_given_in_input>
51 result: {
52 "msg" : "updated license information",
53 "key": <key>
54 }
55 error: null
56
57 Example error output:
58
59 .. code-block:: bash
60
61 id : <id_given_in_input>
62 result : null
63 error : {
64 "license key is not valid"
65 or
66 "trial licenses cannot be uploaded"
67 or
68 "error occurred while updating license"
69 }
70
71
@@ -0,0 +1,344 b''
1 .. _pull-request-methods-ref:
2
3 pull_request methods
4 =================
5
6 close_pull_request
7 ------------------
8
9 .. py:function:: close_pull_request(apiuser, repoid, pullrequestid, userid=<Optional:<OptionalAttr:apiuser>>)
10
11 Close the pull request specified by `pullrequestid`.
12
13 :param apiuser: This is filled automatically from the |authtoken|.
14 :type apiuser: AuthUser
15 :param repoid: Repository name or repository ID to which the pull
16 request belongs.
17 :type repoid: str or int
18 :param pullrequestid: ID of the pull request to be closed.
19 :type pullrequestid: int
20 :param userid: Close the pull request as this user.
21 :type userid: Optional(str or int)
22
23 Example output:
24
25 .. code-block:: bash
26
27 "id": <id_given_in_input>,
28 "result":
29 {
30 "pull_request_id": "<int>",
31 "closed": "<bool>"
32 },
33 "error": null
34
35
36 comment_pull_request
37 --------------------
38
39 .. py:function:: comment_pull_request(apiuser, repoid, pullrequestid, message=<Optional:None>, status=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>)
40
41 Comment on the pull request specified with the `pullrequestid`,
42 in the |repo| specified by the `repoid`, and optionally change the
43 review status.
44
45 :param apiuser: This is filled automatically from the |authtoken|.
46 :type apiuser: AuthUser
47 :param repoid: The repository name or repository ID.
48 :type repoid: str or int
49 :param pullrequestid: The pull request ID.
50 :type pullrequestid: int
51 :param message: The text content of the comment.
52 :type message: str
53 :param status: (**Optional**) Set the approval status of the pull
54 request. Valid options are:
55 * not_reviewed
56 * approved
57 * rejected
58 * under_review
59 :type status: str
60 :param userid: Comment on the pull request as this user
61 :type userid: Optional(str or int)
62
63 Example output:
64
65 .. code-block:: bash
66
67 id : <id_given_in_input>
68 result :
69 {
70 "pull_request_id": "<Integer>",
71 "comment_id": "<Integer>"
72 }
73 error : null
74
75
76 create_pull_request
77 -------------------
78
79 .. py:function:: create_pull_request(apiuser, source_repo, target_repo, source_ref, target_ref, title, description=<Optional:''>, reviewers=<Optional:None>)
80
81 Creates a new pull request.
82
83 Accepts refs in the following formats:
84
85 * branch:<branch_name>:<sha>
86 * branch:<branch_name>
87 * bookmark:<bookmark_name>:<sha> (Mercurial only)
88 * bookmark:<bookmark_name> (Mercurial only)
89
90 :param apiuser: This is filled automatically from the |authtoken|.
91 :type apiuser: AuthUser
92 :param source_repo: Set the source repository name.
93 :type source_repo: str
94 :param target_repo: Set the target repository name.
95 :type target_repo: str
96 :param source_ref: Set the source ref name.
97 :type source_ref: str
98 :param target_ref: Set the target ref name.
99 :type target_ref: str
100 :param title: Set the pull request title.
101 :type title: str
102 :param description: Set the pull request description.
103 :type description: Optional(str)
104 :param reviewers: Set the new pull request reviewers list.
105 :type reviewers: Optional(list)
106
107
108 get_pull_request
109 ----------------
110
111 .. py:function:: get_pull_request(apiuser, repoid, pullrequestid)
112
113 Get a pull request based on the given ID.
114
115 :param apiuser: This is filled automatically from the |authtoken|.
116 :type apiuser: AuthUser
117 :param repoid: Repository name or repository ID from where the pull
118 request was opened.
119 :type repoid: str or int
120 :param pullrequestid: ID of the requested pull request.
121 :type pullrequestid: int
122
123 Example output:
124
125 .. code-block:: bash
126
127 "id": <id_given_in_input>,
128 "result":
129 {
130 "pull_request_id": "<pull_request_id>",
131 "url": "<url>",
132 "title": "<title>",
133 "description": "<description>",
134 "status" : "<status>",
135 "created_on": "<date_time_created>",
136 "updated_on": "<date_time_updated>",
137 "commit_ids": [
138 ...
139 "<commit_id>",
140 "<commit_id>",
141 ...
142 ],
143 "review_status": "<review_status>",
144 "mergeable": {
145 "status": "<bool>",
146 "message": "<message>",
147 },
148 "source": {
149 "clone_url": "<clone_url>",
150 "repository": "<repository_name>",
151 "reference":
152 {
153 "name": "<name>",
154 "type": "<type>",
155 "commit_id": "<commit_id>",
156 }
157 },
158 "target": {
159 "clone_url": "<clone_url>",
160 "repository": "<repository_name>",
161 "reference":
162 {
163 "name": "<name>",
164 "type": "<type>",
165 "commit_id": "<commit_id>",
166 }
167 },
168 "author": <user_obj>,
169 "reviewers": [
170 ...
171 {
172 "user": "<user_obj>",
173 "review_status": "<review_status>",
174 }
175 ...
176 ]
177 },
178 "error": null
179
180
181 get_pull_requests
182 -----------------
183
184 .. py:function:: get_pull_requests(apiuser, repoid, status=<Optional:'new'>)
185
186 Get all pull requests from the repository specified in `repoid`.
187
188 :param apiuser: This is filled automatically from the |authtoken|.
189 :type apiuser: AuthUser
190 :param repoid: Repository name or repository ID.
191 :type repoid: str or int
192 :param status: Only return pull requests with the specified status.
193 Valid options are.
194 * ``new`` (default)
195 * ``open``
196 * ``closed``
197 :type status: str
198
199 Example output:
200
201 .. code-block:: bash
202
203 "id": <id_given_in_input>,
204 "result":
205 [
206 ...
207 {
208 "pull_request_id": "<pull_request_id>",
209 "url": "<url>",
210 "title" : "<title>",
211 "description": "<description>",
212 "status": "<status>",
213 "created_on": "<date_time_created>",
214 "updated_on": "<date_time_updated>",
215 "commit_ids": [
216 ...
217 "<commit_id>",
218 "<commit_id>",
219 ...
220 ],
221 "review_status": "<review_status>",
222 "mergeable": {
223 "status": "<bool>",
224 "message: "<message>",
225 },
226 "source": {
227 "clone_url": "<clone_url>",
228 "reference":
229 {
230 "name": "<name>",
231 "type": "<type>",
232 "commit_id": "<commit_id>",
233 }
234 },
235 "target": {
236 "clone_url": "<clone_url>",
237 "reference":
238 {
239 "name": "<name>",
240 "type": "<type>",
241 "commit_id": "<commit_id>",
242 }
243 },
244 "author": <user_obj>,
245 "reviewers": [
246 ...
247 {
248 "user": "<user_obj>",
249 "review_status": "<review_status>",
250 }
251 ...
252 ]
253 }
254 ...
255 ],
256 "error": null
257
258
259 merge_pull_request
260 ------------------
261
262 .. py:function:: merge_pull_request(apiuser, repoid, pullrequestid, userid=<Optional:<OptionalAttr:apiuser>>)
263
264 Merge the pull request specified by `pullrequestid` into its target
265 repository.
266
267 :param apiuser: This is filled automatically from the |authtoken|.
268 :type apiuser: AuthUser
269 :param repoid: The Repository name or repository ID of the
270 target repository to which the |pr| is to be merged.
271 :type repoid: str or int
272 :param pullrequestid: ID of the pull request which shall be merged.
273 :type pullrequestid: int
274 :param userid: Merge the pull request as this user.
275 :type userid: Optional(str or int)
276
277 Example output:
278
279 .. code-block:: bash
280
281 "id": <id_given_in_input>,
282 "result":
283 {
284 "executed": "<bool>",
285 "failure_reason": "<int>",
286 "merge_commit_id": "<merge_commit_id>",
287 "possible": "<bool>"
288 },
289 "error": null
290
291
292 update_pull_request
293 -------------------
294
295 .. py:function:: update_pull_request(apiuser, repoid, pullrequestid, title=<Optional:''>, description=<Optional:''>, reviewers=<Optional:None>, update_commits=<Optional:None>, close_pull_request=<Optional:None>)
296
297 Updates a pull request.
298
299 :param apiuser: This is filled automatically from the |authtoken|.
300 :type apiuser: AuthUser
301 :param repoid: The repository name or repository ID.
302 :type repoid: str or int
303 :param pullrequestid: The pull request ID.
304 :type pullrequestid: int
305 :param title: Set the pull request title.
306 :type title: str
307 :param description: Update pull request description.
308 :type description: Optional(str)
309 :param reviewers: Update pull request reviewers list with new value.
310 :type reviewers: Optional(list)
311 :param update_commits: Trigger update of commits for this pull request
312 :type: update_commits: Optional(bool)
313 :param close_pull_request: Close this pull request with rejected state
314 :type: close_pull_request: Optional(bool)
315
316 Example output:
317
318 .. code-block:: bash
319
320 id : <id_given_in_input>
321 result :
322 {
323 "msg": "Updated pull request `63`",
324 "pull_request": <pull_request_object>,
325 "updated_reviewers": {
326 "added": [
327 "username"
328 ],
329 "removed": []
330 },
331 "updated_commits": {
332 "added": [
333 "<sha1_hash>"
334 ],
335 "common": [
336 "<sha1_hash>",
337 "<sha1_hash>",
338 ],
339 "removed": []
340 }
341 }
342 error : null
343
344
@@ -0,0 +1,350 b''
1 .. _repo-group-methods-ref:
2
3 repo_group methods
4 =================
5
6 create_repo_group
7 -----------------
8
9 .. py:function:: create_repo_group(apiuser, group_name, description=<Optional:''>, owner=<Optional:<OptionalAttr:apiuser>>, copy_permissions=<Optional:False>)
10
11 Creates a repository group.
12
13 * If the repository group name contains "/", all the required repository
14 groups will be created.
15
16 For example "foo/bar/baz" will create |repo| groups "foo" and "bar"
17 (with "foo" as parent). It will also create the "baz" repository
18 with "bar" as |repo| group.
19
20 This command can only be run using an |authtoken| with admin
21 permissions.
22
23 :param apiuser: This is filled automatically from the |authtoken|.
24 :type apiuser: AuthUser
25 :param group_name: Set the repository group name.
26 :type group_name: str
27 :param description: Set the |repo| group description.
28 :type description: str
29 :param owner: Set the |repo| group owner.
30 :type owner: str
31 :param copy_permissions:
32 :type copy_permissions:
33
34 Example output:
35
36 .. code-block:: bash
37
38 id : <id_given_in_input>
39 result : {
40 "msg": "Created new repo group `<repo_group_name>`"
41 "repo_group": <repogroup_object>
42 }
43 error : null
44
45
46 Example error output:
47
48 .. code-block:: bash
49
50 id : <id_given_in_input>
51 result : null
52 error : {
53 failed to create repo group `<repogroupid>`
54 }
55
56
57 delete_repo_group
58 -----------------
59
60 .. py:function:: delete_repo_group(apiuser, repogroupid)
61
62 Deletes a |repo| group.
63
64 :param apiuser: This is filled automatically from the |authtoken|.
65 :type apiuser: AuthUser
66 :param repogroupid: Set the name or ID of repository group to be
67 deleted.
68 :type repogroupid: str or int
69
70 Example output:
71
72 .. code-block:: bash
73
74 id : <id_given_in_input>
75 result : {
76 'msg': 'deleted repo group ID:<repogroupid> <repogroupname>
77 'repo_group': null
78 }
79 error : null
80
81 Example error output:
82
83 .. code-block:: bash
84
85 id : <id_given_in_input>
86 result : null
87 error : {
88 "failed to delete repo group ID:<repogroupid> <repogroupname>"
89 }
90
91
92 get_repo_group
93 --------------
94
95 .. py:function:: get_repo_group(apiuser, repogroupid)
96
97 Return the specified |repo| group, along with permissions,
98 and repositories inside the group
99
100 :param apiuser: This is filled automatically from the |authtoken|.
101 :type apiuser: AuthUser
102 :param repogroupid: Specify the name of ID of the repository group.
103 :type repogroupid: str or int
104
105
106 Example output:
107
108 .. code-block:: bash
109
110 {
111 "error": null,
112 "id": repo-group-id,
113 "result": {
114 "group_description": "repo group description",
115 "group_id": 14,
116 "group_name": "group name",
117 "members": [
118 {
119 "name": "super-admin-username",
120 "origin": "super-admin",
121 "permission": "group.admin",
122 "type": "user"
123 },
124 {
125 "name": "owner-name",
126 "origin": "owner",
127 "permission": "group.admin",
128 "type": "user"
129 },
130 {
131 "name": "user-group-name",
132 "origin": "permission",
133 "permission": "group.write",
134 "type": "user_group"
135 }
136 ],
137 "owner": "owner-name",
138 "parent_group": null,
139 "repositories": [ repo-list ]
140 }
141 }
142
143
144 get_repo_groups
145 ---------------
146
147 .. py:function:: get_repo_groups(apiuser)
148
149 Returns all repository groups.
150
151 :param apiuser: This is filled automatically from the |authtoken|.
152 :type apiuser: AuthUser
153
154
155 grant_user_group_permission_to_repo_group
156 -----------------------------------------
157
158 .. py:function:: grant_user_group_permission_to_repo_group(apiuser, repogroupid, usergroupid, perm, apply_to_children=<Optional:'none'>)
159
160 Grant permission for a user group on given repository group, or update
161 existing permissions if found.
162
163 This command can only be run using an |authtoken| with admin
164 permissions on the |repo| group.
165
166 :param apiuser: This is filled automatically from the |authtoken|.
167 :type apiuser: AuthUser
168 :param repogroupid: Set the name or id of repository group
169 :type repogroupid: str or int
170 :param usergroupid: id of usergroup
171 :type usergroupid: str or int
172 :param perm: (group.(none|read|write|admin))
173 :type perm: str
174 :param apply_to_children: 'none', 'repos', 'groups', 'all'
175 :type apply_to_children: str
176
177 Example output:
178
179 .. code-block:: bash
180
181 id : <id_given_in_input>
182 result : {
183 "msg" : "Granted perm: `<perm>` (recursive:<apply_to_children>) for user group: `<usersgroupname>` in repo group: `<repo_group_name>`",
184 "success": true
185
186 }
187 error : null
188
189 Example error output:
190
191 .. code-block:: bash
192
193 id : <id_given_in_input>
194 result : null
195 error : {
196 "failed to edit permission for user group: `<usergroup>` in repo group: `<repo_group_name>`"
197 }
198
199
200 grant_user_permission_to_repo_group
201 -----------------------------------
202
203 .. py:function:: grant_user_permission_to_repo_group(apiuser, repogroupid, userid, perm, apply_to_children=<Optional:'none'>)
204
205 Grant permission for a user on the given repository group, or update
206 existing permissions if found.
207
208 This command can only be run using an |authtoken| with admin
209 permissions.
210
211 :param apiuser: This is filled automatically from the |authtoken|.
212 :type apiuser: AuthUser
213 :param repogroupid: Set the name or ID of repository group.
214 :type repogroupid: str or int
215 :param userid: Set the user name.
216 :type userid: str
217 :param perm: (group.(none|read|write|admin))
218 :type perm: str
219 :param apply_to_children: 'none', 'repos', 'groups', 'all'
220 :type apply_to_children: str
221
222 Example output:
223
224 .. code-block:: bash
225
226 id : <id_given_in_input>
227 result: {
228 "msg" : "Granted perm: `<perm>` (recursive:<apply_to_children>) for user: `<username>` in repo group: `<repo_group_name>`",
229 "success": true
230 }
231 error: null
232
233 Example error output:
234
235 .. code-block:: bash
236
237 id : <id_given_in_input>
238 result : null
239 error : {
240 "failed to edit permission for user: `<userid>` in repo group: `<repo_group_name>`"
241 }
242
243
244 revoke_user_group_permission_from_repo_group
245 --------------------------------------------
246
247 .. py:function:: revoke_user_group_permission_from_repo_group(apiuser, repogroupid, usergroupid, apply_to_children=<Optional:'none'>)
248
249 Revoke permission for user group on given repository.
250
251 This command can only be run using an |authtoken| with admin
252 permissions on the |repo| group.
253
254 :param apiuser: This is filled automatically from the |authtoken|.
255 :type apiuser: AuthUser
256 :param repogroupid: name or id of repository group
257 :type repogroupid: str or int
258 :param usergroupid:
259 :param apply_to_children: 'none', 'repos', 'groups', 'all'
260 :type apply_to_children: str
261
262 Example output:
263
264 .. code-block:: bash
265
266 id : <id_given_in_input>
267 result: {
268 "msg" : "Revoked perm (recursive:<apply_to_children>) for user group: `<usersgroupname>` in repo group: `<repo_group_name>`",
269 "success": true
270 }
271 error: null
272
273 Example error output:
274
275 .. code-block:: bash
276
277 id : <id_given_in_input>
278 result : null
279 error : {
280 "failed to edit permission for user group: `<usergroup>` in repo group: `<repo_group_name>`"
281 }
282
283
284 revoke_user_permission_from_repo_group
285 --------------------------------------
286
287 .. py:function:: revoke_user_permission_from_repo_group(apiuser, repogroupid, userid, apply_to_children=<Optional:'none'>)
288
289 Revoke permission for a user in a given repository group.
290
291 This command can only be run using an |authtoken| with admin
292 permissions on the |repo| group.
293
294 :param apiuser: This is filled automatically from the |authtoken|.
295 :type apiuser: AuthUser
296 :param repogroupid: Set the name or ID of the repository group.
297 :type repogroupid: str or int
298 :param userid: Set the user name to revoke.
299 :type userid: str
300 :param apply_to_children: 'none', 'repos', 'groups', 'all'
301 :type apply_to_children: str
302
303 Example output:
304
305 .. code-block:: bash
306
307 id : <id_given_in_input>
308 result: {
309 "msg" : "Revoked perm (recursive:<apply_to_children>) for user: `<username>` in repo group: `<repo_group_name>`",
310 "success": true
311 }
312 error: null
313
314 Example error output:
315
316 .. code-block:: bash
317
318 id : <id_given_in_input>
319 result : null
320 error : {
321 "failed to edit permission for user: `<userid>` in repo group: `<repo_group_name>`"
322 }
323
324
325 update_repo_group
326 -----------------
327
328 .. py:function:: update_repo_group(apiuser, repogroupid, group_name=<Optional:''>, description=<Optional:''>, owner=<Optional:<OptionalAttr:apiuser>>, parent=<Optional:None>, enable_locking=<Optional:False>)
329
330 Updates repository group with the details given.
331
332 This command can only be run using an |authtoken| with admin
333 permissions.
334
335 :param apiuser: This is filled automatically from the |authtoken|.
336 :type apiuser: AuthUser
337 :param repogroupid: Set the ID of repository group.
338 :type repogroupid: str or int
339 :param group_name: Set the name of the |repo| group.
340 :type group_name: str
341 :param description: Set a description for the group.
342 :type description: str
343 :param owner: Set the |repo| group owner.
344 :type owner: str
345 :param parent: Set the |repo| group parent.
346 :type parent: str or int
347 :param enable_locking: Enable |repo| locking. The default is false.
348 :type enable_locking: bool
349
350
This diff has been collapsed as it changes many lines, (967 lines changed) Show them Hide them
@@ -0,0 +1,967 b''
1 .. _repo-methods-ref:
2
3 repo methods
4 =================
5
6 add_field_to_repo
7 -----------------
8
9 .. py:function:: add_field_to_repo(apiuser, repoid, key, label=<Optional:''>, description=<Optional:''>)
10
11 Adds an extra field to a repository.
12
13 This command can only be run using an |authtoken| with at least
14 write permissions to the |repo|.
15
16 :param apiuser: This is filled automatically from the |authtoken|.
17 :type apiuser: AuthUser
18 :param repoid: Set the repository name or repository id.
19 :type repoid: str or int
20 :param key: Create a unique field key for this repository.
21 :type key: str
22 :param label:
23 :type label: Optional(str)
24 :param description:
25 :type description: Optional(str)
26
27
28 comment_commit
29 --------------
30
31 .. py:function:: comment_commit(apiuser, repoid, commit_id, message, userid=<Optional:<OptionalAttr:apiuser>>, status=<Optional:None>)
32
33 Set a commit comment, and optionally change the status of the commit.
34
35 :param apiuser: This is filled automatically from the |authtoken|.
36 :type apiuser: AuthUser
37 :param repoid: Set the repository name or repository ID.
38 :type repoid: str or int
39 :param commit_id: Specify the commit_id for which to set a comment.
40 :type commit_id: str
41 :param message: The comment text.
42 :type message: str
43 :param userid: Set the user name of the comment creator.
44 :type userid: Optional(str or int)
45 :param status: status, one of 'not_reviewed', 'approved', 'rejected',
46 'under_review'
47 :type status: str
48
49 Example error output:
50
51 .. code-block:: json
52
53 {
54 "id" : <id_given_in_input>,
55 "result" : {
56 "msg": "Commented on commit `<commit_id>` for repository `<repoid>`",
57 "status_change": null or <status>,
58 "success": true
59 },
60 "error" : null
61 }
62
63
64 create_repo
65 -----------
66
67 .. py:function:: create_repo(apiuser, repo_name, repo_type, owner=<Optional:<OptionalAttr:apiuser>>, description=<Optional:''>, private=<Optional:False>, clone_uri=<Optional:None>, landing_rev=<Optional:'rev:tip'>, enable_statistics=<Optional:False>, enable_locking=<Optional:False>, enable_downloads=<Optional:False>, copy_permissions=<Optional:False>)
68
69 Creates a repository.
70
71 * If the repository name contains "/", all the required repository
72 groups will be created.
73
74 For example "foo/bar/baz" will create |repo| groups "foo" and "bar"
75 (with "foo" as parent). It will also create the "baz" repository
76 with "bar" as |repo| group.
77
78 This command can only be run using an |authtoken| with at least
79 write permissions to the |repo|.
80
81 :param apiuser: This is filled automatically from the |authtoken|.
82 :type apiuser: AuthUser
83 :param repo_name: Set the repository name.
84 :type repo_name: str
85 :param repo_type: Set the repository type; 'hg','git', or 'svn'.
86 :type repo_type: str
87 :param owner: user_id or username
88 :type owner: Optional(str)
89 :param description: Set the repository description.
90 :type description: Optional(str)
91 :param private:
92 :type private: bool
93 :param clone_uri:
94 :type clone_uri: str
95 :param landing_rev: <rev_type>:<rev>
96 :type landing_rev: str
97 :param enable_locking:
98 :type enable_locking: bool
99 :param enable_downloads:
100 :type enable_downloads: bool
101 :param enable_statistics:
102 :type enable_statistics: bool
103 :param copy_permissions: Copy permission from group in which the
104 repository is being created.
105 :type copy_permissions: bool
106
107
108 Example output:
109
110 .. code-block:: bash
111
112 id : <id_given_in_input>
113 result: {
114 "msg": "Created new repository `<reponame>`",
115 "success": true,
116 "task": "<celery task id or None if done sync>"
117 }
118 error: null
119
120
121 Example error output:
122
123 .. code-block:: bash
124
125 id : <id_given_in_input>
126 result : null
127 error : {
128 'failed to create repository `<repo_name>`
129 }
130
131
132 delete_repo
133 -----------
134
135 .. py:function:: delete_repo(apiuser, repoid, forks=<Optional:''>)
136
137 Deletes a repository.
138
139 * When the `forks` parameter is set it's possible to detach or delete
140 forks of deleted repository.
141
142 This command can only be run using an |authtoken| with admin
143 permissions on the |repo|.
144
145 :param apiuser: This is filled automatically from the |authtoken|.
146 :type apiuser: AuthUser
147 :param repoid: Set the repository name or repository ID.
148 :type repoid: str or int
149 :param forks: Set to `detach` or `delete` forks from the |repo|.
150 :type forks: Optional(str)
151
152 Example error output:
153
154 .. code-block:: bash
155
156 id : <id_given_in_input>
157 result: {
158 "msg": "Deleted repository `<reponame>`",
159 "success": true
160 }
161 error: null
162
163
164 fork_repo
165 ---------
166
167 .. py:function:: fork_repo(apiuser, repoid, fork_name, owner=<Optional:<OptionalAttr:apiuser>>, description=<Optional:''>, copy_permissions=<Optional:False>, private=<Optional:False>, landing_rev=<Optional:'rev:tip'>)
168
169 Creates a fork of the specified |repo|.
170
171 * If using |RCE| with Celery this will immediately return a success
172 message, even though the fork will be created asynchronously.
173
174 This command can only be run using an |authtoken| with fork
175 permissions on the |repo|.
176
177 :param apiuser: This is filled automatically from the |authtoken|.
178 :type apiuser: AuthUser
179 :param repoid: Set repository name or repository ID.
180 :type repoid: str or int
181 :param fork_name: Set the fork name.
182 :type fork_name: str
183 :param owner: Set the fork owner.
184 :type owner: str
185 :param description: Set the fork descripton.
186 :type description: str
187 :param copy_permissions: Copy permissions from parent |repo|. The
188 default is False.
189 :type copy_permissions: bool
190 :param private: Make the fork private. The default is False.
191 :type private: bool
192 :param landing_rev: Set the landing revision. The default is tip.
193
194 Example output:
195
196 .. code-block:: bash
197
198 id : <id_for_response>
199 api_key : "<api_key>"
200 args: {
201 "repoid" : "<reponame or repo_id>",
202 "fork_name": "<forkname>",
203 "owner": "<username or user_id = Optional(=apiuser)>",
204 "description": "<description>",
205 "copy_permissions": "<bool>",
206 "private": "<bool>",
207 "landing_rev": "<landing_rev>"
208 }
209
210 Example error output:
211
212 .. code-block:: bash
213
214 id : <id_given_in_input>
215 result: {
216 "msg": "Created fork of `<reponame>` as `<forkname>`",
217 "success": true,
218 "task": "<celery task id or None if done sync>"
219 }
220 error: null
221
222
223 get_repo
224 --------
225
226 .. py:function:: get_repo(apiuser, repoid, cache=<Optional:True>)
227
228 Gets an existing repository by its name or repository_id.
229
230 The members section so the output returns users groups or users
231 associated with that repository.
232
233 This command can only be run using an |authtoken| with admin rights,
234 or users with at least read rights to the |repo|.
235
236 :param apiuser: This is filled automatically from the |authtoken|.
237 :type apiuser: AuthUser
238 :param repoid: The repository name or repository id.
239 :type repoid: str or int
240 :param cache: use the cached value for last changeset
241 :type: cache: Optional(bool)
242
243 Example output:
244
245 .. code-block:: bash
246
247 {
248 "error": null,
249 "id": <repo_id>,
250 "result": {
251 "clone_uri": null,
252 "created_on": "timestamp",
253 "description": "repo description",
254 "enable_downloads": false,
255 "enable_locking": false,
256 "enable_statistics": false,
257 "followers": [
258 {
259 "active": true,
260 "admin": false,
261 "api_key": "****************************************",
262 "api_keys": [
263 "****************************************"
264 ],
265 "email": "user@example.com",
266 "emails": [
267 "user@example.com"
268 ],
269 "extern_name": "rhodecode",
270 "extern_type": "rhodecode",
271 "firstname": "username",
272 "ip_addresses": [],
273 "language": null,
274 "last_login": "2015-09-16T17:16:35.854",
275 "lastname": "surname",
276 "user_id": <user_id>,
277 "username": "name"
278 }
279 ],
280 "fork_of": "parent-repo",
281 "landing_rev": [
282 "rev",
283 "tip"
284 ],
285 "last_changeset": {
286 "author": "User <user@example.com>",
287 "branch": "default",
288 "date": "timestamp",
289 "message": "last commit message",
290 "parents": [
291 {
292 "raw_id": "commit-id"
293 }
294 ],
295 "raw_id": "commit-id",
296 "revision": <revision number>,
297 "short_id": "short id"
298 },
299 "lock_reason": null,
300 "locked_by": null,
301 "locked_date": null,
302 "members": [
303 {
304 "name": "super-admin-name",
305 "origin": "super-admin",
306 "permission": "repository.admin",
307 "type": "user"
308 },
309 {
310 "name": "owner-name",
311 "origin": "owner",
312 "permission": "repository.admin",
313 "type": "user"
314 },
315 {
316 "name": "user-group-name",
317 "origin": "permission",
318 "permission": "repository.write",
319 "type": "user_group"
320 }
321 ],
322 "owner": "owner-name",
323 "permissions": [
324 {
325 "name": "super-admin-name",
326 "origin": "super-admin",
327 "permission": "repository.admin",
328 "type": "user"
329 },
330 {
331 "name": "owner-name",
332 "origin": "owner",
333 "permission": "repository.admin",
334 "type": "user"
335 },
336 {
337 "name": "user-group-name",
338 "origin": "permission",
339 "permission": "repository.write",
340 "type": "user_group"
341 }
342 ],
343 "private": true,
344 "repo_id": 676,
345 "repo_name": "user-group/repo-name",
346 "repo_type": "hg"
347 }
348 }
349
350
351 get_repo_changeset
352 ------------------
353
354 .. py:function:: get_repo_changeset(apiuser, repoid, revision, details=<Optional:'basic'>)
355
356 Returns information about a changeset.
357
358 Additionally parameters define the amount of details returned by
359 this function.
360
361 This command can only be run using an |authtoken| with admin rights,
362 or users with at least read rights to the |repo|.
363
364 :param apiuser: This is filled automatically from the |authtoken|.
365 :type apiuser: AuthUser
366 :param repoid: The repository name or repository id
367 :type repoid: str or int
368 :param revision: revision for which listing should be done
369 :type revision: str
370 :param details: details can be 'basic|extended|full' full gives diff
371 info details like the diff itself, and number of changed files etc.
372 :type details: Optional(str)
373
374
375 get_repo_changesets
376 -------------------
377
378 .. py:function:: get_repo_changesets(apiuser, repoid, start_rev, limit, details=<Optional:'basic'>)
379
380 Returns a set of commits limited by the number starting
381 from the `start_rev` option.
382
383 Additional parameters define the amount of details returned by this
384 function.
385
386 This command can only be run using an |authtoken| with admin rights,
387 or users with at least read rights to |repos|.
388
389 :param apiuser: This is filled automatically from the |authtoken|.
390 :type apiuser: AuthUser
391 :param repoid: The repository name or repository ID.
392 :type repoid: str or int
393 :param start_rev: The starting revision from where to get changesets.
394 :type start_rev: str
395 :param limit: Limit the number of commits to this amount
396 :type limit: str or int
397 :param details: Set the level of detail returned. Valid option are:
398 ``basic``, ``extended`` and ``full``.
399 :type details: Optional(str)
400
401 .. note::
402
403 Setting the parameter `details` to the value ``full`` is extensive
404 and returns details like the diff itself, and the number
405 of changed files.
406
407
408 get_repo_nodes
409 --------------
410
411 .. py:function:: get_repo_nodes(apiuser, repoid, revision, root_path, ret_type=<Optional:'all'>, details=<Optional:'basic'>, max_file_bytes=<Optional:None>)
412
413 Returns a list of nodes and children in a flat list for a given
414 path at given revision.
415
416 It's possible to specify ret_type to show only `files` or `dirs`.
417
418 This command can only be run using an |authtoken| with admin rights,
419 or users with at least read rights to |repos|.
420
421 :param apiuser: This is filled automatically from the |authtoken|.
422 :type apiuser: AuthUser
423 :param repoid: The repository name or repository ID.
424 :type repoid: str or int
425 :param revision: The revision for which listing should be done.
426 :type revision: str
427 :param root_path: The path from which to start displaying.
428 :type root_path: str
429 :param ret_type: Set the return type. Valid options are
430 ``all`` (default), ``files`` and ``dirs``.
431 :type ret_type: Optional(str)
432 :param details: Returns extended information about nodes, such as
433 md5, binary, and or content. The valid options are ``basic`` and
434 ``full``.
435 :type details: Optional(str)
436 :param max_file_bytes: Only return file content under this file size bytes
437 :type details: Optional(int)
438
439 Example output:
440
441 .. code-block:: bash
442
443 id : <id_given_in_input>
444 result: [
445 {
446 "name" : "<name>"
447 "type" : "<type>",
448 "binary": "<true|false>" (only in extended mode)
449 "md5" : "<md5 of file content>" (only in extended mode)
450 },
451 ...
452 ]
453 error: null
454
455
456 get_repo_refs
457 -------------
458
459 .. py:function:: get_repo_refs(apiuser, repoid)
460
461 Returns a dictionary of current references. It returns
462 bookmarks, branches, closed_branches, and tags for given repository
463
464 It's possible to specify ret_type to show only `files` or `dirs`.
465
466 This command can only be run using an |authtoken| with admin rights,
467 or users with at least read rights to |repos|.
468
469 :param apiuser: This is filled automatically from the |authtoken|.
470 :type apiuser: AuthUser
471 :param repoid: The repository name or repository ID.
472 :type repoid: str or int
473
474 Example output:
475
476 .. code-block:: bash
477
478 id : <id_given_in_input>
479 result: [
480 TODO...
481 ]
482 error: null
483
484
485 get_repo_settings
486 -----------------
487
488 .. py:function:: get_repo_settings(apiuser, repoid, key=<Optional:None>)
489
490 Returns all settings for a repository. If key is given it only returns the
491 setting identified by the key or null.
492
493 :param apiuser: This is filled automatically from the |authtoken|.
494 :type apiuser: AuthUser
495 :param repoid: The repository name or repository id.
496 :type repoid: str or int
497 :param key: Key of the setting to return.
498 :type: key: Optional(str)
499
500 Example output:
501
502 .. code-block:: bash
503
504 {
505 "error": null,
506 "id": 237,
507 "result": {
508 "extensions_largefiles": true,
509 "hooks_changegroup_push_logger": true,
510 "hooks_changegroup_repo_size": false,
511 "hooks_outgoing_pull_logger": true,
512 "phases_publish": "True",
513 "rhodecode_hg_use_rebase_for_merging": true,
514 "rhodecode_pr_merge_enabled": true,
515 "rhodecode_use_outdated_comments": true
516 }
517 }
518
519
520 get_repos
521 ---------
522
523 .. py:function:: get_repos(apiuser)
524
525 Lists all existing repositories.
526
527 This command can only be run using an |authtoken| with admin rights,
528 or users with at least read rights to |repos|.
529
530 :param apiuser: This is filled automatically from the |authtoken|.
531 :type apiuser: AuthUser
532
533 Example output:
534
535 .. code-block:: bash
536
537 id : <id_given_in_input>
538 result: [
539 {
540 "repo_id" : "<repo_id>",
541 "repo_name" : "<reponame>"
542 "repo_type" : "<repo_type>",
543 "clone_uri" : "<clone_uri>",
544 "private": : "<bool>",
545 "created_on" : "<datetimecreated>",
546 "description" : "<description>",
547 "landing_rev": "<landing_rev>",
548 "owner": "<repo_owner>",
549 "fork_of": "<name_of_fork_parent>",
550 "enable_downloads": "<bool>",
551 "enable_locking": "<bool>",
552 "enable_statistics": "<bool>",
553 },
554 ...
555 ]
556 error: null
557
558
559 grant_user_group_permission
560 ---------------------------
561
562 .. py:function:: grant_user_group_permission(apiuser, repoid, usergroupid, perm)
563
564 Grant permission for a user group on the specified repository,
565 or update existing permissions.
566
567 This command can only be run using an |authtoken| with admin
568 permissions on the |repo|.
569
570 :param apiuser: This is filled automatically from the |authtoken|.
571 :type apiuser: AuthUser
572 :param repoid: Set the repository name or repository ID.
573 :type repoid: str or int
574 :param usergroupid: Specify the ID of the user group.
575 :type usergroupid: str or int
576 :param perm: Set the user group permissions using the following
577 format: (repository.(none|read|write|admin))
578 :type perm: str
579
580 Example output:
581
582 .. code-block:: bash
583
584 id : <id_given_in_input>
585 result : {
586 "msg" : "Granted perm: `<perm>` for group: `<usersgroupname>` in repo: `<reponame>`",
587 "success": true
588
589 }
590 error : null
591
592 Example error output:
593
594 .. code-block:: bash
595
596 id : <id_given_in_input>
597 result : null
598 error : {
599 "failed to edit permission for user group: `<usergroup>` in repo `<repo>`'
600 }
601
602
603 grant_user_permission
604 ---------------------
605
606 .. py:function:: grant_user_permission(apiuser, repoid, userid, perm)
607
608 Grant permissions for the specified user on the given repository,
609 or update existing permissions if found.
610
611 This command can only be run using an |authtoken| with admin
612 permissions on the |repo|.
613
614 :param apiuser: This is filled automatically from the |authtoken|.
615 :type apiuser: AuthUser
616 :param repoid: Set the repository name or repository ID.
617 :type repoid: str or int
618 :param userid: Set the user name.
619 :type userid: str
620 :param perm: Set the user permissions, using the following format
621 ``(repository.(none|read|write|admin))``
622 :type perm: str
623
624 Example output:
625
626 .. code-block:: bash
627
628 id : <id_given_in_input>
629 result: {
630 "msg" : "Granted perm: `<perm>` for user: `<username>` in repo: `<reponame>`",
631 "success": true
632 }
633 error: null
634
635
636 invalidate_cache
637 ----------------
638
639 .. py:function:: invalidate_cache(apiuser, repoid, delete_keys=<Optional:False>)
640
641 Invalidates the cache for the specified repository.
642
643 This command can only be run using an |authtoken| with admin rights to
644 the specified repository.
645
646 This command takes the following options:
647
648 :param apiuser: This is filled automatically from |authtoken|.
649 :type apiuser: AuthUser
650 :param repoid: Sets the repository name or repository ID.
651 :type repoid: str or int
652 :param delete_keys: This deletes the invalidated keys instead of
653 just flagging them.
654 :type delete_keys: Optional(``True`` | ``False``)
655
656 Example output:
657
658 .. code-block:: bash
659
660 id : <id_given_in_input>
661 result : {
662 'msg': Cache for repository `<repository name>` was invalidated,
663 'repository': <repository name>
664 }
665 error : null
666
667 Example error output:
668
669 .. code-block:: bash
670
671 id : <id_given_in_input>
672 result : null
673 error : {
674 'Error occurred during cache invalidation action'
675 }
676
677
678 lock
679 ----
680
681 .. py:function:: lock(apiuser, repoid, locked=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>)
682
683 Sets the lock state of the specified |repo| by the given user.
684 From more information, see :ref:`repo-locking`.
685
686 * If the ``userid`` option is not set, the repository is locked to the
687 user who called the method.
688 * If the ``locked`` parameter is not set, the current lock state of the
689 repository is displayed.
690
691 This command can only be run using an |authtoken| with admin rights to
692 the specified repository.
693
694 This command takes the following options:
695
696 :param apiuser: This is filled automatically from the |authtoken|.
697 :type apiuser: AuthUser
698 :param repoid: Sets the repository name or repository ID.
699 :type repoid: str or int
700 :param locked: Sets the lock state.
701 :type locked: Optional(``True`` | ``False``)
702 :param userid: Set the repository lock to this user.
703 :type userid: Optional(str or int)
704
705 Example error output:
706
707 .. code-block:: bash
708
709 id : <id_given_in_input>
710 result : {
711 'repo': '<reponame>',
712 'locked': <bool: lock state>,
713 'locked_since': <int: lock timestamp>,
714 'locked_by': <username of person who made the lock>,
715 'lock_reason': <str: reason for locking>,
716 'lock_state_changed': <bool: True if lock state has been changed in this request>,
717 'msg': 'Repo `<reponame>` locked by `<username>` on <timestamp>.'
718 or
719 'msg': 'Repo `<repository name>` not locked.'
720 or
721 'msg': 'User `<user name>` set lock state for repo `<repository name>` to `<new lock state>`'
722 }
723 error : null
724
725 Example error output:
726
727 .. code-block:: bash
728
729 id : <id_given_in_input>
730 result : null
731 error : {
732 'Error occurred locking repository `<reponame>`
733 }
734
735
736 pull
737 ----
738
739 .. py:function:: pull(apiuser, repoid)
740
741 Triggers a pull on the given repository from a remote location. You
742 can use this to keep remote repositories up-to-date.
743
744 This command can only be run using an |authtoken| with admin
745 rights to the specified repository. For more information,
746 see :ref:`config-token-ref`.
747
748 This command takes the following options:
749
750 :param apiuser: This is filled automatically from the |authtoken|.
751 :type apiuser: AuthUser
752 :param repoid: The repository name or repository ID.
753 :type repoid: str or int
754
755 Example output:
756
757 .. code-block:: bash
758
759 id : <id_given_in_input>
760 result : {
761 "msg": "Pulled from `<repository name>`"
762 "repository": "<repository name>"
763 }
764 error : null
765
766 Example error output:
767
768 .. code-block:: bash
769
770 id : <id_given_in_input>
771 result : null
772 error : {
773 "Unable to pull changes from `<reponame>`"
774 }
775
776
777 remove_field_from_repo
778 ----------------------
779
780 .. py:function:: remove_field_from_repo(apiuser, repoid, key)
781
782 Removes an extra field from a repository.
783
784 This command can only be run using an |authtoken| with at least
785 write permissions to the |repo|.
786
787 :param apiuser: This is filled automatically from the |authtoken|.
788 :type apiuser: AuthUser
789 :param repoid: Set the repository name or repository ID.
790 :type repoid: str or int
791 :param key: Set the unique field key for this repository.
792 :type key: str
793
794
795 revoke_user_group_permission
796 ----------------------------
797
798 .. py:function:: revoke_user_group_permission(apiuser, repoid, usergroupid)
799
800 Revoke the permissions of a user group on a given repository.
801
802 This command can only be run using an |authtoken| with admin
803 permissions on the |repo|.
804
805 :param apiuser: This is filled automatically from the |authtoken|.
806 :type apiuser: AuthUser
807 :param repoid: Set the repository name or repository ID.
808 :type repoid: str or int
809 :param usergroupid: Specify the user group ID.
810 :type usergroupid: str or int
811
812 Example output:
813
814 .. code-block:: bash
815
816 id : <id_given_in_input>
817 result: {
818 "msg" : "Revoked perm for group: `<usersgroupname>` in repo: `<reponame>`",
819 "success": true
820 }
821 error: null
822
823
824 revoke_user_permission
825 ----------------------
826
827 .. py:function:: revoke_user_permission(apiuser, repoid, userid)
828
829 Revoke permission for a user on the specified repository.
830
831 This command can only be run using an |authtoken| with admin
832 permissions on the |repo|.
833
834 :param apiuser: This is filled automatically from the |authtoken|.
835 :type apiuser: AuthUser
836 :param repoid: Set the repository name or repository ID.
837 :type repoid: str or int
838 :param userid: Set the user name of revoked user.
839 :type userid: str or int
840
841 Example error output:
842
843 .. code-block:: bash
844
845 id : <id_given_in_input>
846 result: {
847 "msg" : "Revoked perm for user: `<username>` in repo: `<reponame>`",
848 "success": true
849 }
850 error: null
851
852
853 set_repo_settings
854 -----------------
855
856 .. py:function:: set_repo_settings(apiuser, repoid, settings)
857
858 Update repository settings. Returns true on success.
859
860 :param apiuser: This is filled automatically from the |authtoken|.
861 :type apiuser: AuthUser
862 :param repoid: The repository name or repository id.
863 :type repoid: str or int
864 :param settings: The new settings for the repository.
865 :type: settings: dict
866
867 Example output:
868
869 .. code-block:: bash
870
871 {
872 "error": null,
873 "id": 237,
874 "result": true
875 }
876
877
878 strip
879 -----
880
881 .. py:function:: strip(apiuser, repoid, revision, branch)
882
883 Strips the given revision from the specified repository.
884
885 * This will remove the revision and all of its decendants.
886
887 This command can only be run using an |authtoken| with admin rights to
888 the specified repository.
889
890 This command takes the following options:
891
892 :param apiuser: This is filled automatically from the |authtoken|.
893 :type apiuser: AuthUser
894 :param repoid: The repository name or repository ID.
895 :type repoid: str or int
896 :param revision: The revision you wish to strip.
897 :type revision: str
898 :param branch: The branch from which to strip the revision.
899 :type branch: str
900
901 Example output:
902
903 .. code-block:: bash
904
905 id : <id_given_in_input>
906 result : {
907 "msg": "'Stripped commit <commit_hash> from repo `<repository name>`'"
908 "repository": "<repository name>"
909 }
910 error : null
911
912 Example error output:
913
914 .. code-block:: bash
915
916 id : <id_given_in_input>
917 result : null
918 error : {
919 "Unable to strip commit <commit_hash> from repo `<repository name>`"
920 }
921
922
923 update_repo
924 -----------
925
926 .. py:function:: update_repo(apiuser, repoid, name=<Optional:None>, owner=<Optional:<OptionalAttr:apiuser>>, group=<Optional:None>, fork_of=<Optional:None>, description=<Optional:''>, private=<Optional:False>, clone_uri=<Optional:None>, landing_rev=<Optional:'rev:tip'>, enable_statistics=<Optional:False>, enable_locking=<Optional:False>, enable_downloads=<Optional:False>, fields=<Optional:''>)
927
928 Updates a repository with the given information.
929
930 This command can only be run using an |authtoken| with at least
931 write permissions to the |repo|.
932
933 :param apiuser: This is filled automatically from the |authtoken|.
934 :type apiuser: AuthUser
935 :param repoid: repository name or repository ID.
936 :type repoid: str or int
937 :param name: Update the |repo| name.
938 :type name: str
939 :param owner: Set the |repo| owner.
940 :type owner: str
941 :param group: Set the |repo| group the |repo| belongs to.
942 :type group: str
943 :param fork_of: Set the master |repo| name.
944 :type fork_of: str
945 :param description: Update the |repo| description.
946 :type description: str
947 :param private: Set the |repo| as private. (True | False)
948 :type private: bool
949 :param clone_uri: Update the |repo| clone URI.
950 :type clone_uri: str
951 :param landing_rev: Set the |repo| landing revision. Default is
952 ``tip``.
953 :type landing_rev: str
954 :param enable_statistics: Enable statistics on the |repo|,
955 (True | False).
956 :type enable_statistics: bool
957 :param enable_locking: Enable |repo| locking.
958 :type enable_locking: bool
959 :param enable_downloads: Enable downloads from the |repo|,
960 (True | False).
961 :type enable_downloads: bool
962 :param fields: Add extra fields to the |repo|. Use the following
963 example format: ``field_key=field_val,field_key2=fieldval2``.
964 Escape ', ' with \,
965 :type fields: str
966
967
@@ -0,0 +1,115 b''
1 .. _server-methods-ref:
2
3 server methods
4 =================
5
6 get_ip
7 ------
8
9 .. py:function:: get_ip(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)
10
11 Displays the IP Address as seen from the |RCE| server.
12
13 * This command displays the IP Address, as well as all the defined IP
14 addresses for the specified user. If the ``userid`` is not set, the
15 data returned is for the user calling the method.
16
17 This command can only be run using an |authtoken| with admin rights to
18 the specified repository.
19
20 This command takes the following options:
21
22 :param apiuser: This is filled automatically from |authtoken|.
23 :type apiuser: AuthUser
24 :param userid: Sets the userid for which associated IP Address data
25 is returned.
26 :type userid: Optional(str or int)
27
28 Example output:
29
30 .. code-block:: bash
31
32 id : <id_given_in_input>
33 result : {
34 "server_ip_addr": "<ip_from_clien>",
35 "user_ips": [
36 {
37 "ip_addr": "<ip_with_mask>",
38 "ip_range": ["<start_ip>", "<end_ip>"],
39 },
40 ...
41 ]
42 }
43
44
45 get_server_info
46 ---------------
47
48 .. py:function:: get_server_info(apiuser)
49
50 Returns the |RCE| server information.
51
52 This includes the running version of |RCE| and all installed
53 packages. This command takes the following options:
54
55 :param apiuser: This is filled automatically from the |authtoken|.
56 :type apiuser: AuthUser
57
58 Example output:
59
60 .. code-block:: bash
61
62 id : <id_given_in_input>
63 result : {
64 'modules': [<module name>,...]
65 'py_version': <python version>,
66 'platform': <platform type>,
67 'rhodecode_version': <rhodecode version>
68 }
69 error : null
70
71
72 rescan_repos
73 ------------
74
75 .. py:function:: rescan_repos(apiuser, remove_obsolete=<Optional:False>)
76
77 Triggers a rescan of the specified repositories.
78
79 * If the ``remove_obsolete`` option is set, it also deletes repositories
80 that are found in the database but not on the file system, so called
81 "clean zombies".
82
83 This command can only be run using an |authtoken| with admin rights to
84 the specified repository.
85
86 This command takes the following options:
87
88 :param apiuser: This is filled automatically from the |authtoken|.
89 :type apiuser: AuthUser
90 :param remove_obsolete: Deletes repositories from the database that
91 are not found on the filesystem.
92 :type remove_obsolete: Optional(``True`` | ``False``)
93
94 Example output:
95
96 .. code-block:: bash
97
98 id : <id_given_in_input>
99 result : {
100 'added': [<added repository name>,...]
101 'removed': [<removed repository name>,...]
102 }
103 error : null
104
105 Example error output:
106
107 .. code-block:: bash
108
109 id : <id_given_in_input>
110 result : null
111 error : {
112 'Error occurred during rescan repositories action'
113 }
114
115
@@ -0,0 +1,406 b''
1 .. _user-group-methods-ref:
2
3 user_group methods
4 =================
5
6 add_user_to_user_group
7 ----------------------
8
9 .. py:function:: add_user_to_user_group(apiuser, usergroupid, userid)
10
11 Adds a user to a `user group`. If the user already exists in the group
12 this command will return false.
13
14 This command can only be run using an |authtoken| with admin rights to
15 the specified user group.
16
17 This command takes the following options:
18
19 :param apiuser: This is filled automatically from the |authtoken|.
20 :type apiuser: AuthUser
21 :param usergroupid: Set the name of the `user group` to which a
22 user will be added.
23 :type usergroupid: int
24 :param userid: Set the `user_id` of the user to add to the group.
25 :type userid: int
26
27 Example output:
28
29 .. code-block:: bash
30
31 id : <id_given_in_input>
32 result : {
33 "success": True|False # depends on if member is in group
34 "msg": "added member `<username>` to user group `<groupname>` |
35 User is already in that group"
36
37 }
38 error : null
39
40 Example error output:
41
42 .. code-block:: bash
43
44 id : <id_given_in_input>
45 result : null
46 error : {
47 "failed to add member to user group `<user_group_name>`"
48 }
49
50
51 create_user_group
52 -----------------
53
54 .. py:function:: create_user_group(apiuser, group_name, description=<Optional:''>, owner=<Optional:<OptionalAttr:apiuser>>, active=<Optional:True>)
55
56 Creates a new user group.
57
58 This command can only be run using an |authtoken| with admin rights to
59 the specified repository.
60
61 This command takes the following options:
62
63 :param apiuser: This is filled automatically from the |authtoken|.
64 :type apiuser: AuthUser
65 :param group_name: Set the name of the new user group.
66 :type group_name: str
67 :param description: Give a description of the new user group.
68 :type description: str
69 :param owner: Set the owner of the new user group.
70 If not set, the owner is the |authtoken| user.
71 :type owner: Optional(str or int)
72 :param active: Set this group as active.
73 :type active: Optional(``True`` | ``False``)
74
75 Example output:
76
77 .. code-block:: bash
78
79 id : <id_given_in_input>
80 result: {
81 "msg": "created new user group `<groupname>`",
82 "user_group": <user_group_object>
83 }
84 error: null
85
86 Example error output:
87
88 .. code-block:: bash
89
90 id : <id_given_in_input>
91 result : null
92 error : {
93 "user group `<group name>` already exist"
94 or
95 "failed to create group `<group name>`"
96 }
97
98
99 delete_user_group
100 -----------------
101
102 .. py:function:: delete_user_group(apiuser, usergroupid)
103
104 Deletes the specified `user group`.
105
106 This command can only be run using an |authtoken| with admin rights to
107 the specified repository.
108
109 This command takes the following options:
110
111 :param apiuser: filled automatically from apikey
112 :type apiuser: AuthUser
113 :param usergroupid:
114 :type usergroupid: int
115
116 Example output:
117
118 .. code-block:: bash
119
120 id : <id_given_in_input>
121 result : {
122 "msg": "deleted user group ID:<user_group_id> <user_group_name>"
123 }
124 error : null
125
126 Example error output:
127
128 .. code-block:: bash
129
130 id : <id_given_in_input>
131 result : null
132 error : {
133 "failed to delete user group ID:<user_group_id> <user_group_name>"
134 or
135 "RepoGroup assigned to <repo_groups_list>"
136 }
137
138
139 get_user_group
140 --------------
141
142 .. py:function:: get_user_group(apiuser, usergroupid)
143
144 Returns the data of an existing user group.
145
146 This command can only be run using an |authtoken| with admin rights to
147 the specified repository.
148
149 :param apiuser: This is filled automatically from the |authtoken|.
150 :type apiuser: AuthUser
151 :param usergroupid: Set the user group from which to return data.
152 :type usergroupid: str or int
153
154 Example error output:
155
156 .. code-block:: bash
157
158 {
159 "error": null,
160 "id": <id>,
161 "result": {
162 "active": true,
163 "group_description": "group description",
164 "group_name": "group name",
165 "members": [
166 {
167 "name": "owner-name",
168 "origin": "owner",
169 "permission": "usergroup.admin",
170 "type": "user"
171 },
172 {
173 {
174 "name": "user name",
175 "origin": "permission",
176 "permission": "usergroup.admin",
177 "type": "user"
178 },
179 {
180 "name": "user group name",
181 "origin": "permission",
182 "permission": "usergroup.write",
183 "type": "user_group"
184 }
185 ],
186 "owner": "owner name",
187 "users": [],
188 "users_group_id": 2
189 }
190 }
191
192
193 get_user_groups
194 ---------------
195
196 .. py:function:: get_user_groups(apiuser)
197
198 Lists all the existing user groups within RhodeCode.
199
200 This command can only be run using an |authtoken| with admin rights to
201 the specified repository.
202
203 This command takes the following options:
204
205 :param apiuser: This is filled automatically from the |authtoken|.
206 :type apiuser: AuthUser
207
208 Example error output:
209
210 .. code-block:: bash
211
212 id : <id_given_in_input>
213 result : [<user_group_obj>,...]
214 error : null
215
216
217 grant_user_group_permission_to_user_group
218 -----------------------------------------
219
220 .. py:function:: grant_user_group_permission_to_user_group(apiuser, usergroupid, sourceusergroupid, perm)
221
222 Give one user group permissions to another user group.
223
224 :param apiuser: This is filled automatically from the |authtoken|.
225 :type apiuser: AuthUser
226 :param usergroupid: Set the user group on which to edit permissions.
227 :type usergroupid: str or int
228 :param sourceusergroupid: Set the source user group to which
229 access/permissions will be granted.
230 :type sourceusergroupid: str or int
231 :param perm: (usergroup.(none|read|write|admin))
232 :type perm: str
233
234 Example output:
235
236 .. code-block:: bash
237
238 id : <id_given_in_input>
239 result : {
240 "msg": "Granted perm: `<perm_name>` for user group: `<source_user_group_name>` in user group: `<user_group_name>`",
241 "success": true
242 }
243 error : null
244
245
246 grant_user_permission_to_user_group
247 -----------------------------------
248
249 .. py:function:: grant_user_permission_to_user_group(apiuser, usergroupid, userid, perm)
250
251 Set permissions for a user in a user group.
252
253 :param apiuser: This is filled automatically from the |authtoken|.
254 :type apiuser: AuthUser
255 :param usergroupid: Set the user group to edit permissions on.
256 :type usergroupid: str or int
257 :param userid: Set the user from whom you wish to set permissions.
258 :type userid: str
259 :param perm: (usergroup.(none|read|write|admin))
260 :type perm: str
261
262 Example output:
263
264 .. code-block:: bash
265
266 id : <id_given_in_input>
267 result : {
268 "msg": "Granted perm: `<perm_name>` for user: `<username>` in user group: `<user_group_name>`",
269 "success": true
270 }
271 error : null
272
273
274 remove_user_from_user_group
275 ---------------------------
276
277 .. py:function:: remove_user_from_user_group(apiuser, usergroupid, userid)
278
279 Removes a user from a user group.
280
281 * If the specified user is not in the group, this command will return
282 `false`.
283
284 This command can only be run using an |authtoken| with admin rights to
285 the specified user group.
286
287 :param apiuser: This is filled automatically from the |authtoken|.
288 :type apiuser: AuthUser
289 :param usergroupid: Sets the user group name.
290 :type usergroupid: str or int
291 :param userid: The user you wish to remove from |RCE|.
292 :type userid: str or int
293
294 Example output:
295
296 .. code-block:: bash
297
298 id : <id_given_in_input>
299 result: {
300 "success": True|False, # depends on if member is in group
301 "msg": "removed member <username> from user group <groupname> |
302 User wasn't in group"
303 }
304 error: null
305
306
307 revoke_user_group_permission_from_user_group
308 --------------------------------------------
309
310 .. py:function:: revoke_user_group_permission_from_user_group(apiuser, usergroupid, sourceusergroupid)
311
312 Revoke the permissions that one user group has to another.
313
314 :param apiuser: This is filled automatically from the |authtoken|.
315 :type apiuser: AuthUser
316 :param usergroupid: Set the user group on which to edit permissions.
317 :type usergroupid: str or int
318 :param sourceusergroupid: Set the user group from which permissions
319 are revoked.
320 :type sourceusergroupid: str or int
321
322 Example output:
323
324 .. code-block:: bash
325
326 id : <id_given_in_input>
327 result : {
328 "msg": "Revoked perm for user group: `<user_group_name>` in user group: `<target_user_group_name>`",
329 "success": true
330 }
331 error : null
332
333
334 revoke_user_permission_from_user_group
335 --------------------------------------
336
337 .. py:function:: revoke_user_permission_from_user_group(apiuser, usergroupid, userid)
338
339 Revoke a users permissions in a user group.
340
341 :param apiuser: This is filled automatically from the |authtoken|.
342 :type apiuser: AuthUser
343 :param usergroupid: Set the user group from which to revoke the user
344 permissions.
345 :type: usergroupid: str or int
346 :param userid: Set the userid of the user whose permissions will be
347 revoked.
348 :type userid: str
349
350 Example output:
351
352 .. code-block:: bash
353
354 id : <id_given_in_input>
355 result : {
356 "msg": "Revoked perm for user: `<username>` in user group: `<user_group_name>`",
357 "success": true
358 }
359 error : null
360
361
362 update_user_group
363 -----------------
364
365 .. py:function:: update_user_group(apiuser, usergroupid, group_name=<Optional:''>, description=<Optional:''>, owner=<Optional:None>, active=<Optional:True>)
366
367 Updates the specified `user group` with the details provided.
368
369 This command can only be run using an |authtoken| with admin rights to
370 the specified repository.
371
372 :param apiuser: This is filled automatically from the |authtoken|.
373 :type apiuser: AuthUser
374 :param usergroupid: Set the id of the `user group` to update.
375 :type usergroupid: str or int
376 :param group_name: Set the new name the `user group`
377 :type group_name: str
378 :param description: Give a description for the `user group`
379 :type description: str
380 :param owner: Set the owner of the `user group`.
381 :type owner: Optional(str or int)
382 :param active: Set the group as active.
383 :type active: Optional(``True`` | ``False``)
384
385 Example output:
386
387 .. code-block:: bash
388
389 id : <id_given_in_input>
390 result : {
391 "msg": 'updated user group ID:<user group id> <user group name>',
392 "user_group": <user_group_object>
393 }
394 error : null
395
396 Example error output:
397
398 .. code-block:: bash
399
400 id : <id_given_in_input>
401 result : null
402 error : {
403 "failed to update user group `<user group name>`"
404 }
405
406
@@ -0,0 +1,295 b''
1 .. _user-methods-ref:
2
3 user methods
4 =================
5
6 create_user
7 -----------
8
9 .. py:function:: create_user(apiuser, username, email, password=<Optional:''>, firstname=<Optional:''>, lastname=<Optional:''>, active=<Optional:True>, admin=<Optional:False>, extern_name=<Optional:'rhodecode'>, extern_type=<Optional:'rhodecode'>, force_password_change=<Optional:False>)
10
11 Creates a new user and returns the new user object.
12
13 This command can only be run using an |authtoken| with admin rights to
14 the specified repository.
15
16 This command takes the following options:
17
18 :param apiuser: This is filled automatically from the |authtoken|.
19 :type apiuser: AuthUser
20 :param username: Set the new username.
21 :type username: str or int
22 :param email: Set the user email address.
23 :type email: str
24 :param password: Set the new user password.
25 :type password: Optional(str)
26 :param firstname: Set the new user firstname.
27 :type firstname: Optional(str)
28 :param lastname: Set the new user surname.
29 :type lastname: Optional(str)
30 :param active: Set the user as active.
31 :type active: Optional(``True`` | ``False``)
32 :param admin: Give the new user admin rights.
33 :type admin: Optional(``True`` | ``False``)
34 :param extern_name: Set the authentication plugin name.
35 Using LDAP this is filled with LDAP UID.
36 :type extern_name: Optional(str)
37 :param extern_type: Set the new user authentication plugin.
38 :type extern_type: Optional(str)
39 :param force_password_change: Force the new user to change password
40 on next login.
41 :type force_password_change: Optional(``True`` | ``False``)
42
43 Example output:
44
45 .. code-block:: bash
46
47 id : <id_given_in_input>
48 result: {
49 "msg" : "created new user `<username>`",
50 "user": <user_obj>
51 }
52 error: null
53
54 Example error output:
55
56 .. code-block:: bash
57
58 id : <id_given_in_input>
59 result : null
60 error : {
61 "user `<username>` already exist"
62 or
63 "email `<email>` already exist"
64 or
65 "failed to create user `<username>`"
66 }
67
68
69 delete_user
70 -----------
71
72 .. py:function:: delete_user(apiuser, userid)
73
74 Deletes the specified user from the |RCE| user database.
75
76 This command can only be run using an |authtoken| with admin rights to
77 the specified repository.
78
79 .. important::
80
81 Ensure all open pull requests and open code review
82 requests to this user are close.
83
84 Also ensure all repositories, or repository groups owned by this
85 user are reassigned before deletion.
86
87 This command takes the following options:
88
89 :param apiuser: This is filled automatically from the |authtoken|.
90 :type apiuser: AuthUser
91 :param userid: Set the user to delete.
92 :type userid: str or int
93
94 Example output:
95
96 .. code-block:: bash
97
98 id : <id_given_in_input>
99 result: {
100 "msg" : "deleted user ID:<userid> <username>",
101 "user": null
102 }
103 error: null
104
105 Example error output:
106
107 .. code-block:: bash
108
109 id : <id_given_in_input>
110 result : null
111 error : {
112 "failed to delete user ID:<userid> <username>"
113 }
114
115
116 get_user
117 --------
118
119 .. py:function:: get_user(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)
120
121 Returns the information associated with a username or userid.
122
123 * If the ``userid`` is not set, this command returns the information
124 for the ``userid`` calling the method.
125
126 .. note::
127
128 Normal users may only run this command against their ``userid``. For
129 full privileges you must run this command using an |authtoken| with
130 admin rights.
131
132 :param apiuser: This is filled automatically from the |authtoken|.
133 :type apiuser: AuthUser
134 :param userid: Sets the userid for which data will be returned.
135 :type userid: Optional(str or int)
136
137 Example output:
138
139 .. code-block:: bash
140
141 {
142 "error": null,
143 "id": <id>,
144 "result": {
145 "active": true,
146 "admin": false,
147 "api_key": "api-key",
148 "api_keys": [ list of keys ],
149 "email": "user@example.com",
150 "emails": [
151 "user@example.com"
152 ],
153 "extern_name": "rhodecode",
154 "extern_type": "rhodecode",
155 "firstname": "username",
156 "ip_addresses": [],
157 "language": null,
158 "last_login": "Timestamp",
159 "lastname": "surnae",
160 "permissions": {
161 "global": [
162 "hg.inherit_default_perms.true",
163 "usergroup.read",
164 "hg.repogroup.create.false",
165 "hg.create.none",
166 "hg.extern_activate.manual",
167 "hg.create.write_on_repogroup.false",
168 "hg.usergroup.create.false",
169 "group.none",
170 "repository.none",
171 "hg.register.none",
172 "hg.fork.repository"
173 ],
174 "repositories": { "username/example": "repository.write"},
175 "repositories_groups": { "user-group/repo": "group.none" },
176 "user_groups": { "user_group_name": "usergroup.read" }
177 },
178 "user_id": 32,
179 "username": "username"
180 }
181 }
182
183
184 get_user_locks
185 --------------
186
187 .. py:function:: get_user_locks(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)
188
189 Displays all repositories locked by the specified user.
190
191 * If this command is run by a non-admin user, it returns
192 a list of |repos| locked by that user.
193
194 This command takes the following options:
195
196 :param apiuser: This is filled automatically from the |authtoken|.
197 :type apiuser: AuthUser
198 :param userid: Sets the userid whose list of locked |repos| will be
199 displayed.
200 :type userid: Optional(str or int)
201
202 Example output:
203
204 .. code-block:: bash
205
206 id : <id_given_in_input>
207 result : {
208 [repo_object, repo_object,...]
209 }
210 error : null
211
212
213 get_users
214 ---------
215
216 .. py:function:: get_users(apiuser)
217
218 Lists all users in the |RCE| user database.
219
220 This command can only be run using an |authtoken| with admin rights to
221 the specified repository.
222
223 This command takes the following options:
224
225 :param apiuser: This is filled automatically from the |authtoken|.
226 :type apiuser: AuthUser
227
228 Example output:
229
230 .. code-block:: bash
231
232 id : <id_given_in_input>
233 result: [<user_object>, ...]
234 error: null
235
236
237 update_user
238 -----------
239
240 .. py:function:: update_user(apiuser, userid, username=<Optional:None>, email=<Optional:None>, password=<Optional:None>, firstname=<Optional:None>, lastname=<Optional:None>, active=<Optional:None>, admin=<Optional:None>, extern_type=<Optional:None>, extern_name=<Optional:None>)
241
242 Updates the details for the specified user, if that user exists.
243
244 This command can only be run using an |authtoken| with admin rights to
245 the specified repository.
246
247 This command takes the following options:
248
249 :param apiuser: This is filled automatically from |authtoken|.
250 :type apiuser: AuthUser
251 :param userid: Set the ``userid`` to update.
252 :type userid: str or int
253 :param username: Set the new username.
254 :type username: str or int
255 :param email: Set the new email.
256 :type email: str
257 :param password: Set the new password.
258 :type password: Optional(str)
259 :param firstname: Set the new first name.
260 :type firstname: Optional(str)
261 :param lastname: Set the new surname.
262 :type lastname: Optional(str)
263 :param active: Set the new user as active.
264 :type active: Optional(``True`` | ``False``)
265 :param admin: Give the user admin rights.
266 :type admin: Optional(``True`` | ``False``)
267 :param extern_name: Set the authentication plugin user name.
268 Using LDAP this is filled with LDAP UID.
269 :type extern_name: Optional(str)
270 :param extern_type: Set the authentication plugin type.
271 :type extern_type: Optional(str)
272
273
274 Example output:
275
276 .. code-block:: bash
277
278 id : <id_given_in_input>
279 result: {
280 "msg" : "updated user ID:<userid> <username>",
281 "user": <user_object>,
282 }
283 error: null
284
285 Example error output:
286
287 .. code-block:: bash
288
289 id : <id_given_in_input>
290 result : null
291 error : {
292 "failed to update user `<username>`"
293 }
294
295
This diff has been collapsed as it changes many lines, (2638 lines changed) Show them Hide them
@@ -1,2825 +1,207 b''
1 .. _api:
1 .. _api:
2
2
3 API Documentation
3 API Documentation
4 =================
4 =================
5
5
6 The |RCE| API uses a single scheme for calling all API methods. The API is
6 The |RCE| API uses a single scheme for calling all API methods. The API is
7 implemented with JSON protocol in both directions. To send API requests to
7 implemented with JSON protocol in both directions. To send API requests to
8 your instance of |RCE|, use the following URL format
8 your instance of |RCE|, use the following URL format
9 ``<your_server>/_admin``
9 ``<your_server>/_admin``
10
10
11 .. note::
11 .. note::
12
12
13 To use the API, you should configure the :file:`~/.rhoderc` file with
13 To use the API, you should configure the :file:`~/.rhoderc` file with
14 access details per instance. For more information, see
14 access details per instance. For more information, see
15 :ref:`config-rhoderc`.
15 :ref:`config-rhoderc`.
16
16
17
17
18 API ACCESS FOR WEB VIEWS
18 API ACCESS FOR WEB VIEWS
19 ------------------------
19 ------------------------
20
20
21 API access can also be turned on for each web view in |RCE| that is
21 API access can also be turned on for each web view in |RCE| that is
22 decorated with a `@LoginRequired` decorator. To enable API access, change
22 decorated with a `@LoginRequired` decorator. To enable API access, change
23 the standard login decorator to `@LoginRequired(api_access=True)`.
23 the standard login decorator to `@LoginRequired(api_access=True)`.
24
24
25 From |RCM| version 1.7.0 you can configure a white list
25 From |RCM| version 1.7.0 you can configure a white list
26 of views that have API access enabled by default. To enable these,
26 of views that have API access enabled by default. To enable these,
27 edit the |RCM| configuration ``.ini`` file. The default location is:
27 edit the |RCM| configuration ``.ini`` file. The default location is:
28
28
29 * |RCM| Pre-2.2.7 :file:`root/rhodecode/data/production.ini`
29 * |RCM| Pre-2.2.7 :file:`root/rhodecode/data/production.ini`
30 * |RCM| 3.0 :file:`/home/{user}/.rccontrol/{instance-id}/rhodecode.ini`
30 * |RCM| 3.0 :file:`/home/{user}/.rccontrol/{instance-id}/rhodecode.ini`
31
31
32 To configure the white list, edit this section of the file. In this
32 To configure the white list, edit this section of the file. In this
33 configuration example, API access is granted to the patch/diff raw file and
33 configuration example, API access is granted to the patch/diff raw file and
34 archive.
34 archive.
35
35
36 .. code-block:: ini
36 .. code-block:: ini
37
37
38 ## List of controllers (using glob syntax) that AUTH TOKENS could be used for access.
38 ## List of controllers (using glob syntax) that AUTH TOKENS could be used for access.
39 ## Adding ?auth_token = <token> to the url authenticates this request as if it
39 ## Adding ?auth_token = <token> to the url authenticates this request as if it
40 ## came from the the logged in user who own this authentication token.
40 ## came from the the logged in user who own this authentication token.
41 ##
41 ##
42 ## Syntax is <ControllerClass>:<function_pattern>.
42 ## Syntax is <ControllerClass>:<function_pattern>.
43 ## The list should be "," separated and on a single line.
43 ## The list should be "," separated and on a single line.
44 ##
44 ##
45 api_access_controllers_whitelist = ChangesetController:changeset_patch,ChangesetController:changeset_raw,ilesController:raw,FilesController:archivefile,
45 api_access_controllers_whitelist = ChangesetController:changeset_patch,ChangesetController:changeset_raw,ilesController:raw,FilesController:archivefile,
46
46
47 After this change, a |RCE| view can be accessed without login by adding a
47 After this change, a |RCE| view can be accessed without login by adding a
48 GET parameter ``?auth_token=<auth_token>`` to a url. For example to
48 GET parameter ``?auth_token=<auth_token>`` to a url. For example to
49 access the raw diff.
49 access the raw diff.
50
50
51 .. code-block:: html
51 .. code-block:: html
52
52
53 http://<server>/<repo>/changeset-diff/<sha>?auth_token=<auth_token>
53 http://<server>/<repo>/changeset-diff/<sha>?auth_token=<auth_token>
54
54
55 By default this is only enabled on RSS/ATOM feed views. Exposing raw diffs is a
55 By default this is only enabled on RSS/ATOM feed views. Exposing raw diffs is a
56 good way to integrate with 3rd party services like code review, or build farms
56 good way to integrate with 3rd party services like code review, or build farms
57 that could download archives.
57 that could download archives.
58
58
59 API ACCESS
59 API ACCESS
60 ----------
60 ----------
61
61
62 All clients are required to send JSON-RPC spec JSON data.
62 All clients are required to send JSON-RPC spec JSON data.
63
63
64 .. code-block:: bash
64 .. code-block:: bash
65
65
66 {
66 {
67 "id:"<id>",
67 "id:"<id>",
68 "auth_token":"<auth_token>",
68 "auth_token":"<auth_token>",
69 "method":"<method_name>",
69 "method":"<method_name>",
70 "args":{"<arg_key>":"<arg_val>"}
70 "args":{"<arg_key>":"<arg_val>"}
71 }
71 }
72
72
73 Example call for auto pulling from remote repositories using curl:
73 Example call for auto pulling from remote repositories using curl:
74
74
75 .. code-block:: bash
75 .. code-block:: bash
76
76
77 curl https://server.com/_admin/api -X POST -H 'content-type:text/plain' --data-binary '{"id":1,
77 curl https://server.com/_admin/api -X POST -H 'content-type:text/plain' --data-binary '{"id":1,
78 "auth_token":"xe7cdb2v278e4evbdf5vs04v832v0efvcbcve4a3","method":"pull", "args":{"repo":"CPython"}}'
78 "auth_token":"xe7cdb2v278e4evbdf5vs04v832v0efvcbcve4a3","method":"pull", "args":{"repo":"CPython"}}'
79
79
80 Provide those parameters:
80 Provide those parameters:
81 - **id** A value of any type, which is used to match the response with the
81 - **id** A value of any type, which is used to match the response with the
82 request that it is replying to.
82 request that it is replying to.
83 - **auth_token** for access and permission validation.
83 - **auth_token** for access and permission validation.
84 - **method** is name of method to call
84 - **method** is name of method to call
85 - **args** is an ``key:value`` list of arguments to pass to method
85 - **args** is an ``key:value`` list of arguments to pass to method
86
86
87 .. note::
87 .. note::
88
88
89 To get your |authtoken|, from the |RCE| interface,
89 To get your |authtoken|, from the |RCE| interface,
90 go to:
90 go to:
91 :menuselection:`username --> My account --> Auth tokens`
91 :menuselection:`username --> My account --> Auth tokens`
92
92
93 For security reasons you should always create a dedicated |authtoken| for
93 For security reasons you should always create a dedicated |authtoken| for
94 API use only.
94 API use only.
95
95
96
96
97 The |RCE| API will always return a JSON-RPC response:
97 The |RCE| API will always return a JSON-RPC response:
98
98
99 .. code-block:: bash
99 .. code-block:: bash
100
100
101 {
101 {
102 "id": <id>, # matching id sent by request
102 "id": <id>, # matching id sent by request
103 "result": "<result>"|null, # JSON formatted result, null if any errors
103 "result": "<result>"|null, # JSON formatted result, null if any errors
104 "error": "null"|<error_message> # JSON formatted error (if any)
104 "error": "null"|<error_message> # JSON formatted error (if any)
105 }
105 }
106
106
107 All responses from API will be with `HTTP/1.0 200 OK` status code.
107 All responses from API will be with `HTTP/1.0 200 OK` status code.
108 If there is an error when calling the API, the *error* key will contain a
108 If there is an error when calling the API, the *error* key will contain a
109 failure description and the *result* will be `null`.
109 failure description and the *result* will be `null`.
110
110
111 API CLIENT
111 API CLIENT
112 ----------
112 ----------
113
113
114 To install the |RCE| API, see :ref:`install-tools`. To configure the API per
114 To install the |RCE| API, see :ref:`install-tools`. To configure the API per
115 instance, see the :ref:`rc-tools` section as you need to configure a
115 instance, see the :ref:`rc-tools` section as you need to configure a
116 :file:`~/.rhoderc` file with your |authtokens|.
116 :file:`~/.rhoderc` file with your |authtokens|.
117
117
118 Once you have set up your instance API access, use the following examples to
118 Once you have set up your instance API access, use the following examples to
119 get started.
119 get started.
120
120
121 .. code-block:: bash
121 .. code-block:: bash
122
122
123 # Getting the 'rhodecode' repository
123 # Getting the 'rhodecode' repository
124 # from a RhodeCode Enterprise instance
124 # from a RhodeCode Enterprise instance
125 rhodecode-api --instance-name=enterprise-1 get_repo repoid:rhodecode
125 rhodecode-api --instance-name=enterprise-1 get_repo repoid:rhodecode
126
126
127 Calling method get_repo => http://127.0.0.1:5000
127 Calling method get_repo => http://127.0.0.1:5000
128 Server response
128 Server response
129 {
129 {
130 <json data>
130 <json data>
131 }
131 }
132
132
133 # Creating a new mercurial repository called 'brand-new'
133 # Creating a new mercurial repository called 'brand-new'
134 # with a description 'Repo-description'
134 # with a description 'Repo-description'
135 rhodecode-api --instance-name=enterprise-1 create_repo repo_name:brand-new repo_type:hg description:Repo-description
135 rhodecode-api --instance-name=enterprise-1 create_repo repo_name:brand-new repo_type:hg description:Repo-description
136 {
136 {
137 "error": null,
137 "error": null,
138 "id": 1110,
138 "id": 1110,
139 "result": {
139 "result": {
140 "msg": "Created new repository `brand-new`",
140 "msg": "Created new repository `brand-new`",
141 "success": true,
141 "success": true,
142 "task": null
142 "task": null
143 }
143 }
144 }
144 }
145
145
146 A broken example, what not to do.
146 A broken example, what not to do.
147
147
148 .. code-block:: bash
148 .. code-block:: bash
149
149
150 # A call missing the required arguments
150 # A call missing the required arguments
151 # and not specifying the instance
151 # and not specifying the instance
152 rhodecode-api get_repo
152 rhodecode-api get_repo
153
153
154 Calling method get_repo => http://127.0.0.1:5000
154 Calling method get_repo => http://127.0.0.1:5000
155 Server response
155 Server response
156 "Missing non optional `repoid` arg in JSON DATA"
156 "Missing non optional `repoid` arg in JSON DATA"
157
157
158 You can specify pure JSON using the ``--format`` parameter.
158 You can specify pure JSON using the ``--format`` parameter.
159
159
160 .. code-block:: bash
160 .. code-block:: bash
161
161
162 rhodecode-api --format=json get_repo repoid:rhodecode
162 rhodecode-api --format=json get_repo repoid:rhodecode
163
163
164 In such case only output that this function shows is pure JSON, we can use that
164 In such case only output that this function shows is pure JSON, we can use that
165 and pipe output to some json formatter.
165 and pipe output to some json formatter.
166
166
167 If output is in pure JSON format, you can pipe output to a JSON formatter.
167 If output is in pure JSON format, you can pipe output to a JSON formatter.
168
168
169 .. code-block:: bash
169 .. code-block:: bash
170
170
171 rhodecode-api --instance-name=enterprise-1 --format=json get_repo repoid:rhodecode | python -m json.tool
171 rhodecode-api --instance-name=enterprise-1 --format=json get_repo repoid:rhodecode | python -m json.tool
172
172
173 API METHODS
173 API METHODS
174 -----------
174 -----------
175
175
176 Each method by default required following arguments.
176 Each method by default required following arguments.
177
177
178 .. code-block:: bash
178 .. code-block:: bash
179
179
180 id : "<id_for_response>"
180 id : "<id_for_response>"
181 auth_token : "<auth_token>"
181 auth_token : "<auth_token>"
182 method : "<method name>"
182 method : "<method name>"
183 args : {}
183 args : {}
184
184
185 Use each **param** from docs and put it in args, Optional parameters
185 Use each **param** from docs and put it in args, Optional parameters
186 are not required in args.
186 are not required in args.
187
187
188 .. code-block:: bash
188 .. code-block:: bash
189
189
190 args: {"repoid": "rhodecode"}
190 args: {"repoid": "rhodecode"}
191
191
192 .. Note: From this point on things are generated by the script in
192 .. Note: From this point on things are generated by the script in
193 `scripts/fabfile.py`. To change things below, update the docstrings in the
193 `scripts/fabfile.py`. To change things below, update the docstrings in the
194 ApiController.
194 ApiController.
195
195
196 .. --- API DEFS MARKER ---
196 .. --- API DEFS MARKER ---
197
197 .. toctree::
198 pull
199 ----
200
201 .. py:function:: pull(apiuser, repoid)
202
203 Triggers a pull on the given repository from a remote location. You
204 can use this to keep remote repositories up-to-date.
205
206 This command can only be run using an |authtoken| with admin
207 rights to the specified repository. For more information,
208 see :ref:`config-token-ref`.
209
210 This command takes the following options:
211
212 :param apiuser: This is filled automatically from the |authtoken|.
213 :type apiuser: AuthUser
214 :param repoid: The repository name or repository ID.
215 :type repoid: str or int
216
217 Example output:
218
219 .. code-block:: bash
220
221 id : <id_given_in_input>
222 result : {
223 "msg": "Pulled from `<repository name>`"
224 "repository": "<repository name>"
225 }
226 error : null
227
228 Example error output:
229
230 .. code-block:: bash
231
232 id : <id_given_in_input>
233 result : null
234 error : {
235 "Unable to pull changes from `<reponame>`"
236 }
237
238
239 strip
240 -----
241
242 .. py:function:: strip(apiuser, repoid, revision, branch)
243
244 Strips the given revision from the specified repository.
245
246 * This will remove the revision and all of its decendants.
247
248 This command can only be run using an |authtoken| with admin rights to
249 the specified repository.
250
251 This command takes the following options:
252
253 :param apiuser: This is filled automatically from the |authtoken|.
254 :type apiuser: AuthUser
255 :param repoid: The repository name or repository ID.
256 :type repoid: str or int
257 :param revision: The revision you wish to strip.
258 :type revision: str
259 :param branch: The branch from which to strip the revision.
260 :type branch: str
261
262 Example output:
263
264 .. code-block:: bash
265
266 id : <id_given_in_input>
267 result : {
268 "msg": "'Stripped commit <commit_hash> from repo `<repository name>`'"
269 "repository": "<repository name>"
270 }
271 error : null
272
273 Example error output:
274
275 .. code-block:: bash
276
277 id : <id_given_in_input>
278 result : null
279 error : {
280 "Unable to strip commit <commit_hash> from repo `<repository name>`"
281 }
282
283
284 rescan_repos
285 ------------
286
287 .. py:function:: rescan_repos(apiuser, remove_obsolete=<Optional:False>)
288
289 Triggers a rescan of the specified repositories.
290
291 * If the ``remove_obsolete`` option is set, it also deletes repositories
292 that are found in the database but not on the file system, so called
293 "clean zombies".
294
295 This command can only be run using an |authtoken| with admin rights to
296 the specified repository.
297
298 This command takes the following options:
299
300 :param apiuser: This is filled automatically from the |authtoken|.
301 :type apiuser: AuthUser
302 :param remove_obsolete: Deletes repositories from the database that
303 are not found on the filesystem.
304 :type remove_obsolete: Optional(``True`` | ``False``)
305
306 Example output:
307
308 .. code-block:: bash
309
310 id : <id_given_in_input>
311 result : {
312 'added': [<added repository name>,...]
313 'removed': [<removed repository name>,...]
314 }
315 error : null
316
317 Example error output:
318
319 .. code-block:: bash
320
321 id : <id_given_in_input>
322 result : null
323 error : {
324 'Error occurred during rescan repositories action'
325 }
326
327
328 invalidate_cache
329 ----------------
330
331 .. py:function:: invalidate_cache(apiuser, repoid, delete_keys=<Optional:False>)
332
333 Invalidates the cache for the specified repository.
334
335 This command can only be run using an |authtoken| with admin rights to
336 the specified repository.
337
338 This command takes the following options:
339
340 :param apiuser: This is filled automatically from |authtoken|.
341 :type apiuser: AuthUser
342 :param repoid: Sets the repository name or repository ID.
343 :type repoid: str or int
344 :param delete_keys: This deletes the invalidated keys instead of
345 just flagging them.
346 :type delete_keys: Optional(``True`` | ``False``)
347
348 Example output:
349
350 .. code-block:: bash
351
352 id : <id_given_in_input>
353 result : {
354 'msg': Cache for repository `<repository name>` was invalidated,
355 'repository': <repository name>
356 }
357 error : null
358
359 Example error output:
360
361 .. code-block:: bash
362
363 id : <id_given_in_input>
364 result : null
365 error : {
366 'Error occurred during cache invalidation action'
367 }
368
369
370 lock
371 ----
372
373 .. py:function:: lock(apiuser, repoid, locked=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>)
374
375 Sets the lock state of the specified |repo| by the given user.
376 From more information, see :ref:`repo-locking`.
377
378 * If the ``userid`` option is not set, the repository is locked to the
379 user who called the method.
380 * If the ``locked`` parameter is not set, the current lock state of the
381 repository is displayed.
382
383 This command can only be run using an |authtoken| with admin rights to
384 the specified repository.
385
386 This command takes the following options:
387
388 :param apiuser: This is filled automatically from the |authtoken|.
389 :type apiuser: AuthUser
390 :param repoid: Sets the repository name or repository ID.
391 :type repoid: str or int
392 :param locked: Sets the lock state.
393 :type locked: Optional(``True`` | ``False``)
394 :param userid: Set the repository lock to this user.
395 :type userid: Optional(str or int)
396
397 Example error output:
398
399 .. code-block:: bash
400
401 id : <id_given_in_input>
402 result : {
403 'repo': '<reponame>',
404 'locked': <bool: lock state>,
405 'locked_since': <int: lock timestamp>,
406 'locked_by': <username of person who made the lock>,
407 'lock_reason': <str: reason for locking>,
408 'lock_state_changed': <bool: True if lock state has been changed in this request>,
409 'msg': 'Repo `<reponame>` locked by `<username>` on <timestamp>.'
410 or
411 'msg': 'Repo `<repository name>` not locked.'
412 or
413 'msg': 'User `<user name>` set lock state for repo `<repository name>` to `<new lock state>`'
414 }
415 error : null
416
417 Example error output:
418
419 .. code-block:: bash
420
421 id : <id_given_in_input>
422 result : null
423 error : {
424 'Error occurred locking repository `<reponame>`
425 }
426
427
428 get_locks
429 ---------
430
431 .. py:function:: get_locks(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)
432
433 Displays all repositories locked by the specified user.
434
435 * If this command is run by a non-admin user, it returns
436 a list of |repos| locked by that user.
437
438 This command takes the following options:
439
440 :param apiuser: This is filled automatically from the |authtoken|.
441 :type apiuser: AuthUser
442 :param userid: Sets the userid whose list of locked |repos| will be
443 displayed.
444 :type userid: Optional(str or int)
445
446 Example output:
447
448 .. code-block:: bash
449
450 id : <id_given_in_input>
451 result : {
452 [repo_object, repo_object,...]
453 }
454 error : null
455
456
457 get_ip
458 ------
459
460 .. py:function:: get_ip(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)
461
462 Displays the IP Address as seen from the |RCE| server.
463
464 * This command displays the IP Address, as well as all the defined IP
465 addresses for the specified user. If the ``userid`` is not set, the
466 data returned is for the user calling the method.
467
468 This command can only be run using an |authtoken| with admin rights to
469 the specified repository.
470
471 This command takes the following options:
472
473 :param apiuser: This is filled automatically from |authtoken|.
474 :type apiuser: AuthUser
475 :param userid: Sets the userid for which associated IP Address data
476 is returned.
477 :type userid: Optional(str or int)
478
479 Example output:
480
481 .. code-block:: bash
482
483 id : <id_given_in_input>
484 result : {
485 "server_ip_addr": "<ip_from_clien>",
486 "user_ips": [
487 {
488 "ip_addr": "<ip_with_mask>",
489 "ip_range": ["<start_ip>", "<end_ip>"],
490 },
491 ...
492 ]
493 }
494
495
496 show_ip
497 -------
498
499 .. py:function:: show_ip(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)
500
501 Displays the IP Address as seen from the |RCE| server.
502
503 * This command displays the IP Address, as well as all the defined IP
504 addresses for the specified user. If the ``userid`` is not set, the
505 data returned is for the user calling the method.
506
507 This command can only be run using an |authtoken| with admin rights to
508 the specified repository.
509
510 This command takes the following options:
511
512 :param apiuser: This is filled automatically from |authtoken|.
513 :type apiuser: AuthUser
514 :param userid: Sets the userid for which associated IP Address data
515 is returned.
516 :type userid: Optional(str or int)
517
518 Example output:
519
520 .. code-block:: bash
521
522 id : <id_given_in_input>
523 result : {
524 "server_ip_addr": "<ip_from_clien>",
525 "user_ips": [
526 {
527 "ip_addr": "<ip_with_mask>",
528 "ip_range": ["<start_ip>", "<end_ip>"],
529 },
530 ...
531 ]
532 }
533
534
535 get_license_info
536 ----------------
537
538 .. py:function:: get_license_info(apiuser)
539
540 Returns the |RCE| license information.
541
542 :param apiuser: This is filled automatically from the |authtoken|.
543 :type apiuser: AuthUser
544
545 Example output:
546
547 .. code-block:: bash
548
549 id : <id_given_in_input>
550 result : {
551 'rhodecode_version': <rhodecode version>,
552 'token': <license token>,
553 'issued_to': <license owner>,
554 'issued_on': <license issue date>,
555 'expires_on': <license expiration date>,
556 'type': <license type>,
557 'users_limit': <license users limit>,
558 'key': <license key>
559 }
560 error : null
561
562
563 set_license_key
564 ---------------
565
566 .. py:function:: set_license_key(apiuser, key)
567
568 Sets the |RCE| license key.
569
570 :param apiuser: This is filled automatically from the |authtoken|.
571 :type apiuser: AuthUser
572 :param key: This is the license key to be set.
573 :type key: str
574
575 Example output:
576
577 .. code-block:: bash
578
579 id : <id_given_in_input>
580 result: {
581 "msg" : "updated license information",
582 "key": <key>
583 }
584 error: null
585
586 Example error output:
587
588 .. code-block:: bash
589
590 id : <id_given_in_input>
591 result : null
592 error : {
593 "license key is not valid"
594 or
595 "trial licenses cannot be uploaded"
596 or
597 "error occurred while updating license"
598 }
599
600
601 get_server_info
602 ---------------
603
604 .. py:function:: get_server_info(apiuser)
605
606 Returns the |RCE| server information.
607
608 This includes the running version of |RCE| and all installed
609 packages. This command takes the following options:
610
611 :param apiuser: This is filled automatically from the |authtoken|.
612 :type apiuser: AuthUser
613
614 Example output:
615
616 .. code-block:: bash
617
618 id : <id_given_in_input>
619 result : {
620 'modules': [<module name>,...]
621 'py_version': <python version>,
622 'platform': <platform type>,
623 'rhodecode_version': <rhodecode version>
624 }
625 error : null
626
627
628 get_user
629 --------
630
631 .. py:function:: get_user(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)
632
633 Returns the information associated with a username or userid.
634
635 * If the ``userid`` is not set, this command returns the information
636 for the ``userid`` calling the method.
637
638 .. note::
639
640 Normal users may only run this command against their ``userid``. For
641 full privileges you must run this command using an |authtoken| with
642 admin rights.
643
644 This command takes the following options:
645
646 :param apiuser: This is filled automatically from the |authtoken|.
647 :type apiuser: AuthUser
648 :param userid: Sets the userid for which data will be returned.
649 :type userid: Optional(str or int)
650
651 Example output:
652
653 .. code-block:: bash
654
655 {
656 "error": null,
657 "id": <id>,
658 "result": {
659 "active": true,
660 "admin": false,
661 "api_key": "api-key",
662 "api_keys": [ list of keys ],
663 "email": "user@example.com",
664 "emails": [
665 "user@example.com"
666 ],
667 "extern_name": "rhodecode",
668 "extern_type": "rhodecode",
669 "firstname": "username",
670 "ip_addresses": [],
671 "language": null,
672 "last_login": "Timestamp",
673 "lastname": "surnae",
674 "permissions": {
675 "global": [
676 "hg.inherit_default_perms.true",
677 "usergroup.read",
678 "hg.repogroup.create.false",
679 "hg.create.none",
680 "hg.extern_activate.manual",
681 "hg.create.write_on_repogroup.false",
682 "hg.usergroup.create.false",
683 "group.none",
684 "repository.none",
685 "hg.register.none",
686 "hg.fork.repository"
687 ],
688 "repositories": { "username/example": "repository.write"},
689 "repositories_groups": { "user-group/repo": "group.none" },
690 "user_groups": { "user_group_name": "usergroup.read" }
691 },
692 "user_id": 32,
693 "username": "username"
694 }
695 }
696
697
698 get_users
699 ---------
700
701 .. py:function:: get_users(apiuser)
702
703 Lists all users in the |RCE| user database.
704
705 This command can only be run using an |authtoken| with admin rights to
706 the specified repository.
707
708 This command takes the following options:
709
710 :param apiuser: This is filled automatically from the |authtoken|.
711 :type apiuser: AuthUser
712
713 Example output:
714
715 .. code-block:: bash
716
717 id : <id_given_in_input>
718 result: [<user_object>, ...]
719 error: null
720
721
722 create_user
723 -----------
724
725 .. py:function:: create_user(apiuser, username, email, password=<Optional:''>, firstname=<Optional:''>, lastname=<Optional:''>, active=<Optional:True>, admin=<Optional:False>, extern_name=<Optional:'rhodecode'>, extern_type=<Optional:'rhodecode'>, force_password_change=<Optional:False>)
726
727 Creates a new user and returns the new user object.
728
729 This command can only be run using an |authtoken| with admin rights to
730 the specified repository.
731
732 This command takes the following options:
733
734 :param apiuser: This is filled automatically from the |authtoken|.
735 :type apiuser: AuthUser
736 :param username: Set the new username.
737 :type username: str or int
738 :param email: Set the user email address.
739 :type email: str
740 :param password: Set the new user password.
741 :type password: Optional(str)
742 :param firstname: Set the new user firstname.
743 :type firstname: Optional(str)
744 :param lastname: Set the new user surname.
745 :type lastname: Optional(str)
746 :param active: Set the user as active.
747 :type active: Optional(``True`` | ``False``)
748 :param admin: Give the new user admin rights.
749 :type admin: Optional(``True`` | ``False``)
750 :param extern_name: Set the authentication plugin name.
751 Using LDAP this is filled with LDAP UID.
752 :type extern_name: Optional(str)
753 :param extern_type: Set the new user authentication plugin.
754 :type extern_type: Optional(str)
755 :param force_password_change: Force the new user to change password
756 on next login.
757 :type force_password_change: Optional(``True`` | ``False``)
758
759 Example output:
760
761 .. code-block:: bash
762
763 id : <id_given_in_input>
764 result: {
765 "msg" : "created new user `<username>`",
766 "user": <user_obj>
767 }
768 error: null
769
770 Example error output:
771
772 .. code-block:: bash
773
774 id : <id_given_in_input>
775 result : null
776 error : {
777 "user `<username>` already exist"
778 or
779 "email `<email>` already exist"
780 or
781 "failed to create user `<username>`"
782 }
783
784
785 update_user
786 -----------
787
788 .. py:function:: update_user(apiuser, userid, username=<Optional:None>, email=<Optional:None>, password=<Optional:None>, firstname=<Optional:None>, lastname=<Optional:None>, active=<Optional:None>, admin=<Optional:None>, extern_type=<Optional:None>, extern_name=<Optional:None>)
789
790 Updates the details for the specified user, if that user exists.
791
792 This command can only be run using an |authtoken| with admin rights to
793 the specified repository.
794
795 This command takes the following options:
796
797 :param apiuser: This is filled automatically from |authtoken|.
798 :type apiuser: AuthUser
799 :param userid: Set the ``userid`` to update.
800 :type userid: str or int
801 :param username: Set the new username.
802 :type username: str or int
803 :param email: Set the new email.
804 :type email: str
805 :param password: Set the new password.
806 :type password: Optional(str)
807 :param firstname: Set the new first name.
808 :type firstname: Optional(str)
809 :param lastname: Set the new surname.
810 :type lastname: Optional(str)
811 :param active: Set the new user as active.
812 :type active: Optional(``True`` | ``False``)
813 :param admin: Give the user admin rights.
814 :type admin: Optional(``True`` | ``False``)
815 :param extern_name: Set the authentication plugin user name.
816 Using LDAP this is filled with LDAP UID.
817 :type extern_name: Optional(str)
818 :param extern_type: Set the authentication plugin type.
819 :type extern_type: Optional(str)
820
821
822 Example output:
823
824 .. code-block:: bash
825
826 id : <id_given_in_input>
827 result: {
828 "msg" : "updated user ID:<userid> <username>",
829 "user": <user_object>,
830 }
831 error: null
832
833 Example error output:
834
835 .. code-block:: bash
836
837 id : <id_given_in_input>
838 result : null
839 error : {
840 "failed to update user `<username>`"
841 }
842
843
844 delete_user
845 -----------
846
847 .. py:function:: delete_user(apiuser, userid)
848
849 Deletes the specified user from the |RCE| user database.
850
851 This command can only be run using an |authtoken| with admin rights to
852 the specified repository.
853
854 .. important::
855
856 Ensure all open pull requests and open code review
857 requests to this user are close.
858
859 Also ensure all repositories, or repository groups owned by this
860 user are reassigned before deletion.
861
862 This command takes the following options:
863
864 :param apiuser: This is filled automatically from the |authtoken|.
865 :type apiuser: AuthUser
866 :param userid: Set the user to delete.
867 :type userid: str or int
868
869 Example output:
870
871 .. code-block:: bash
872
873 id : <id_given_in_input>
874 result: {
875 "msg" : "deleted user ID:<userid> <username>",
876 "user": null
877 }
878 error: null
879
880 Example error output:
881
882 .. code-block:: bash
883
884 id : <id_given_in_input>
885 result : null
886 error : {
887 "failed to delete user ID:<userid> <username>"
888 }
889
890
891 get_user_group
892 --------------
893
894 .. py:function:: get_user_group(apiuser, usergroupid)
895
896 Returns the data of an existing user group.
897
898 This command can only be run using an |authtoken| with admin rights to
899 the specified repository.
900
901 :param apiuser: This is filled automatically from the |authtoken|.
902 :type apiuser: AuthUser
903 :param usergroupid: Set the user group from which to return data.
904 :type usergroupid: str or int
905
906 Example error output:
907
908 .. code-block:: bash
909
910 {
911 "error": null,
912 "id": <id>,
913 "result": {
914 "active": true,
915 "group_description": "group description",
916 "group_name": "group name",
917 "members": [
918 {
919 "name": "owner-name",
920 "origin": "owner",
921 "permission": "usergroup.admin",
922 "type": "user"
923 },
924 {
925 {
926 "name": "user name",
927 "origin": "permission",
928 "permission": "usergroup.admin",
929 "type": "user"
930 },
931 {
932 "name": "user group name",
933 "origin": "permission",
934 "permission": "usergroup.write",
935 "type": "user_group"
936 }
937 ],
938 "owner": "owner name",
939 "users": [],
940 "users_group_id": 2
941 }
942 }
943
944
945 get_user_groups
946 ---------------
947
948 .. py:function:: get_user_groups(apiuser)
949
950 Lists all the existing user groups within RhodeCode.
951
952 This command can only be run using an |authtoken| with admin rights to
953 the specified repository.
954
955 This command takes the following options:
956
957 :param apiuser: This is filled automatically from the |authtoken|.
958 :type apiuser: AuthUser
959
960 Example error output:
961
962 .. code-block:: bash
963
964 id : <id_given_in_input>
965 result : [<user_group_obj>,...]
966 error : null
967
968
969 create_user_group
970 -----------------
971
972 .. py:function:: create_user_group(apiuser, group_name, description=<Optional:''>, owner=<Optional:<OptionalAttr:apiuser>>, active=<Optional:True>)
973
974 Creates a new user group.
975
976 This command can only be run using an |authtoken| with admin rights to
977 the specified repository.
978
979 This command takes the following options:
980
981 :param apiuser: This is filled automatically from the |authtoken|.
982 :type apiuser: AuthUser
983 :param group_name: Set the name of the new user group.
984 :type group_name: str
985 :param description: Give a description of the new user group.
986 :type description: str
987 :param owner: Set the owner of the new user group.
988 If not set, the owner is the |authtoken| user.
989 :type owner: Optional(str or int)
990 :param active: Set this group as active.
991 :type active: Optional(``True`` | ``False``)
992
993 Example output:
994
995 .. code-block:: bash
996
997 id : <id_given_in_input>
998 result: {
999 "msg": "created new user group `<groupname>`",
1000 "user_group": <user_group_object>
1001 }
1002 error: null
1003
1004 Example error output:
1005
1006 .. code-block:: bash
1007
1008 id : <id_given_in_input>
1009 result : null
1010 error : {
1011 "user group `<group name>` already exist"
1012 or
1013 "failed to create group `<group name>`"
1014 }
1015
1016
1017 update_user_group
1018 -----------------
1019
1020 .. py:function:: update_user_group(apiuser, usergroupid, group_name=<Optional:''>, description=<Optional:''>, owner=<Optional:None>, active=<Optional:True>)
1021
1022 Updates the specified `user group` with the details provided.
1023
1024 This command can only be run using an |authtoken| with admin rights to
1025 the specified repository.
1026
1027 :param apiuser: This is filled automatically from the |authtoken|.
1028 :type apiuser: AuthUser
1029 :param usergroupid: Set the id of the `user group` to update.
1030 :type usergroupid: str or int
1031 :param group_name: Set the new name the `user group`
1032 :type group_name: str
1033 :param description: Give a description for the `user group`
1034 :type description: str
1035 :param owner: Set the owner of the `user group`.
1036 :type owner: Optional(str or int)
1037 :param active: Set the group as active.
1038 :type active: Optional(``True`` | ``False``)
1039
1040 Example output:
1041
1042 .. code-block:: bash
1043
1044 id : <id_given_in_input>
1045 result : {
1046 "msg": 'updated user group ID:<user group id> <user group name>',
1047 "user_group": <user_group_object>
1048 }
1049 error : null
1050
1051 Example error output:
1052
1053 .. code-block:: bash
1054
1055 id : <id_given_in_input>
1056 result : null
1057 error : {
1058 "failed to update user group `<user group name>`"
1059 }
1060
1061
1062 delete_user_group
1063 -----------------
1064
1065 .. py:function:: delete_user_group(apiuser, usergroupid)
1066
1067 Deletes the specified `user group`.
1068
1069 This command can only be run using an |authtoken| with admin rights to
1070 the specified repository.
1071
1072 This command takes the following options:
1073
1074 :param apiuser: filled automatically from apikey
1075 :type apiuser: AuthUser
1076 :param usergroupid:
1077 :type usergroupid: int
1078
1079 Example output:
1080
1081 .. code-block:: bash
1082
1083 id : <id_given_in_input>
1084 result : {
1085 "msg": "deleted user group ID:<user_group_id> <user_group_name>"
1086 }
1087 error : null
1088
1089 Example error output:
1090
1091 .. code-block:: bash
1092
1093 id : <id_given_in_input>
1094 result : null
1095 error : {
1096 "failed to delete user group ID:<user_group_id> <user_group_name>"
1097 or
1098 "RepoGroup assigned to <repo_groups_list>"
1099 }
1100
1101
1102 add_user_to_user_group
1103 ----------------------
1104
1105 .. py:function:: add_user_to_user_group(apiuser, usergroupid, userid)
1106
1107 Adds a user to a `user group`. If the user already exists in the group
1108 this command will return false.
1109
1110 This command can only be run using an |authtoken| with admin rights to
1111 the specified user group.
1112
1113 This command takes the following options:
1114
1115 :param apiuser: This is filled automatically from the |authtoken|.
1116 :type apiuser: AuthUser
1117 :param usergroupid: Set the name of the `user group` to which a
1118 user will be added.
1119 :type usergroupid: int
1120 :param userid: Set the `user_id` of the user to add to the group.
1121 :type userid: int
1122
1123 Example output:
1124
1125 .. code-block:: bash
1126
1127 id : <id_given_in_input>
1128 result : {
1129 "success": True|False # depends on if member is in group
1130 "msg": "added member `<username>` to user group `<groupname>` |
1131 User is already in that group"
1132
1133 }
1134 error : null
1135
1136 Example error output:
1137
1138 .. code-block:: bash
1139
1140 id : <id_given_in_input>
1141 result : null
1142 error : {
1143 "failed to add member to user group `<user_group_name>`"
1144 }
1145
1146
1147 remove_user_from_user_group
1148 ---------------------------
1149
1150 .. py:function:: remove_user_from_user_group(apiuser, usergroupid, userid)
1151
1152 Removes a user from a user group.
1153
1154 * If the specified user is not in the group, this command will return
1155 `false`.
1156
1157 This command can only be run using an |authtoken| with admin rights to
1158 the specified user group.
1159
1160 :param apiuser: This is filled automatically from the |authtoken|.
1161 :type apiuser: AuthUser
1162 :param usergroupid: Sets the user group name.
1163 :type usergroupid: str or int
1164 :param userid: The user you wish to remove from |RCE|.
1165 :type userid: str or int
1166
1167 Example output:
1168
1169 .. code-block:: bash
1170
1171 id : <id_given_in_input>
1172 result: {
1173 "success": True|False, # depends on if member is in group
1174 "msg": "removed member <username> from user group <groupname> |
1175 User wasn't in group"
1176 }
1177 error: null
1178
1179
1180 grant_user_permission_to_user_group
1181 -----------------------------------
1182
1183 .. py:function:: grant_user_permission_to_user_group(apiuser, usergroupid, userid, perm)
1184
1185 Set permissions for a user in a user group.
1186
1187 :param apiuser: This is filled automatically from the |authtoken|.
1188 :type apiuser: AuthUser
1189 :param usergroupid: Set the user group to edit permissions on.
1190 :type usergroupid: str or int
1191 :param userid: Set the user from whom you wish to set permissions.
1192 :type userid: str
1193 :param perm: (usergroup.(none|read|write|admin))
1194 :type perm: str
1195
1196 Example output:
1197
1198 .. code-block:: bash
1199
1200 id : <id_given_in_input>
1201 result : {
1202 "msg": "Granted perm: `<perm_name>` for user: `<username>` in user group: `<user_group_name>`",
1203 "success": true
1204 }
1205 error : null
1206
1207
1208 revoke_user_permission_from_user_group
1209 --------------------------------------
1210
1211 .. py:function:: revoke_user_permission_from_user_group(apiuser, usergroupid, userid)
1212
1213 Revoke a users permissions in a user group.
1214
1215 :param apiuser: This is filled automatically from the |authtoken|.
1216 :type apiuser: AuthUser
1217 :param usergroupid: Set the user group from which to revoke the user
1218 permissions.
1219 :type: usergroupid: str or int
1220 :param userid: Set the userid of the user whose permissions will be
1221 revoked.
1222 :type userid: str
1223
1224 Example output:
1225
1226 .. code-block:: bash
1227
1228 id : <id_given_in_input>
1229 result : {
1230 "msg": "Revoked perm for user: `<username>` in user group: `<user_group_name>`",
1231 "success": true
1232 }
1233 error : null
1234
1235
1236 grant_user_group_permission_to_user_group
1237 -----------------------------------------
1238
1239 .. py:function:: grant_user_group_permission_to_user_group(apiuser, usergroupid, sourceusergroupid, perm)
1240
1241 Give one user group permissions to another user group.
1242
1243 :param apiuser: This is filled automatically from the |authtoken|.
1244 :type apiuser: AuthUser
1245 :param usergroupid: Set the user group on which to edit permissions.
1246 :type usergroupid: str or int
1247 :param sourceusergroupid: Set the source user group to which
1248 access/permissions will be granted.
1249 :type sourceusergroupid: str or int
1250 :param perm: (usergroup.(none|read|write|admin))
1251 :type perm: str
1252
1253 Example output:
1254
1255 .. code-block:: bash
1256
1257 id : <id_given_in_input>
1258 result : {
1259 "msg": "Granted perm: `<perm_name>` for user group: `<source_user_group_name>` in user group: `<user_group_name>`",
1260 "success": true
1261 }
1262 error : null
1263
1264
1265 revoke_user_group_permission_from_user_group
1266 --------------------------------------------
1267
1268 .. py:function:: revoke_user_group_permission_from_user_group(apiuser, usergroupid, sourceusergroupid)
1269
1270 Revoke the permissions that one user group has to another.
1271
1272 :param apiuser: This is filled automatically from the |authtoken|.
1273 :type apiuser: AuthUser
1274 :param usergroupid: Set the user group on which to edit permissions.
1275 :type usergroupid: str or int
1276 :param sourceusergroupid: Set the user group from which permissions
1277 are revoked.
1278 :type sourceusergroupid: str or int
1279
1280 Example output:
1281
1282 .. code-block:: bash
1283
1284 id : <id_given_in_input>
1285 result : {
1286 "msg": "Revoked perm for user group: `<user_group_name>` in user group: `<target_user_group_name>`",
1287 "success": true
1288 }
1289 error : null
1290
1291
1292 get_pull_request
1293 ----------------
1294
1295 .. py:function:: get_pull_request(apiuser, repoid, pullrequestid)
1296
1297 Get a pull request based on the given ID.
1298
1299 :param apiuser: This is filled automatically from the |authtoken|.
1300 :type apiuser: AuthUser
1301 :param repoid: Repository name or repository ID from where the pull
1302 request was opened.
1303 :type repoid: str or int
1304 :param pullrequestid: ID of the requested pull request.
1305 :type pullrequestid: int
1306
1307 Example output:
1308
1309 .. code-block:: bash
1310
1311 "id": <id_given_in_input>,
1312 "result":
1313 {
1314 "pull_request_id": "<pull_request_id>",
1315 "url": "<url>",
1316 "title": "<title>",
1317 "description": "<description>",
1318 "status" : "<status>",
1319 "created_on": "<date_time_created>",
1320 "updated_on": "<date_time_updated>",
1321 "commit_ids": [
1322 ...
1323 "<commit_id>",
1324 "<commit_id>",
1325 ...
1326 ],
1327 "review_status": "<review_status>",
1328 "mergeable": {
1329 "status": "<bool>",
1330 "message": "<message>",
1331 },
1332 "source": {
1333 "clone_url": "<clone_url>",
1334 "repository": "<repository_name>",
1335 "reference":
1336 {
1337 "name": "<name>",
1338 "type": "<type>",
1339 "commit_id": "<commit_id>",
1340 }
1341 },
1342 "target": {
1343 "clone_url": "<clone_url>",
1344 "repository": "<repository_name>",
1345 "reference":
1346 {
1347 "name": "<name>",
1348 "type": "<type>",
1349 "commit_id": "<commit_id>",
1350 }
1351 },
1352 "author": <user_obj>,
1353 "reviewers": [
1354 ...
1355 {
1356 "user": "<user_obj>",
1357 "review_status": "<review_status>",
1358 }
1359 ...
1360 ]
1361 },
1362 "error": null
1363
1364
1365 get_pull_requests
1366 -----------------
1367
1368 .. py:function:: get_pull_requests(apiuser, repoid, status=<Optional:'new'>)
1369
1370 Get all pull requests from the repository specified in `repoid`.
1371
1372 :param apiuser: This is filled automatically from the |authtoken|.
1373 :type apiuser: AuthUser
1374 :param repoid: Repository name or repository ID.
1375 :type repoid: str or int
1376 :param status: Only return pull requests with the specified status.
1377 Valid options are.
1378 * ``new`` (default)
1379 * ``open``
1380 * ``closed``
1381 :type status: str
1382
1383 Example output:
1384
1385 .. code-block:: bash
1386
1387 "id": <id_given_in_input>,
1388 "result":
1389 [
1390 ...
1391 {
1392 "pull_request_id": "<pull_request_id>",
1393 "url": "<url>",
1394 "title" : "<title>",
1395 "description": "<description>",
1396 "status": "<status>",
1397 "created_on": "<date_time_created>",
1398 "updated_on": "<date_time_updated>",
1399 "commit_ids": [
1400 ...
1401 "<commit_id>",
1402 "<commit_id>",
1403 ...
1404 ],
1405 "review_status": "<review_status>",
1406 "mergeable": {
1407 "status": "<bool>",
1408 "message: "<message>",
1409 },
1410 "source": {
1411 "clone_url": "<clone_url>",
1412 "reference":
1413 {
1414 "name": "<name>",
1415 "type": "<type>",
1416 "commit_id": "<commit_id>",
1417 }
1418 },
1419 "target": {
1420 "clone_url": "<clone_url>",
1421 "reference":
1422 {
1423 "name": "<name>",
1424 "type": "<type>",
1425 "commit_id": "<commit_id>",
1426 }
1427 },
1428 "author": <user_obj>,
1429 "reviewers": [
1430 ...
1431 {
1432 "user": "<user_obj>",
1433 "review_status": "<review_status>",
1434 }
1435 ...
1436 ]
1437 }
1438 ...
1439 ],
1440 "error": null
1441
1442
1443 merge_pull_request
1444 ------------------
1445
1446 .. py:function:: merge_pull_request(apiuser, repoid, pullrequestid, userid=<Optional:<OptionalAttr:apiuser>>)
1447
1448 Merge the pull request specified by `pullrequestid` into its target
1449 repository.
1450
1451 :param apiuser: This is filled automatically from the |authtoken|.
1452 :type apiuser: AuthUser
1453 :param repoid: The Repository name or repository ID of the
1454 target repository to which the |pr| is to be merged.
1455 :type repoid: str or int
1456 :param pullrequestid: ID of the pull request which shall be merged.
1457 :type pullrequestid: int
1458 :param userid: Merge the pull request as this user.
1459 :type userid: Optional(str or int)
1460
1461 Example output:
1462
1463 .. code-block:: bash
1464
1465 "id": <id_given_in_input>,
1466 "result":
1467 {
1468 "executed": "<bool>",
1469 "failure_reason": "<int>",
1470 "merge_commit_id": "<merge_commit_id>",
1471 "possible": "<bool>"
1472 },
1473 "error": null
1474
1475
1476 close_pull_request
1477 ------------------
1478
1479 .. py:function:: close_pull_request(apiuser, repoid, pullrequestid, userid=<Optional:<OptionalAttr:apiuser>>)
1480
1481 Close the pull request specified by `pullrequestid`.
1482
1483 :param apiuser: This is filled automatically from the |authtoken|.
1484 :type apiuser: AuthUser
1485 :param repoid: Repository name or repository ID to which the pull
1486 request belongs.
1487 :type repoid: str or int
1488 :param pullrequestid: ID of the pull request to be closed.
1489 :type pullrequestid: int
1490 :param userid: Close the pull request as this user.
1491 :type userid: Optional(str or int)
1492
1493 Example output:
1494
1495 .. code-block:: bash
1496
1497 "id": <id_given_in_input>,
1498 "result":
1499 {
1500 "pull_request_id": "<int>",
1501 "closed": "<bool>"
1502 },
1503 "error": null
1504
1505
1506 comment_pull_request
1507 --------------------
1508
1509 .. py:function:: comment_pull_request(apiuser, repoid, pullrequestid, message=<Optional:None>, status=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>)
1510
198
1511 Comment on the pull request specified with the `pullrequestid`,
199 methods/license-methods
1512 in the |repo| specified by the `repoid`, and optionally change the
200 methods/deprecated-methods
1513 review status.
201 methods/gist-methods
1514
202 methods/pull-request-methods
1515 :param apiuser: This is filled automatically from the |authtoken|.
203 methods/repo-methods
1516 :type apiuser: AuthUser
204 methods/repo-group-methods
1517 :param repoid: The repository name or repository ID.
205 methods/server-methods
1518 :type repoid: str or int
206 methods/user-methods
1519 :param pullrequestid: The pull request ID.
207 methods/user-group-methods
1520 :type pullrequestid: int
1521 :param message: The text content of the comment.
1522 :type message: str
1523 :param status: (**Optional**) Set the approval status of the pull
1524 request. Valid options are:
1525 * not_reviewed
1526 * approved
1527 * rejected
1528 * under_review
1529 :type status: str
1530 :param userid: Comment on the pull request as this user
1531 :type userid: Optional(str or int)
1532
1533 Example output:
1534
1535 .. code-block:: bash
1536
1537 id : <id_given_in_input>
1538 result :
1539 {
1540 "pull_request_id": "<Integer>",
1541 "comment_id": "<Integer>"
1542 }
1543 error : null
1544
1545
1546 create_pull_request
1547 -------------------
1548
1549 .. py:function:: create_pull_request(apiuser, source_repo, target_repo, source_ref, target_ref, title, description=<Optional:''>, reviewers=<Optional:None>)
1550
1551 Creates a new pull request.
1552
1553 Accepts refs in the following formats:
1554
1555 * branch:<branch_name>:<sha>
1556 * branch:<branch_name>
1557 * bookmark:<bookmark_name>:<sha> (Mercurial only)
1558 * bookmark:<bookmark_name> (Mercurial only)
1559
1560 :param apiuser: This is filled automatically from the |authtoken|.
1561 :type apiuser: AuthUser
1562 :param source_repo: Set the source repository name.
1563 :type source_repo: str
1564 :param target_repo: Set the target repository name.
1565 :type target_repo: str
1566 :param source_ref: Set the source ref name.
1567 :type source_ref: str
1568 :param target_ref: Set the target ref name.
1569 :type target_ref: str
1570 :param title: Set the pull request title.
1571 :type title: str
1572 :param description: Set the pull request description.
1573 :type description: Optional(str)
1574 :param reviewers: Set the new pull request reviewers list.
1575 :type reviewers: Optional(list)
1576
1577
1578 update_pull_request
1579 -------------------
1580
1581 .. py:function:: update_pull_request(apiuser, repoid, pullrequestid, title=<Optional:''>, description=<Optional:''>, reviewers=<Optional:None>, update_commits=<Optional:None>, close_pull_request=<Optional:None>)
1582
1583 Updates a pull request.
1584
1585 :param apiuser: This is filled automatically from the |authtoken|.
1586 :type apiuser: AuthUser
1587 :param repoid: The repository name or repository ID.
1588 :type repoid: str or int
1589 :param pullrequestid: The pull request ID.
1590 :type pullrequestid: int
1591 :param title: Set the pull request title.
1592 :type title: str
1593 :param description: Update pull request description.
1594 :type description: Optional(str)
1595 :param reviewers: Update pull request reviewers list with new value.
1596 :type reviewers: Optional(list)
1597 :param update_commits: Trigger update of commits for this pull request
1598 :type: update_commits: Optional(bool)
1599 :param close_pull_request: Close this pull request with rejected state
1600 :type: close_pull_request: Optional(bool)
1601
1602 Example output:
1603
1604 .. code-block:: bash
1605
1606 id : <id_given_in_input>
1607 result :
1608 {
1609 "msg": "Updated pull request `63`",
1610 "pull_request": <pull_request_object>,
1611 "updated_reviewers": {
1612 "added": [
1613 "username"
1614 ],
1615 "removed": []
1616 },
1617 "updated_commits": {
1618 "added": [
1619 "<sha1_hash>"
1620 ],
1621 "common": [
1622 "<sha1_hash>",
1623 "<sha1_hash>",
1624 ],
1625 "removed": []
1626 }
1627 }
1628 error : null
1629
1630
1631 get_repo
1632 --------
1633
1634 .. py:function:: get_repo(apiuser, repoid, cache=<Optional:True>)
1635
1636 Gets an existing repository by its name or repository_id.
1637
1638 The members section so the output returns users groups or users
1639 associated with that repository.
1640
1641 This command can only be run using an |authtoken| with admin rights,
1642 or users with at least read rights to the |repo|.
1643
1644 :param apiuser: This is filled automatically from the |authtoken|.
1645 :type apiuser: AuthUser
1646 :param repoid: The repository name or repository id.
1647 :type repoid: str or int
1648 :param cache: use the cached value for last changeset
1649 :type: cache: Optional(bool)
1650
1651 Example output:
1652
1653 .. code-block:: bash
1654
1655 {
1656 "error": null,
1657 "id": <repo_id>,
1658 "result": {
1659 "clone_uri": null,
1660 "created_on": "timestamp",
1661 "description": "repo description",
1662 "enable_downloads": false,
1663 "enable_locking": false,
1664 "enable_statistics": false,
1665 "followers": [
1666 {
1667 "active": true,
1668 "admin": false,
1669 "api_key": "****************************************",
1670 "api_keys": [
1671 "****************************************"
1672 ],
1673 "email": "user@example.com",
1674 "emails": [
1675 "user@example.com"
1676 ],
1677 "extern_name": "rhodecode",
1678 "extern_type": "rhodecode",
1679 "firstname": "username",
1680 "ip_addresses": [],
1681 "language": null,
1682 "last_login": "2015-09-16T17:16:35.854",
1683 "lastname": "surname",
1684 "user_id": <user_id>,
1685 "username": "name"
1686 }
1687 ],
1688 "fork_of": "parent-repo",
1689 "landing_rev": [
1690 "rev",
1691 "tip"
1692 ],
1693 "last_changeset": {
1694 "author": "User <user@example.com>",
1695 "branch": "default",
1696 "date": "timestamp",
1697 "message": "last commit message",
1698 "parents": [
1699 {
1700 "raw_id": "commit-id"
1701 }
1702 ],
1703 "raw_id": "commit-id",
1704 "revision": <revision number>,
1705 "short_id": "short id"
1706 },
1707 "lock_reason": null,
1708 "locked_by": null,
1709 "locked_date": null,
1710 "members": [
1711 {
1712 "name": "super-admin-name",
1713 "origin": "super-admin",
1714 "permission": "repository.admin",
1715 "type": "user"
1716 },
1717 {
1718 "name": "owner-name",
1719 "origin": "owner",
1720 "permission": "repository.admin",
1721 "type": "user"
1722 },
1723 {
1724 "name": "user-group-name",
1725 "origin": "permission",
1726 "permission": "repository.write",
1727 "type": "user_group"
1728 }
1729 ],
1730 "owner": "owner-name",
1731 "permissions": [
1732 {
1733 "name": "super-admin-name",
1734 "origin": "super-admin",
1735 "permission": "repository.admin",
1736 "type": "user"
1737 },
1738 {
1739 "name": "owner-name",
1740 "origin": "owner",
1741 "permission": "repository.admin",
1742 "type": "user"
1743 },
1744 {
1745 "name": "user-group-name",
1746 "origin": "permission",
1747 "permission": "repository.write",
1748 "type": "user_group"
1749 }
1750 ],
1751 "private": true,
1752 "repo_id": 676,
1753 "repo_name": "user-group/repo-name",
1754 "repo_type": "hg"
1755 }
1756 }
1757
1758
1759 get_repos
1760 ---------
1761
1762 .. py:function:: get_repos(apiuser)
1763
1764 Lists all existing repositories.
1765
1766 This command can only be run using an |authtoken| with admin rights,
1767 or users with at least read rights to |repos|.
1768
1769 :param apiuser: This is filled automatically from the |authtoken|.
1770 :type apiuser: AuthUser
1771
1772 Example output:
1773
1774 .. code-block:: bash
1775
1776 id : <id_given_in_input>
1777 result: [
1778 {
1779 "repo_id" : "<repo_id>",
1780 "repo_name" : "<reponame>"
1781 "repo_type" : "<repo_type>",
1782 "clone_uri" : "<clone_uri>",
1783 "private": : "<bool>",
1784 "created_on" : "<datetimecreated>",
1785 "description" : "<description>",
1786 "landing_rev": "<landing_rev>",
1787 "owner": "<repo_owner>",
1788 "fork_of": "<name_of_fork_parent>",
1789 "enable_downloads": "<bool>",
1790 "enable_locking": "<bool>",
1791 "enable_statistics": "<bool>",
1792 },
1793 ...
1794 ]
1795 error: null
1796
1797
1798 get_repo_changeset
1799 ------------------
1800
1801 .. py:function:: get_repo_changeset(apiuser, repoid, revision, details=<Optional:'basic'>)
1802
1803 Returns information about a changeset.
1804
1805 Additionally parameters define the amount of details returned by
1806 this function.
1807
1808 This command can only be run using an |authtoken| with admin rights,
1809 or users with at least read rights to the |repo|.
1810
1811 :param apiuser: This is filled automatically from the |authtoken|.
1812 :type apiuser: AuthUser
1813 :param repoid: The repository name or repository id
1814 :type repoid: str or int
1815 :param revision: revision for which listing should be done
1816 :type revision: str
1817 :param details: details can be 'basic|extended|full' full gives diff
1818 info details like the diff itself, and number of changed files etc.
1819 :type details: Optional(str)
1820
1821
1822 get_repo_changesets
1823 -------------------
1824
1825 .. py:function:: get_repo_changesets(apiuser, repoid, start_rev, limit, details=<Optional:'basic'>)
1826
1827 Returns a set of changesets limited by the number of commits starting
1828 from the `start_rev` option.
1829
1830 Additional parameters define the amount of details returned by this
1831 function.
1832
1833 This command can only be run using an |authtoken| with admin rights,
1834 or users with at least read rights to |repos|.
1835
1836 :param apiuser: This is filled automatically from the |authtoken|.
1837 :type apiuser: AuthUser
1838 :param repoid: The repository name or repository ID.
1839 :type repoid: str or int
1840 :param start_rev: The starting revision from where to get changesets.
1841 :type start_rev: str
1842 :param limit: Limit the number of changesets to this amount
1843 :type limit: str or int
1844 :param details: Set the level of detail returned. Valid option are:
1845 ``basic``, ``extended`` and ``full``.
1846 :type details: Optional(str)
1847
1848 .. note::
1849
1850 Setting the parameter `details` to the value ``full`` is extensive
1851 and returns details like the diff itself, and the number
1852 of changed files.
1853
1854
1855 get_repo_nodes
1856 --------------
1857
1858 .. py:function:: get_repo_nodes(apiuser, repoid, revision, root_path, ret_type=<Optional:'all'>, details=<Optional:'basic'>)
1859
1860 Returns a list of nodes and children in a flat list for a given
1861 path at given revision.
1862
1863 It's possible to specify ret_type to show only `files` or `dirs`.
1864
1865 This command can only be run using an |authtoken| with admin rights,
1866 or users with at least read rights to |repos|.
1867
1868 :param apiuser: This is filled automatically from the |authtoken|.
1869 :type apiuser: AuthUser
1870 :param repoid: The repository name or repository ID.
1871 :type repoid: str or int
1872 :param revision: The revision for which listing should be done.
1873 :type revision: str
1874 :param root_path: The path from which to start displaying.
1875 :type root_path: str
1876 :param ret_type: Set the return type. Valid options are
1877 ``all`` (default), ``files`` and ``dirs``.
1878 :type ret_type: Optional(str)
1879 :param details: Returns extended information about nodes, such as
1880 md5, binary, and or content. The valid options are ``basic`` and
1881 ``full``.
1882 :type details: Optional(str)
1883 :param max_file_bytes: Only return file content under this file size bytes
1884 :type details: Optional(int)
1885
1886 Example output:
1887
1888 .. code-block:: bash
1889
1890 id : <id_given_in_input>
1891 result: [
1892 {
1893 "name" : "<name>"
1894 "type" : "<type>",
1895 "binary": "<true|false>" (only in extended mode)
1896 "md5" : "<md5 of file content>" (only in extended mode)
1897 },
1898 ...
1899 ]
1900 error: null
1901
1902
1903 create_repo
1904 -----------
1905
1906 .. py:function:: create_repo(apiuser, repo_name, repo_type, owner=<Optional:<OptionalAttr:apiuser>>, description=<Optional:''>, private=<Optional:False>, clone_uri=<Optional:None>, landing_rev=<Optional:'rev:tip'>, enable_statistics=<Optional:False>, enable_locking=<Optional:False>, enable_downloads=<Optional:False>, copy_permissions=<Optional:False>)
1907
1908 Creates a repository.
1909
1910 * If the repository name contains "/", all the required repository
1911 groups will be created.
1912
1913 For example "foo/bar/baz" will create |repo| groups "foo" and "bar"
1914 (with "foo" as parent). It will also create the "baz" repository
1915 with "bar" as |repo| group.
1916
1917 This command can only be run using an |authtoken| with at least
1918 write permissions to the |repo|.
1919
1920 :param apiuser: This is filled automatically from the |authtoken|.
1921 :type apiuser: AuthUser
1922 :param repo_name: Set the repository name.
1923 :type repo_name: str
1924 :param repo_type: Set the repository type; 'hg','git', or 'svn'.
1925 :type repo_type: str
1926 :param owner: user_id or username
1927 :type owner: Optional(str)
1928 :param description: Set the repository description.
1929 :type description: Optional(str)
1930 :param private:
1931 :type private: bool
1932 :param clone_uri:
1933 :type clone_uri: str
1934 :param landing_rev: <rev_type>:<rev>
1935 :type landing_rev: str
1936 :param enable_locking:
1937 :type enable_locking: bool
1938 :param enable_downloads:
1939 :type enable_downloads: bool
1940 :param enable_statistics:
1941 :type enable_statistics: bool
1942 :param copy_permissions: Copy permission from group in which the
1943 repository is being created.
1944 :type copy_permissions: bool
1945
1946
1947 Example output:
1948
1949 .. code-block:: bash
1950
1951 id : <id_given_in_input>
1952 result: {
1953 "msg": "Created new repository `<reponame>`",
1954 "success": true,
1955 "task": "<celery task id or None if done sync>"
1956 }
1957 error: null
1958
1959
1960 Example error output:
1961
1962 .. code-block:: bash
1963
1964 id : <id_given_in_input>
1965 result : null
1966 error : {
1967 'failed to create repository `<repo_name>`
1968 }
1969
1970
1971 add_field_to_repo
1972 -----------------
1973
1974 .. py:function:: add_field_to_repo(apiuser, repoid, key, label=<Optional:''>, description=<Optional:''>)
1975
1976 Adds an extra field to a repository.
1977
1978 This command can only be run using an |authtoken| with at least
1979 write permissions to the |repo|.
1980
1981 :param apiuser: This is filled automatically from the |authtoken|.
1982 :type apiuser: AuthUser
1983 :param repoid: Set the repository name or repository id.
1984 :type repoid: str or int
1985 :param key: Create a unique field key for this repository.
1986 :type key: str
1987 :param label:
1988 :type label: Optional(str)
1989 :param description:
1990 :type description: Optional(str)
1991
1992
1993 remove_field_from_repo
1994 ----------------------
1995
1996 .. py:function:: remove_field_from_repo(apiuser, repoid, key)
1997
1998 Removes an extra field from a repository.
1999
2000 This command can only be run using an |authtoken| with at least
2001 write permissions to the |repo|.
2002
2003 :param apiuser: This is filled automatically from the |authtoken|.
2004 :type apiuser: AuthUser
2005 :param repoid: Set the repository name or repository ID.
2006 :type repoid: str or int
2007 :param key: Set the unique field key for this repository.
2008 :type key: str
2009
2010
2011 update_repo
2012 -----------
2013
2014 .. py:function:: update_repo(apiuser, repoid, name=<Optional:None>, owner=<Optional:<OptionalAttr:apiuser>>, group=<Optional:None>, fork_of=<Optional:None>, description=<Optional:''>, private=<Optional:False>, clone_uri=<Optional:None>, landing_rev=<Optional:'rev:tip'>, enable_statistics=<Optional:False>, enable_locking=<Optional:False>, enable_downloads=<Optional:False>, fields=<Optional:''>)
2015
2016 Updates a repository with the given information.
2017
2018 This command can only be run using an |authtoken| with at least
2019 write permissions to the |repo|.
2020
2021 :param apiuser: This is filled automatically from the |authtoken|.
2022 :type apiuser: AuthUser
2023 :param repoid: repository name or repository ID.
2024 :type repoid: str or int
2025 :param name: Update the |repo| name.
2026 :type name: str
2027 :param owner: Set the |repo| owner.
2028 :type owner: str
2029 :param group: Set the |repo| group the |repo| belongs to.
2030 :type group: str
2031 :param fork_of: Set the master |repo| name.
2032 :type fork_of: str
2033 :param description: Update the |repo| description.
2034 :type description: str
2035 :param private: Set the |repo| as private. (True | False)
2036 :type private: bool
2037 :param clone_uri: Update the |repo| clone URI.
2038 :type clone_uri: str
2039 :param landing_rev: Set the |repo| landing revision. Default is
2040 ``tip``.
2041 :type landing_rev: str
2042 :param enable_statistics: Enable statistics on the |repo|,
2043 (True | False).
2044 :type enable_statistics: bool
2045 :param enable_locking: Enable |repo| locking.
2046 :type enable_locking: bool
2047 :param enable_downloads: Enable downloads from the |repo|,
2048 (True | False).
2049 :type enable_downloads: bool
2050 :param fields: Add extra fields to the |repo|. Use the following
2051 example format: ``field_key=field_val,field_key2=fieldval2``.
2052 Escape ', ' with \,
2053 :type fields: str
2054
2055
2056 fork_repo
2057 ---------
2058
2059 .. py:function:: fork_repo(apiuser, repoid, fork_name, owner=<Optional:<OptionalAttr:apiuser>>, description=<Optional:''>, copy_permissions=<Optional:False>, private=<Optional:False>, landing_rev=<Optional:'rev:tip'>)
2060
2061 Creates a fork of the specified |repo|.
2062
2063 * If using |RCE| with Celery this will immediately return a success
2064 message, even though the fork will be created asynchronously.
2065
2066 This command can only be run using an |authtoken| with fork
2067 permissions on the |repo|.
2068
2069 :param apiuser: This is filled automatically from the |authtoken|.
2070 :type apiuser: AuthUser
2071 :param repoid: Set repository name or repository ID.
2072 :type repoid: str or int
2073 :param fork_name: Set the fork name.
2074 :type fork_name: str
2075 :param owner: Set the fork owner.
2076 :type owner: str
2077 :param description: Set the fork descripton.
2078 :type description: str
2079 :param copy_permissions: Copy permissions from parent |repo|. The
2080 default is False.
2081 :type copy_permissions: bool
2082 :param private: Make the fork private. The default is False.
2083 :type private: bool
2084 :param landing_rev: Set the landing revision. The default is tip.
2085
2086 Example output:
2087
2088 .. code-block:: bash
2089
2090 id : <id_for_response>
2091 api_key : "<api_key>"
2092 args: {
2093 "repoid" : "<reponame or repo_id>",
2094 "fork_name": "<forkname>",
2095 "owner": "<username or user_id = Optional(=apiuser)>",
2096 "description": "<description>",
2097 "copy_permissions": "<bool>",
2098 "private": "<bool>",
2099 "landing_rev": "<landing_rev>"
2100 }
2101
2102 Example error output:
2103
2104 .. code-block:: bash
2105
2106 id : <id_given_in_input>
2107 result: {
2108 "msg": "Created fork of `<reponame>` as `<forkname>`",
2109 "success": true,
2110 "task": "<celery task id or None if done sync>"
2111 }
2112 error: null
2113
2114
2115 delete_repo
2116 -----------
2117
2118 .. py:function:: delete_repo(apiuser, repoid, forks=<Optional:''>)
2119
2120 Deletes a repository.
2121
2122 * When the `forks` parameter is set it's possible to detach or delete
2123 forks of deleted repository.
2124
2125 This command can only be run using an |authtoken| with admin
2126 permissions on the |repo|.
2127
2128 :param apiuser: This is filled automatically from the |authtoken|.
2129 :type apiuser: AuthUser
2130 :param repoid: Set the repository name or repository ID.
2131 :type repoid: str or int
2132 :param forks: Set to `detach` or `delete` forks from the |repo|.
2133 :type forks: Optional(str)
2134
2135 Example error output:
2136
2137 .. code-block:: bash
2138
2139 id : <id_given_in_input>
2140 result: {
2141 "msg": "Deleted repository `<reponame>`",
2142 "success": true
2143 }
2144 error: null
2145
2146
2147 comment_commit
2148 --------------
2149
2150 .. py:function:: comment_commit(apiuser, repoid, commit_id, message, userid=<Optional:<OptionalAttr:apiuser>>, status=<Optional:None>)
2151
2152 Set a commit comment, and optionally change the status of the commit.
2153 This command can be executed only using api_key belonging to user
2154 with admin rights, or repository administrator.
2155
2156 :param apiuser: This is filled automatically from the |authtoken|.
2157 :type apiuser: AuthUser
2158 :param repoid: Set the repository name or repository ID.
2159 :type repoid: str or int
2160 :param commit_id: Specify the commit_id for which to set a comment.
2161 :type commit_id: str
2162 :param message: The comment text.
2163 :type message: str
2164 :param userid: Set the user name of the comment creator.
2165 :type userid: Optional(str or int)
2166 :param status: status, one of 'not_reviewed', 'approved', 'rejected',
2167 'under_review'
2168 :type status: str
2169
2170 Example error output:
2171
2172 .. code-block:: json
2173
2174 {
2175 "id" : <id_given_in_input>,
2176 "result" : {
2177 "msg": "Commented on commit `<commit_id>` for repository `<repoid>`",
2178 "status_change": null or <status>,
2179 "success": true
2180 },
2181 "error" : null
2182 }
2183
2184
2185 changeset_comment
2186 -----------------
2187
2188 .. py:function:: changeset_comment(apiuser, repoid, revision, message, userid=<Optional:<OptionalAttr:apiuser>>, status=<Optional:None>)
2189
2190 .. deprecated:: 3.4.0
2191
2192 Please use method `comment_commit` instead.
2193
2194
2195 Set a changeset comment, and optionally change the status of the
2196 changeset.
2197
2198 This command can only be run using an |authtoken| with admin
2199 permissions on the |repo|.
2200
2201 :param apiuser: This is filled automatically from the |authtoken|.
2202 :type apiuser: AuthUser
2203 :param repoid: Set the repository name or repository ID.
2204 :type repoid: str or int
2205 :param revision: Specify the revision for which to set a comment.
2206 :type revision: str
2207 :param message: The comment text.
2208 :type message: str
2209 :param userid: Set the user name of the comment creator.
2210 :type userid: Optional(str or int)
2211 :param status: Set the comment status. The following are valid options:
2212 * not_reviewed
2213 * approved
2214 * rejected
2215 * under_review
2216 :type status: str
2217
2218 Example error output:
2219
2220 .. code-block:: json
2221
2222 {
2223 "id" : <id_given_in_input>,
2224 "result" : {
2225 "msg": "Commented on commit `<revision>` for repository `<repoid>`",
2226 "status_change": null or <status>,
2227 "success": true
2228 },
2229 "error" : null
2230 }
2231
2232
2233 grant_user_permission
2234 ---------------------
2235
2236 .. py:function:: grant_user_permission(apiuser, repoid, userid, perm)
2237
2238 Grant permissions for the specified user on the given repository,
2239 or update existing permissions if found.
2240
2241 This command can only be run using an |authtoken| with admin
2242 permissions on the |repo|.
2243
2244 :param apiuser: This is filled automatically from the |authtoken|.
2245 :type apiuser: AuthUser
2246 :param repoid: Set the repository name or repository ID.
2247 :type repoid: str or int
2248 :param userid: Set the user name.
2249 :type userid: str
2250 :param perm: Set the user permissions, using the following format
2251 ``(repository.(none|read|write|admin))``
2252 :type perm: str
2253
2254 Example output:
2255
2256 .. code-block:: bash
2257
2258 id : <id_given_in_input>
2259 result: {
2260 "msg" : "Granted perm: `<perm>` for user: `<username>` in repo: `<reponame>`",
2261 "success": true
2262 }
2263 error: null
2264
2265
2266 revoke_user_permission
2267 ----------------------
2268
2269 .. py:function:: revoke_user_permission(apiuser, repoid, userid)
2270
2271 Revoke permission for a user on the specified repository.
2272
2273 This command can only be run using an |authtoken| with admin
2274 permissions on the |repo|.
2275
2276 :param apiuser: This is filled automatically from the |authtoken|.
2277 :type apiuser: AuthUser
2278 :param repoid: Set the repository name or repository ID.
2279 :type repoid: str or int
2280 :param userid: Set the user name of revoked user.
2281 :type userid: str or int
2282
2283 Example error output:
2284
2285 .. code-block:: bash
2286
2287 id : <id_given_in_input>
2288 result: {
2289 "msg" : "Revoked perm for user: `<username>` in repo: `<reponame>`",
2290 "success": true
2291 }
2292 error: null
2293
2294
2295 grant_user_group_permission
2296 ---------------------------
2297
2298 .. py:function:: grant_user_group_permission(apiuser, repoid, usergroupid, perm)
2299
2300 Grant permission for a user group on the specified repository,
2301 or update existing permissions.
2302
2303 This command can only be run using an |authtoken| with admin
2304 permissions on the |repo|.
2305
2306 :param apiuser: This is filled automatically from the |authtoken|.
2307 :type apiuser: AuthUser
2308 :param repoid: Set the repository name or repository ID.
2309 :type repoid: str or int
2310 :param usergroupid: Specify the ID of the user group.
2311 :type usergroupid: str or int
2312 :param perm: Set the user group permissions using the following
2313 format: (repository.(none|read|write|admin))
2314 :type perm: str
2315
2316 Example output:
2317
2318 .. code-block:: bash
2319
2320 id : <id_given_in_input>
2321 result : {
2322 "msg" : "Granted perm: `<perm>` for group: `<usersgroupname>` in repo: `<reponame>`",
2323 "success": true
2324
2325 }
2326 error : null
2327
2328 Example error output:
2329
2330 .. code-block:: bash
2331
2332 id : <id_given_in_input>
2333 result : null
2334 error : {
2335 "failed to edit permission for user group: `<usergroup>` in repo `<repo>`'
2336 }
2337
2338
2339 revoke_user_group_permission
2340 ----------------------------
2341
2342 .. py:function:: revoke_user_group_permission(apiuser, repoid, usergroupid)
2343
2344 Revoke the permissions of a user group on a given repository.
2345
2346 This command can only be run using an |authtoken| with admin
2347 permissions on the |repo|.
2348
2349 :param apiuser: This is filled automatically from the |authtoken|.
2350 :type apiuser: AuthUser
2351 :param repoid: Set the repository name or repository ID.
2352 :type repoid: str or int
2353 :param usergroupid: Specify the user group ID.
2354 :type usergroupid: str or int
2355
2356 Example output:
2357
2358 .. code-block:: bash
2359
2360 id : <id_given_in_input>
2361 result: {
2362 "msg" : "Revoked perm for group: `<usersgroupname>` in repo: `<reponame>`",
2363 "success": true
2364 }
2365 error: null
2366
2367
2368 get_repo_group
2369 --------------
2370
2371 .. py:function:: get_repo_group(apiuser, repogroupid)
2372
2373 Return the specified |repo| group, along with permissions,
2374 and repositories inside the group
2375
2376 :param apiuser: This is filled automatically from the |authtoken|.
2377 :type apiuser: AuthUser
2378 :param repogroupid: Specify the name of ID of the repository group.
2379 :type repogroupid: str or int
2380
2381
2382 Example output:
2383
2384 .. code-block:: bash
2385
2386 {
2387 "error": null,
2388 "id": repo-group-id,
2389 "result": {
2390 "group_description": "repo group description",
2391 "group_id": 14,
2392 "group_name": "group name",
2393 "members": [
2394 {
2395 "name": "super-admin-username",
2396 "origin": "super-admin",
2397 "permission": "group.admin",
2398 "type": "user"
2399 },
2400 {
2401 "name": "owner-name",
2402 "origin": "owner",
2403 "permission": "group.admin",
2404 "type": "user"
2405 },
2406 {
2407 "name": "user-group-name",
2408 "origin": "permission",
2409 "permission": "group.write",
2410 "type": "user_group"
2411 }
2412 ],
2413 "owner": "owner-name",
2414 "parent_group": null,
2415 "repositories": [ repo-list ]
2416 }
2417 }
2418
2419
2420 get_repo_groups
2421 ---------------
2422
2423 .. py:function:: get_repo_groups(apiuser)
2424
2425 Returns all repository groups.
2426
2427 :param apiuser: This is filled automatically from the |authtoken|.
2428 :type apiuser: AuthUser
2429
2430
2431 create_repo_group
2432 -----------------
2433
2434 .. py:function:: create_repo_group(apiuser, group_name, description=<Optional:''>, owner=<Optional:<OptionalAttr:apiuser>>, copy_permissions=<Optional:False>)
2435
2436 Creates a repository group.
2437
2438 * If the repository group name contains "/", all the required repository
2439 groups will be created.
2440
2441 For example "foo/bar/baz" will create |repo| groups "foo" and "bar"
2442 (with "foo" as parent). It will also create the "baz" repository
2443 with "bar" as |repo| group.
2444
2445 This command can only be run using an |authtoken| with admin
2446 permissions.
2447
2448 :param apiuser: This is filled automatically from the |authtoken|.
2449 :type apiuser: AuthUser
2450 :param group_name: Set the repository group name.
2451 :type group_name: str
2452 :param description: Set the |repo| group description.
2453 :type description: str
2454 :param owner: Set the |repo| group owner.
2455 :type owner: str
2456 :param copy_permissions:
2457 :type copy_permissions:
2458
2459 Example output:
2460
2461 .. code-block:: bash
2462
2463 id : <id_given_in_input>
2464 result : {
2465 "msg": "Created new repo group `<repo_group_name>`"
2466 "repo_group": <repogroup_object>
2467 }
2468 error : null
2469
2470
2471 Example error output:
2472
2473 .. code-block:: bash
2474
2475 id : <id_given_in_input>
2476 result : null
2477 error : {
2478 failed to create repo group `<repogroupid>`
2479 }
2480
2481
2482 update_repo_group
2483 -----------------
2484
2485 .. py:function:: update_repo_group(apiuser, repogroupid, group_name=<Optional:''>, description=<Optional:''>, owner=<Optional:<OptionalAttr:apiuser>>, parent=<Optional:None>, enable_locking=<Optional:False>)
2486
2487 Updates repository group with the details given.
2488
2489 This command can only be run using an |authtoken| with admin
2490 permissions.
2491
2492 :param apiuser: This is filled automatically from the |authtoken|.
2493 :type apiuser: AuthUser
2494 :param repogroupid: Set the ID of repository group.
2495 :type repogroupid: str or int
2496 :param group_name: Set the name of the |repo| group.
2497 :type group_name: str
2498 :param description: Set a description for the group.
2499 :type description: str
2500 :param owner: Set the |repo| group owner.
2501 :type owner: str
2502 :param parent: Set the |repo| group parent.
2503 :type parent: str or int
2504 :param enable_locking: Enable |repo| locking. The default is false.
2505 :type enable_locking: bool
2506
2507
2508 delete_repo_group
2509 -----------------
2510
2511 .. py:function:: delete_repo_group(apiuser, repogroupid)
2512
2513 Deletes a |repo| group.
2514
2515 :param apiuser: This is filled automatically from the |authtoken|.
2516 :type apiuser: AuthUser
2517 :param repogroupid: Set the name or ID of repository group to be
2518 deleted.
2519 :type repogroupid: str or int
2520
2521 Example output:
2522
2523 .. code-block:: bash
2524
2525 id : <id_given_in_input>
2526 result : {
2527 'msg': 'deleted repo group ID:<repogroupid> <repogroupname>
2528 'repo_group': null
2529 }
2530 error : null
2531
2532 Example error output:
2533
2534 .. code-block:: bash
2535
2536 id : <id_given_in_input>
2537 result : null
2538 error : {
2539 "failed to delete repo group ID:<repogroupid> <repogroupname>"
2540 }
2541
2542
2543 grant_user_permission_to_repo_group
2544 -----------------------------------
2545
2546 .. py:function:: grant_user_permission_to_repo_group(apiuser, repogroupid, userid, perm, apply_to_children=<Optional:'none'>)
2547
2548 Grant permission for a user on the given repository group, or update
2549 existing permissions if found.
2550
2551 This command can only be run using an |authtoken| with admin
2552 permissions.
2553
2554 :param apiuser: This is filled automatically from the |authtoken|.
2555 :type apiuser: AuthUser
2556 :param repogroupid: Set the name or ID of repository group.
2557 :type repogroupid: str or int
2558 :param userid: Set the user name.
2559 :type userid: str
2560 :param perm: (group.(none|read|write|admin))
2561 :type perm: str
2562 :param apply_to_children: 'none', 'repos', 'groups', 'all'
2563 :type apply_to_children: str
2564
2565 Example output:
2566
2567 .. code-block:: bash
2568
2569 id : <id_given_in_input>
2570 result: {
2571 "msg" : "Granted perm: `<perm>` (recursive:<apply_to_children>) for user: `<username>` in repo group: `<repo_group_name>`",
2572 "success": true
2573 }
2574 error: null
2575
2576 Example error output:
2577
2578 .. code-block:: bash
2579
2580 id : <id_given_in_input>
2581 result : null
2582 error : {
2583 "failed to edit permission for user: `<userid>` in repo group: `<repo_group_name>`"
2584 }
2585
2586
2587 revoke_user_permission_from_repo_group
2588 --------------------------------------
2589
2590 .. py:function:: revoke_user_permission_from_repo_group(apiuser, repogroupid, userid, apply_to_children=<Optional:'none'>)
2591
2592 Revoke permission for a user in a given repository group.
2593
2594 This command can only be run using an |authtoken| with admin
2595 permissions on the |repo| group.
2596
2597 :param apiuser: This is filled automatically from the |authtoken|.
2598 :type apiuser: AuthUser
2599 :param repogroupid: Set the name or ID of the repository group.
2600 :type repogroupid: str or int
2601 :param userid: Set the user name to revoke.
2602 :type userid: str
2603 :param apply_to_children: 'none', 'repos', 'groups', 'all'
2604 :type apply_to_children: str
2605
2606 Example output:
2607
2608 .. code-block:: bash
2609
2610 id : <id_given_in_input>
2611 result: {
2612 "msg" : "Revoked perm (recursive:<apply_to_children>) for user: `<username>` in repo group: `<repo_group_name>`",
2613 "success": true
2614 }
2615 error: null
2616
2617 Example error output:
2618
2619 .. code-block:: bash
2620
2621 id : <id_given_in_input>
2622 result : null
2623 error : {
2624 "failed to edit permission for user: `<userid>` in repo group: `<repo_group_name>`"
2625 }
2626
2627
2628 grant_user_group_permission_to_repo_group
2629 -----------------------------------------
2630
2631 .. py:function:: grant_user_group_permission_to_repo_group(apiuser, repogroupid, usergroupid, perm, apply_to_children=<Optional:'none'>)
2632
2633 Grant permission for a user group on given repository group, or update
2634 existing permissions if found.
2635
2636 This command can only be run using an |authtoken| with admin
2637 permissions on the |repo| group.
2638
2639 :param apiuser: This is filled automatically from the |authtoken|.
2640 :type apiuser: AuthUser
2641 :param repogroupid: Set the name or id of repository group
2642 :type repogroupid: str or int
2643 :param usergroupid: id of usergroup
2644 :type usergroupid: str or int
2645 :param perm: (group.(none|read|write|admin))
2646 :type perm: str
2647 :param apply_to_children: 'none', 'repos', 'groups', 'all'
2648 :type apply_to_children: str
2649
2650 Example output:
2651
2652 .. code-block:: bash
2653
2654 id : <id_given_in_input>
2655 result : {
2656 "msg" : "Granted perm: `<perm>` (recursive:<apply_to_children>) for user group: `<usersgroupname>` in repo group: `<repo_group_name>`",
2657 "success": true
2658
2659 }
2660 error : null
2661
2662 Example error output:
2663
2664 .. code-block:: bash
2665
2666 id : <id_given_in_input>
2667 result : null
2668 error : {
2669 "failed to edit permission for user group: `<usergroup>` in repo group: `<repo_group_name>`"
2670 }
2671
2672
2673 revoke_user_group_permission_from_repo_group
2674 --------------------------------------------
2675
2676 .. py:function:: revoke_user_group_permission_from_repo_group(apiuser, repogroupid, usergroupid, apply_to_children=<Optional:'none'>)
2677
2678 Revoke permission for user group on given repository.
2679
2680 This command can only be run using an |authtoken| with admin
2681 permissions on the |repo| group.
2682
2683 :param apiuser: This is filled automatically from the |authtoken|.
2684 :type apiuser: AuthUser
2685 :param repogroupid: name or id of repository group
2686 :type repogroupid: str or int
2687 :param usergroupid:
2688 :param apply_to_children: 'none', 'repos', 'groups', 'all'
2689 :type apply_to_children: str
2690
2691 Example output:
2692
2693 .. code-block:: bash
2694
2695 id : <id_given_in_input>
2696 result: {
2697 "msg" : "Revoked perm (recursive:<apply_to_children>) for user group: `<usersgroupname>` in repo group: `<repo_group_name>`",
2698 "success": true
2699 }
2700 error: null
2701
2702 Example error output:
2703
2704 .. code-block:: bash
2705
2706 id : <id_given_in_input>
2707 result : null
2708 error : {
2709 "failed to edit permission for user group: `<usergroup>` in repo group: `<repo_group_name>`"
2710 }
2711
2712
2713 get_gist
2714 --------
2715
2716 .. py:function:: get_gist(apiuser, gistid, content=<Optional:False>)
2717
2718 Get the specified gist, based on the gist ID.
2719
2720 :param apiuser: This is filled automatically from the |authtoken|.
2721 :type apiuser: AuthUser
2722 :param gistid: Set the id of the private or public gist
2723 :type gistid: str
2724 :param content: Return the gist content. Default is false.
2725 :type content: Optional(bool)
2726
2727
2728 get_gists
2729 ---------
2730
2731 .. py:function:: get_gists(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)
2732
2733 Get all gists for given user. If userid is empty returned gists
2734 are for user who called the api
2735
2736 :param apiuser: This is filled automatically from the |authtoken|.
2737 :type apiuser: AuthUser
2738 :param userid: user to get gists for
2739 :type userid: Optional(str or int)
2740
2741
2742 create_gist
2743 -----------
2744
2745 .. py:function:: create_gist(apiuser, files, owner=<Optional:<OptionalAttr:apiuser>>, gist_type=<Optional:u'public'>, lifetime=<Optional:-1>, acl_level=<Optional:u'acl_public'>, description=<Optional:''>)
2746
2747 Creates a new Gist.
2748
2749 :param apiuser: This is filled automatically from the |authtoken|.
2750 :type apiuser: AuthUser
2751 :param files: files to be added to the gist. The data structure has
2752 to match the following example::
2753
2754 {'filename': {'content':'...', 'lexer': null},
2755 'filename2': {'content':'...', 'lexer': null}}
2756
2757 :type files: dict
2758 :param owner: Set the gist owner, defaults to api method caller
2759 :type owner: Optional(str or int)
2760 :param gist_type: type of gist ``public`` or ``private``
2761 :type gist_type: Optional(str)
2762 :param lifetime: time in minutes of gist lifetime
2763 :type lifetime: Optional(int)
2764 :param acl_level: acl level for this gist, can be
2765 ``acl_public`` or ``acl_private`` If the value is set to
2766 ``acl_private`` only logged in users are able to access this gist.
2767 If not set it defaults to ``acl_public``.
2768 :type acl_level: Optional(str)
2769 :param description: gist description
2770 :type description: Optional(str)
2771
2772 Example output:
2773
2774 .. code-block:: bash
2775
2776 id : <id_given_in_input>
2777 result : {
2778 "msg": "created new gist",
2779 "gist": {}
2780 }
2781 error : null
2782
2783 Example error output:
2784
2785 .. code-block:: bash
2786
2787 id : <id_given_in_input>
2788 result : null
2789 error : {
2790 "failed to create gist"
2791 }
2792
2793
2794 delete_gist
2795 -----------
2796
2797 .. py:function:: delete_gist(apiuser, gistid)
2798
2799 Deletes existing gist
2800
2801 :param apiuser: filled automatically from apikey
2802 :type apiuser: AuthUser
2803 :param gistid: id of gist to delete
2804 :type gistid: str
2805
2806 Example output:
2807
2808 .. code-block:: bash
2809
2810 id : <id_given_in_input>
2811 result : {
2812 "deleted gist ID: <gist_id>",
2813 "gist": null
2814 }
2815 error : null
2816
2817 Example error output:
2818
2819 .. code-block:: bash
2820
2821 id : <id_given_in_input>
2822 result : null
2823 error : {
2824 "failed to delete gist ID:<gist_id>"
2825 }
General Comments 0
You need to be logged in to leave comments. Login now