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// IssuesMode says who may write issues in a repository.
24enum IssuesMode {
25 // Not set.
26 ISSUES_MODE_UNSPECIFIED = 0;
27 // Issues are disabled.
28 ISSUES_MODE_OFF = 1;
29 // Only the owner may write issues.
30 ISSUES_MODE_OWNER = 2;
31 // Issues are open to public participation.
32 ISSUES_MODE_PUBLIC = 3;
33}
34
35// RepoSettings are the settings of a repository that govern its merge
36// requests and issues.
37message RepoSettings {
38 // AllowedMergeModes are the modes with which a merge request of the
39 // repository may be merged. It is never empty in a response and has no
40 // duplicate. Every mode is allowed by default. MERGE_MODE_UNSPECIFIED is
41 // rejected.
42 repeated MergeMode allowed_merge_modes = 1;
43 // FailingChecksBlock is unused: servers ignore it and never set it. A merge
44 // needs passing checks unless MergeMergeRequestRequest.ignore_checks is set.
45 bool failing_checks_block = 2 [deprecated = true];
46 // Issues is the issue participation mode of the repository.
47 IssuesMode issues = 3;
48 // AllowAutoMerge says whether auto-merge can be enabled on the merge requests
49 // of the repository (see MergeRequestService.EnableAutoMerge). It is false by
50 // default. Set only by servers with the "merge_requests.auto_merge" feature.
51 bool allow_auto_merge = 4;
52}
53
54// Repo is the metadata of a repository. Git-owned state (refs, trees, history)
55// is read through GitService.
56message Repo {
57 // Name is the unique, lowercase repository name: 1-100 characters from
58 // [a-z0-9._-], without a ".git" suffix. It is also the URL path: /<name>.
59 string name = 1;
60 // Description is a free one-line description. It may be empty.
61 string description = 2;
62 // Visibility is who may read the repository.
63 Visibility visibility = 3;
64 // DefaultBranch is the short name of the branch HEAD points to, for example
65 // "main". It is set even when the branch does not exist yet (empty
66 // repository).
67 string default_branch = 4;
68 // CreatedAt is when the repository was created.
69 google.protobuf.Timestamp created_at = 5;
70 // PushedAt is the time of the last push. It is unset until the first push.
71 google.protobuf.Timestamp pushed_at = 6;
72 // Settings are the settings of the repository. Always set in a
73 // response, with the defaults for a repository that never changed them.
74 RepoSettings settings = 7;
75 // Topics classify the repository, as on GitHub: at most 20, each 1-50
76 // characters from [a-z0-9-], starting with a letter or a digit, sorted
77 // and without duplicates.
78 repeated string topics = 8;
79}
80
81// RepoService manages repositories and their metadata.
82//
83// Anonymous callers see public repositories only. A private repository that the
84// caller cannot read is reported as not_found.
85service RepoService {
86 // ListRepos lists the repositories the caller may see, ordered by name.
87 rpc ListRepos(ListReposRequest) returns (ListReposResponse);
88 // GetRepo returns one repository. Fails with not_found if it does not exist
89 // or is private and not readable by the caller.
90 rpc GetRepo(GetRepoRequest) returns (GetRepoResponse);
91 // CreateRepo creates an empty repository with the default settings. Needs
92 // the repo:write scope. Fails
93 // with already_exists if the name is taken and invalid_argument if the name
94 // is not valid.
95 rpc CreateRepo(CreateRepoRequest) returns (CreateRepoResponse);
96 // UpdateRepo changes the fields named in update_mask, including the merge
97 // settings. Needs the repo:admin scope.
98 rpc UpdateRepo(UpdateRepoRequest) returns (UpdateRepoResponse);
99 // DeleteRepo deletes a repository. Needs the repo:admin scope. The server
100 // moves the data aside rather than destroying it; there is no undelete RPC.
101 rpc DeleteRepo(DeleteRepoRequest) returns (DeleteRepoResponse);
102}
103
104// ListReposRequest selects a page of repositories.
105message ListReposRequest {
106 // PageSize is the maximum number of repositories to return. 0 means the
107 // server default; values above the server maximum are lowered to it.
108 int32 page_size = 1;
109 // PageToken is the next_page_token of a previous response, to get the page
110 // after it. Empty for the first page.
111 string page_token = 2;
112}
113
114// ListReposResponse is one page of repositories.
115message ListReposResponse {
116 // Repos are the repositories of this page, ordered by name.
117 repeated Repo repos = 1;
118 // NextPageToken is passed as page_token to get the next page. Empty when
119 // there is no next page.
120 string next_page_token = 2;
121}
122
123// GetRepoRequest names the repository to read.
124message GetRepoRequest {
125 // Repo is the repository name.
126 string repo = 1;
127}
128
129// GetRepoResponse holds the repository.
130message GetRepoResponse {
131 // Repo is the repository metadata.
132 Repo repo = 1;
133}
134
135// CreateRepoRequest describes the repository to create.
136message CreateRepoRequest {
137 // Name is the name of the new repository. Names are lowercase; an uppercase
138 // name is rejected with invalid_argument.
139 string name = 1;
140 // Description is an optional one-line description.
141 string description = 2;
142 // Visibility of the new repository. VISIBILITY_UNSPECIFIED means private.
143 Visibility visibility = 3;
144 // Topics are the optional topics of the new repository (see Repo.topics);
145 // they are lowercased, sorted and deduplicated.
146 repeated string topics = 4;
147}
148
149// CreateRepoResponse holds the new repository.
150message CreateRepoResponse {
151 // Repo is the created repository.
152 Repo repo = 1;
153}
154
155// UpdateRepoRequest changes some fields of a repository.
156message UpdateRepoRequest {
157 // Repo is the name of the repository to change. Repositories cannot be
158 // renamed.
159 string repo = 1;
160 // Description is the new description. Used only if update_mask contains
161 // "description"; an empty value then clears it.
162 string description = 2;
163 // Visibility is the new visibility. Used only if update_mask contains
164 // "visibility"; it must not be VISIBILITY_UNSPECIFIED then.
165 Visibility visibility = 3;
166 // DefaultBranch is the short name of the new default branch. Used only if
167 // update_mask contains "default_branch". The branch must exist, otherwise
168 // the call fails with failed_precondition.
169 string default_branch = 4;
170 // UpdateMask lists the fields to change: "description", "visibility",
171 // "default_branch", "topics", "settings.allowed_merge_modes" and/or
172 // "settings.allow_auto_merge". "settings" stands for the two merge settings
173 // paths. It must not be empty unless issues is set. Other paths are
174 // invalid_argument, including "settings.issues" and "issues": the issues
175 // field is applied outside the mask.
176 google.protobuf.FieldMask update_mask = 5;
177 // Settings holds the new merge settings. Only the fields named in
178 // update_mask are used. allowed_merge_modes must then not be empty nor
179 // contain MERGE_MODE_UNSPECIFIED, otherwise the call fails with
180 // invalid_argument. Changing settings needs the repo:admin scope, like any
181 // other field.
182 RepoSettings settings = 6;
183 // Topics replace the topics of the repository (see Repo.topics). Used only
184 // if update_mask contains "topics"; an empty list then clears them.
185 repeated string topics = 7;
186 // Issues is the new issue participation mode. When absent it is unchanged.
187 // It is applied whatever update_mask contains, and may be the only change
188 // (an empty update_mask is then valid). When present it must not be
189 // ISSUES_MODE_UNSPECIFIED: that is invalid_argument. Changing it needs the
190 // repo:admin scope and a token with no branch limit, like any other field.
191 optional IssuesMode issues = 8;
192}
193
194// UpdateRepoResponse holds the repository after the update.
195message UpdateRepoResponse {
196 // Repo is the updated repository.
197 Repo repo = 1;
198}
199
200// DeleteRepoRequest names the repository to delete.
201message DeleteRepoRequest {
202 // Repo is the repository name.
203 string repo = 1;
204}
205
206// DeleteRepoResponse is empty.
207message DeleteRepoResponse {}