1// Copyright 2019 Google LLC.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14//
15
16syntax = "proto3";
17
18package google.devtools.source.v1;
19
20option cc_enable_arenas = true;
21option csharp_namespace = "Google.Cloud.DevTools.Source.V1";
22option go_package = "google.golang.org/genproto/googleapis/devtools/source/v1;source";
23option java_multiple_files = true;
24option java_outer_classname = "SourceContextProto";
25option java_package = "com.google.devtools.source.v1";
26option php_namespace = "Google\\Cloud\\DevTools\\Source\\V1";
27
28// A SourceContext is a reference to a tree of files. A SourceContext together
29// with a path point to a unique revision of a single file or directory.
30message SourceContext {
31  // A SourceContext can refer any one of the following types of repositories.
32  oneof context {
33    // A SourceContext referring to a revision in a cloud repo.
34    CloudRepoSourceContext cloud_repo = 1;
35
36    // A SourceContext referring to a snapshot in a cloud workspace.
37    CloudWorkspaceSourceContext cloud_workspace = 2;
38
39    // A SourceContext referring to a Gerrit project.
40    GerritSourceContext gerrit = 3;
41
42    // A SourceContext referring to any third party Git repo (e.g. GitHub).
43    GitSourceContext git = 6;
44  }
45}
46
47// An ExtendedSourceContext is a SourceContext combined with additional
48// details describing the context.
49message ExtendedSourceContext {
50  // Any source context.
51  SourceContext context = 1;
52
53  // Labels with user defined metadata.
54  map<string, string> labels = 2;
55}
56
57// An alias to a repo revision.
58message AliasContext {
59  // The type of an Alias.
60  enum Kind {
61    // Do not use.
62    ANY = 0;
63
64    // Git tag
65    FIXED = 1;
66
67    // Git branch
68    MOVABLE = 2;
69
70    // OTHER is used to specify non-standard aliases, those not of the kinds
71    // above. For example, if a Git repo has a ref named "refs/foo/bar", it
72    // is considered to be of kind OTHER.
73    OTHER = 4;
74  }
75
76  // The alias kind.
77  Kind kind = 1;
78
79  // The alias name.
80  string name = 2;
81}
82
83// A CloudRepoSourceContext denotes a particular revision in a cloud
84// repo (a repo hosted by the Google Cloud Platform).
85message CloudRepoSourceContext {
86  // The ID of the repo.
87  RepoId repo_id = 1;
88
89  // A revision in a cloud repository can be identified by either its revision
90  // ID or its Alias.
91  oneof revision {
92    // A revision ID.
93    string revision_id = 2;
94
95    // The name of an alias (branch, tag, etc.).
96    string alias_name = 3 [deprecated = true];
97
98    // An alias, which may be a branch or tag.
99    AliasContext alias_context = 4;
100  }
101}
102
103// A CloudWorkspaceSourceContext denotes a workspace at a particular snapshot.
104message CloudWorkspaceSourceContext {
105  // The ID of the workspace.
106  CloudWorkspaceId workspace_id = 1;
107
108  // The ID of the snapshot.
109  // An empty snapshot_id refers to the most recent snapshot.
110  string snapshot_id = 2;
111}
112
113// A SourceContext referring to a Gerrit project.
114message GerritSourceContext {
115  // The URI of a running Gerrit instance.
116  string host_uri = 1;
117
118  // The full project name within the host. Projects may be nested, so
119  // "project/subproject" is a valid project name.
120  // The "repo name" is hostURI/project.
121  string gerrit_project = 2;
122
123  // A revision in a Gerrit project can be identified by either its revision ID
124  // or its alias.
125  oneof revision {
126    // A revision (commit) ID.
127    string revision_id = 3;
128
129    // The name of an alias (branch, tag, etc.).
130    string alias_name = 4 [deprecated = true];
131
132    // An alias, which may be a branch or tag.
133    AliasContext alias_context = 5;
134  }
135}
136
137// A GitSourceContext denotes a particular revision in a third party Git
138// repository (e.g. GitHub).
139message GitSourceContext {
140  // Git repository URL.
141  string url = 1;
142
143  // Git commit hash.
144  // required.
145  string revision_id = 2;
146}
147
148// A unique identifier for a cloud repo.
149message RepoId {
150  // A cloud repository can be identified by either its project ID and
151  // repository name combination, or its globally unique identifier.
152  oneof id {
153    // A combination of a project ID and a repo name.
154    ProjectRepoId project_repo_id = 1;
155
156    // A server-assigned, globally unique identifier.
157    string uid = 2;
158  }
159}
160
161// Selects a repo using a Google Cloud Platform project ID
162// (e.g. winged-cargo-31) and a repo name within that project.
163message ProjectRepoId {
164  // The ID of the project.
165  string project_id = 1;
166
167  // The name of the repo. Leave empty for the default repo.
168  string repo_name = 2;
169}
170
171// A CloudWorkspaceId is a unique identifier for a cloud workspace.
172// A cloud workspace is a place associated with a repo where modified files
173// can be stored before they are committed.
174message CloudWorkspaceId {
175  // The ID of the repo containing the workspace.
176  RepoId repo_id = 1;
177
178  // The unique name of the workspace within the repo.  This is the name
179  // chosen by the client in the Source API's CreateWorkspace method.
180  string name = 2;
181}
182