diff options
Diffstat (limited to 'proto/operations.proto')
| -rw-r--r-- | proto/operations.proto | 258 |
1 files changed, 148 insertions, 110 deletions
diff --git a/proto/operations.proto b/proto/operations.proto index 82fab9fee..4b6264bb7 100644 --- a/proto/operations.proto +++ b/proto/operations.proto @@ -15,14 +15,28 @@ option go_package = "gitlab.com/gitlab-org/gitaly/v16/proto/go/gitalypb"; // '/allowed' endpoint. service OperationService { - // UserCreateBranch ... + // UserCreateBranch creates a single branch in the context of a specific user. It executes + // hooks and contacts Rails to verify that the user is allowed to create the branch. The + // following known error conditions may happen: + // + // - `FailedPrecondition` if the Git revision provided in start_point can't be found or updated. + // - `InvalidArgument` if the commit ID resolved from the start_point can't be parsed. + // - `PermissionDenied` with an embedded `UserCreateBranchError` if any custom hooks return a + // non-zero exit code. rpc UserCreateBranch(UserCreateBranchRequest) returns (UserCreateBranchResponse) { option (op_type) = { op: MUTATOR }; } - // UserUpdateBranch ... + // UserUpdateBranch updates a branch to point to a new revision. It executes hooks and + // contacts Rails to verify that the user is allowed to update the branch. The following + // known error conditions may happen: + // + // - `InvalidArgument` if any of the request fields can't be validated. + // - `Internal` if the newrev or oldrev are invalid in the context of the repository. + // - `UserUpdateBranchResponse` with the `PreReceiveError` field set, if any custom hooks + // return a non-zero exit code. rpc UserUpdateBranch(UserUpdateBranchRequest) returns (UserUpdateBranchResponse) { option (op_type) = { op: MUTATOR @@ -57,7 +71,14 @@ service OperationService { }; } - // UserDeleteTag ... + // UserDeleteTag deletes an existing tag. It executes hooks and contacts Rails to verify that + // the user is allowed to delete the tag. The following known error conditions may happen: + // + // - `InvalidArgument` if the repository, tag_name, user, or expected_old_oid (if provided) + // are invalid. + // - `FailedPrecondition` if the tag_name can't be found, or the ref couldn't be deleted due + // to a concurrent write to the same ref. + // - `Internal` if the tag_name can't be resolved or an unknown error occurs. rpc UserDeleteTag(UserDeleteTagRequest) returns (UserDeleteTagResponse) { option (op_type) = { op: MUTATOR @@ -88,19 +109,30 @@ service OperationService { // The merge commit is created with the given user as author/committer and // the given message. // - // This RPC requires confirmation to make any user-visible changes to the - // repository. The first request sent shall contain details about the - // requested merge, which will result in a response with the created merge - // commit ID. Only if a second message with `apply = true` is sent will the - // merge be applied. + // This is a two-stage RPC that requires confirmation to make user-visible + // changes to the repository: + // - The first request contains details about the requested merge, which + // will result in a response with the created merge commit ID. + // - The second request should set `apply = true` to apply the merge. + // + // After the second request, it executes hooks and contacts Rails to verify + // that the user is allowed to update the branch. The following known error + // conditions may happen: + // + // - `InvalidArgument` if request fields can't be validated or resolved. + // - `NotFound` if the branch can't be found. + // - `FailedPrecondition` if there are merge conflicts, if the merge is + // aborted by setting `apply = false` in the second request, or if the + // merge fails due to a concurrent write to the same ref. + // - `PermissionDenied` if the user doesn't have permissions to merge a branch. rpc UserMergeBranch(stream UserMergeBranchRequest) returns (stream UserMergeBranchResponse) { option (op_type) = { op: MUTATOR }; } - // UserFFBranch tries to perform a fast-forward merge of the given branch to - // the given commit. If the merge is not a fast-forward merge, the request + // UserFFBranch tries to perform a fast-forward merge of a given commit into + // the given branch. If the merge is not a fast-forward merge, the request // will fail. The RPC will return an empty response in case updating the // reference fails e.g. because of a race. rpc UserFFBranch(UserFFBranchRequest) returns (UserFFBranchResponse) { @@ -175,21 +207,23 @@ service OperationService { } -// UserCreateBranchRequest ... +// UserCreateBranchRequest is a request for the UserCreateBranch RPC. message UserCreateBranchRequest { - // repository ... + // repository is the repository in which the branch should be created. Repository repository = 1 [(target_repository)=true]; - // branch_name ... + // branch_name is the name of the branch to create. bytes branch_name = 2; - // user ... + // user to execute the action as. Also used to perform authentication and + // authorization via an external endpoint. User user = 3; - // start_point ... + // start_point is the Git revision to start the branch at. See the gitrevisions(1) + // man pages for supported syntax. bytes start_point = 4; } -// UserCreateBranchResponse ... +// UserCreateBranchResponse is a response for the UserCreateBranch RPC. message UserCreateBranchResponse { - // branch ... + // branch is the branch that was created. Branch branch = 1; // PreReceiveError had previously been set when creation of the branch was refused by hooks. @@ -208,23 +242,24 @@ message UserCreateBranchError { } } -// UserUpdateBranchRequest ... +// UserUpdateBranchRequest is a request for the UserUpdateBranch RPC. message UserUpdateBranchRequest { - // repository ... + // repository is the repository to update the branch in. Repository repository = 1 [(target_repository)=true]; - // branch_name ... + // branch_name is the name of the branch to update. bytes branch_name = 2; - // user ... + // user to execute the action as. Also used to perform authentication and + // authorization via an external endpoint. User user = 3; - // newrev ... + // newrev is the Git revision which the branch will point to. bytes newrev = 4; - // oldrev ... + // oldrev is the Git revision which the branch currently points to. bytes oldrev = 5; } -// UserUpdateBranchResponse ... +// UserUpdateBranchResponse is a response for the UserUpdateBranch RPC. message UserUpdateBranchResponse { - // pre_receive_error ... + // pre_receive_error indicates an error that occurred while executing custom hooks. string pre_receive_error = 1; } @@ -236,9 +271,8 @@ message UserDeleteBranchRequest { // name only, e.g. in case you want to delete `refs/heads/main` the request needs to only contain // `main` as the branch name. bytes branch_name = 2; - // user is the user on whose behalf we should delete the branch. This information is used to - // perform access checks against the Rails `/internal/allowed` API. This user is also exposed to - // any custom hooks executed as part of this RPC call. + // user to execute the action as. Also used to perform authentication and + // authorization via an external endpoint. User user = 3; // expected_old_oid is the object ID which branch is expected to point to. // This is used as a safety guard to avoid races when branch has been @@ -263,7 +297,7 @@ message UserDeleteBranchResponse { // defined error cases. message UserDeleteBranchError { oneof error { - // access_checkError is set if the RPC failed because `/internal/allowed` failed. + // access_check is set if the RPC failed due to an external access check. AccessCheckError access_check = 1; // reference_updateError is set if the RPC failed because updating the // reference to the new object ID has failed. @@ -274,13 +308,14 @@ message UserDeleteBranchError { } } -// UserDeleteTagRequest ... +// UserDeleteTagRequest is a request for the UserDeleteTag RPC. message UserDeleteTagRequest { - // repository ... + // repository is the repository from which the tag should be deleted. Repository repository = 1 [(target_repository)=true]; - // tag_name ... + // tag_name is the name of the tag to delete. bytes tag_name = 2; - // user ... + // user to execute the action as. Also used to perform authentication and + // authorization via an external endpoint. User user = 3; // expected_old_oid is the object ID which tag is expected to point to. // This is used as a safety guard to avoid races when tag has been @@ -292,9 +327,9 @@ message UserDeleteTagRequest { string expected_old_oid = 4; } -// UserDeleteTagResponse ... +// UserDeleteTagResponse is a response for the UserDeleteTag RPC. message UserDeleteTagResponse { - // pre_receive_error ... + // pre_receive_error indicates an error that occurred while executing custom hooks. string pre_receive_error = 1; } @@ -305,8 +340,8 @@ message UserCreateTagRequest { // tag_name is the name of the tag that shall be created. Note that this should be set to the name // only: if you want to create a tag `refs/heads/v1.0`, you need to pass `v1.0` as TagName. bytes tag_name = 2; - // user is the user as which the tag shall be created. This user is used to perform access checks - // against Rails' `/internal/allowed` endpoint. + // user to execute the action as. Also used to perform authentication and + // authorization via an external endpoint. User user = 3; // target_revision is the revision that the newly created tag should be pointing to. Note that if // the revision points to a tag, that tag will be peeled to the commit it is pointing to. If the @@ -341,7 +376,7 @@ message UserCreateTagResponse { // userCreateTag fails. message UserCreateTagError { oneof error { - // access_checkError is set if the RPC failed because `/internal/allowed` failed. + // access_check is set if the RPC failed due to an external access check. AccessCheckError access_check = 1; // reference_updateError is set if the RPC failed because updating the // reference to the new object ID has failed. @@ -354,14 +389,14 @@ message UserCreateTagError { } } -// UserMergeBranchRequest ... -// The first set of parameters must only be set in the first message to declare -// parameters for the merge. +// UserMergeBranchRequest is a request for the UserMergeBranch RPC. +// All mandatory parameters except for `apply` should be set in the first +// message. message UserMergeBranchRequest { // repository is the repository to compute the merge for. Repository repository = 1 [(target_repository)=true]; - // user is the user to compute the merge as. Its name and mail address are - // used as author and committer of the merge. + // user to execute the action as. Also used to perform authentication and + // authorization via an external endpoint. User user = 2; // commit_id is the object ID (hash) of the object that shall be merged into // the target branch. @@ -384,27 +419,24 @@ message UserMergeBranchRequest { // will return an error. string expected_old_oid = 8; - // apply must only be set in the second message. Only if this second message - // is sent and if apply is set to true will the branch be updated to point to - // the merge commit. + // apply is used in the second message. Setting it to true will proceed with + // the merge. Setting it to false will abort the merge. bool apply = 6; } -// UserMergeBranchResponse ... +// UserMergeBranchResponse is a response for the UserMergeBranch RPC. message UserMergeBranchResponse { - // commit_id is the merge commit the branch will be updated to. - // The caller can still abort the merge. - // First message. + // commit_id is the merge commit the branch will be updated to. This is sent + // as the response to the first request. string commit_id = 1; reserved 2; - // branch_update if set, is the merge has been applied to the branch. - // Second message + // branch_update contains the commit ID of the merge commit if the merge has + // been applied to the branch. This is sent as the response to the second + // request. OperationBranchUpdate branch_update = 3; - // PreReceiveError had previously been set in case access checks refused the merge. This has been - // changed to Instead we return a proper gRPC error with UserMergeBranchError details set to an - // access_checkError. + // Reserved for backwards compatibility. Structured errors are now used instead. reserved "pre_receive_error"; reserved 4; } @@ -413,7 +445,7 @@ message UserMergeBranchResponse { // details in case UserMergeBranch fails. message UserMergeBranchError { oneof error { - // access_checkError is set if the RPC failed because `/internal/allowed` failed. + // access_check is set if the RPC failed due to an external access check. AccessCheckError access_check = 1; // reference_updateError is set if the RPC failed because updating the // reference to the new object ID has failed. @@ -426,18 +458,19 @@ message UserMergeBranchError { } } -// UserMergeToRefRequest ... +// UserMergeToRefRequest is a request for the UserMergeToRef RPC. message UserMergeToRefRequest { // repository is the repository in which the merge shall be computed. Repository repository = 1 [(target_repository)=true]; - // user is the user as which the merge commit shall be created. + // user to execute the action as. Also used to perform authentication and + // authorization via an external endpoint. User user = 2; // source_sha is the object ID of the second parent of the computed merge. string source_sha = 3; // branch contains the name of the branch which should be used as the first // parent of the computed merge. It is deprecated in favor of // `first_parent_ref` and will be ignored in case it is set. - bytes branch = 4; + bytes branch = 4 [deprecated = true]; // target_ref contains the fully qualified reference which should be updated // with the computed merge commit. bytes target_ref = 5; @@ -470,13 +503,14 @@ message UserMergeToRefRequest { string expected_old_oid = 10; } -// UserMergeToRefResponse ... +// UserMergeToRefResponse is a response for the UserMergeToRef RPC. message UserMergeToRefResponse { // commit_id is the object ID of the computed merge commit. string commit_id = 1; - // PreReceiveError had never been set because this RPC does not perform authentication via - // `/internal/allowed`. This field was thus removed without replacement. + // pre_receive_error had never been set because this RPC does not perform + // authentication and authorization via an external endpoint. This field was + // thus removed without replacement. reserved "pre_receive_error"; reserved 2; } @@ -485,7 +519,8 @@ message UserMergeToRefResponse { message UserRebaseToRefRequest { // repository is the repository in which the rebase shall be computed. Repository repository = 1 [(target_repository)=true]; - // user is the user as which the rebased commits shall be created. + // user to execute the action as. Also used to perform authentication and + // authorization via an external endpoint. User user = 2; // source_sha is the object ID of the commit to be rebased. string source_sha = 3; @@ -528,16 +563,16 @@ message OperationBranchUpdate { bool branch_created = 3; } -// UserFFBranchRequest contains parameters for the UserFFBranch RPC. +// UserFFBranchRequest is a request for the UserFFBranch RPC. message UserFFBranchRequest { // repository is the repository for which to perform the fast-forward merge. Repository repository = 1 [(target_repository)=true]; - // user is the user which to perform the fast-forward merge as. This is used - // for authorization checks. + // user to execute the action as. Also used to perform authentication and + // authorization via an external endpoint. User user = 2; - // commit_id is the commit ID to update the branch to. + // commit_id is the commit ID to fast-forward the branch to. string commit_id = 3; - // branch is the name of the branch that shall be update. This must be the + // branch is the name of the branch to fast-forward. This must be the // branch name only and not a fully qualified reference, e.g. "master" // instead of "refs/heads/master". bytes branch = 4; @@ -552,21 +587,22 @@ message UserFFBranchRequest { string expected_old_oid = 5; } -// UserFFBranchResponse ... +// UserFFBranchResponse is a response for the UserFFBranch RPC. message UserFFBranchResponse { - // branch_update ... + // branch_update contains details of the fast-forwarded branch. OperationBranchUpdate branch_update = 1; - // pre_receive_error ... + // pre_receive_error is set in the case of an `Internal` error and contains + // details of the failed custom hook. string pre_receive_error = 2; } -// UserCherryPickRequest ... +// UserCherryPickRequest is a request for the UserCherryPick RPC. message UserCherryPickRequest { // repository is the repository into which the cherry-pick shall be // performed. Repository repository = 1 [(target_repository)=true]; - // user is the user to perform the cherry-pick as. This is used for - // authorization checks and as the committer of the computed cherry-pick. + // user to execute the action as. Also used to perform authentication and + // authorization via an external endpoint. User user = 2; // commit is the commit to cherry-pick onto the given branch. GitCommit commit = 3; @@ -599,7 +635,7 @@ message UserCherryPickRequest { string expected_old_oid = 10; } -// UserCherryPickResponse ... +// UserCherryPickResponse is a response for the UserCherryPick RPC. message UserCherryPickResponse { // branch_update represents details about the updated branch. OperationBranchUpdate branch_update = 1; @@ -637,20 +673,19 @@ message UserCherryPickError { NotAncestorError target_branch_diverged = 2; // changes_already_applied is returned if the result after applying the cherry pick is empty. ChangesAlreadyAppliedError changes_already_applied = 3; - // access_check is returned in case GitLab's `/internal/allowed` endpoint rejected - // the change. + // access_check is set if the RPC failed due to an external access check. AccessCheckError access_check = 4; } } -// UserRevertRequest ... +// UserRevertRequest is a request for the UserRevert RPC. message UserRevertRequest { // repository is the repository in which the revert shall be applied. Repository repository = 1 [(target_repository)=true]; - // user is the user to perform the revert as. This is used both for - // authorization and as author/committer for the revert commit. + // user to execute the action as. Also used to perform authentication and + // authorization via an external endpoint. User user = 2; - // commit iis the commit to revert. + // commit is the commit to revert. Only the `id` field is required. GitCommit commit = 3; // branch_name is the name of the branch onto which the reverted commit shall // be committed. @@ -681,7 +716,7 @@ message UserRevertRequest { string expected_old_oid = 10; } -// UserRevertResponse ... +// UserRevertResponse is a response for the UserRevert RPC. message UserRevertResponse { // CreateTreeError represents an error which happened when computing the // revert. @@ -712,7 +747,7 @@ message UserRevertResponse { // UserCommitFilesActionHeader contains the details of the action to be performed. message UserCommitFilesActionHeader { - // ActionType ... + // ActionType is the type of action to perform. enum ActionType { // CREATE creates a new file. CREATE = 0; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH @@ -772,7 +807,8 @@ message UserCommitFilesAction { message UserCommitFilesRequestHeader { // repository is the target repository where to apply the commit. Repository repository = 1 [(target_repository)=true]; - // user is the user peforming the call. + // user to execute the action as. Also used to perform authentication and + // authorization via an external endpoint. User user = 2; // branch_name is the name of the branch to point to the new commit. If start_sha and start_branch_name // are not defined, the commit of branch_name is used as the parent commit. @@ -838,7 +874,7 @@ message UserCommitFilesResponse { // defined error cases. message UserCommitFilesError { oneof error { - // access_checkError is set if the RPC failed because `/internal/allowed` failed. + // access_check is set if the RPC failed due to an external access check. AccessCheckError access_check = 1; // index_update is set to the error message when an operation conflicts with the repository // index, such as creating a file that already exists. @@ -849,7 +885,7 @@ message UserCommitFilesError { } } -// UserRebaseConfirmableRequest ... +// UserRebaseConfirmableRequest is a request for the UserRebaseConfirmable RPC. message UserRebaseConfirmableRequest { // Header contains information to compute the rebase and must be sent as // first message. @@ -857,8 +893,8 @@ message UserRebaseConfirmableRequest { // repository is the repository in which the rebase will be computed and // applied. Repository repository = 1 [(target_repository)=true]; - // user is the user to compute the rebase as. It will be used as - // "committer" of rebased commits. + // user to execute the action as. Also used to perform authentication and + // authorization via an external endpoint. User user = 2; // rebase_id does nothing anymore. string rebase_id = 3 [deprecated=true]; @@ -892,7 +928,7 @@ message UserRebaseConfirmableRequest { } } -// UserRebaseConfirmableResponse ... +// UserRebaseConfirmableResponse is a response for the UserRebaseConfirmable RPC. message UserRebaseConfirmableResponse { oneof user_rebase_confirmable_response_payload { // rebase_sha is the commit the branch will be updated to, it will be present @@ -902,19 +938,21 @@ message UserRebaseConfirmableResponse { // It is present in the second response. bool rebase_applied = 2; } - // pre_receive_error contains an error message if the rebase failed because - // of an error raised by hooks. - string pre_receive_error = 3; - // git_error contains an error message if git operations have failed. - string git_error = 4; + // Deprecated in favour of `UserRebaseConfirmableError`. + reserved 3; + reserved "pre_receive_error"; + // Deprecated in favour of `UserRebaseConfirmableError`. + reserved 4; + reserved "git_error"; } -// UserSquashRequest ... +// UserSquashRequest is a request for the UserSquash RPC. message UserSquashRequest { // repository is the repository into which the squashed commit shall be // written. Repository repository = 1 [(target_repository)=true]; - // user is used for authorization checks. + // user to execute the action as. Also used to perform authentication and + // authorization via an external endpoint. User user = 2; // start_sha is the object ID of the start commit of the range which shall be // squashed. Must be an ancestor of end_sha. @@ -934,31 +972,30 @@ message UserSquashRequest { reserved "squash_id"; } -// UserSquashResponse ... +// UserSquashResponse is a response for the UserSquash RPC. message UserSquashResponse { // squash_sha is the object ID of the squashed commit. string squash_sha = 1; - // DEPRECATED: https://gitlab.com/gitlab-org/gitaly/proto/merge_requests/161 + // Deprecated as custom hooks aren't executed. reserved 2; reserved "pre_receive_error"; - // GitError is not used anymore. Instead, this RPC always returns a real - // error with an optional UserRebaseConfirmableError, which may be set on + // git_error is not used anymore. Instead, this RPC always returns a real + // error with an optional `UserSquashError`, which may be set on // special errors. reserved 3; reserved "git_error"; } -// UserRebaseConfirmableError ... +// UserRebaseConfirmableError is a structured error for the UserRebaseConfirmable RPC. message UserRebaseConfirmableError { oneof error { // rebase_conflict is returned in case rebasing commits on top of the start // commit fails with a merge conflict and in case merge squashing commits // fails with a merge conflict. MergeConflictError rebase_conflict = 1; - // access_checkError is returned in case GitLab's `/internal/allowed` endpoint rejected - // the change. + // access_check is set if the RPC failed due to an external access check. AccessCheckError access_check = 2; } } @@ -976,13 +1013,14 @@ message UserSquashError { } } -// UserApplyPatchRequest ... +// UserApplyPatchRequest is a request for the UserApplyPatch RPC. message UserApplyPatchRequest { // Header contains information about how to apply the patches. message Header { // repository is the repository to which the patches shall be applied to. Repository repository = 1 [(target_repository)=true]; - // user is used for authentication. + // user to execute the action as. Also used to perform authentication and + // authorization via an external endpoint. User user = 2; // target_branch is the branch onto which the patches shall be applied. bytes target_branch = 3; @@ -1009,18 +1047,18 @@ message UserApplyPatchRequest { } } -// UserApplyPatchResponse ... +// UserApplyPatchResponse is a response for the UserApplyPatch RPC. message UserApplyPatchResponse { // branch_update contains information about the updated branch. OperationBranchUpdate branch_update = 1; } -// UserUpdateSubmoduleRequest ... +// UserUpdateSubmoduleRequest is a request for the UserUpdateSubmodule RPC. message UserUpdateSubmoduleRequest { // repository is the repository in which the submodule shall be updated. Repository repository = 1 [(target_repository)=true]; - // user is used both for authorization and as author/committer of the - // resulting commit. + // user to execute the action as. Also used to perform authentication and + // authorization via an external endpoint. User user = 2; // commit_sha is the object ID the submodule shall be updated to. string commit_sha = 3; @@ -1046,7 +1084,7 @@ message UserUpdateSubmoduleRequest { string expected_old_oid = 8; } -// UserUpdateSubmoduleResponse ... +// UserUpdateSubmoduleResponse is a response for the UserUpdateSubmodule RPC. message UserUpdateSubmoduleResponse { // branch_update contains information about the updated branch. OperationBranchUpdate branch_update = 1; |