ermite-api
The public API contract of ermite, a single-user Git forge: protobuf definitions for its ConnectRPC services and the Go code generated from them.
Status: early development. The contract defines fourteen services (below); the server that implements them is being built.
import "bnema.dev/ermite-api/gen/ermite"
The contract has no version number. It only changes in backward-compatible ways (new fields, messages, RPCs and services), and CI rejects any breaking change.
Services
Handlers are mounted under /-/api/ by the server. Errors are Connect codes.
| Service |
RPCs |
RepoService |
ListRepos, GetRepo, CreateRepo, UpdateRepo (field mask, merge settings), DeleteRepo |
GitService |
ListRefs, GetTree, ListPaths, GetBlob (streamed), ListCommits, GetCommit (structured diff), ResolveRevision |
TokenService |
CreateToken (secret shown once), ListTokens, RevokeToken |
MergeRequestService |
CreateMergeRequest, ListMergeRequests, GetMergeRequest (commits, diff, comments), AddComment, ResolveComment, CloseMergeRequest, MergeMergeRequest, MarkRead |
SessionService |
CreateLoginLink, SignOutEverywhere (owner only) |
EventService |
Watch (streamed, resumable) |
RunnerService |
RegisterRunner, FetchJob (long poll), UpdateJob (steps, annotations), AppendLog (offset-idempotent), Heartbeat, WatchJob (cancel requests, streamed), CompleteJob (idempotent), ResolveActions (where to download the uses: actions), UploadSummary (job summary of a step); for CI runners |
RunService |
ListRuns, GetRun, GetJob, GetJobLog (streamed, follow), ListAnnotations, GetStepSummaries, CancelRun, RerunRun, DispatchWorkflow, ListChecks, ListRunners, RemoveRunner |
SecretService |
SetSecret, ListSecrets (names only, never values), DeleteSecret; scopes instance, repository and environment |
VariableService |
SetVariable, GetVariable, ListVariables, DeleteVariable; same scopes |
EnvironmentService |
CreateEnvironment, ListEnvironments, DeleteEnvironment |
JobArtifactService |
CreateJobArtifact, UploadJobArtifactBlock (client stream), CommitJobArtifact, FinalizeJobArtifact, ListJobArtifacts, DownloadJobArtifact (streamed, resumable), DeleteJobArtifact; artifacts v4 for CI runners, scoped to the run of the job token |
ArtifactService |
ListArtifacts, DownloadArtifact (streamed, resumable), DeleteArtifact; artifacts of a run for people |
ServerService |
GetVersion (server version and feature list), GetSigningKey (commit signing key), RotateOIDCKey (key of the CI OIDC ID tokens, owner only) |
Tokens carry scopes only; presets such as cli or agent are a client concern.
Layout
proto/ermite/: .proto files of the ermite package, one per service (repo, git, merge_request, token, session, event, server, runner, run, ci_settings, artifact) plus shared types. Checked by buf lint and buf breaking.gen/ermite/: generated Go messages. gen/ermite/ermiteconnect/: generated Connect clients and handlers. Committed, never edited by hand.
Generate
buf generate
License
MIT. See LICENSE.
source
1# ermite-api
2
3The public API contract of [ermite](https://git.bnema.dev/bnema/ermite), a single-user Git forge: protobuf definitions for its ConnectRPC services and the Go code generated from them.
4
5Status: early development. The contract defines fourteen services (below); the server that implements them is being built.
6
7```go
8import "bnema.dev/ermite-api/gen/ermite"
9```
10
11The contract has no version number. It only changes in backward-compatible ways (new fields, messages, RPCs and services), and CI rejects any breaking change.
12
13## Services
14
15Handlers are mounted under `/-/api/` by the server. Errors are Connect codes.
16
17| Service | RPCs |
18|---|---|
19| `RepoService` | `ListRepos`, `GetRepo`, `CreateRepo`, `UpdateRepo` (field mask, merge settings), `DeleteRepo` |
20| `GitService` | `ListRefs`, `GetTree`, `ListPaths`, `GetBlob` (streamed), `ListCommits`, `GetCommit` (structured diff), `ResolveRevision` |
21| `TokenService` | `CreateToken` (secret shown once), `ListTokens`, `RevokeToken` |
22| `MergeRequestService` | `CreateMergeRequest`, `ListMergeRequests`, `GetMergeRequest` (commits, diff, comments), `AddComment`, `ResolveComment`, `CloseMergeRequest`, `MergeMergeRequest`, `MarkRead` |
23| `SessionService` | `CreateLoginLink`, `SignOutEverywhere` (owner only) |
24| `EventService` | `Watch` (streamed, resumable) |
25| `RunnerService` | `RegisterRunner`, `FetchJob` (long poll), `UpdateJob` (steps, annotations), `AppendLog` (offset-idempotent), `Heartbeat`, `WatchJob` (cancel requests, streamed), `CompleteJob` (idempotent), `ResolveActions` (where to download the `uses:` actions), `UploadSummary` (job summary of a step); for CI runners |
26| `RunService` | `ListRuns`, `GetRun`, `GetJob`, `GetJobLog` (streamed, follow), `ListAnnotations`, `GetStepSummaries`, `CancelRun`, `RerunRun`, `DispatchWorkflow`, `ListChecks`, `ListRunners`, `RemoveRunner` |
27| `SecretService` | `SetSecret`, `ListSecrets` (names only, never values), `DeleteSecret`; scopes instance, repository and environment |
28| `VariableService` | `SetVariable`, `GetVariable`, `ListVariables`, `DeleteVariable`; same scopes |
29| `EnvironmentService` | `CreateEnvironment`, `ListEnvironments`, `DeleteEnvironment` |
30| `JobArtifactService` | `CreateJobArtifact`, `UploadJobArtifactBlock` (client stream), `CommitJobArtifact`, `FinalizeJobArtifact`, `ListJobArtifacts`, `DownloadJobArtifact` (streamed, resumable), `DeleteJobArtifact`; artifacts v4 for CI runners, scoped to the run of the job token |
31| `ArtifactService` | `ListArtifacts`, `DownloadArtifact` (streamed, resumable), `DeleteArtifact`; artifacts of a run for people |
32| `ServerService` | `GetVersion` (server version and feature list), `GetSigningKey` (commit signing key), `RotateOIDCKey` (key of the CI OIDC ID tokens, owner only) |
33
34Tokens carry scopes only; presets such as `cli` or `agent` are a client concern.
35
36## Layout
37
38- `proto/ermite/`: `.proto` files of the `ermite` package, one per service (`repo`, `git`, `merge_request`, `token`, `session`, `event`, `server`, `runner`, `run`, `ci_settings`, `artifact`) plus shared `types`. Checked by `buf lint` and `buf breaking`.
39- `gen/ermite/`: generated Go messages. `gen/ermite/ermiteconnect/`: generated Connect clients and handlers. Committed, never edited by hand.
40
41## Generate
42
43```sh
44buf generate
45```
46
47## License
48
49MIT. See [LICENSE](LICENSE).