repo.proto RawHistoryFolder

1// SPDX-License-Identifier: MIT
2
3syntax = "proto3";
4
5package ermite;
6
7import "google/protobuf/field_mask.proto";
8import "ermite/types.proto";
9import "google/protobuf/timestamp.proto";
10
11// Visibility says who may read a repository.
12enum Visibility {
13  // Not set. In requests, the server applies its default (private on create,
14  // unchanged on update). Never returned by the server.
15  VISIBILITY_UNSPECIFIED = 0;
16  // Anyone, including anonymous callers, may read the repository.
17  VISIBILITY_PUBLIC = 1;
18  // Only callers holding the repo:read scope on the repository may read it.
19  // Everyone else gets not_found, never permission_denied.
20  VISIBILITY_PRIVATE = 2;
21}
22
23// RepoSettings are the settings of a repository that govern its merge
24// requests.
25message RepoSettings {
26  // AllowedMergeModes are the modes with which a merge request of the
27  // repository may be merged. It is never empty in a response and has no
28  // duplicate. Both MERGE_MODE_FAST_FORWARD and MERGE_MODE_SQUASH are allowed
29  // by default. MERGE_MODE_UNSPECIFIED is rejected.
30  repeated MergeMode allowed_merge_modes = 1;
31  // FailingChecksBlock says whether a merge request whose checks fail cannot be
32  // merged. It is true at creation of the repository and always stored
33  // explicitly, so a later change of the server default never alters an
34  // existing repository.
35  bool failing_checks_block = 2;
36}
37
38// Repo is the metadata of a repository. Git-owned state (refs, trees, history)
39// is read through GitService.
40message Repo {
41  // Name is the unique, lowercase repository name: 1-100 characters from
42  // [a-z0-9._-], without a ".git" suffix. It is also the URL path: /<name>.
43  string name = 1;
44  // Description is a free one-line description. It may be empty.
45  string description = 2;
46  // Visibility is who may read the repository.
47  Visibility visibility = 3;
48  // DefaultBranch is the short name of the branch HEAD points to, for example
49  // "main". It is set even when the branch does not exist yet (empty
50  // repository).
51  string default_branch = 4;
52  // CreatedAt is when the repository was created.
53  google.protobuf.Timestamp created_at = 5;
54  // PushedAt is the time of the last push. It is unset until the first push.
55  google.protobuf.Timestamp pushed_at = 6;
56  // Settings are the merge settings of the repository. Always set in a
57  // response, with the defaults for a repository that never changed them.
58  RepoSettings settings = 7;
59}
60
61// RepoService manages repositories and their metadata.
62//
63// Anonymous callers see public repositories only. A private repository that the
64// caller cannot read is reported as not_found.
65service RepoService {
66  // ListRepos lists the repositories the caller may see, ordered by name.
67  rpc ListRepos(ListReposRequest) returns (ListReposResponse);
68  // GetRepo returns one repository. Fails with not_found if it does not exist
69  // or is private and not readable by the caller.
70  rpc GetRepo(GetRepoRequest) returns (GetRepoResponse);
71  // CreateRepo creates an empty repository with the default settings. Needs
72  // the repo:write scope. Fails
73  // with already_exists if the name is taken and invalid_argument if the name
74  // is not valid.
75  rpc CreateRepo(CreateRepoRequest) returns (CreateRepoResponse);
76  // UpdateRepo changes the fields named in update_mask, including the merge
77  // settings. Needs the repo:admin scope.
78  rpc UpdateRepo(UpdateRepoRequest) returns (UpdateRepoResponse);
79  // DeleteRepo deletes a repository. Needs the repo:admin scope. The server
80  // moves the data aside rather than destroying it; there is no undelete RPC.
81  rpc DeleteRepo(DeleteRepoRequest) returns (DeleteRepoResponse);
82}
83
84// ListReposRequest selects a page of repositories.
85message ListReposRequest {
86  // PageSize is the maximum number of repositories to return. 0 means the
87  // server default; values above the server maximum are lowered to it.
88  int32 page_size = 1;
89  // PageToken is the next_page_token of a previous response, to get the page
90  // after it. Empty for the first page.
91  string page_token = 2;
92}
93
94// ListReposResponse is one page of repositories.
95message ListReposResponse {
96  // Repos are the repositories of this page, ordered by name.
97  repeated Repo repos = 1;
98  // NextPageToken is passed as page_token to get the next page. Empty when
99  // there is no next page.
100  string next_page_token = 2;
101}
102
103// GetRepoRequest names the repository to read.
104message GetRepoRequest {
105  // Repo is the repository name.
106  string repo = 1;
107}
108
109// GetRepoResponse holds the repository.
110message GetRepoResponse {
111  // Repo is the repository metadata.
112  Repo repo = 1;
113}
114
115// CreateRepoRequest describes the repository to create.
116message CreateRepoRequest {
117  // Name is the name of the new repository. Names are lowercase; an uppercase
118  // name is rejected with invalid_argument.
119  string name = 1;
120  // Description is an optional one-line description.
121  string description = 2;
122  // Visibility of the new repository. VISIBILITY_UNSPECIFIED means private.
123  Visibility visibility = 3;
124}
125
126// CreateRepoResponse holds the new repository.
127message CreateRepoResponse {
128  // Repo is the created repository.
129  Repo repo = 1;
130}
131
132// UpdateRepoRequest changes some fields of a repository.
133message UpdateRepoRequest {
134  // Repo is the name of the repository to change. Repositories cannot be
135  // renamed.
136  string repo = 1;
137  // Description is the new description. Used only if update_mask contains
138  // "description"; an empty value then clears it.
139  string description = 2;
140  // Visibility is the new visibility. Used only if update_mask contains
141  // "visibility"; it must not be VISIBILITY_UNSPECIFIED then.
142  Visibility visibility = 3;
143  // DefaultBranch is the short name of the new default branch. Used only if
144  // update_mask contains "default_branch". The branch must exist, otherwise
145  // the call fails with failed_precondition.
146  string default_branch = 4;
147  // UpdateMask lists the fields to change: "description", "visibility",
148  // "default_branch", "settings.allowed_merge_modes" and/or
149  // "settings.failing_checks_block". "settings" stands for both settings
150  // paths. It must not be empty. Other paths are invalid_argument.
151  google.protobuf.FieldMask update_mask = 5;
152  // Settings holds the new merge settings. Only the fields named in
153  // update_mask are used. allowed_merge_modes must then not be empty nor
154  // contain MERGE_MODE_UNSPECIFIED, otherwise the call fails with
155  // invalid_argument. Changing settings needs the repo:admin scope, like any
156  // other field.
157  RepoSettings settings = 6;
158}
159
160// UpdateRepoResponse holds the repository after the update.
161message UpdateRepoResponse {
162  // Repo is the updated repository.
163  Repo repo = 1;
164}
165
166// DeleteRepoRequest names the repository to delete.
167message DeleteRepoRequest {
168  // Repo is the repository name.
169  string repo = 1;
170}
171
172// DeleteRepoResponse is empty.
173message DeleteRepoResponse {}