##// END OF EJS Templates
docs: update API documentation
marcink -
r3495:32c1e2aa default
parent child Browse files
Show More
@@ -0,0 +1,37 b''
1 .. _store-methods-ref:
2
3 store methods
4 =============
5
6 file_store_add (EE only)
7 ------------------------
8
9 .. py:function:: file_store_add(apiuser, filename, content)
10
11 Upload API for the file_store
12
13 Example usage from CLI::
14 rhodecode-api --instance-name=enterprise-1 upload_file "{"content": "$(cat image.jpg | base64)", "filename":"image.jpg"}"
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 filename: name of the file uploaded
21 :type filename: str
22 :param content: base64 encoded content of the uploaded file
23 :type content: str
24
25 Example output:
26
27 .. code-block:: bash
28
29 id : <id_given_in_input>
30 result: {
31 "access_path": "/_file_store/download/84d156f7-8323-4ad3-9fce-4a8e88e1deaf-0.jpg",
32 "access_path_fqn": "http://server.domain.com/_file_store/download/84d156f7-8323-4ad3-9fce-4a8e88e1deaf-0.jpg",
33 "store_fid": "84d156f7-8323-4ad3-9fce-4a8e88e1deaf-0.jpg"
34 }
35 error : null
36
37
@@ -1,208 +1,209 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 |RCE| version 1.7.0 you can configure a white list
25 From |RCE| 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 |RCE| configuration ``.ini`` file. The default location is:
27 edit the |RCE| configuration ``.ini`` file. The default location is:
28
28
29 * |RCE| Pre-2.2.7 :file:`root/rhodecode/data/production.ini`
29 * |RCE| Pre-2.2.7 :file:`root/rhodecode/data/production.ini`
30 * |RCE| 3.0 :file:`/home/{user}/.rccontrol/{instance-id}/rhodecode.ini`
30 * |RCE| 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 = RepoCommitsView:repo_commit_raw,RepoCommitsView:repo_commit_patch,RepoCommitsView:repo_commit_download
45 api_access_controllers_whitelist = RepoCommitsView:repo_commit_raw,RepoCommitsView:repo_commit_patch,RepoCommitsView:repo_commit_download
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":{"repoid":"CPython"}}'
78 "auth_token":"xe7cdb2v278e4evbdf5vs04v832v0efvcbcve4a3","method":"pull", "args":{"repoid":"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 .. toctree::
197 .. toctree::
198
198
199 methods/views
199 methods/repo-methods
200 methods/store-methods
200 methods/license-methods
201 methods/license-methods
201 methods/deprecated-methods
202 methods/deprecated-methods
202 methods/gist-methods
203 methods/gist-methods
203 methods/pull-request-methods
204 methods/pull-request-methods
204 methods/repo-methods
205 methods/repo-methods
205 methods/repo-group-methods
206 methods/repo-group-methods
206 methods/server-methods
207 methods/server-methods
207 methods/user-methods
208 methods/user-methods
208 methods/user-group-methods
209 methods/user-group-methods
@@ -1,428 +1,434 b''
1 .. _pull-request-methods-ref:
1 .. _pull-request-methods-ref:
2
2
3 pull_request methods
3 pull_request methods
4 ====================
4 ====================
5
5
6 close_pull_request
6 close_pull_request
7 ------------------
7 ------------------
8
8
9 .. py:function:: close_pull_request(apiuser, pullrequestid, repoid=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>, message=<Optional:''>)
9 .. py:function:: close_pull_request(apiuser, pullrequestid, repoid=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>, message=<Optional:''>)
10
10
11 Close the pull request specified by `pullrequestid`.
11 Close the pull request specified by `pullrequestid`.
12
12
13 :param apiuser: This is filled automatically from the |authtoken|.
13 :param apiuser: This is filled automatically from the |authtoken|.
14 :type apiuser: AuthUser
14 :type apiuser: AuthUser
15 :param repoid: Repository name or repository ID to which the pull
15 :param repoid: Repository name or repository ID to which the pull
16 request belongs.
16 request belongs.
17 :type repoid: str or int
17 :type repoid: str or int
18 :param pullrequestid: ID of the pull request to be closed.
18 :param pullrequestid: ID of the pull request to be closed.
19 :type pullrequestid: int
19 :type pullrequestid: int
20 :param userid: Close the pull request as this user.
20 :param userid: Close the pull request as this user.
21 :type userid: Optional(str or int)
21 :type userid: Optional(str or int)
22 :param message: Optional message to close the Pull Request with. If not
22 :param message: Optional message to close the Pull Request with. If not
23 specified it will be generated automatically.
23 specified it will be generated automatically.
24 :type message: Optional(str)
24 :type message: Optional(str)
25
25
26 Example output:
26 Example output:
27
27
28 .. code-block:: bash
28 .. code-block:: bash
29
29
30 "id": <id_given_in_input>,
30 "id": <id_given_in_input>,
31 "result": {
31 "result": {
32 "pull_request_id": "<int>",
32 "pull_request_id": "<int>",
33 "close_status": "<str:status_lbl>,
33 "close_status": "<str:status_lbl>,
34 "closed": "<bool>"
34 "closed": "<bool>"
35 },
35 },
36 "error": null
36 "error": null
37
37
38
38
39 comment_pull_request
39 comment_pull_request
40 --------------------
40 --------------------
41
41
42 .. py:function:: comment_pull_request(apiuser, pullrequestid, repoid=<Optional:None>, message=<Optional:None>, commit_id=<Optional:None>, status=<Optional:None>, comment_type=<Optional:u'note'>, resolves_comment_id=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>)
42 .. py:function:: comment_pull_request(apiuser, pullrequestid, repoid=<Optional:None>, message=<Optional:None>, commit_id=<Optional:None>, status=<Optional:None>, comment_type=<Optional:u'note'>, resolves_comment_id=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>)
43
43
44 Comment on the pull request specified with the `pullrequestid`,
44 Comment on the pull request specified with the `pullrequestid`,
45 in the |repo| specified by the `repoid`, and optionally change the
45 in the |repo| specified by the `repoid`, and optionally change the
46 review status.
46 review status.
47
47
48 :param apiuser: This is filled automatically from the |authtoken|.
48 :param apiuser: This is filled automatically from the |authtoken|.
49 :type apiuser: AuthUser
49 :type apiuser: AuthUser
50 :param repoid: Optional repository name or repository ID.
50 :param repoid: Optional repository name or repository ID.
51 :type repoid: str or int
51 :type repoid: str or int
52 :param pullrequestid: The pull request ID.
52 :param pullrequestid: The pull request ID.
53 :type pullrequestid: int
53 :type pullrequestid: int
54 :param commit_id: Specify the commit_id for which to set a comment. If
54 :param commit_id: Specify the commit_id for which to set a comment. If
55 given commit_id is different than latest in the PR status
55 given commit_id is different than latest in the PR status
56 change won't be performed.
56 change won't be performed.
57 :type commit_id: str
57 :type commit_id: str
58 :param message: The text content of the comment.
58 :param message: The text content of the comment.
59 :type message: str
59 :type message: str
60 :param status: (**Optional**) Set the approval status of the pull
60 :param status: (**Optional**) Set the approval status of the pull
61 request. One of: 'not_reviewed', 'approved', 'rejected',
61 request. One of: 'not_reviewed', 'approved', 'rejected',
62 'under_review'
62 'under_review'
63 :type status: str
63 :type status: str
64 :param comment_type: Comment type, one of: 'note', 'todo'
64 :param comment_type: Comment type, one of: 'note', 'todo'
65 :type comment_type: Optional(str), default: 'note'
65 :type comment_type: Optional(str), default: 'note'
66 :param userid: Comment on the pull request as this user
66 :param userid: Comment on the pull request as this user
67 :type userid: Optional(str or int)
67 :type userid: Optional(str or int)
68
68
69 Example output:
69 Example output:
70
70
71 .. code-block:: bash
71 .. code-block:: bash
72
72
73 id : <id_given_in_input>
73 id : <id_given_in_input>
74 result : {
74 result : {
75 "pull_request_id": "<Integer>",
75 "pull_request_id": "<Integer>",
76 "comment_id": "<Integer>",
76 "comment_id": "<Integer>",
77 "status": {"given": <given_status>,
77 "status": {"given": <given_status>,
78 "was_changed": <bool status_was_actually_changed> },
78 "was_changed": <bool status_was_actually_changed> },
79 },
79 },
80 error : null
80 error : null
81
81
82
82
83 create_pull_request
83 create_pull_request
84 -------------------
84 -------------------
85
85
86 .. py:function:: create_pull_request(apiuser, source_repo, target_repo, source_ref, target_ref, title=<Optional:''>, description=<Optional:''>, description_renderer=<Optional:''>, reviewers=<Optional:None>)
86 .. py:function:: create_pull_request(apiuser, source_repo, target_repo, source_ref, target_ref, owner=<Optional:<OptionalAttr:apiuser>>, title=<Optional:''>, description=<Optional:''>, description_renderer=<Optional:''>, reviewers=<Optional:None>)
87
87
88 Creates a new pull request.
88 Creates a new pull request.
89
89
90 Accepts refs in the following formats:
90 Accepts refs in the following formats:
91
91
92 * branch:<branch_name>:<sha>
92 * branch:<branch_name>:<sha>
93 * branch:<branch_name>
93 * branch:<branch_name>
94 * bookmark:<bookmark_name>:<sha> (Mercurial only)
94 * bookmark:<bookmark_name>:<sha> (Mercurial only)
95 * bookmark:<bookmark_name> (Mercurial only)
95 * bookmark:<bookmark_name> (Mercurial only)
96
96
97 :param apiuser: This is filled automatically from the |authtoken|.
97 :param apiuser: This is filled automatically from the |authtoken|.
98 :type apiuser: AuthUser
98 :type apiuser: AuthUser
99 :param source_repo: Set the source repository name.
99 :param source_repo: Set the source repository name.
100 :type source_repo: str
100 :type source_repo: str
101 :param target_repo: Set the target repository name.
101 :param target_repo: Set the target repository name.
102 :type target_repo: str
102 :type target_repo: str
103 :param source_ref: Set the source ref name.
103 :param source_ref: Set the source ref name.
104 :type source_ref: str
104 :type source_ref: str
105 :param target_ref: Set the target ref name.
105 :param target_ref: Set the target ref name.
106 :type target_ref: str
106 :type target_ref: str
107 :param owner: user_id or username
108 :type owner: Optional(str)
107 :param title: Optionally Set the pull request title, it's generated otherwise
109 :param title: Optionally Set the pull request title, it's generated otherwise
108 :type title: str
110 :type title: str
109 :param description: Set the pull request description.
111 :param description: Set the pull request description.
110 :type description: Optional(str)
112 :type description: Optional(str)
111 :type description_renderer: Optional(str)
113 :type description_renderer: Optional(str)
112 :param description_renderer: Set pull request renderer for the description.
114 :param description_renderer: Set pull request renderer for the description.
113 It should be 'rst', 'markdown' or 'plain'. If not give default
115 It should be 'rst', 'markdown' or 'plain'. If not give default
114 system renderer will be used
116 system renderer will be used
115 :param reviewers: Set the new pull request reviewers list.
117 :param reviewers: Set the new pull request reviewers list.
116 Reviewer defined by review rules will be added automatically to the
118 Reviewer defined by review rules will be added automatically to the
117 defined list.
119 defined list.
118 :type reviewers: Optional(list)
120 :type reviewers: Optional(list)
119 Accepts username strings or objects of the format:
121 Accepts username strings or objects of the format:
120
122
121 [{'username': 'nick', 'reasons': ['original author'], 'mandatory': <bool>}]
123 [{'username': 'nick', 'reasons': ['original author'], 'mandatory': <bool>}]
122
124
123
125
124 get_pull_request
126 get_pull_request
125 ----------------
127 ----------------
126
128
127 .. py:function:: get_pull_request(apiuser, pullrequestid, repoid=<Optional:None>)
129 .. py:function:: get_pull_request(apiuser, pullrequestid, repoid=<Optional:None>)
128
130
129 Get a pull request based on the given ID.
131 Get a pull request based on the given ID.
130
132
131 :param apiuser: This is filled automatically from the |authtoken|.
133 :param apiuser: This is filled automatically from the |authtoken|.
132 :type apiuser: AuthUser
134 :type apiuser: AuthUser
133 :param repoid: Optional, repository name or repository ID from where
135 :param repoid: Optional, repository name or repository ID from where
134 the pull request was opened.
136 the pull request was opened.
135 :type repoid: str or int
137 :type repoid: str or int
136 :param pullrequestid: ID of the requested pull request.
138 :param pullrequestid: ID of the requested pull request.
137 :type pullrequestid: int
139 :type pullrequestid: int
138
140
139 Example output:
141 Example output:
140
142
141 .. code-block:: bash
143 .. code-block:: bash
142
144
143 "id": <id_given_in_input>,
145 "id": <id_given_in_input>,
144 "result":
146 "result":
145 {
147 {
146 "pull_request_id": "<pull_request_id>",
148 "pull_request_id": "<pull_request_id>",
147 "url": "<url>",
149 "url": "<url>",
148 "title": "<title>",
150 "title": "<title>",
149 "description": "<description>",
151 "description": "<description>",
150 "status" : "<status>",
152 "status" : "<status>",
151 "created_on": "<date_time_created>",
153 "created_on": "<date_time_created>",
152 "updated_on": "<date_time_updated>",
154 "updated_on": "<date_time_updated>",
153 "commit_ids": [
155 "commit_ids": [
154 ...
156 ...
155 "<commit_id>",
157 "<commit_id>",
156 "<commit_id>",
158 "<commit_id>",
157 ...
159 ...
158 ],
160 ],
159 "review_status": "<review_status>",
161 "review_status": "<review_status>",
160 "mergeable": {
162 "mergeable": {
161 "status": "<bool>",
163 "status": "<bool>",
162 "message": "<message>",
164 "message": "<message>",
163 },
165 },
164 "source": {
166 "source": {
165 "clone_url": "<clone_url>",
167 "clone_url": "<clone_url>",
166 "repository": "<repository_name>",
168 "repository": "<repository_name>",
167 "reference":
169 "reference":
168 {
170 {
169 "name": "<name>",
171 "name": "<name>",
170 "type": "<type>",
172 "type": "<type>",
171 "commit_id": "<commit_id>",
173 "commit_id": "<commit_id>",
172 }
174 }
173 },
175 },
174 "target": {
176 "target": {
175 "clone_url": "<clone_url>",
177 "clone_url": "<clone_url>",
176 "repository": "<repository_name>",
178 "repository": "<repository_name>",
177 "reference":
179 "reference":
178 {
180 {
179 "name": "<name>",
181 "name": "<name>",
180 "type": "<type>",
182 "type": "<type>",
181 "commit_id": "<commit_id>",
183 "commit_id": "<commit_id>",
182 }
184 }
183 },
185 },
184 "merge": {
186 "merge": {
185 "clone_url": "<clone_url>",
187 "clone_url": "<clone_url>",
186 "reference":
188 "reference":
187 {
189 {
188 "name": "<name>",
190 "name": "<name>",
189 "type": "<type>",
191 "type": "<type>",
190 "commit_id": "<commit_id>",
192 "commit_id": "<commit_id>",
191 }
193 }
192 },
194 },
193 "author": <user_obj>,
195 "author": <user_obj>,
194 "reviewers": [
196 "reviewers": [
195 ...
197 ...
196 {
198 {
197 "user": "<user_obj>",
199 "user": "<user_obj>",
198 "review_status": "<review_status>",
200 "review_status": "<review_status>",
199 }
201 }
200 ...
202 ...
201 ]
203 ]
202 },
204 },
203 "error": null
205 "error": null
204
206
205
207
206 get_pull_request_comments
208 get_pull_request_comments
207 -------------------------
209 -------------------------
208
210
209 .. py:function:: get_pull_request_comments(apiuser, pullrequestid, repoid=<Optional:None>)
211 .. py:function:: get_pull_request_comments(apiuser, pullrequestid, repoid=<Optional:None>)
210
212
211 Get all comments of pull request specified with the `pullrequestid`
213 Get all comments of pull request specified with the `pullrequestid`
212
214
213 :param apiuser: This is filled automatically from the |authtoken|.
215 :param apiuser: This is filled automatically from the |authtoken|.
214 :type apiuser: AuthUser
216 :type apiuser: AuthUser
215 :param repoid: Optional repository name or repository ID.
217 :param repoid: Optional repository name or repository ID.
216 :type repoid: str or int
218 :type repoid: str or int
217 :param pullrequestid: The pull request ID.
219 :param pullrequestid: The pull request ID.
218 :type pullrequestid: int
220 :type pullrequestid: int
219
221
220 Example output:
222 Example output:
221
223
222 .. code-block:: bash
224 .. code-block:: bash
223
225
224 id : <id_given_in_input>
226 id : <id_given_in_input>
225 result : [
227 result : [
226 {
228 {
227 "comment_author": {
229 "comment_author": {
228 "active": true,
230 "active": true,
229 "full_name_or_username": "Tom Gore",
231 "full_name_or_username": "Tom Gore",
230 "username": "admin"
232 "username": "admin"
231 },
233 },
232 "comment_created_on": "2017-01-02T18:43:45.533",
234 "comment_created_on": "2017-01-02T18:43:45.533",
233 "comment_f_path": null,
235 "comment_f_path": null,
234 "comment_id": 25,
236 "comment_id": 25,
235 "comment_lineno": null,
237 "comment_lineno": null,
236 "comment_status": {
238 "comment_status": {
237 "status": "under_review",
239 "status": "under_review",
238 "status_lbl": "Under Review"
240 "status_lbl": "Under Review"
239 },
241 },
240 "comment_text": "Example text",
242 "comment_text": "Example text",
241 "comment_type": null,
243 "comment_type": null,
242 "pull_request_version": null
244 "pull_request_version": null
243 }
245 }
244 ],
246 ],
245 error : null
247 error : null
246
248
247
249
248 get_pull_requests
250 get_pull_requests
249 -----------------
251 -----------------
250
252
251 .. py:function:: get_pull_requests(apiuser, repoid, status=<Optional:'new'>)
253 .. py:function:: get_pull_requests(apiuser, repoid, status=<Optional:'new'>, merge_state=<Optional:True>)
252
254
253 Get all pull requests from the repository specified in `repoid`.
255 Get all pull requests from the repository specified in `repoid`.
254
256
255 :param apiuser: This is filled automatically from the |authtoken|.
257 :param apiuser: This is filled automatically from the |authtoken|.
256 :type apiuser: AuthUser
258 :type apiuser: AuthUser
257 :param repoid: Optional repository name or repository ID.
259 :param repoid: Optional repository name or repository ID.
258 :type repoid: str or int
260 :type repoid: str or int
259 :param status: Only return pull requests with the specified status.
261 :param status: Only return pull requests with the specified status.
260 Valid options are.
262 Valid options are.
261 * ``new`` (default)
263 * ``new`` (default)
262 * ``open``
264 * ``open``
263 * ``closed``
265 * ``closed``
264 :type status: str
266 :type status: str
267 :param merge_state: Optional calculate merge state for each repository.
268 This could result in longer time to fetch the data
269 :type merge_state: bool
265
270
266 Example output:
271 Example output:
267
272
268 .. code-block:: bash
273 .. code-block:: bash
269
274
270 "id": <id_given_in_input>,
275 "id": <id_given_in_input>,
271 "result":
276 "result":
272 [
277 [
273 ...
278 ...
274 {
279 {
275 "pull_request_id": "<pull_request_id>",
280 "pull_request_id": "<pull_request_id>",
276 "url": "<url>",
281 "url": "<url>",
277 "title" : "<title>",
282 "title" : "<title>",
278 "description": "<description>",
283 "description": "<description>",
279 "status": "<status>",
284 "status": "<status>",
280 "created_on": "<date_time_created>",
285 "created_on": "<date_time_created>",
281 "updated_on": "<date_time_updated>",
286 "updated_on": "<date_time_updated>",
282 "commit_ids": [
287 "commit_ids": [
283 ...
288 ...
284 "<commit_id>",
289 "<commit_id>",
285 "<commit_id>",
290 "<commit_id>",
286 ...
291 ...
287 ],
292 ],
288 "review_status": "<review_status>",
293 "review_status": "<review_status>",
289 "mergeable": {
294 "mergeable": {
290 "status": "<bool>",
295 "status": "<bool>",
291 "message: "<message>",
296 "message: "<message>",
292 },
297 },
293 "source": {
298 "source": {
294 "clone_url": "<clone_url>",
299 "clone_url": "<clone_url>",
295 "reference":
300 "reference":
296 {
301 {
297 "name": "<name>",
302 "name": "<name>",
298 "type": "<type>",
303 "type": "<type>",
299 "commit_id": "<commit_id>",
304 "commit_id": "<commit_id>",
300 }
305 }
301 },
306 },
302 "target": {
307 "target": {
303 "clone_url": "<clone_url>",
308 "clone_url": "<clone_url>",
304 "reference":
309 "reference":
305 {
310 {
306 "name": "<name>",
311 "name": "<name>",
307 "type": "<type>",
312 "type": "<type>",
308 "commit_id": "<commit_id>",
313 "commit_id": "<commit_id>",
309 }
314 }
310 },
315 },
311 "merge": {
316 "merge": {
312 "clone_url": "<clone_url>",
317 "clone_url": "<clone_url>",
313 "reference":
318 "reference":
314 {
319 {
315 "name": "<name>",
320 "name": "<name>",
316 "type": "<type>",
321 "type": "<type>",
317 "commit_id": "<commit_id>",
322 "commit_id": "<commit_id>",
318 }
323 }
319 },
324 },
320 "author": <user_obj>,
325 "author": <user_obj>,
321 "reviewers": [
326 "reviewers": [
322 ...
327 ...
323 {
328 {
324 "user": "<user_obj>",
329 "user": "<user_obj>",
325 "review_status": "<review_status>",
330 "review_status": "<review_status>",
326 }
331 }
327 ...
332 ...
328 ]
333 ]
329 }
334 }
330 ...
335 ...
331 ],
336 ],
332 "error": null
337 "error": null
333
338
334
339
335 merge_pull_request
340 merge_pull_request
336 ------------------
341 ------------------
337
342
338 .. py:function:: merge_pull_request(apiuser, pullrequestid, repoid=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>)
343 .. py:function:: merge_pull_request(apiuser, pullrequestid, repoid=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>)
339
344
340 Merge the pull request specified by `pullrequestid` into its target
345 Merge the pull request specified by `pullrequestid` into its target
341 repository.
346 repository.
342
347
343 :param apiuser: This is filled automatically from the |authtoken|.
348 :param apiuser: This is filled automatically from the |authtoken|.
344 :type apiuser: AuthUser
349 :type apiuser: AuthUser
345 :param repoid: Optional, repository name or repository ID of the
350 :param repoid: Optional, repository name or repository ID of the
346 target repository to which the |pr| is to be merged.
351 target repository to which the |pr| is to be merged.
347 :type repoid: str or int
352 :type repoid: str or int
348 :param pullrequestid: ID of the pull request which shall be merged.
353 :param pullrequestid: ID of the pull request which shall be merged.
349 :type pullrequestid: int
354 :type pullrequestid: int
350 :param userid: Merge the pull request as this user.
355 :param userid: Merge the pull request as this user.
351 :type userid: Optional(str or int)
356 :type userid: Optional(str or int)
352
357
353 Example output:
358 Example output:
354
359
355 .. code-block:: bash
360 .. code-block:: bash
356
361
357 "id": <id_given_in_input>,
362 "id": <id_given_in_input>,
358 "result": {
363 "result": {
359 "executed": "<bool>",
364 "executed": "<bool>",
360 "failure_reason": "<int>",
365 "failure_reason": "<int>",
366 "merge_status_message": "<str>",
361 "merge_commit_id": "<merge_commit_id>",
367 "merge_commit_id": "<merge_commit_id>",
362 "possible": "<bool>",
368 "possible": "<bool>",
363 "merge_ref": {
369 "merge_ref": {
364 "commit_id": "<commit_id>",
370 "commit_id": "<commit_id>",
365 "type": "<type>",
371 "type": "<type>",
366 "name": "<name>"
372 "name": "<name>"
367 }
373 }
368 },
374 },
369 "error": null
375 "error": null
370
376
371
377
372 update_pull_request
378 update_pull_request
373 -------------------
379 -------------------
374
380
375 .. py:function:: update_pull_request(apiuser, pullrequestid, repoid=<Optional:None>, title=<Optional:''>, description=<Optional:''>, description_renderer=<Optional:''>, reviewers=<Optional:None>, update_commits=<Optional:None>)
381 .. py:function:: update_pull_request(apiuser, pullrequestid, repoid=<Optional:None>, title=<Optional:''>, description=<Optional:''>, description_renderer=<Optional:''>, reviewers=<Optional:None>, update_commits=<Optional:None>)
376
382
377 Updates a pull request.
383 Updates a pull request.
378
384
379 :param apiuser: This is filled automatically from the |authtoken|.
385 :param apiuser: This is filled automatically from the |authtoken|.
380 :type apiuser: AuthUser
386 :type apiuser: AuthUser
381 :param repoid: Optional repository name or repository ID.
387 :param repoid: Optional repository name or repository ID.
382 :type repoid: str or int
388 :type repoid: str or int
383 :param pullrequestid: The pull request ID.
389 :param pullrequestid: The pull request ID.
384 :type pullrequestid: int
390 :type pullrequestid: int
385 :param title: Set the pull request title.
391 :param title: Set the pull request title.
386 :type title: str
392 :type title: str
387 :param description: Update pull request description.
393 :param description: Update pull request description.
388 :type description: Optional(str)
394 :type description: Optional(str)
389 :type description_renderer: Optional(str)
395 :type description_renderer: Optional(str)
390 :param description_renderer: Update pull request renderer for the description.
396 :param description_renderer: Update pull request renderer for the description.
391 It should be 'rst', 'markdown' or 'plain'
397 It should be 'rst', 'markdown' or 'plain'
392 :param reviewers: Update pull request reviewers list with new value.
398 :param reviewers: Update pull request reviewers list with new value.
393 :type reviewers: Optional(list)
399 :type reviewers: Optional(list)
394 Accepts username strings or objects of the format:
400 Accepts username strings or objects of the format:
395
401
396 [{'username': 'nick', 'reasons': ['original author'], 'mandatory': <bool>}]
402 [{'username': 'nick', 'reasons': ['original author'], 'mandatory': <bool>}]
397
403
398 :param update_commits: Trigger update of commits for this pull request
404 :param update_commits: Trigger update of commits for this pull request
399 :type: update_commits: Optional(bool)
405 :type: update_commits: Optional(bool)
400
406
401 Example output:
407 Example output:
402
408
403 .. code-block:: bash
409 .. code-block:: bash
404
410
405 id : <id_given_in_input>
411 id : <id_given_in_input>
406 result : {
412 result : {
407 "msg": "Updated pull request `63`",
413 "msg": "Updated pull request `63`",
408 "pull_request": <pull_request_object>,
414 "pull_request": <pull_request_object>,
409 "updated_reviewers": {
415 "updated_reviewers": {
410 "added": [
416 "added": [
411 "username"
417 "username"
412 ],
418 ],
413 "removed": []
419 "removed": []
414 },
420 },
415 "updated_commits": {
421 "updated_commits": {
416 "added": [
422 "added": [
417 "<sha1_hash>"
423 "<sha1_hash>"
418 ],
424 ],
419 "common": [
425 "common": [
420 "<sha1_hash>",
426 "<sha1_hash>",
421 "<sha1_hash>",
427 "<sha1_hash>",
422 ],
428 ],
423 "removed": []
429 "removed": []
424 }
430 }
425 }
431 }
426 error : null
432 error : null
427
433
428
434
@@ -1,1028 +1,1134 b''
1 .. _repo-methods-ref:
1 .. _repo-methods-ref:
2
2
3 repo methods
3 repo methods
4 ============
4 ============
5
5
6 add_field_to_repo
6 add_field_to_repo
7 -----------------
7 -----------------
8
8
9 .. py:function:: add_field_to_repo(apiuser, repoid, key, label=<Optional:''>, description=<Optional:''>)
9 .. py:function:: add_field_to_repo(apiuser, repoid, key, label=<Optional:''>, description=<Optional:''>)
10
10
11 Adds an extra field to a repository.
11 Adds an extra field to a repository.
12
12
13 This command can only be run using an |authtoken| with at least
13 This command can only be run using an |authtoken| with at least
14 write permissions to the |repo|.
14 write permissions to the |repo|.
15
15
16 :param apiuser: This is filled automatically from the |authtoken|.
16 :param apiuser: This is filled automatically from the |authtoken|.
17 :type apiuser: AuthUser
17 :type apiuser: AuthUser
18 :param repoid: Set the repository name or repository id.
18 :param repoid: Set the repository name or repository id.
19 :type repoid: str or int
19 :type repoid: str or int
20 :param key: Create a unique field key for this repository.
20 :param key: Create a unique field key for this repository.
21 :type key: str
21 :type key: str
22 :param label:
22 :param label:
23 :type label: Optional(str)
23 :type label: Optional(str)
24 :param description:
24 :param description:
25 :type description: Optional(str)
25 :type description: Optional(str)
26
26
27
27
28 comment_commit
28 comment_commit
29 --------------
29 --------------
30
30
31 .. py:function:: comment_commit(apiuser, repoid, commit_id, message, status=<Optional:None>, comment_type=<Optional:u'note'>, resolves_comment_id=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>)
31 .. py:function:: comment_commit(apiuser, repoid, commit_id, message, status=<Optional:None>, comment_type=<Optional:u'note'>, resolves_comment_id=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>)
32
32
33 Set a commit comment, and optionally change the status of the commit.
33 Set a commit comment, and optionally change the status of the commit.
34
34
35 :param apiuser: This is filled automatically from the |authtoken|.
35 :param apiuser: This is filled automatically from the |authtoken|.
36 :type apiuser: AuthUser
36 :type apiuser: AuthUser
37 :param repoid: Set the repository name or repository ID.
37 :param repoid: Set the repository name or repository ID.
38 :type repoid: str or int
38 :type repoid: str or int
39 :param commit_id: Specify the commit_id for which to set a comment.
39 :param commit_id: Specify the commit_id for which to set a comment.
40 :type commit_id: str
40 :type commit_id: str
41 :param message: The comment text.
41 :param message: The comment text.
42 :type message: str
42 :type message: str
43 :param status: (**Optional**) status of commit, one of: 'not_reviewed',
43 :param status: (**Optional**) status of commit, one of: 'not_reviewed',
44 'approved', 'rejected', 'under_review'
44 'approved', 'rejected', 'under_review'
45 :type status: str
45 :type status: str
46 :param comment_type: Comment type, one of: 'note', 'todo'
46 :param comment_type: Comment type, one of: 'note', 'todo'
47 :type comment_type: Optional(str), default: 'note'
47 :type comment_type: Optional(str), default: 'note'
48 :param userid: Set the user name of the comment creator.
48 :param userid: Set the user name of the comment creator.
49 :type userid: Optional(str or int)
49 :type userid: Optional(str or int)
50
50
51 Example error output:
51 Example error output:
52
52
53 .. code-block:: bash
53 .. code-block:: bash
54
54
55 {
55 {
56 "id" : <id_given_in_input>,
56 "id" : <id_given_in_input>,
57 "result" : {
57 "result" : {
58 "msg": "Commented on commit `<commit_id>` for repository `<repoid>`",
58 "msg": "Commented on commit `<commit_id>` for repository `<repoid>`",
59 "status_change": null or <status>,
59 "status_change": null or <status>,
60 "success": true
60 "success": true
61 },
61 },
62 "error" : null
62 "error" : null
63 }
63 }
64
64
65
65
66 create_repo
66 create_repo
67 -----------
67 -----------
68
68
69 .. py:function:: create_repo(apiuser, repo_name, repo_type, owner=<Optional:<OptionalAttr:apiuser>>, description=<Optional:''>, private=<Optional:False>, clone_uri=<Optional:None>, push_uri=<Optional:None>, landing_rev=<Optional:'rev:tip'>, enable_statistics=<Optional:False>, enable_locking=<Optional:False>, enable_downloads=<Optional:False>, copy_permissions=<Optional:False>)
69 .. py:function:: create_repo(apiuser, repo_name, repo_type, owner=<Optional:<OptionalAttr:apiuser>>, description=<Optional:''>, private=<Optional:False>, clone_uri=<Optional:None>, push_uri=<Optional:None>, landing_rev=<Optional:'rev:tip'>, enable_statistics=<Optional:False>, enable_locking=<Optional:False>, enable_downloads=<Optional:False>, copy_permissions=<Optional:False>)
70
70
71 Creates a repository.
71 Creates a repository.
72
72
73 * If the repository name contains "/", repository will be created inside
73 * If the repository name contains "/", repository will be created inside
74 a repository group or nested repository groups
74 a repository group or nested repository groups
75
75
76 For example "foo/bar/repo1" will create |repo| called "repo1" inside
76 For example "foo/bar/repo1" will create |repo| called "repo1" inside
77 group "foo/bar". You have to have permissions to access and write to
77 group "foo/bar". You have to have permissions to access and write to
78 the last repository group ("bar" in this example)
78 the last repository group ("bar" in this example)
79
79
80 This command can only be run using an |authtoken| with at least
80 This command can only be run using an |authtoken| with at least
81 permissions to create repositories, or write permissions to
81 permissions to create repositories, or write permissions to
82 parent repository groups.
82 parent repository groups.
83
83
84 :param apiuser: This is filled automatically from the |authtoken|.
84 :param apiuser: This is filled automatically from the |authtoken|.
85 :type apiuser: AuthUser
85 :type apiuser: AuthUser
86 :param repo_name: Set the repository name.
86 :param repo_name: Set the repository name.
87 :type repo_name: str
87 :type repo_name: str
88 :param repo_type: Set the repository type; 'hg','git', or 'svn'.
88 :param repo_type: Set the repository type; 'hg','git', or 'svn'.
89 :type repo_type: str
89 :type repo_type: str
90 :param owner: user_id or username
90 :param owner: user_id or username
91 :type owner: Optional(str)
91 :type owner: Optional(str)
92 :param description: Set the repository description.
92 :param description: Set the repository description.
93 :type description: Optional(str)
93 :type description: Optional(str)
94 :param private: set repository as private
94 :param private: set repository as private
95 :type private: bool
95 :type private: bool
96 :param clone_uri: set clone_uri
96 :param clone_uri: set clone_uri
97 :type clone_uri: str
97 :type clone_uri: str
98 :param push_uri: set push_uri
98 :param push_uri: set push_uri
99 :type push_uri: str
99 :type push_uri: str
100 :param landing_rev: <rev_type>:<rev>
100 :param landing_rev: <rev_type>:<rev>
101 :type landing_rev: str
101 :type landing_rev: str
102 :param enable_locking:
102 :param enable_locking:
103 :type enable_locking: bool
103 :type enable_locking: bool
104 :param enable_downloads:
104 :param enable_downloads:
105 :type enable_downloads: bool
105 :type enable_downloads: bool
106 :param enable_statistics:
106 :param enable_statistics:
107 :type enable_statistics: bool
107 :type enable_statistics: bool
108 :param copy_permissions: Copy permission from group in which the
108 :param copy_permissions: Copy permission from group in which the
109 repository is being created.
109 repository is being created.
110 :type copy_permissions: bool
110 :type copy_permissions: bool
111
111
112
112
113 Example output:
113 Example output:
114
114
115 .. code-block:: bash
115 .. code-block:: bash
116
116
117 id : <id_given_in_input>
117 id : <id_given_in_input>
118 result: {
118 result: {
119 "msg": "Created new repository `<reponame>`",
119 "msg": "Created new repository `<reponame>`",
120 "success": true,
120 "success": true,
121 "task": "<celery task id or None if done sync>"
121 "task": "<celery task id or None if done sync>"
122 }
122 }
123 error: null
123 error: null
124
124
125
125
126 Example error output:
126 Example error output:
127
127
128 .. code-block:: bash
128 .. code-block:: bash
129
129
130 id : <id_given_in_input>
130 id : <id_given_in_input>
131 result : null
131 result : null
132 error : {
132 error : {
133 'failed to create repository `<repo_name>`'
133 'failed to create repository `<repo_name>`'
134 }
134 }
135
135
136
136
137 delete_repo
137 delete_repo
138 -----------
138 -----------
139
139
140 .. py:function:: delete_repo(apiuser, repoid, forks=<Optional:''>)
140 .. py:function:: delete_repo(apiuser, repoid, forks=<Optional:''>)
141
141
142 Deletes a repository.
142 Deletes a repository.
143
143
144 * When the `forks` parameter is set it's possible to detach or delete
144 * When the `forks` parameter is set it's possible to detach or delete
145 forks of deleted repository.
145 forks of deleted repository.
146
146
147 This command can only be run using an |authtoken| with admin
147 This command can only be run using an |authtoken| with admin
148 permissions on the |repo|.
148 permissions on the |repo|.
149
149
150 :param apiuser: This is filled automatically from the |authtoken|.
150 :param apiuser: This is filled automatically from the |authtoken|.
151 :type apiuser: AuthUser
151 :type apiuser: AuthUser
152 :param repoid: Set the repository name or repository ID.
152 :param repoid: Set the repository name or repository ID.
153 :type repoid: str or int
153 :type repoid: str or int
154 :param forks: Set to `detach` or `delete` forks from the |repo|.
154 :param forks: Set to `detach` or `delete` forks from the |repo|.
155 :type forks: Optional(str)
155 :type forks: Optional(str)
156
156
157 Example error output:
157 Example error output:
158
158
159 .. code-block:: bash
159 .. code-block:: bash
160
160
161 id : <id_given_in_input>
161 id : <id_given_in_input>
162 result: {
162 result: {
163 "msg": "Deleted repository `<reponame>`",
163 "msg": "Deleted repository `<reponame>`",
164 "success": true
164 "success": true
165 }
165 }
166 error: null
166 error: null
167
167
168
168
169 fork_repo
169 fork_repo
170 ---------
170 ---------
171
171
172 .. py:function:: fork_repo(apiuser, repoid, fork_name, owner=<Optional:<OptionalAttr:apiuser>>, description=<Optional:''>, private=<Optional:False>, clone_uri=<Optional:None>, landing_rev=<Optional:'rev:tip'>, copy_permissions=<Optional:False>)
172 .. py:function:: fork_repo(apiuser, repoid, fork_name, owner=<Optional:<OptionalAttr:apiuser>>, description=<Optional:''>, private=<Optional:False>, clone_uri=<Optional:None>, landing_rev=<Optional:'rev:tip'>, copy_permissions=<Optional:False>)
173
173
174 Creates a fork of the specified |repo|.
174 Creates a fork of the specified |repo|.
175
175
176 * If the fork_name contains "/", fork will be created inside
176 * If the fork_name contains "/", fork will be created inside
177 a repository group or nested repository groups
177 a repository group or nested repository groups
178
178
179 For example "foo/bar/fork-repo" will create fork called "fork-repo"
179 For example "foo/bar/fork-repo" will create fork called "fork-repo"
180 inside group "foo/bar". You have to have permissions to access and
180 inside group "foo/bar". You have to have permissions to access and
181 write to the last repository group ("bar" in this example)
181 write to the last repository group ("bar" in this example)
182
182
183 This command can only be run using an |authtoken| with minimum
183 This command can only be run using an |authtoken| with minimum
184 read permissions of the forked repo, create fork permissions for an user.
184 read permissions of the forked repo, create fork permissions for an user.
185
185
186 :param apiuser: This is filled automatically from the |authtoken|.
186 :param apiuser: This is filled automatically from the |authtoken|.
187 :type apiuser: AuthUser
187 :type apiuser: AuthUser
188 :param repoid: Set repository name or repository ID.
188 :param repoid: Set repository name or repository ID.
189 :type repoid: str or int
189 :type repoid: str or int
190 :param fork_name: Set the fork name, including it's repository group membership.
190 :param fork_name: Set the fork name, including it's repository group membership.
191 :type fork_name: str
191 :type fork_name: str
192 :param owner: Set the fork owner.
192 :param owner: Set the fork owner.
193 :type owner: str
193 :type owner: str
194 :param description: Set the fork description.
194 :param description: Set the fork description.
195 :type description: str
195 :type description: str
196 :param copy_permissions: Copy permissions from parent |repo|. The
196 :param copy_permissions: Copy permissions from parent |repo|. The
197 default is False.
197 default is False.
198 :type copy_permissions: bool
198 :type copy_permissions: bool
199 :param private: Make the fork private. The default is False.
199 :param private: Make the fork private. The default is False.
200 :type private: bool
200 :type private: bool
201 :param landing_rev: Set the landing revision. The default is tip.
201 :param landing_rev: Set the landing revision. The default is tip.
202
202
203 Example output:
203 Example output:
204
204
205 .. code-block:: bash
205 .. code-block:: bash
206
206
207 id : <id_for_response>
207 id : <id_for_response>
208 api_key : "<api_key>"
208 api_key : "<api_key>"
209 args: {
209 args: {
210 "repoid" : "<reponame or repo_id>",
210 "repoid" : "<reponame or repo_id>",
211 "fork_name": "<forkname>",
211 "fork_name": "<forkname>",
212 "owner": "<username or user_id = Optional(=apiuser)>",
212 "owner": "<username or user_id = Optional(=apiuser)>",
213 "description": "<description>",
213 "description": "<description>",
214 "copy_permissions": "<bool>",
214 "copy_permissions": "<bool>",
215 "private": "<bool>",
215 "private": "<bool>",
216 "landing_rev": "<landing_rev>"
216 "landing_rev": "<landing_rev>"
217 }
217 }
218
218
219 Example error output:
219 Example error output:
220
220
221 .. code-block:: bash
221 .. code-block:: bash
222
222
223 id : <id_given_in_input>
223 id : <id_given_in_input>
224 result: {
224 result: {
225 "msg": "Created fork of `<reponame>` as `<forkname>`",
225 "msg": "Created fork of `<reponame>` as `<forkname>`",
226 "success": true,
226 "success": true,
227 "task": "<celery task id or None if done sync>"
227 "task": "<celery task id or None if done sync>"
228 }
228 }
229 error: null
229 error: null
230
230
231
231
232 get_repo
232 get_repo
233 --------
233 --------
234
234
235 .. py:function:: get_repo(apiuser, repoid, cache=<Optional:True>)
235 .. py:function:: get_repo(apiuser, repoid, cache=<Optional:True>)
236
236
237 Gets an existing repository by its name or repository_id.
237 Gets an existing repository by its name or repository_id.
238
238
239 The members section so the output returns users groups or users
239 The members section so the output returns users groups or users
240 associated with that repository.
240 associated with that repository.
241
241
242 This command can only be run using an |authtoken| with admin rights,
242 This command can only be run using an |authtoken| with admin rights,
243 or users with at least read rights to the |repo|.
243 or users with at least read rights to the |repo|.
244
244
245 :param apiuser: This is filled automatically from the |authtoken|.
245 :param apiuser: This is filled automatically from the |authtoken|.
246 :type apiuser: AuthUser
246 :type apiuser: AuthUser
247 :param repoid: The repository name or repository id.
247 :param repoid: The repository name or repository id.
248 :type repoid: str or int
248 :type repoid: str or int
249 :param cache: use the cached value for last changeset
249 :param cache: use the cached value for last changeset
250 :type: cache: Optional(bool)
250 :type: cache: Optional(bool)
251
251
252 Example output:
252 Example output:
253
253
254 .. code-block:: bash
254 .. code-block:: bash
255
255
256 {
256 {
257 "error": null,
257 "error": null,
258 "id": <repo_id>,
258 "id": <repo_id>,
259 "result": {
259 "result": {
260 "clone_uri": null,
260 "clone_uri": null,
261 "created_on": "timestamp",
261 "created_on": "timestamp",
262 "description": "repo description",
262 "description": "repo description",
263 "enable_downloads": false,
263 "enable_downloads": false,
264 "enable_locking": false,
264 "enable_locking": false,
265 "enable_statistics": false,
265 "enable_statistics": false,
266 "followers": [
266 "followers": [
267 {
267 {
268 "active": true,
268 "active": true,
269 "admin": false,
269 "admin": false,
270 "api_key": "****************************************",
270 "api_key": "****************************************",
271 "api_keys": [
271 "api_keys": [
272 "****************************************"
272 "****************************************"
273 ],
273 ],
274 "email": "user@example.com",
274 "email": "user@example.com",
275 "emails": [
275 "emails": [
276 "user@example.com"
276 "user@example.com"
277 ],
277 ],
278 "extern_name": "rhodecode",
278 "extern_name": "rhodecode",
279 "extern_type": "rhodecode",
279 "extern_type": "rhodecode",
280 "firstname": "username",
280 "firstname": "username",
281 "ip_addresses": [],
281 "ip_addresses": [],
282 "language": null,
282 "language": null,
283 "last_login": "2015-09-16T17:16:35.854",
283 "last_login": "2015-09-16T17:16:35.854",
284 "lastname": "surname",
284 "lastname": "surname",
285 "user_id": <user_id>,
285 "user_id": <user_id>,
286 "username": "name"
286 "username": "name"
287 }
287 }
288 ],
288 ],
289 "fork_of": "parent-repo",
289 "fork_of": "parent-repo",
290 "landing_rev": [
290 "landing_rev": [
291 "rev",
291 "rev",
292 "tip"
292 "tip"
293 ],
293 ],
294 "last_changeset": {
294 "last_changeset": {
295 "author": "User <user@example.com>",
295 "author": "User <user@example.com>",
296 "branch": "default",
296 "branch": "default",
297 "date": "timestamp",
297 "date": "timestamp",
298 "message": "last commit message",
298 "message": "last commit message",
299 "parents": [
299 "parents": [
300 {
300 {
301 "raw_id": "commit-id"
301 "raw_id": "commit-id"
302 }
302 }
303 ],
303 ],
304 "raw_id": "commit-id",
304 "raw_id": "commit-id",
305 "revision": <revision number>,
305 "revision": <revision number>,
306 "short_id": "short id"
306 "short_id": "short id"
307 },
307 },
308 "lock_reason": null,
308 "lock_reason": null,
309 "locked_by": null,
309 "locked_by": null,
310 "locked_date": null,
310 "locked_date": null,
311 "owner": "owner-name",
311 "owner": "owner-name",
312 "permissions": [
312 "permissions": [
313 {
313 {
314 "name": "super-admin-name",
314 "name": "super-admin-name",
315 "origin": "super-admin",
315 "origin": "super-admin",
316 "permission": "repository.admin",
316 "permission": "repository.admin",
317 "type": "user"
317 "type": "user"
318 },
318 },
319 {
319 {
320 "name": "owner-name",
320 "name": "owner-name",
321 "origin": "owner",
321 "origin": "owner",
322 "permission": "repository.admin",
322 "permission": "repository.admin",
323 "type": "user"
323 "type": "user"
324 },
324 },
325 {
325 {
326 "name": "user-group-name",
326 "name": "user-group-name",
327 "origin": "permission",
327 "origin": "permission",
328 "permission": "repository.write",
328 "permission": "repository.write",
329 "type": "user_group"
329 "type": "user_group"
330 }
330 }
331 ],
331 ],
332 "private": true,
332 "private": true,
333 "repo_id": 676,
333 "repo_id": 676,
334 "repo_name": "user-group/repo-name",
334 "repo_name": "user-group/repo-name",
335 "repo_type": "hg"
335 "repo_type": "hg"
336 }
336 }
337 }
337 }
338
338
339
339
340 get_repo_changeset
340 get_repo_changeset
341 ------------------
341 ------------------
342
342
343 .. py:function:: get_repo_changeset(apiuser, repoid, revision, details=<Optional:'basic'>)
343 .. py:function:: get_repo_changeset(apiuser, repoid, revision, details=<Optional:'basic'>)
344
344
345 Returns information about a changeset.
345 Returns information about a changeset.
346
346
347 Additionally parameters define the amount of details returned by
347 Additionally parameters define the amount of details returned by
348 this function.
348 this function.
349
349
350 This command can only be run using an |authtoken| with admin rights,
350 This command can only be run using an |authtoken| with admin rights,
351 or users with at least read rights to the |repo|.
351 or users with at least read rights to the |repo|.
352
352
353 :param apiuser: This is filled automatically from the |authtoken|.
353 :param apiuser: This is filled automatically from the |authtoken|.
354 :type apiuser: AuthUser
354 :type apiuser: AuthUser
355 :param repoid: The repository name or repository id
355 :param repoid: The repository name or repository id
356 :type repoid: str or int
356 :type repoid: str or int
357 :param revision: revision for which listing should be done
357 :param revision: revision for which listing should be done
358 :type revision: str
358 :type revision: str
359 :param details: details can be 'basic|extended|full' full gives diff
359 :param details: details can be 'basic|extended|full' full gives diff
360 info details like the diff itself, and number of changed files etc.
360 info details like the diff itself, and number of changed files etc.
361 :type details: Optional(str)
361 :type details: Optional(str)
362
362
363
363
364 get_repo_changesets
364 get_repo_changesets
365 -------------------
365 -------------------
366
366
367 .. py:function:: get_repo_changesets(apiuser, repoid, start_rev, limit, details=<Optional:'basic'>)
367 .. py:function:: get_repo_changesets(apiuser, repoid, start_rev, limit, details=<Optional:'basic'>)
368
368
369 Returns a set of commits limited by the number starting
369 Returns a set of commits limited by the number starting
370 from the `start_rev` option.
370 from the `start_rev` option.
371
371
372 Additional parameters define the amount of details returned by this
372 Additional parameters define the amount of details returned by this
373 function.
373 function.
374
374
375 This command can only be run using an |authtoken| with admin rights,
375 This command can only be run using an |authtoken| with admin rights,
376 or users with at least read rights to |repos|.
376 or users with at least read rights to |repos|.
377
377
378 :param apiuser: This is filled automatically from the |authtoken|.
378 :param apiuser: This is filled automatically from the |authtoken|.
379 :type apiuser: AuthUser
379 :type apiuser: AuthUser
380 :param repoid: The repository name or repository ID.
380 :param repoid: The repository name or repository ID.
381 :type repoid: str or int
381 :type repoid: str or int
382 :param start_rev: The starting revision from where to get changesets.
382 :param start_rev: The starting revision from where to get changesets.
383 :type start_rev: str
383 :type start_rev: str
384 :param limit: Limit the number of commits to this amount
384 :param limit: Limit the number of commits to this amount
385 :type limit: str or int
385 :type limit: str or int
386 :param details: Set the level of detail returned. Valid option are:
386 :param details: Set the level of detail returned. Valid option are:
387 ``basic``, ``extended`` and ``full``.
387 ``basic``, ``extended`` and ``full``.
388 :type details: Optional(str)
388 :type details: Optional(str)
389
389
390 .. note::
390 .. note::
391
391
392 Setting the parameter `details` to the value ``full`` is extensive
392 Setting the parameter `details` to the value ``full`` is extensive
393 and returns details like the diff itself, and the number
393 and returns details like the diff itself, and the number
394 of changed files.
394 of changed files.
395
395
396
396
397 get_repo_comments
398 -----------------
399
400 .. py:function:: get_repo_comments(apiuser, repoid, commit_id=<Optional:None>, comment_type=<Optional:None>, userid=<Optional:None>)
401
402 Get all comments for a repository
403
404 :param apiuser: This is filled automatically from the |authtoken|.
405 :type apiuser: AuthUser
406 :param repoid: Set the repository name or repository ID.
407 :type repoid: str or int
408 :param commit_id: Optionally filter the comments by the commit_id
409 :type commit_id: Optional(str), default: None
410 :param comment_type: Optionally filter the comments by the comment_type
411 one of: 'note', 'todo'
412 :type comment_type: Optional(str), default: None
413 :param userid: Optionally filter the comments by the author of comment
414 :type userid: Optional(str or int), Default: None
415
416 Example error output:
417
418 .. code-block:: bash
419
420 {
421 "id" : <id_given_in_input>,
422 "result" : [
423 {
424 "comment_author": <USER_DETAILS>,
425 "comment_created_on": "2017-02-01T14:38:16.309",
426 "comment_f_path": "file.txt",
427 "comment_id": 282,
428 "comment_lineno": "n1",
429 "comment_resolved_by": null,
430 "comment_status": [],
431 "comment_text": "This file needs a header",
432 "comment_type": "todo"
433 }
434 ],
435 "error" : null
436 }
437
438
439 get_repo_file
440 -------------
441
442 .. py:function:: get_repo_file(apiuser, repoid, commit_id, file_path, max_file_bytes=<Optional:None>, details=<Optional:'basic'>, cache=<Optional:True>)
443
444 Returns a single file from repository at given revision.
445
446 This command can only be run using an |authtoken| with admin rights,
447 or users with at least read rights to |repos|.
448
449 :param apiuser: This is filled automatically from the |authtoken|.
450 :type apiuser: AuthUser
451 :param repoid: The repository name or repository ID.
452 :type repoid: str or int
453 :param commit_id: The revision for which listing should be done.
454 :type commit_id: str
455 :param file_path: The path from which to start displaying.
456 :type file_path: str
457 :param details: Returns different set of information about nodes.
458 The valid options are ``minimal`` ``basic`` and ``full``.
459 :type details: Optional(str)
460 :param max_file_bytes: Only return file content under this file size bytes
461 :type max_file_bytes: Optional(int)
462 :param cache: Use internal caches for fetching files. If disabled fetching
463 files is slower but more memory efficient
464 :type cache: Optional(bool)
465 Example output:
466
467 .. code-block:: bash
468
469 id : <id_given_in_input>
470 result: {
471 "binary": false,
472 "extension": "py",
473 "lines": 35,
474 "content": "....",
475 "md5": "76318336366b0f17ee249e11b0c99c41",
476 "mimetype": "text/x-python",
477 "name": "python.py",
478 "size": 817,
479 "type": "file",
480 }
481 error: null
482
483
484 get_repo_fts_tree
485 -----------------
486
487 .. py:function:: get_repo_fts_tree(apiuser, repoid, commit_id, root_path)
488
489 Returns a list of tree nodes for path at given revision. This api is built
490 strictly for usage in full text search building, and shouldn't be consumed
491
492 This command can only be run using an |authtoken| with admin rights,
493 or users with at least read rights to |repos|.
494
495
397 get_repo_nodes
496 get_repo_nodes
398 --------------
497 --------------
399
498
400 .. py:function:: get_repo_nodes(apiuser, repoid, revision, root_path, ret_type=<Optional:'all'>, details=<Optional:'basic'>, max_file_bytes=<Optional:None>)
499 .. py:function:: get_repo_nodes(apiuser, repoid, revision, root_path, ret_type=<Optional:'all'>, details=<Optional:'basic'>, max_file_bytes=<Optional:None>)
401
500
402 Returns a list of nodes and children in a flat list for a given
501 Returns a list of nodes and children in a flat list for a given
403 path at given revision.
502 path at given revision.
404
503
405 It's possible to specify ret_type to show only `files` or `dirs`.
504 It's possible to specify ret_type to show only `files` or `dirs`.
406
505
407 This command can only be run using an |authtoken| with admin rights,
506 This command can only be run using an |authtoken| with admin rights,
408 or users with at least read rights to |repos|.
507 or users with at least read rights to |repos|.
409
508
410 :param apiuser: This is filled automatically from the |authtoken|.
509 :param apiuser: This is filled automatically from the |authtoken|.
411 :type apiuser: AuthUser
510 :type apiuser: AuthUser
412 :param repoid: The repository name or repository ID.
511 :param repoid: The repository name or repository ID.
413 :type repoid: str or int
512 :type repoid: str or int
414 :param revision: The revision for which listing should be done.
513 :param revision: The revision for which listing should be done.
415 :type revision: str
514 :type revision: str
416 :param root_path: The path from which to start displaying.
515 :param root_path: The path from which to start displaying.
417 :type root_path: str
516 :type root_path: str
418 :param ret_type: Set the return type. Valid options are
517 :param ret_type: Set the return type. Valid options are
419 ``all`` (default), ``files`` and ``dirs``.
518 ``all`` (default), ``files`` and ``dirs``.
420 :type ret_type: Optional(str)
519 :type ret_type: Optional(str)
421 :param details: Returns extended information about nodes, such as
520 :param details: Returns extended information about nodes, such as
422 md5, binary, and or content. The valid options are ``basic`` and
521 md5, binary, and or content.
423 ``full``.
522 The valid options are ``basic`` and ``full``.
424 :type details: Optional(str)
523 :type details: Optional(str)
425 :param max_file_bytes: Only return file content under this file size bytes
524 :param max_file_bytes: Only return file content under this file size bytes
426 :type details: Optional(int)
525 :type details: Optional(int)
427
526
428 Example output:
527 Example output:
429
528
430 .. code-block:: bash
529 .. code-block:: bash
431
530
432 id : <id_given_in_input>
531 id : <id_given_in_input>
433 result: [
532 result: [
434 {
533 {
435 "name" : "<name>"
534 "binary": false,
436 "type" : "<type>",
535 "content": "File line
437 "binary": "<true|false>" (only in extended mode)
536 Line2
438 "md5" : "<md5 of file content>" (only in extended mode)
537 ",
538 "extension": "md",
539 "lines": 2,
540 "md5": "059fa5d29b19c0657e384749480f6422",
541 "mimetype": "text/x-minidsrc",
542 "name": "file.md",
543 "size": 580,
544 "type": "file"
439 },
545 },
440 ...
546 ...
441 ]
547 ]
442 error: null
548 error: null
443
549
444
550
445 get_repo_refs
551 get_repo_refs
446 -------------
552 -------------
447
553
448 .. py:function:: get_repo_refs(apiuser, repoid)
554 .. py:function:: get_repo_refs(apiuser, repoid)
449
555
450 Returns a dictionary of current references. It returns
556 Returns a dictionary of current references. It returns
451 bookmarks, branches, closed_branches, and tags for given repository
557 bookmarks, branches, closed_branches, and tags for given repository
452
558
453 It's possible to specify ret_type to show only `files` or `dirs`.
559 It's possible to specify ret_type to show only `files` or `dirs`.
454
560
455 This command can only be run using an |authtoken| with admin rights,
561 This command can only be run using an |authtoken| with admin rights,
456 or users with at least read rights to |repos|.
562 or users with at least read rights to |repos|.
457
563
458 :param apiuser: This is filled automatically from the |authtoken|.
564 :param apiuser: This is filled automatically from the |authtoken|.
459 :type apiuser: AuthUser
565 :type apiuser: AuthUser
460 :param repoid: The repository name or repository ID.
566 :param repoid: The repository name or repository ID.
461 :type repoid: str or int
567 :type repoid: str or int
462
568
463 Example output:
569 Example output:
464
570
465 .. code-block:: bash
571 .. code-block:: bash
466
572
467 id : <id_given_in_input>
573 id : <id_given_in_input>
468 "result": {
574 "result": {
469 "bookmarks": {
575 "bookmarks": {
470 "dev": "5611d30200f4040ba2ab4f3d64e5b06408a02188",
576 "dev": "5611d30200f4040ba2ab4f3d64e5b06408a02188",
471 "master": "367f590445081d8ec8c2ea0456e73ae1f1c3d6cf"
577 "master": "367f590445081d8ec8c2ea0456e73ae1f1c3d6cf"
472 },
578 },
473 "branches": {
579 "branches": {
474 "default": "5611d30200f4040ba2ab4f3d64e5b06408a02188",
580 "default": "5611d30200f4040ba2ab4f3d64e5b06408a02188",
475 "stable": "367f590445081d8ec8c2ea0456e73ae1f1c3d6cf"
581 "stable": "367f590445081d8ec8c2ea0456e73ae1f1c3d6cf"
476 },
582 },
477 "branches_closed": {},
583 "branches_closed": {},
478 "tags": {
584 "tags": {
479 "tip": "5611d30200f4040ba2ab4f3d64e5b06408a02188",
585 "tip": "5611d30200f4040ba2ab4f3d64e5b06408a02188",
480 "v4.4.0": "1232313f9e6adac5ce5399c2a891dc1e72b79022",
586 "v4.4.0": "1232313f9e6adac5ce5399c2a891dc1e72b79022",
481 "v4.4.1": "cbb9f1d329ae5768379cdec55a62ebdd546c4e27",
587 "v4.4.1": "cbb9f1d329ae5768379cdec55a62ebdd546c4e27",
482 "v4.4.2": "24ffe44a27fcd1c5b6936144e176b9f6dd2f3a17",
588 "v4.4.2": "24ffe44a27fcd1c5b6936144e176b9f6dd2f3a17",
483 }
589 }
484 }
590 }
485 error: null
591 error: null
486
592
487
593
488 get_repo_settings
594 get_repo_settings
489 -----------------
595 -----------------
490
596
491 .. py:function:: get_repo_settings(apiuser, repoid, key=<Optional:None>)
597 .. py:function:: get_repo_settings(apiuser, repoid, key=<Optional:None>)
492
598
493 Returns all settings for a repository. If key is given it only returns the
599 Returns all settings for a repository. If key is given it only returns the
494 setting identified by the key or null.
600 setting identified by the key or null.
495
601
496 :param apiuser: This is filled automatically from the |authtoken|.
602 :param apiuser: This is filled automatically from the |authtoken|.
497 :type apiuser: AuthUser
603 :type apiuser: AuthUser
498 :param repoid: The repository name or repository id.
604 :param repoid: The repository name or repository id.
499 :type repoid: str or int
605 :type repoid: str or int
500 :param key: Key of the setting to return.
606 :param key: Key of the setting to return.
501 :type: key: Optional(str)
607 :type: key: Optional(str)
502
608
503 Example output:
609 Example output:
504
610
505 .. code-block:: bash
611 .. code-block:: bash
506
612
507 {
613 {
508 "error": null,
614 "error": null,
509 "id": 237,
615 "id": 237,
510 "result": {
616 "result": {
511 "extensions_largefiles": true,
617 "extensions_largefiles": true,
512 "extensions_evolve": true,
618 "extensions_evolve": true,
513 "hooks_changegroup_push_logger": true,
619 "hooks_changegroup_push_logger": true,
514 "hooks_changegroup_repo_size": false,
620 "hooks_changegroup_repo_size": false,
515 "hooks_outgoing_pull_logger": true,
621 "hooks_outgoing_pull_logger": true,
516 "phases_publish": "True",
622 "phases_publish": "True",
517 "rhodecode_hg_use_rebase_for_merging": true,
623 "rhodecode_hg_use_rebase_for_merging": true,
518 "rhodecode_pr_merge_enabled": true,
624 "rhodecode_pr_merge_enabled": true,
519 "rhodecode_use_outdated_comments": true
625 "rhodecode_use_outdated_comments": true
520 }
626 }
521 }
627 }
522
628
523
629
524 get_repos
630 get_repos
525 ---------
631 ---------
526
632
527 .. py:function:: get_repos(apiuser, root=<Optional:None>, traverse=<Optional:True>)
633 .. py:function:: get_repos(apiuser, root=<Optional:None>, traverse=<Optional:True>)
528
634
529 Lists all existing repositories.
635 Lists all existing repositories.
530
636
531 This command can only be run using an |authtoken| with admin rights,
637 This command can only be run using an |authtoken| with admin rights,
532 or users with at least read rights to |repos|.
638 or users with at least read rights to |repos|.
533
639
534 :param apiuser: This is filled automatically from the |authtoken|.
640 :param apiuser: This is filled automatically from the |authtoken|.
535 :type apiuser: AuthUser
641 :type apiuser: AuthUser
536 :param root: specify root repository group to fetch repositories.
642 :param root: specify root repository group to fetch repositories.
537 filters the returned repositories to be members of given root group.
643 filters the returned repositories to be members of given root group.
538 :type root: Optional(None)
644 :type root: Optional(None)
539 :param traverse: traverse given root into subrepositories. With this flag
645 :param traverse: traverse given root into subrepositories. With this flag
540 set to False, it will only return top-level repositories from `root`.
646 set to False, it will only return top-level repositories from `root`.
541 if root is empty it will return just top-level repositories.
647 if root is empty it will return just top-level repositories.
542 :type traverse: Optional(True)
648 :type traverse: Optional(True)
543
649
544
650
545 Example output:
651 Example output:
546
652
547 .. code-block:: bash
653 .. code-block:: bash
548
654
549 id : <id_given_in_input>
655 id : <id_given_in_input>
550 result: [
656 result: [
551 {
657 {
552 "repo_id" : "<repo_id>",
658 "repo_id" : "<repo_id>",
553 "repo_name" : "<reponame>"
659 "repo_name" : "<reponame>"
554 "repo_type" : "<repo_type>",
660 "repo_type" : "<repo_type>",
555 "clone_uri" : "<clone_uri>",
661 "clone_uri" : "<clone_uri>",
556 "private": : "<bool>",
662 "private": : "<bool>",
557 "created_on" : "<datetimecreated>",
663 "created_on" : "<datetimecreated>",
558 "description" : "<description>",
664 "description" : "<description>",
559 "landing_rev": "<landing_rev>",
665 "landing_rev": "<landing_rev>",
560 "owner": "<repo_owner>",
666 "owner": "<repo_owner>",
561 "fork_of": "<name_of_fork_parent>",
667 "fork_of": "<name_of_fork_parent>",
562 "enable_downloads": "<bool>",
668 "enable_downloads": "<bool>",
563 "enable_locking": "<bool>",
669 "enable_locking": "<bool>",
564 "enable_statistics": "<bool>",
670 "enable_statistics": "<bool>",
565 },
671 },
566 ...
672 ...
567 ]
673 ]
568 error: null
674 error: null
569
675
570
676
571 grant_user_group_permission
677 grant_user_group_permission
572 ---------------------------
678 ---------------------------
573
679
574 .. py:function:: grant_user_group_permission(apiuser, repoid, usergroupid, perm)
680 .. py:function:: grant_user_group_permission(apiuser, repoid, usergroupid, perm)
575
681
576 Grant permission for a user group on the specified repository,
682 Grant permission for a user group on the specified repository,
577 or update existing permissions.
683 or update existing permissions.
578
684
579 This command can only be run using an |authtoken| with admin
685 This command can only be run using an |authtoken| with admin
580 permissions on the |repo|.
686 permissions on the |repo|.
581
687
582 :param apiuser: This is filled automatically from the |authtoken|.
688 :param apiuser: This is filled automatically from the |authtoken|.
583 :type apiuser: AuthUser
689 :type apiuser: AuthUser
584 :param repoid: Set the repository name or repository ID.
690 :param repoid: Set the repository name or repository ID.
585 :type repoid: str or int
691 :type repoid: str or int
586 :param usergroupid: Specify the ID of the user group.
692 :param usergroupid: Specify the ID of the user group.
587 :type usergroupid: str or int
693 :type usergroupid: str or int
588 :param perm: Set the user group permissions using the following
694 :param perm: Set the user group permissions using the following
589 format: (repository.(none|read|write|admin))
695 format: (repository.(none|read|write|admin))
590 :type perm: str
696 :type perm: str
591
697
592 Example output:
698 Example output:
593
699
594 .. code-block:: bash
700 .. code-block:: bash
595
701
596 id : <id_given_in_input>
702 id : <id_given_in_input>
597 result : {
703 result : {
598 "msg" : "Granted perm: `<perm>` for group: `<usersgroupname>` in repo: `<reponame>`",
704 "msg" : "Granted perm: `<perm>` for group: `<usersgroupname>` in repo: `<reponame>`",
599 "success": true
705 "success": true
600
706
601 }
707 }
602 error : null
708 error : null
603
709
604 Example error output:
710 Example error output:
605
711
606 .. code-block:: bash
712 .. code-block:: bash
607
713
608 id : <id_given_in_input>
714 id : <id_given_in_input>
609 result : null
715 result : null
610 error : {
716 error : {
611 "failed to edit permission for user group: `<usergroup>` in repo `<repo>`'
717 "failed to edit permission for user group: `<usergroup>` in repo `<repo>`'
612 }
718 }
613
719
614
720
615 grant_user_permission
721 grant_user_permission
616 ---------------------
722 ---------------------
617
723
618 .. py:function:: grant_user_permission(apiuser, repoid, userid, perm)
724 .. py:function:: grant_user_permission(apiuser, repoid, userid, perm)
619
725
620 Grant permissions for the specified user on the given repository,
726 Grant permissions for the specified user on the given repository,
621 or update existing permissions if found.
727 or update existing permissions if found.
622
728
623 This command can only be run using an |authtoken| with admin
729 This command can only be run using an |authtoken| with admin
624 permissions on the |repo|.
730 permissions on the |repo|.
625
731
626 :param apiuser: This is filled automatically from the |authtoken|.
732 :param apiuser: This is filled automatically from the |authtoken|.
627 :type apiuser: AuthUser
733 :type apiuser: AuthUser
628 :param repoid: Set the repository name or repository ID.
734 :param repoid: Set the repository name or repository ID.
629 :type repoid: str or int
735 :type repoid: str or int
630 :param userid: Set the user name.
736 :param userid: Set the user name.
631 :type userid: str
737 :type userid: str
632 :param perm: Set the user permissions, using the following format
738 :param perm: Set the user permissions, using the following format
633 ``(repository.(none|read|write|admin))``
739 ``(repository.(none|read|write|admin))``
634 :type perm: str
740 :type perm: str
635
741
636 Example output:
742 Example output:
637
743
638 .. code-block:: bash
744 .. code-block:: bash
639
745
640 id : <id_given_in_input>
746 id : <id_given_in_input>
641 result: {
747 result: {
642 "msg" : "Granted perm: `<perm>` for user: `<username>` in repo: `<reponame>`",
748 "msg" : "Granted perm: `<perm>` for user: `<username>` in repo: `<reponame>`",
643 "success": true
749 "success": true
644 }
750 }
645 error: null
751 error: null
646
752
647
753
648 invalidate_cache
754 invalidate_cache
649 ----------------
755 ----------------
650
756
651 .. py:function:: invalidate_cache(apiuser, repoid, delete_keys=<Optional:False>)
757 .. py:function:: invalidate_cache(apiuser, repoid, delete_keys=<Optional:False>)
652
758
653 Invalidates the cache for the specified repository.
759 Invalidates the cache for the specified repository.
654
760
655 This command can only be run using an |authtoken| with admin rights to
761 This command can only be run using an |authtoken| with admin rights to
656 the specified repository.
762 the specified repository.
657
763
658 This command takes the following options:
764 This command takes the following options:
659
765
660 :param apiuser: This is filled automatically from |authtoken|.
766 :param apiuser: This is filled automatically from |authtoken|.
661 :type apiuser: AuthUser
767 :type apiuser: AuthUser
662 :param repoid: Sets the repository name or repository ID.
768 :param repoid: Sets the repository name or repository ID.
663 :type repoid: str or int
769 :type repoid: str or int
664 :param delete_keys: This deletes the invalidated keys instead of
770 :param delete_keys: This deletes the invalidated keys instead of
665 just flagging them.
771 just flagging them.
666 :type delete_keys: Optional(``True`` | ``False``)
772 :type delete_keys: Optional(``True`` | ``False``)
667
773
668 Example output:
774 Example output:
669
775
670 .. code-block:: bash
776 .. code-block:: bash
671
777
672 id : <id_given_in_input>
778 id : <id_given_in_input>
673 result : {
779 result : {
674 'msg': Cache for repository `<repository name>` was invalidated,
780 'msg': Cache for repository `<repository name>` was invalidated,
675 'repository': <repository name>
781 'repository': <repository name>
676 }
782 }
677 error : null
783 error : null
678
784
679 Example error output:
785 Example error output:
680
786
681 .. code-block:: bash
787 .. code-block:: bash
682
788
683 id : <id_given_in_input>
789 id : <id_given_in_input>
684 result : null
790 result : null
685 error : {
791 error : {
686 'Error occurred during cache invalidation action'
792 'Error occurred during cache invalidation action'
687 }
793 }
688
794
689
795
690 lock
796 lock
691 ----
797 ----
692
798
693 .. py:function:: lock(apiuser, repoid, locked=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>)
799 .. py:function:: lock(apiuser, repoid, locked=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>)
694
800
695 Sets the lock state of the specified |repo| by the given user.
801 Sets the lock state of the specified |repo| by the given user.
696 From more information, see :ref:`repo-locking`.
802 From more information, see :ref:`repo-locking`.
697
803
698 * If the ``userid`` option is not set, the repository is locked to the
804 * If the ``userid`` option is not set, the repository is locked to the
699 user who called the method.
805 user who called the method.
700 * If the ``locked`` parameter is not set, the current lock state of the
806 * If the ``locked`` parameter is not set, the current lock state of the
701 repository is displayed.
807 repository is displayed.
702
808
703 This command can only be run using an |authtoken| with admin rights to
809 This command can only be run using an |authtoken| with admin rights to
704 the specified repository.
810 the specified repository.
705
811
706 This command takes the following options:
812 This command takes the following options:
707
813
708 :param apiuser: This is filled automatically from the |authtoken|.
814 :param apiuser: This is filled automatically from the |authtoken|.
709 :type apiuser: AuthUser
815 :type apiuser: AuthUser
710 :param repoid: Sets the repository name or repository ID.
816 :param repoid: Sets the repository name or repository ID.
711 :type repoid: str or int
817 :type repoid: str or int
712 :param locked: Sets the lock state.
818 :param locked: Sets the lock state.
713 :type locked: Optional(``True`` | ``False``)
819 :type locked: Optional(``True`` | ``False``)
714 :param userid: Set the repository lock to this user.
820 :param userid: Set the repository lock to this user.
715 :type userid: Optional(str or int)
821 :type userid: Optional(str or int)
716
822
717 Example error output:
823 Example error output:
718
824
719 .. code-block:: bash
825 .. code-block:: bash
720
826
721 id : <id_given_in_input>
827 id : <id_given_in_input>
722 result : {
828 result : {
723 'repo': '<reponame>',
829 'repo': '<reponame>',
724 'locked': <bool: lock state>,
830 'locked': <bool: lock state>,
725 'locked_since': <int: lock timestamp>,
831 'locked_since': <int: lock timestamp>,
726 'locked_by': <username of person who made the lock>,
832 'locked_by': <username of person who made the lock>,
727 'lock_reason': <str: reason for locking>,
833 'lock_reason': <str: reason for locking>,
728 'lock_state_changed': <bool: True if lock state has been changed in this request>,
834 'lock_state_changed': <bool: True if lock state has been changed in this request>,
729 'msg': 'Repo `<reponame>` locked by `<username>` on <timestamp>.'
835 'msg': 'Repo `<reponame>` locked by `<username>` on <timestamp>.'
730 or
836 or
731 'msg': 'Repo `<repository name>` not locked.'
837 'msg': 'Repo `<repository name>` not locked.'
732 or
838 or
733 'msg': 'User `<user name>` set lock state for repo `<repository name>` to `<new lock state>`'
839 'msg': 'User `<user name>` set lock state for repo `<repository name>` to `<new lock state>`'
734 }
840 }
735 error : null
841 error : null
736
842
737 Example error output:
843 Example error output:
738
844
739 .. code-block:: bash
845 .. code-block:: bash
740
846
741 id : <id_given_in_input>
847 id : <id_given_in_input>
742 result : null
848 result : null
743 error : {
849 error : {
744 'Error occurred locking repository `<reponame>`'
850 'Error occurred locking repository `<reponame>`'
745 }
851 }
746
852
747
853
748 maintenance
854 maintenance
749 -----------
855 -----------
750
856
751 .. py:function:: maintenance(apiuser, repoid)
857 .. py:function:: maintenance(apiuser, repoid)
752
858
753 Triggers a maintenance on the given repository.
859 Triggers a maintenance on the given repository.
754
860
755 This command can only be run using an |authtoken| with admin
861 This command can only be run using an |authtoken| with admin
756 rights to the specified repository. For more information,
862 rights to the specified repository. For more information,
757 see :ref:`config-token-ref`.
863 see :ref:`config-token-ref`.
758
864
759 This command takes the following options:
865 This command takes the following options:
760
866
761 :param apiuser: This is filled automatically from the |authtoken|.
867 :param apiuser: This is filled automatically from the |authtoken|.
762 :type apiuser: AuthUser
868 :type apiuser: AuthUser
763 :param repoid: The repository name or repository ID.
869 :param repoid: The repository name or repository ID.
764 :type repoid: str or int
870 :type repoid: str or int
765
871
766 Example output:
872 Example output:
767
873
768 .. code-block:: bash
874 .. code-block:: bash
769
875
770 id : <id_given_in_input>
876 id : <id_given_in_input>
771 result : {
877 result : {
772 "msg": "executed maintenance command",
878 "msg": "executed maintenance command",
773 "executed_actions": [
879 "executed_actions": [
774 <action_message>, <action_message2>...
880 <action_message>, <action_message2>...
775 ],
881 ],
776 "repository": "<repository name>"
882 "repository": "<repository name>"
777 }
883 }
778 error : null
884 error : null
779
885
780 Example error output:
886 Example error output:
781
887
782 .. code-block:: bash
888 .. code-block:: bash
783
889
784 id : <id_given_in_input>
890 id : <id_given_in_input>
785 result : null
891 result : null
786 error : {
892 error : {
787 "Unable to execute maintenance on `<reponame>`"
893 "Unable to execute maintenance on `<reponame>`"
788 }
894 }
789
895
790
896
791 pull
897 pull
792 ----
898 ----
793
899
794 .. py:function:: pull(apiuser, repoid, remote_uri=<Optional:None>)
900 .. py:function:: pull(apiuser, repoid, remote_uri=<Optional:None>)
795
901
796 Triggers a pull on the given repository from a remote location. You
902 Triggers a pull on the given repository from a remote location. You
797 can use this to keep remote repositories up-to-date.
903 can use this to keep remote repositories up-to-date.
798
904
799 This command can only be run using an |authtoken| with admin
905 This command can only be run using an |authtoken| with admin
800 rights to the specified repository. For more information,
906 rights to the specified repository. For more information,
801 see :ref:`config-token-ref`.
907 see :ref:`config-token-ref`.
802
908
803 This command takes the following options:
909 This command takes the following options:
804
910
805 :param apiuser: This is filled automatically from the |authtoken|.
911 :param apiuser: This is filled automatically from the |authtoken|.
806 :type apiuser: AuthUser
912 :type apiuser: AuthUser
807 :param repoid: The repository name or repository ID.
913 :param repoid: The repository name or repository ID.
808 :type repoid: str or int
914 :type repoid: str or int
809 :param remote_uri: Optional remote URI to pass in for pull
915 :param remote_uri: Optional remote URI to pass in for pull
810 :type remote_uri: str
916 :type remote_uri: str
811
917
812 Example output:
918 Example output:
813
919
814 .. code-block:: bash
920 .. code-block:: bash
815
921
816 id : <id_given_in_input>
922 id : <id_given_in_input>
817 result : {
923 result : {
818 "msg": "Pulled from url `<remote_url>` on repo `<repository name>`"
924 "msg": "Pulled from url `<remote_url>` on repo `<repository name>`"
819 "repository": "<repository name>"
925 "repository": "<repository name>"
820 }
926 }
821 error : null
927 error : null
822
928
823 Example error output:
929 Example error output:
824
930
825 .. code-block:: bash
931 .. code-block:: bash
826
932
827 id : <id_given_in_input>
933 id : <id_given_in_input>
828 result : null
934 result : null
829 error : {
935 error : {
830 "Unable to push changes from `<remote_url>`"
936 "Unable to push changes from `<remote_url>`"
831 }
937 }
832
938
833
939
834 remove_field_from_repo
940 remove_field_from_repo
835 ----------------------
941 ----------------------
836
942
837 .. py:function:: remove_field_from_repo(apiuser, repoid, key)
943 .. py:function:: remove_field_from_repo(apiuser, repoid, key)
838
944
839 Removes an extra field from a repository.
945 Removes an extra field from a repository.
840
946
841 This command can only be run using an |authtoken| with at least
947 This command can only be run using an |authtoken| with at least
842 write permissions to the |repo|.
948 write permissions to the |repo|.
843
949
844 :param apiuser: This is filled automatically from the |authtoken|.
950 :param apiuser: This is filled automatically from the |authtoken|.
845 :type apiuser: AuthUser
951 :type apiuser: AuthUser
846 :param repoid: Set the repository name or repository ID.
952 :param repoid: Set the repository name or repository ID.
847 :type repoid: str or int
953 :type repoid: str or int
848 :param key: Set the unique field key for this repository.
954 :param key: Set the unique field key for this repository.
849 :type key: str
955 :type key: str
850
956
851
957
852 revoke_user_group_permission
958 revoke_user_group_permission
853 ----------------------------
959 ----------------------------
854
960
855 .. py:function:: revoke_user_group_permission(apiuser, repoid, usergroupid)
961 .. py:function:: revoke_user_group_permission(apiuser, repoid, usergroupid)
856
962
857 Revoke the permissions of a user group on a given repository.
963 Revoke the permissions of a user group on a given repository.
858
964
859 This command can only be run using an |authtoken| with admin
965 This command can only be run using an |authtoken| with admin
860 permissions on the |repo|.
966 permissions on the |repo|.
861
967
862 :param apiuser: This is filled automatically from the |authtoken|.
968 :param apiuser: This is filled automatically from the |authtoken|.
863 :type apiuser: AuthUser
969 :type apiuser: AuthUser
864 :param repoid: Set the repository name or repository ID.
970 :param repoid: Set the repository name or repository ID.
865 :type repoid: str or int
971 :type repoid: str or int
866 :param usergroupid: Specify the user group ID.
972 :param usergroupid: Specify the user group ID.
867 :type usergroupid: str or int
973 :type usergroupid: str or int
868
974
869 Example output:
975 Example output:
870
976
871 .. code-block:: bash
977 .. code-block:: bash
872
978
873 id : <id_given_in_input>
979 id : <id_given_in_input>
874 result: {
980 result: {
875 "msg" : "Revoked perm for group: `<usersgroupname>` in repo: `<reponame>`",
981 "msg" : "Revoked perm for group: `<usersgroupname>` in repo: `<reponame>`",
876 "success": true
982 "success": true
877 }
983 }
878 error: null
984 error: null
879
985
880
986
881 revoke_user_permission
987 revoke_user_permission
882 ----------------------
988 ----------------------
883
989
884 .. py:function:: revoke_user_permission(apiuser, repoid, userid)
990 .. py:function:: revoke_user_permission(apiuser, repoid, userid)
885
991
886 Revoke permission for a user on the specified repository.
992 Revoke permission for a user on the specified repository.
887
993
888 This command can only be run using an |authtoken| with admin
994 This command can only be run using an |authtoken| with admin
889 permissions on the |repo|.
995 permissions on the |repo|.
890
996
891 :param apiuser: This is filled automatically from the |authtoken|.
997 :param apiuser: This is filled automatically from the |authtoken|.
892 :type apiuser: AuthUser
998 :type apiuser: AuthUser
893 :param repoid: Set the repository name or repository ID.
999 :param repoid: Set the repository name or repository ID.
894 :type repoid: str or int
1000 :type repoid: str or int
895 :param userid: Set the user name of revoked user.
1001 :param userid: Set the user name of revoked user.
896 :type userid: str or int
1002 :type userid: str or int
897
1003
898 Example error output:
1004 Example error output:
899
1005
900 .. code-block:: bash
1006 .. code-block:: bash
901
1007
902 id : <id_given_in_input>
1008 id : <id_given_in_input>
903 result: {
1009 result: {
904 "msg" : "Revoked perm for user: `<username>` in repo: `<reponame>`",
1010 "msg" : "Revoked perm for user: `<username>` in repo: `<reponame>`",
905 "success": true
1011 "success": true
906 }
1012 }
907 error: null
1013 error: null
908
1014
909
1015
910 set_repo_settings
1016 set_repo_settings
911 -----------------
1017 -----------------
912
1018
913 .. py:function:: set_repo_settings(apiuser, repoid, settings)
1019 .. py:function:: set_repo_settings(apiuser, repoid, settings)
914
1020
915 Update repository settings. Returns true on success.
1021 Update repository settings. Returns true on success.
916
1022
917 :param apiuser: This is filled automatically from the |authtoken|.
1023 :param apiuser: This is filled automatically from the |authtoken|.
918 :type apiuser: AuthUser
1024 :type apiuser: AuthUser
919 :param repoid: The repository name or repository id.
1025 :param repoid: The repository name or repository id.
920 :type repoid: str or int
1026 :type repoid: str or int
921 :param settings: The new settings for the repository.
1027 :param settings: The new settings for the repository.
922 :type: settings: dict
1028 :type: settings: dict
923
1029
924 Example output:
1030 Example output:
925
1031
926 .. code-block:: bash
1032 .. code-block:: bash
927
1033
928 {
1034 {
929 "error": null,
1035 "error": null,
930 "id": 237,
1036 "id": 237,
931 "result": true
1037 "result": true
932 }
1038 }
933
1039
934
1040
935 strip
1041 strip
936 -----
1042 -----
937
1043
938 .. py:function:: strip(apiuser, repoid, revision, branch)
1044 .. py:function:: strip(apiuser, repoid, revision, branch)
939
1045
940 Strips the given revision from the specified repository.
1046 Strips the given revision from the specified repository.
941
1047
942 * This will remove the revision and all of its decendants.
1048 * This will remove the revision and all of its decendants.
943
1049
944 This command can only be run using an |authtoken| with admin rights to
1050 This command can only be run using an |authtoken| with admin rights to
945 the specified repository.
1051 the specified repository.
946
1052
947 This command takes the following options:
1053 This command takes the following options:
948
1054
949 :param apiuser: This is filled automatically from the |authtoken|.
1055 :param apiuser: This is filled automatically from the |authtoken|.
950 :type apiuser: AuthUser
1056 :type apiuser: AuthUser
951 :param repoid: The repository name or repository ID.
1057 :param repoid: The repository name or repository ID.
952 :type repoid: str or int
1058 :type repoid: str or int
953 :param revision: The revision you wish to strip.
1059 :param revision: The revision you wish to strip.
954 :type revision: str
1060 :type revision: str
955 :param branch: The branch from which to strip the revision.
1061 :param branch: The branch from which to strip the revision.
956 :type branch: str
1062 :type branch: str
957
1063
958 Example output:
1064 Example output:
959
1065
960 .. code-block:: bash
1066 .. code-block:: bash
961
1067
962 id : <id_given_in_input>
1068 id : <id_given_in_input>
963 result : {
1069 result : {
964 "msg": "'Stripped commit <commit_hash> from repo `<repository name>`'"
1070 "msg": "'Stripped commit <commit_hash> from repo `<repository name>`'"
965 "repository": "<repository name>"
1071 "repository": "<repository name>"
966 }
1072 }
967 error : null
1073 error : null
968
1074
969 Example error output:
1075 Example error output:
970
1076
971 .. code-block:: bash
1077 .. code-block:: bash
972
1078
973 id : <id_given_in_input>
1079 id : <id_given_in_input>
974 result : null
1080 result : null
975 error : {
1081 error : {
976 "Unable to strip commit <commit_hash> from repo `<repository name>`"
1082 "Unable to strip commit <commit_hash> from repo `<repository name>`"
977 }
1083 }
978
1084
979
1085
980 update_repo
1086 update_repo
981 -----------
1087 -----------
982
1088
983 .. py:function:: update_repo(apiuser, repoid, repo_name=<Optional:None>, owner=<Optional:<OptionalAttr:apiuser>>, description=<Optional:''>, private=<Optional:False>, clone_uri=<Optional:None>, push_uri=<Optional:None>, landing_rev=<Optional:'rev:tip'>, fork_of=<Optional:None>, enable_statistics=<Optional:False>, enable_locking=<Optional:False>, enable_downloads=<Optional:False>, fields=<Optional:''>)
1089 .. py:function:: update_repo(apiuser, repoid, repo_name=<Optional:None>, owner=<Optional:<OptionalAttr:apiuser>>, description=<Optional:''>, private=<Optional:False>, clone_uri=<Optional:None>, push_uri=<Optional:None>, landing_rev=<Optional:'rev:tip'>, fork_of=<Optional:None>, enable_statistics=<Optional:False>, enable_locking=<Optional:False>, enable_downloads=<Optional:False>, fields=<Optional:''>)
984
1090
985 Updates a repository with the given information.
1091 Updates a repository with the given information.
986
1092
987 This command can only be run using an |authtoken| with at least
1093 This command can only be run using an |authtoken| with at least
988 admin permissions to the |repo|.
1094 admin permissions to the |repo|.
989
1095
990 * If the repository name contains "/", repository will be updated
1096 * If the repository name contains "/", repository will be updated
991 accordingly with a repository group or nested repository groups
1097 accordingly with a repository group or nested repository groups
992
1098
993 For example repoid=repo-test name="foo/bar/repo-test" will update |repo|
1099 For example repoid=repo-test name="foo/bar/repo-test" will update |repo|
994 called "repo-test" and place it inside group "foo/bar".
1100 called "repo-test" and place it inside group "foo/bar".
995 You have to have permissions to access and write to the last repository
1101 You have to have permissions to access and write to the last repository
996 group ("bar" in this example)
1102 group ("bar" in this example)
997
1103
998 :param apiuser: This is filled automatically from the |authtoken|.
1104 :param apiuser: This is filled automatically from the |authtoken|.
999 :type apiuser: AuthUser
1105 :type apiuser: AuthUser
1000 :param repoid: repository name or repository ID.
1106 :param repoid: repository name or repository ID.
1001 :type repoid: str or int
1107 :type repoid: str or int
1002 :param repo_name: Update the |repo| name, including the
1108 :param repo_name: Update the |repo| name, including the
1003 repository group it's in.
1109 repository group it's in.
1004 :type repo_name: str
1110 :type repo_name: str
1005 :param owner: Set the |repo| owner.
1111 :param owner: Set the |repo| owner.
1006 :type owner: str
1112 :type owner: str
1007 :param fork_of: Set the |repo| as fork of another |repo|.
1113 :param fork_of: Set the |repo| as fork of another |repo|.
1008 :type fork_of: str
1114 :type fork_of: str
1009 :param description: Update the |repo| description.
1115 :param description: Update the |repo| description.
1010 :type description: str
1116 :type description: str
1011 :param private: Set the |repo| as private. (True | False)
1117 :param private: Set the |repo| as private. (True | False)
1012 :type private: bool
1118 :type private: bool
1013 :param clone_uri: Update the |repo| clone URI.
1119 :param clone_uri: Update the |repo| clone URI.
1014 :type clone_uri: str
1120 :type clone_uri: str
1015 :param landing_rev: Set the |repo| landing revision. Default is ``rev:tip``.
1121 :param landing_rev: Set the |repo| landing revision. Default is ``rev:tip``.
1016 :type landing_rev: str
1122 :type landing_rev: str
1017 :param enable_statistics: Enable statistics on the |repo|, (True | False).
1123 :param enable_statistics: Enable statistics on the |repo|, (True | False).
1018 :type enable_statistics: bool
1124 :type enable_statistics: bool
1019 :param enable_locking: Enable |repo| locking.
1125 :param enable_locking: Enable |repo| locking.
1020 :type enable_locking: bool
1126 :type enable_locking: bool
1021 :param enable_downloads: Enable downloads from the |repo|, (True | False).
1127 :param enable_downloads: Enable downloads from the |repo|, (True | False).
1022 :type enable_downloads: bool
1128 :type enable_downloads: bool
1023 :param fields: Add extra fields to the |repo|. Use the following
1129 :param fields: Add extra fields to the |repo|. Use the following
1024 example format: ``field_key=field_val,field_key2=fieldval2``.
1130 example format: ``field_key=field_val,field_key2=fieldval2``.
1025 Escape ', ' with \,
1131 Escape ', ' with \,
1026 :type fields: str
1132 :type fields: str
1027
1133
1028
1134
@@ -1,234 +1,268 b''
1 .. _server-methods-ref:
1 .. _server-methods-ref:
2
2
3 server methods
3 server methods
4 ==============
4 ==============
5
5
6 cleanup_sessions
6 cleanup_sessions
7 ----------------
7 ----------------
8
8
9 .. py:function:: cleanup_sessions(apiuser, older_then=<Optional:60>)
9 .. py:function:: cleanup_sessions(apiuser, older_then=<Optional:60>)
10
10
11 Triggers a session cleanup action.
11 Triggers a session cleanup action.
12
12
13 If the ``older_then`` option is set, only sessions that hasn't been
13 If the ``older_then`` option is set, only sessions that hasn't been
14 accessed in the given number of days will be removed.
14 accessed in the given number of days will be removed.
15
15
16 This command can only be run using an |authtoken| with admin rights to
16 This command can only be run using an |authtoken| with admin rights to
17 the specified repository.
17 the specified repository.
18
18
19 This command takes the following options:
19 This command takes the following options:
20
20
21 :param apiuser: This is filled automatically from the |authtoken|.
21 :param apiuser: This is filled automatically from the |authtoken|.
22 :type apiuser: AuthUser
22 :type apiuser: AuthUser
23 :param older_then: Deletes session that hasn't been accessed
23 :param older_then: Deletes session that hasn't been accessed
24 in given number of days.
24 in given number of days.
25 :type older_then: Optional(int)
25 :type older_then: Optional(int)
26
26
27 Example output:
27 Example output:
28
28
29 .. code-block:: bash
29 .. code-block:: bash
30
30
31 id : <id_given_in_input>
31 id : <id_given_in_input>
32 result: {
32 result: {
33 "backend": "<type of backend>",
33 "backend": "<type of backend>",
34 "sessions_removed": <number_of_removed_sessions>
34 "sessions_removed": <number_of_removed_sessions>
35 }
35 }
36 error : null
36 error : null
37
37
38 Example error output:
38 Example error output:
39
39
40 .. code-block:: bash
40 .. code-block:: bash
41
41
42 id : <id_given_in_input>
42 id : <id_given_in_input>
43 result : null
43 result : null
44 error : {
44 error : {
45 'Error occurred during session cleanup'
45 'Error occurred during session cleanup'
46 }
46 }
47
47
48
48
49 get_ip
49 get_ip
50 ------
50 ------
51
51
52 .. py:function:: get_ip(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)
52 .. py:function:: get_ip(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)
53
53
54 Displays the IP Address as seen from the |RCE| server.
54 Displays the IP Address as seen from the |RCE| server.
55
55
56 * This command displays the IP Address, as well as all the defined IP
56 * This command displays the IP Address, as well as all the defined IP
57 addresses for the specified user. If the ``userid`` is not set, the
57 addresses for the specified user. If the ``userid`` is not set, the
58 data returned is for the user calling the method.
58 data returned is for the user calling the method.
59
59
60 This command can only be run using an |authtoken| with admin rights to
60 This command can only be run using an |authtoken| with admin rights to
61 the specified repository.
61 the specified repository.
62
62
63 This command takes the following options:
63 This command takes the following options:
64
64
65 :param apiuser: This is filled automatically from |authtoken|.
65 :param apiuser: This is filled automatically from |authtoken|.
66 :type apiuser: AuthUser
66 :type apiuser: AuthUser
67 :param userid: Sets the userid for which associated IP Address data
67 :param userid: Sets the userid for which associated IP Address data
68 is returned.
68 is returned.
69 :type userid: Optional(str or int)
69 :type userid: Optional(str or int)
70
70
71 Example output:
71 Example output:
72
72
73 .. code-block:: bash
73 .. code-block:: bash
74
74
75 id : <id_given_in_input>
75 id : <id_given_in_input>
76 result : {
76 result : {
77 "server_ip_addr": "<ip_from_clien>",
77 "server_ip_addr": "<ip_from_clien>",
78 "user_ips": [
78 "user_ips": [
79 {
79 {
80 "ip_addr": "<ip_with_mask>",
80 "ip_addr": "<ip_with_mask>",
81 "ip_range": ["<start_ip>", "<end_ip>"],
81 "ip_range": ["<start_ip>", "<end_ip>"],
82 },
82 },
83 ...
83 ...
84 ]
84 ]
85 }
85 }
86
86
87
87
88 get_method
88 get_method
89 ----------
89 ----------
90
90
91 .. py:function:: get_method(apiuser, pattern=<Optional:'*'>)
91 .. py:function:: get_method(apiuser, pattern=<Optional:'*'>)
92
92
93 Returns list of all available API methods. By default match pattern
93 Returns list of all available API methods. By default match pattern
94 os "*" but any other pattern can be specified. eg *comment* will return
94 os "*" but any other pattern can be specified. eg *comment* will return
95 all methods with comment inside them. If just single method is matched
95 all methods with comment inside them. If just single method is matched
96 returned data will also include method specification
96 returned data will also include method specification
97
97
98 This command can only be run using an |authtoken| with admin rights to
98 This command can only be run using an |authtoken| with admin rights to
99 the specified repository.
99 the specified repository.
100
100
101 This command takes the following options:
101 This command takes the following options:
102
102
103 :param apiuser: This is filled automatically from the |authtoken|.
103 :param apiuser: This is filled automatically from the |authtoken|.
104 :type apiuser: AuthUser
104 :type apiuser: AuthUser
105 :param pattern: pattern to match method names against
105 :param pattern: pattern to match method names against
106 :type older_then: Optional("*")
106 :type pattern: Optional("*")
107
107
108 Example output:
108 Example output:
109
109
110 .. code-block:: bash
110 .. code-block:: bash
111
111
112 id : <id_given_in_input>
112 id : <id_given_in_input>
113 "result": [
113 "result": [
114 "changeset_comment",
114 "changeset_comment",
115 "comment_pull_request",
115 "comment_pull_request",
116 "comment_commit"
116 "comment_commit"
117 ]
117 ]
118 error : null
118 error : null
119
119
120 .. code-block:: bash
120 .. code-block:: bash
121
121
122 id : <id_given_in_input>
122 id : <id_given_in_input>
123 "result": [
123 "result": [
124 "comment_commit",
124 "comment_commit",
125 {
125 {
126 "apiuser": "<RequiredType>",
126 "apiuser": "<RequiredType>",
127 "comment_type": "<Optional:u'note'>",
127 "comment_type": "<Optional:u'note'>",
128 "commit_id": "<RequiredType>",
128 "commit_id": "<RequiredType>",
129 "message": "<RequiredType>",
129 "message": "<RequiredType>",
130 "repoid": "<RequiredType>",
130 "repoid": "<RequiredType>",
131 "request": "<RequiredType>",
131 "request": "<RequiredType>",
132 "resolves_comment_id": "<Optional:None>",
132 "resolves_comment_id": "<Optional:None>",
133 "status": "<Optional:None>",
133 "status": "<Optional:None>",
134 "userid": "<Optional:<OptionalAttr:apiuser>>"
134 "userid": "<Optional:<OptionalAttr:apiuser>>"
135 }
135 }
136 ]
136 ]
137 error : null
137 error : null
138
138
139
139
140 get_repo_store
140 get_repo_store
141 --------------
141 --------------
142
142
143 .. py:function:: get_repo_store(apiuser)
143 .. py:function:: get_repo_store(apiuser)
144
144
145 Returns the |RCE| repository storage information.
145 Returns the |RCE| repository storage information.
146
146
147 :param apiuser: This is filled automatically from the |authtoken|.
147 :param apiuser: This is filled automatically from the |authtoken|.
148 :type apiuser: AuthUser
148 :type apiuser: AuthUser
149
149
150 Example output:
150 Example output:
151
151
152 .. code-block:: bash
152 .. code-block:: bash
153
153
154 id : <id_given_in_input>
154 id : <id_given_in_input>
155 result : {
155 result : {
156 'modules': [<module name>,...]
156 'modules': [<module name>,...]
157 'py_version': <python version>,
157 'py_version': <python version>,
158 'platform': <platform type>,
158 'platform': <platform type>,
159 'rhodecode_version': <rhodecode version>
159 'rhodecode_version': <rhodecode version>
160 }
160 }
161 error : null
161 error : null
162
162
163
163
164 get_server_info
164 get_server_info
165 ---------------
165 ---------------
166
166
167 .. py:function:: get_server_info(apiuser)
167 .. py:function:: get_server_info(apiuser)
168
168
169 Returns the |RCE| server information.
169 Returns the |RCE| server information.
170
170
171 This includes the running version of |RCE| and all installed
171 This includes the running version of |RCE| and all installed
172 packages. This command takes the following options:
172 packages. This command takes the following options:
173
173
174 :param apiuser: This is filled automatically from the |authtoken|.
174 :param apiuser: This is filled automatically from the |authtoken|.
175 :type apiuser: AuthUser
175 :type apiuser: AuthUser
176
176
177 Example output:
177 Example output:
178
178
179 .. code-block:: bash
179 .. code-block:: bash
180
180
181 id : <id_given_in_input>
181 id : <id_given_in_input>
182 result : {
182 result : {
183 'modules': [<module name>,...]
183 'modules': [<module name>,...]
184 'py_version': <python version>,
184 'py_version': <python version>,
185 'platform': <platform type>,
185 'platform': <platform type>,
186 'rhodecode_version': <rhodecode version>
186 'rhodecode_version': <rhodecode version>
187 }
187 }
188 error : null
188 error : null
189
189
190
190
191 rescan_repos
191 rescan_repos
192 ------------
192 ------------
193
193
194 .. py:function:: rescan_repos(apiuser, remove_obsolete=<Optional:False>)
194 .. py:function:: rescan_repos(apiuser, remove_obsolete=<Optional:False>)
195
195
196 Triggers a rescan of the specified repositories.
196 Triggers a rescan of the specified repositories.
197
197
198 * If the ``remove_obsolete`` option is set, it also deletes repositories
198 * If the ``remove_obsolete`` option is set, it also deletes repositories
199 that are found in the database but not on the file system, so called
199 that are found in the database but not on the file system, so called
200 "clean zombies".
200 "clean zombies".
201
201
202 This command can only be run using an |authtoken| with admin rights to
202 This command can only be run using an |authtoken| with admin rights to
203 the specified repository.
203 the specified repository.
204
204
205 This command takes the following options:
205 This command takes the following options:
206
206
207 :param apiuser: This is filled automatically from the |authtoken|.
207 :param apiuser: This is filled automatically from the |authtoken|.
208 :type apiuser: AuthUser
208 :type apiuser: AuthUser
209 :param remove_obsolete: Deletes repositories from the database that
209 :param remove_obsolete: Deletes repositories from the database that
210 are not found on the filesystem.
210 are not found on the filesystem.
211 :type remove_obsolete: Optional(``True`` | ``False``)
211 :type remove_obsolete: Optional(``True`` | ``False``)
212
212
213 Example output:
213 Example output:
214
214
215 .. code-block:: bash
215 .. code-block:: bash
216
216
217 id : <id_given_in_input>
217 id : <id_given_in_input>
218 result : {
218 result : {
219 'added': [<added repository name>,...]
219 'added': [<added repository name>,...]
220 'removed': [<removed repository name>,...]
220 'removed': [<removed repository name>,...]
221 }
221 }
222 error : null
222 error : null
223
223
224 Example error output:
224 Example error output:
225
225
226 .. code-block:: bash
226 .. code-block:: bash
227
227
228 id : <id_given_in_input>
228 id : <id_given_in_input>
229 result : null
229 result : null
230 error : {
230 error : {
231 'Error occurred during rescan repositories action'
231 'Error occurred during rescan repositories action'
232 }
232 }
233
233
234
234
235 store_exception
236 ---------------
237
238 .. py:function:: store_exception(apiuser, exc_data_json, prefix=<Optional:'rhodecode'>)
239
240 Stores sent exception inside the built-in exception tracker in |RCE| server.
241
242 This command can only be run using an |authtoken| with admin rights to
243 the specified repository.
244
245 This command takes the following options:
246
247 :param apiuser: This is filled automatically from the |authtoken|.
248 :type apiuser: AuthUser
249
250 :param exc_data_json: JSON data with exception e.g
251 {"exc_traceback": "Value `1` is not allowed", "exc_type_name": "ValueError"}
252 :type exc_data_json: JSON data
253
254 :param prefix: prefix for error type, e.g 'rhodecode', 'vcsserver', 'rhodecode-tools'
255 :type prefix: Optional("rhodecode")
256
257 Example output:
258
259 .. code-block:: bash
260
261 id : <id_given_in_input>
262 "result": {
263 "exc_id": 139718459226384,
264 "exc_url": "http://localhost:8080/_admin/settings/exceptions/139718459226384"
265 }
266 error : null
267
268
1 NO CONTENT: file was removed
NO CONTENT: file was removed
General Comments 0
You need to be logged in to leave comments. Login now