proto/remote.proto


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153

syntax = "proto3";

package gitaly;

import "lint.proto";
import "shared.proto";

option go_package = "gitlab.com/gitlab-org/gitaly/v16/proto/go/gitalypb";

// RemoteService is a service providing RPCs to interact with a remote
// repository that is hosted on another Git server.
service RemoteService {

  // UpdateRemoteMirror compares the references in the target repository and its remote mirror
  // repository. Any differences in the references are then addressed by pushing the differing
  // references to the mirror. Created and modified references are updated, removed references are
  // deleted from the mirror. UpdateRemoteMirror updates all tags. Branches are updated if they match
  // the patterns specified in the requests.
  rpc UpdateRemoteMirror(stream UpdateRemoteMirrorRequest) returns (UpdateRemoteMirrorResponse) {
    option (op_type) = {
        op: ACCESSOR
      };
  }

  // FindRemoteRepository detects whether a repository exists at the given URI. This is done by
  // asking git-ls-remote(1) to enumerate the remote's HEAD and then checking that we recognize it
  // as a valid reference.
  rpc FindRemoteRepository(FindRemoteRepositoryRequest) returns (FindRemoteRepositoryResponse) {
    option (op_type) = {
        op: ACCESSOR
        scope_level: STORAGE
      };
  }

  // FindRemoteRootRef tries to find the root reference of a remote
  // repository. The root reference is the default branch as pointed to by
  // the remotes HEAD reference. Returns an InvalidArgument error if the
  // specified remote does not exist and a NotFound error in case no HEAD
  // branch was found.
  rpc FindRemoteRootRef(FindRemoteRootRefRequest) returns (FindRemoteRootRefResponse) {
    option (op_type) = {
        op: ACCESSOR
      };
  }
}

// UpdateRemoteMirrorRequest is a request for the UpdateRemoteMirror RPC.
message UpdateRemoteMirrorRequest {
  // Remote defines a remote repository that diverged references should be pushed to.
  message Remote {
    // url is the URL of the remote repository.
    string url = 1;
    // http_authorization_header is an optional HTTP header used for
    // authenticating against the remote repository.
    string http_authorization_header = 2;
    // resolved_address holds the resolved IP address of the remote_url. This is
    // used to avoid DNS rebinding by mapping the url to the resolved address.
    // Only IPv4 dotted decimal ("192.0.2.1"), IPv6 ("2001:db8::68"), or IPv4-mapped
    // IPv6 ("::ffff:192.0.2.1") forms are supported.
    // Works with HTTP/HTTPS/Git/SSH protocols.
    // Optional.
    string resolved_address = 4;

    // HttpHost has been removed in favor of ResolvedAddress.
    reserved 3;
    reserved "http_host";
  }

  // repository is the repository whose mirror repository to update.
  Repository repository = 1 [(target_repository)=true];
  // remote contains parameters required to connect to the remote repository.
  // This allows Gitaly to use an in-memory remote and does not require any
  // on-disk remote configuration.
  Remote remote = 7;
  // only_branches_matching contains patterns to match branches against. Only the
  // matched branches are updated in the remote mirror. If no patterns are
  // specified, all branches are updated. The patterns should only contain the
  // branch name without the 'refs/heads/' prefix. "*" can be used as a
  // wildcard to match anything. only_branches_matching can be streamed to the
  // server over multiple messages. Optional.
  repeated bytes only_branches_matching = 3; // protolint:disable:this REPEATED_FIELD_NAMES_PLURALIZED
  // ssh_key is the SSH key to use for accessing to the mirror repository.
  // Optional.
  string ssh_key = 4;
  // known_hosts specifies the identities used for strict host key checking.
  // Optional.
  string known_hosts = 5;
  // keep_divergent_refs specifies whether or not to update diverged references
  // in the mirror repository.
  bool keep_divergent_refs = 6;

  reserved 2;
  reserved "ref_name";
}

// UpdateRemoteMirrorResponse is a response for the UpdateRemoteMirror RPC.
message UpdateRemoteMirrorResponse {
  // divergent_refs contains a list of references that had diverged in the
  // mirror from the source repository.
  repeated bytes divergent_refs = 1;
}

// FindRemoteRepositoryRequest is a request for the FindRemoteRepository RPC.
message FindRemoteRepositoryRequest {
  // remote is the remote repository being checked. Because this RPC is not executed within a
  // repository, the remote parameter must specify a valid Git URL for the targeted repository.
  string remote = 1;
  // storage_name is used to redirect request to proper storage where it can be handled.
  // As of now it doesn't matter what storage will be used, but it still must be a valid.
  // For more details: https://gitlab.com/gitlab-org/gitaly/-/issues/2442
  string storage_name = 2 [(storage)=true];
}

// FindRemoteRepositoryResponse is a response for the FindRemoteRepository RPC. This might throw a
// GRPC Unavailable code to signal the request failure is transient.
message FindRemoteRepositoryResponse {
  // exists specifies if the remote repository exists.
  bool exists = 1;
}

// FindRemoteRootRefRequest represents a request for the FindRemoteRootRef RPC.
message FindRemoteRootRefRequest {
  // repository is the repository in which the request shall be executed in. If
  // a remote name is given, then this is the repository in which the remote
  // will be looked up.
  Repository repository = 1 [(target_repository)=true];
  // remote_url specifies the remote repository URL which should be fetched from.
  string remote_url = 3;
  // http_authorization_header is the HTTP header which should be added to the
  // request in order to authenticate against the repository.
  string http_authorization_header = 4;
  // resolved_address holds the resolved IP address of the remote_url. This is
  // used to avoid DNS rebinding by mapping the url to the resolved address.
  // Only IPv4 dotted decimal ("192.0.2.1"), IPv6 ("2001:db8::68"), or IPv4-mapped
  // IPv6 ("::ffff:192.0.2.1") forms are supported.
  // Works with HTTP/HTTPS/Git/SSH protocols.
  // Optional.
  string resolved_address = 6;

  reserved 2;
  reserved "remote";

  // HttpHost has been removed in favor of ResolvedAddress.
  reserved 5;
  reserved "http_host";
}

// FindRemoteRootRefResponse represents the response for the FindRemoteRootRef
// request.
message FindRemoteRootRefResponse {
  // ref is the name of the remote root reference.
  string ref = 1;
}