1// SPDX-License-Identifier: MIT
2
3syntax = "proto3";
4
5package ermite;
6
7import "google/protobuf/timestamp.proto";
8
9// ServerService describes the server itself.
10service ServerService {
11 // GetVersion returns the server version and the optional capabilities of the
12 // contract it implements. It needs no authentication, so a client can call
13 // it first to check compatibility.
14 rpc GetVersion(GetVersionRequest) returns (GetVersionResponse);
15 // GetSigningKey returns the public key with which the server signs the
16 // commits it creates (squash and merge commits, see MergeMode). It needs no
17 // authentication: the key is public, and anyone verifying a commit needs it.
18 // Servers that implement it list "signing_key" in
19 // GetVersionResponse.features.
20 rpc GetSigningKey(GetSigningKeyRequest) returns (GetSigningKeyResponse);
21 // RotateOIDCKey replaces the key with which the server signs the OIDC ID
22 // tokens of CI jobs (Job.id_token_url) by a new one. The previous key stops
23 // signing at once but stays in the server's JWKS
24 // ("/-/oidc/.well-known/jwks") for 24 hours, so that tokens it signed still
25 // verify until they expire. It needs owner rights: the admin token, the
26 // owner's session, or a token with every scope and no repository list or
27 // branch prefixes (permission_denied otherwise). It fails with
28 // failed_precondition when the server issues no ID tokens (it has no
29 // secrets key to seal the key with). Servers that implement it list
30 // "ci.oidc" in GetVersionResponse.features.
31 rpc RotateOIDCKey(RotateOIDCKeyRequest) returns (RotateOIDCKeyResponse);
32}
33
34// GetVersionRequest is empty.
35message GetVersionRequest {}
36
37// GetVersionResponse describes the running server.
38message GetVersionResponse {
39 // Version is the server release, for example "v0.4.0", or "devel" for an
40 // untagged build. Informational: clients must not compare it to decide what
41 // is supported, they use features instead.
42 string version = 1;
43 // Features lists identifiers of the optional capabilities of the contract
44 // that this server implements, for example "repo.update" or
45 // "events.resume". A client that needs a capability missing from this list
46 // should warn instead of failing on an unimplemented RPC or ignored field.
47 // Identifiers are lowercase, dot-separated and never reused. The CI
48 // identifiers are "ci.runs" (RunService runs, jobs, logs, checks, and the
49 // run_updated and job_updated events), "ci.runs.filters" (ListRuns honours
50 // its filters) and "ci.runners" (RunnerService, and RunService.ListRunners
51 // and RemoveRunner). The CI execution identifiers are "ci.actions"
52 // (RunnerService.ResolveActions and Job.github_token), "ci.annotations"
53 // (annotations in UpdateJob and CompleteJob, and RunService.ListAnnotations)
54 // and "ci.summaries" (RunnerService.UploadSummary and
55 // RunService.GetStepSummaries). The CI platform identifiers are "ci.secrets"
56 // (SecretService, VariableService and EnvironmentService, and in Job the
57 // secrets, vars, environment, permissions and trusted fields and Run.trusted),
58 // "ci.dispatch" (RunService.DispatchWorkflow), "ci.concurrency"
59 // (CI_STATUS_PENDING and RunJob.concurrency_group), "ci.cache" (Job.cache)
60 // and "ci.artifacts" (JobArtifactService and ArtifactService). The merge
61 // request identifier "merge_requests.mergeability" covers
62 // MergeRequest.mergeability, the MergeRequestMergeability event and
63 // MERGE_MODE_MERGE_COMMIT. "merge_requests.auto_merge" covers
64 // RepoSettings.allow_auto_merge, MergeRequest.auto_merge and auto_merged,
65 // the EnableAutoMerge and CancelAutoMerge RPCs, the
66 // MergeRequestAutoMergeEnabled and MergeRequestAutoMergeCancelled events
67 // and MergeRequestMerged.auto. "releases" covers ReleaseService and the
68 // release_published, release_updated, release_deleted and release_unpublished events.
69 repeated string features = 2;
70}
71
72// GetSigningKeyRequest is empty.
73message GetSigningKeyRequest {}
74
75// GetSigningKeyResponse describes the commit signing key of the server.
76message GetSigningKeyResponse {
77 // PublicKey is the public key as one OpenSSH authorized_keys line, for
78 // example "ssh-ed25519 AAAA...". Commits are signed in the SSH signature
79 // format (SSHSIG).
80 string public_key = 1;
81 // Fingerprint is the SHA-256 fingerprint of the key, in the form
82 // "SHA256:<base64>" that ssh-keygen prints.
83 string fingerprint = 2;
84 // CommitterName is the name the server records as the committer of the
85 // commits it creates.
86 string committer_name = 3;
87 // CommitterEmail is the email address the server records as the committer of
88 // the commits it creates. It is the principal of allowed_signers.
89 string committer_email = 4;
90 // AllowedSigners is a ready-to-use line for an allowed signers file
91 // ("<committer_email> <public_key>"), to verify these commits with
92 // "git config gpg.ssh.allowedSignersFile".
93 string allowed_signers = 5;
94}
95
96// RotateOIDCKeyRequest is empty.
97message RotateOIDCKeyRequest {}
98
99// RotateOIDCKeyResponse describes the new signing key of the ID tokens.
100message RotateOIDCKeyResponse {
101 // Issuer is the "iss" of the ID tokens, for example
102 // "https://git.example.com/-/oidc". Its discovery document is at
103 // "<issuer>/.well-known/openid-configuration".
104 string issuer = 1;
105 // Kid is the key id of the new key, the "kid" of the tokens it signs: the
106 // RFC 7638 thumbprint of its public key, base64url without padding.
107 string kid = 2;
108 // RetiredKid is the key id of the key it replaces; empty when there was
109 // none.
110 string retired_kid = 3;
111 // RetiredUntil is when the replaced key leaves the JWKS. Unset when there
112 // was none.
113 google.protobuf.Timestamp retired_until = 4;
114}