1// SPDX-License-Identifier: MIT
2
3syntax = "proto3";
4
5package ermite;
6
7import "ermite/git.proto";
8import "ermite/types.proto";
9import "google/protobuf/timestamp.proto";
10
11// MergeRequestState is where a merge request is in its life.
12enum MergeRequestState {
13 // Not set. In ListMergeRequestsRequest.state it means every state. Never
14 // returned by the server.
15 MERGE_REQUEST_STATE_UNSPECIFIED = 0;
16 // The merge request awaits review; it can be commented on, merged or closed.
17 MERGE_REQUEST_STATE_OPEN = 1;
18 // The source branch was merged into the target. Final.
19 MERGE_REQUEST_STATE_MERGED = 2;
20 // The merge request was closed without merging. Final.
21 MERGE_REQUEST_STATE_CLOSED = 3;
22}
23
24// DiffSide is the side of a diff a line comment is attached to.
25enum DiffSide {
26 // Not set. On a Comment it means the comment is general, not attached to a
27 // line. In AddCommentRequest it is valid only for a general comment.
28 DIFF_SIDE_UNSPECIFIED = 0;
29 // The old side: the line is a Line.old_number (a deletion or a context line).
30 DIFF_SIDE_OLD = 1;
31 // The new side: the line is a Line.new_number (an addition or a context
32 // line).
33 DIFF_SIDE_NEW = 2;
34}
35
36// Verdict is the judgement a reviewer gives with a comment.
37enum Verdict {
38 // Not set. The comment carries no verdict. In AddCommentRequest it means a
39 // plain comment.
40 VERDICT_UNSPECIFIED = 0;
41 // The reviewer approves the merge request. The comment is created resolved.
42 VERDICT_APPROVE = 1;
43 // The reviewer asks for changes. The comment starts unresolved.
44 VERDICT_CHANGES_REQUESTED = 2;
45}
46
47// MergeabilityState tells whether the head of an open merge request can be
48// merged into its target.
49enum MergeabilityState {
50 // Not set.
51 MERGEABILITY_STATE_UNSPECIFIED = 0;
52 // The server has no result yet for the current tips of both branches. It
53 // is replaced by another state when the check completes.
54 MERGEABILITY_STATE_CHECKING = 1;
55 // The target is an ancestor of the head: every mode can merge.
56 MERGEABILITY_STATE_UP_TO_DATE = 2;
57 // The target has commits the head lacks, but the head merges cleanly:
58 // squash and merge commit can merge, fast-forward cannot.
59 MERGEABILITY_STATE_BEHIND = 3;
60 // The head does not merge cleanly into the target, or the branches share no
61 // history: no mode can merge.
62 MERGEABILITY_STATE_CONFLICT = 4;
63}
64
65// Mergeability is the result of checking an open merge request against the
66// tips of its branches.
67message Mergeability {
68 // State is the result.
69 MergeabilityState state = 1;
70 // TargetId is the commit the target branch pointed to when checked. Empty
71 // while CHECKING.
72 string target_id = 2;
73 // HeadId is the commit the source branch pointed to when checked. Empty
74 // while CHECKING.
75 string head_id = 3;
76 // Behind is the number of commits of the target that the head lacks. Set
77 // only when state is BEHIND.
78 int32 behind = 4;
79 // BehindCapped says that Behind is a lower bound: the server stops counting
80 // at 1,000.
81 bool behind_capped = 5;
82 // ConflictPaths are the paths that conflict, at most 20. Set only when
83 // state is CONFLICT; empty when the branches share no history.
84 repeated string conflict_paths = 6;
85 // ConflictPathsTruncated says that more paths conflict than listed.
86 bool conflict_paths_truncated = 7;
87 // CheckedAt is when the server computed the result. Unset while CHECKING.
88 google.protobuf.Timestamp checked_at = 8;
89}
90
91// AutoMerge is the pending auto-merge of an open merge request: the server
92// merges it by itself once its checks pass. Set only by servers with the
93// "merge_requests.auto_merge" feature.
94message AutoMerge {
95 // Mode is the merge mode used. Never MERGE_MODE_UNSPECIFIED.
96 MergeMode mode = 1;
97 // HeadId is the head the auto-merge was enabled for. A new head cancels the
98 // auto-merge.
99 string head_id = 2;
100 // EnabledBy names who enabled the auto-merge, like MergeRequest.author.
101 string enabled_by = 3;
102 // EnabledAt is when the auto-merge was enabled.
103 google.protobuf.Timestamp enabled_at = 4;
104}
105
106// MergeRequest asks to merge one branch of a repository into another branch
107// of the same repository. It is about a branch, not about who wrote it.
108message MergeRequest {
109 // Repo is the name of the repository.
110 string repo = 1;
111 // Number identifies the merge request within its repository, starting at 1
112 // and never reused. It is written "!<number>" in messages and URLs.
113 int64 number = 2;
114 // Title is a one-line plain-text title, at most 120 characters.
115 string title = 3;
116 // Description is a plain-text description, at most 8,000 characters. It may
117 // be empty. Clients show it escaped, with line breaks kept.
118 string description = 4;
119 // SourceBranch is the short name of the branch to merge, for example
120 // "feat/x".
121 string source_branch = 5;
122 // TargetBranch is the short name of the branch to merge into, for example
123 // "main".
124 string target_branch = 6;
125 // State is where the merge request is in its life.
126 MergeRequestState state = 7;
127 // Author names who created the merge request: the label of the token that
128 // was used, "root" for the root token, or "owner" for a web session. It is
129 // informational: labels are not unique and the token may be gone.
130 string author = 8;
131 // CreatedAt is when the merge request was created.
132 google.protobuf.Timestamp created_at = 9;
133 // UpdatedAt is when the merge request last changed: title, description,
134 // state, or a comment added or resolved. Pushes to the source branch do not
135 // change it.
136 google.protobuf.Timestamp updated_at = 10;
137 // HeadId is the id of the commit the source branch points to. While the
138 // merge request is open it is read from Git at every call, so it changes
139 // when the branch is pushed; it is empty if the branch was deleted. Once
140 // merged or closed it is the head at that moment.
141 string head_id = 11;
142 // MergedCommitId is the id of the commit the target branch points to after
143 // the merge: the head for a fast-forward, the new commit for a squash or a
144 // merge commit.
145 // Empty unless state is MERGED.
146 string merged_commit_id = 12;
147 // MergeMode is how the merge request was merged. MERGE_MODE_UNSPECIFIED
148 // unless state is MERGED.
149 MergeMode merge_mode = 13;
150 // Mergeability tells whether the head can be merged into the target. Set
151 // while the merge request is OPEN, with state CHECKING until the server has
152 // a result for the current tips; never set once merged or closed. It is a
153 // hint: MergeMergeRequest checks again. Set only by servers with the
154 // "merge_requests.mergeability" feature.
155 Mergeability mergeability = 14;
156 // AutoMerge is the pending auto-merge. Set only while the merge request is
157 // OPEN and auto-merge is enabled; unset once merged or closed. Set only by
158 // servers with the "merge_requests.auto_merge" feature.
159 AutoMerge auto_merge = 15;
160 // AutoMerged is true when the server merged the merge request by auto-merge.
161 // Always false unless state is MERGED.
162 bool auto_merged = 16;
163}
164
165// Comment is a note on a merge request, either general or attached to a line
166// of its diff.
167message Comment {
168 // Id identifies the comment within its merge request. Opaque.
169 string id = 1;
170 // Author names who wrote the comment, like MergeRequest.author.
171 string author = 2;
172 // Path is the path of the commented file in the diff (the new path, or the
173 // old path of a deleted file). Empty for a general comment.
174 string path = 3;
175 // Line is the 1-based line number on side. 0 for a general comment.
176 int32 line = 4;
177 // Side tells whether line counts on the old or the new side of the diff.
178 // DIFF_SIDE_UNSPECIFIED for a general comment.
179 DiffSide side = 5;
180 // CommitId is the head of the merge request when the comment was written.
181 // When it differs from the current head the line may have moved; clients
182 // may show the comment as outdated.
183 string commit_id = 6;
184 // Text is the Markdown source, at most 8,000 characters. Clients render it
185 // as Markdown without raw HTML; "^<id>" refers to a note of the same merge
186 // request. Empty when deleted is true, and possibly empty for a comment
187 // that carries a verdict.
188 string text = 7;
189 // Resolved is true once the comment was marked resolved.
190 bool resolved = 8;
191 // CreatedAt is when the comment was written.
192 google.protobuf.Timestamp created_at = 9;
193 // ReplyTo is the id of the root comment this comment replies to. Empty for
194 // a root comment. A reply has the path, line, start_line and side of its
195 // root, and its commit_id is the head when the reply was written. Threads
196 // have one level: a reply never has replies.
197 string reply_to = 10;
198 // StartLine is the 1-based first line of a range that ends at line, on the
199 // same side. 0 for a comment on a single line or a general comment.
200 int32 start_line = 11;
201 // Verdict is the judgement given with the comment. Only a root comment has
202 // one; it never changes after creation.
203 Verdict verdict = 12;
204 // EditedAt is when the text was last changed or the comment was deleted.
205 // Unset if it never was.
206 google.protobuf.Timestamp edited_at = 13;
207 // Deleted is true once the author deleted the comment. Its text is then
208 // empty; its id, anchor, replies and verdict remain.
209 bool deleted = 14;
210}
211
212// AuthorVerdict is the current verdict of one author on a merge request: the
213// one given with the author's latest comment that carries a verdict.
214message AuthorVerdict {
215 // Author names who gave the verdict, like Comment.author.
216 string author = 1;
217 // Verdict is the current verdict. Never VERDICT_UNSPECIFIED.
218 Verdict verdict = 2;
219 // CommentId is the id of the comment that carries the verdict.
220 string comment_id = 3;
221 // CommitId is the head of the merge request when the verdict was given.
222 string commit_id = 4;
223 // CreatedAt is when the verdict was given.
224 google.protobuf.Timestamp created_at = 5;
225 // Stale is true for an approval given on a commit that is not the current
226 // head. A request for changes is never stale.
227 bool stale = 6;
228}
229
230// MergeRequestService reviews and merges branches.
231//
232// Every RPC takes the repository name and, except for creation and listing,
233// the merge request number. A repository that does not exist or that the
234// caller cannot read gives not_found; so does an unknown number. Reading
235// (ListMergeRequests, GetMergeRequest) needs the same access as reading the
236// repository: nothing for a public one, the repo:read scope for a private
237// one. Writing needs a scope on the repository, given per RPC; a caller
238// without it gets permission_denied.
239//
240// Text fields follow the same rules everywhere: valid UTF-8, no control
241// characters (except the line break in description and comment text) and no
242// Unicode bidirectional override or isolate characters; title is one line of
243// at most 120 characters, description and comment text at most 8,000
244// characters. A request that breaks a rule is rejected whole with
245// invalid_argument, and the error carries a BadRequest detail naming the
246// fields.
247//
248// Servers that implement this service list "merge_requests" in
249// GetVersionResponse.features.
250service MergeRequestService {
251 // CreateMergeRequest opens a merge request. Needs the mr:write scope. Fails
252 // with invalid_argument if a text rule is broken, if a branch does not exist
253 // or if source and target are the same branch, and with already_exists if an
254 // open merge request already has the same source and target.
255 rpc CreateMergeRequest(CreateMergeRequestRequest) returns (CreateMergeRequestResponse);
256 // ListMergeRequests lists the merge requests of a repository, highest
257 // number (newest) first, optionally restricted to one state. The listed
258 // merge requests carry no diff or comments; head_id is set. Fails with
259 // not_found if the repository does not exist or is not readable.
260 rpc ListMergeRequests(ListMergeRequestsRequest) returns (ListMergeRequestsResponse);
261 // GetMergeRequest returns one merge request with its commits, its diff and
262 // its comments. The diff compares the target with the head (what the merge
263 // would bring: "target...head"), or, with since_last_read, the head the
264 // caller last marked read with the current head. Fails with not_found if
265 // the repository or the number is unknown.
266 rpc GetMergeRequest(GetMergeRequestRequest) returns (GetMergeRequestResponse);
267 // AddComment adds a general comment, a comment on a line or a range of
268 // lines of the diff, or a reply to a root comment. Needs the mr:write
269 // scope; setting a verdict also needs the mr:review scope (permission_denied
270 // without it). Fails with invalid_argument if the text breaks a rule (it may
271 // be empty only with a verdict), if path, line, start_line and side do not
272 // designate lines of the current diff of the merge request, if reply_to is
273 // not the id of a root comment that is not deleted, if a reply sets path,
274 // line, start_line, side or verdict, or if a verdict is set on a reply; and
275 // with failed_precondition if the merge request is not open. A comment with
276 // VERDICT_APPROVE is created resolved.
277 rpc AddComment(AddCommentRequest) returns (AddCommentResponse);
278 // EditComment replaces the text of a comment. Needs the mr:write scope, and
279 // only the author of the comment can edit it (permission_denied
280 // otherwise). Fails with invalid_argument if the text breaks a rule (it may
281 // be empty only for a comment with a verdict), with not_found if the comment
282 // is unknown, and with failed_precondition if the merge request is not open
283 // or the comment was deleted. Sending the current text succeeds and changes
284 // nothing.
285 rpc EditComment(EditCommentRequest) returns (EditCommentResponse);
286 // DeleteComment deletes a comment: its text is emptied and deleted is set,
287 // while its id, anchor, replies and verdict remain. Needs the mr:write
288 // scope, and only the author of the comment can delete it
289 // (permission_denied otherwise). Fails with not_found if the comment is
290 // unknown and with failed_precondition if the merge request is not open.
291 // Deleting a comment already deleted succeeds and changes nothing.
292 rpc DeleteComment(DeleteCommentRequest) returns (DeleteCommentResponse);
293 // ResolveComment marks a thread resolved or unresolved. Needs the mr:write
294 // scope. Resolution belongs to the root comment: on a reply it fails with
295 // invalid_argument. Fails with not_found if the comment is unknown and with
296 // failed_precondition if the merge request is not open. Setting the state
297 // the comment already has succeeds and changes nothing.
298 rpc ResolveComment(ResolveCommentRequest) returns (ResolveCommentResponse);
299 // CloseMergeRequest closes an open merge request without merging it. Needs
300 // the mr:write scope. Fails with failed_precondition if the merge request
301 // is not open. A closed merge request cannot be reopened: open a new one.
302 rpc CloseMergeRequest(CloseMergeRequestRequest) returns (CloseMergeRequestResponse);
303 // MergeMergeRequest merges an open merge request. Needs the mr:merge scope.
304 // The caller passes the head it reviewed: the server merges only if the
305 // source branch still points to it, so a push between review and merge is
306 // never merged unseen. Fails with invalid_argument if head_id is empty or
307 // not a commit id, and with failed_precondition if the merge request is not
308 // open, if the source branch no longer points to head_id ("branch moved,
309 // read again"), if the mode is fast-forward and the target is not an
310 // ancestor of the head (rebase and push again, or merge with squash or
311 // merge commit), if the mode is squash or merge commit and the head
312 // conflicts with the target or shares no history with it (rebase and push
313 // again), if the mode is not allowed by RepoSettings, or if a check fails
314 // and RepoSettings.failing_checks_block is set. Merges of one
315 // repository run one at a time. Repeating a call that succeeded fails with
316 // failed_precondition (not open). On success the server publishes
317 // MergeRequestMerged then Pushed for the target branch.
318 rpc MergeMergeRequest(MergeMergeRequestRequest) returns (MergeMergeRequestResponse);
319 // EnableAutoMerge asks the server to merge an open merge request by itself
320 // once at least one check passed on its head, every run created on that head
321 // is complete, and the merge would be accepted whatever
322 // RepoSettings.failing_checks_block says. Needs the mr:merge scope and, for a
323 // token limited to branches, write access to the target branch
324 // (permission_denied otherwise). The server records the caller, the mode and
325 // the head the caller saw; it merges as the caller, after resolving the caller
326 // again, and cancels the auto-merge if the caller can no longer merge, if the
327 // mode is no longer allowed, if the source branch moves or if the setting is
328 // turned off. Fails with invalid_argument if the mode is not a merge mode or
329 // if head_id is empty or not a commit id, and with failed_precondition if the
330 // merge request is not open, if the source branch no longer points to head_id
331 // ("branch moved, read again"), is a draft,
332 // RepoSettings.allow_auto_merge is off, the mode is not allowed by
333 // RepoSettings, or the server has no CI. Enabling again replaces the mode.
334 // Publishes MergeRequestAutoMergeEnabled. Needs the
335 // "merge_requests.auto_merge" feature.
336 rpc EnableAutoMerge(EnableAutoMergeRequest) returns (EnableAutoMergeResponse);
337 // CancelAutoMerge cancels the pending auto-merge of an open merge request.
338 // Needs the mr:merge scope and, for a token limited to branches, write access
339 // to the target branch. Fails with failed_precondition if auto-merge is not
340 // enabled. Publishes MergeRequestAutoMergeCancelled.
341 rpc CancelAutoMerge(CancelAutoMergeRequest) returns (CancelAutoMergeResponse);
342 // MarkRead records the head the caller has reviewed, for the since_last_read
343 // option of GetMergeRequest. There is one read position per merge request,
344 // the reviewer's. Needs the mr:write scope. Marking a commit that does not
345 // exist in the repository is invalid_argument.
346 rpc MarkRead(MarkReadRequest) returns (MarkReadResponse);
347}
348
349// CreateMergeRequestRequest describes the merge request to open.
350message CreateMergeRequestRequest {
351 // Repo is the repository name.
352 string repo = 1;
353 // Title is the one-line title. Required.
354 string title = 2;
355 // Description is the optional description.
356 string description = 3;
357 // SourceBranch is the short name of the branch to merge. Required; the
358 // branch must exist.
359 string source_branch = 4;
360 // TargetBranch is the short name of the branch to merge into. Empty means
361 // the default branch of the repository. The branch must exist and differ
362 // from source_branch.
363 string target_branch = 5;
364}
365
366// CreateMergeRequestResponse holds the new merge request.
367message CreateMergeRequestResponse {
368 // MergeRequest is the created merge request.
369 MergeRequest merge_request = 1;
370}
371
372// ListMergeRequestsRequest selects a page of merge requests.
373message ListMergeRequestsRequest {
374 // Repo is the repository name.
375 string repo = 1;
376 // State restricts the result to one state. MERGE_REQUEST_STATE_UNSPECIFIED
377 // means every state.
378 MergeRequestState state = 2;
379 // PageSize is the maximum number of merge requests to return. 0 means the
380 // server default; values above the server maximum are lowered to it.
381 int32 page_size = 3;
382 // PageToken is the next_page_token of a previous response, to continue the
383 // same listing. Empty for the first page. Other fields must be unchanged.
384 string page_token = 4;
385}
386
387// ListMergeRequestsResponse is one page of merge requests.
388message ListMergeRequestsResponse {
389 // MergeRequests are the merge requests of this page, highest number first.
390 repeated MergeRequest merge_requests = 1;
391 // NextPageToken is passed as page_token to get the next page. Empty when
392 // there is no next page.
393 string next_page_token = 2;
394}
395
396// GetMergeRequestRequest selects a merge request.
397message GetMergeRequestRequest {
398 // Repo is the repository name.
399 string repo = 1;
400 // Number is the merge request number.
401 int64 number = 2;
402 // SinceLastRead asks for the diff between the head recorded by MarkRead and
403 // the current head instead of the diff against the target. It works after a
404 // force-push as long as the recorded commit still exists in the repository.
405 // When nothing was marked read, or the recorded commit is gone, the response
406 // holds the diff against the target and says so in last_read_id and
407 // last_read_lost.
408 bool since_last_read = 3;
409}
410
411// GetMergeRequestResponse holds a merge request with its review data.
412message GetMergeRequestResponse {
413 // MergeRequest is the merge request.
414 MergeRequest merge_request = 1;
415 // Commits are the commits of the head that are not in the target
416 // ("target..head"), newest first. At most 100 are returned (a server limit
417 // that may change; rely on commits_truncated, not on the number). Empty when
418 // the source branch was deleted.
419 repeated Commit commits = 2;
420 // CommitsTruncated is true when the branch has more commits than commits
421 // holds.
422 bool commits_truncated = 3;
423 // DiffBaseId is the id of the commit the diff compares from: the merge base
424 // of the target and the head, or the last read head when since_last_read
425 // applied. Empty when the source branch was deleted; diff is then empty.
426 string diff_base_id = 4;
427 // Stats are the totals of the diff, including files that it omits or
428 // truncates.
429 DiffStats stats = 5;
430 // Diff is the structured diff from diff_base_id to the head, with the same
431 // limits and truncated flags as GetCommitResponse.diff.
432 Diff diff = 6;
433 // Comments are every comment of the merge request, oldest first.
434 repeated Comment comments = 7;
435 // LastReadId is the head recorded by MarkRead, whether or not
436 // since_last_read was set. Empty when nothing was marked read.
437 string last_read_id = 8;
438 // LastReadLost is true when since_last_read was set, a head was recorded,
439 // but that commit no longer exists in the repository: the diff is then the
440 // diff against the target. A client should tell the reader to review the
441 // whole change again.
442 bool last_read_lost = 9;
443 // Verdicts are the current verdicts, one per author who gave one, ordered
444 // by the comment that carries them, oldest first.
445 repeated AuthorVerdict verdicts = 10;
446}
447
448// AddCommentRequest describes the comment to add.
449message AddCommentRequest {
450 // Repo is the repository name.
451 string repo = 1;
452 // Number is the merge request number.
453 int64 number = 2;
454 // Path is the file the comment is attached to, as given by the diff of the
455 // merge request: FileDiff.new_path, or old_path for a deleted file. Empty
456 // for a general comment; then line must be 0 and side unspecified.
457 string path = 3;
458 // Line is the 1-based line number on side. It must be the old_number or
459 // new_number of a Line of a hunk of the file; a line outside the hunks is
460 // invalid_argument. 0 for a general comment.
461 int32 line = 4;
462 // Side is the side line counts on. Required when path is set.
463 DiffSide side = 5;
464 // Text is the Markdown source. Required, except when verdict is set.
465 string text = 6;
466 // ReplyTo is the id of the root comment to reply to. Empty for a new root
467 // comment. A reply takes the anchor of its root: path, line, start_line,
468 // side and verdict must then be unset.
469 string reply_to = 7;
470 // StartLine is the 1-based first line of a range ending at line. 0 for a
471 // single line. Needs path; it must be lower than line, and both ends must
472 // be lines of the diff on side.
473 int32 start_line = 8;
474 // Verdict is the judgement to give. Needs the mr:review scope and a root
475 // comment. VERDICT_UNSPECIFIED for a plain comment.
476 Verdict verdict = 9;
477}
478
479// AddCommentResponse holds the new comment.
480message AddCommentResponse {
481 // Comment is the created comment.
482 Comment comment = 1;
483}
484
485// EditCommentRequest describes the new text of a comment.
486message EditCommentRequest {
487 // Repo is the repository name.
488 string repo = 1;
489 // Number is the merge request number.
490 int64 number = 2;
491 // CommentId is the Comment.id to edit.
492 string comment_id = 3;
493 // Text is the new Markdown source. Required, except for a comment that
494 // carries a verdict.
495 string text = 4;
496}
497
498// EditCommentResponse holds the comment after the edit.
499message EditCommentResponse {
500 // Comment is the updated comment.
501 Comment comment = 1;
502}
503
504// DeleteCommentRequest names the comment to delete.
505message DeleteCommentRequest {
506 // Repo is the repository name.
507 string repo = 1;
508 // Number is the merge request number.
509 int64 number = 2;
510 // CommentId is the Comment.id to delete.
511 string comment_id = 3;
512}
513
514// DeleteCommentResponse holds the comment after the deletion.
515message DeleteCommentResponse {
516 // Comment is the deleted comment.
517 Comment comment = 1;
518}
519
520// ResolveCommentRequest changes the resolved state of a comment.
521message ResolveCommentRequest {
522 // Repo is the repository name.
523 string repo = 1;
524 // Number is the merge request number.
525 int64 number = 2;
526 // CommentId is the Comment.id to change.
527 string comment_id = 3;
528 // Resolved is the new state: true to resolve, false to unresolve.
529 bool resolved = 4;
530}
531
532// ResolveCommentResponse holds the comment after the change.
533message ResolveCommentResponse {
534 // Comment is the updated comment.
535 Comment comment = 1;
536}
537
538// CloseMergeRequestRequest names the merge request to close.
539message CloseMergeRequestRequest {
540 // Repo is the repository name.
541 string repo = 1;
542 // Number is the merge request number.
543 int64 number = 2;
544}
545
546// CloseMergeRequestResponse holds the merge request after closing.
547message CloseMergeRequestResponse {
548 // MergeRequest is the closed merge request.
549 MergeRequest merge_request = 1;
550}
551
552// MergeMergeRequestRequest describes the merge to perform.
553message MergeMergeRequestRequest {
554 // Repo is the repository name.
555 string repo = 1;
556 // Number is the merge request number.
557 int64 number = 2;
558 // Mode is how to merge. MERGE_MODE_UNSPECIFIED means fast-forward. The mode
559 // must be in RepoSettings.allowed_merge_modes of the repository.
560 MergeMode mode = 3;
561 // HeadId is the full id of the commit the caller reviewed, that is the
562 // MergeRequest.head_id it was shown. Required. The merge happens only if the
563 // source branch still points to it.
564 string head_id = 4;
565 // DeleteSourceBranch deletes the source branch after the merge. The merge
566 // is refused before anything changes when the source branch is the default
567 // branch of the repository or the source or target of another open merge
568 // request. Servers without the "merge_requests.delete_branch" feature ignore
569 // it.
570 bool delete_source_branch = 5;
571}
572
573// MergeMergeRequestResponse holds the merged merge request.
574message MergeMergeRequestResponse {
575 // MergeRequest is the merge request after the merge: state MERGED,
576 // merged_commit_id set to the new tip of the target branch and merge_mode
577 // set to the mode used.
578 MergeRequest merge_request = 1;
579 // SourceBranchDeleted is true when delete_source_branch was set: the server
580 // deletes the branch after answering. The deletion is skipped, and the
581 // branch kept, if the branch moved or another open merge request uses it
582 // by then; the merge stands either way. Watch reports the deletion with a
583 // Pushed event for the source branch.
584 bool source_branch_deleted = 2;
585}
586
587// EnableAutoMergeRequest describes the auto-merge to enable.
588message EnableAutoMergeRequest {
589 // Repo is the repository name.
590 string repo = 1;
591 // Number is the merge request number.
592 int64 number = 2;
593 // Mode is how to merge. MERGE_MODE_UNSPECIFIED means fast-forward. The mode
594 // must be in RepoSettings.allowed_merge_modes of the repository.
595 MergeMode mode = 3;
596 // HeadId is the full id of the commit the caller reviewed, that is the
597 // MergeRequest.head_id it was shown. Required. The auto-merge is enabled
598 // only if the source branch still points to it; failed_precondition (branch
599 // moved) otherwise.
600 string head_id = 4;
601}
602
603// EnableAutoMergeResponse holds the merge request with auto-merge enabled.
604message EnableAutoMergeResponse {
605 // MergeRequest is the merge request, with auto_merge set.
606 MergeRequest merge_request = 1;
607}
608
609// CancelAutoMergeRequest names the merge request whose auto-merge to cancel.
610message CancelAutoMergeRequest {
611 // Repo is the repository name.
612 string repo = 1;
613 // Number is the merge request number.
614 int64 number = 2;
615}
616
617// CancelAutoMergeResponse holds the merge request after the cancellation.
618message CancelAutoMergeResponse {
619 // MergeRequest is the merge request, with auto_merge unset.
620 MergeRequest merge_request = 1;
621}
622
623// MarkReadRequest records a read position.
624message MarkReadRequest {
625 // Repo is the repository name.
626 string repo = 1;
627 // Number is the merge request number.
628 int64 number = 2;
629 // HeadId is the full id of the commit the caller has reviewed, usually the
630 // MergeRequest.head_id it was shown. Empty means the current head of the
631 // source branch.
632 string head_id = 3;
633}
634
635// MarkReadResponse is empty.
636message MarkReadResponse {}