docs(readme): rewrite README with a short overview and docs/ (#19)
- commit
- e06a09cc1860146664cebc615c9c6a20859f4a9a
- author
- brice · · 2026-10-18 17:43 UTC
- committer
- bnema · · 2026-10-18 17:43 UTC
- parent
- 5143801
- signature
- SSH Unverified
SHA256:VOCA5lYARHcbKDZ7GhTV45VmcjWnJ6ZQIBazj17LivAThe key is unknown
2 files · +54 -29
M README.md +36 -29
| @@ -1,46 +1,53 @@ | |||
| 1 | - | # ermite-api | |
| 1 | + | <h1 align="center">ermite-api</h1> | |
| 2 | 2 | ||
| 3 | - | > Read-only mirror. Development happens at git.bnema.dev; issues and pull requests are closed here. | |
| 3 | + | <p align="center"> | |
| 4 | + | <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License: MIT"></a> | |
| 5 | + | <a href="https://github.com/bnema/ermite-api/commits/main"><img src="https://badgen.net/github/last-commit/bnema/ermite-api/main?icon=github" alt="Last commit"></a> | |
| 6 | + | <a href="https://github.com/bnema/ermite-api/stargazers"><img src="https://badgen.net/github/stars/bnema/ermite-api?icon=github" alt="GitHub stars"></a> | |
| 7 | + | </p> | |
| 8 | + | ||
| 9 | + | <p align="center">The public API of <a href="https://github.com/bnema/ermite">ermite</a>: protobuf definitions and generated Go code for its ConnectRPC services.</p> | |
| 4 | 10 | ||
| 5 | - | The public API contract of [ermite](https://github.com/bnema/ermite), a single-user Git forge: protobuf definitions for its ConnectRPC services and the Go code generated from them. | |
| 11 | + | > Read-only mirror. Development happens at git.bnema.dev; issues and pull requests are closed here. | |
| 6 | 12 | ||
| 7 | - | Status: early development. The contract defines fourteen services (below); the server that implements them is being built. | |
| 13 | + | --- | |
| 8 | 14 | ||
| 9 | 15 | ```go | |
| 10 | - | import "bnema.dev/ermite-api/gen/ermite" | |
| 16 | + | import ( | |
| 17 | + | "bnema.dev/ermite-api/gen/ermite" | |
| 18 | + | "bnema.dev/ermite-api/gen/ermite/ermiteconnect" | |
| 19 | + | ) | |
| 11 | 20 | ``` | |
| 12 | 21 | ||
| 13 | - | 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. | |
| 22 | + | - The server mounts the services under `/-/api/`. Errors are Connect codes. | |
| 23 | + | - No version number: the contract only changes in backward-compatible ways, and CI rejects breaking changes (`buf breaking`). | |
| 24 | + | - Tokens carry scopes only; presets such as `cli` or `agent` are a client concern. | |
| 14 | 25 | ||
| 15 | - | ## Services | |
| 26 | + | Status: early development. | |
| 16 | 27 | ||
| 17 | - | Handlers are mounted under `/-/api/` by the server. Errors are Connect codes. | |
| 28 | + | ## Services | |
| 18 | 29 | ||
| 19 | - | | Service | RPCs | | |
| 30 | + | | Service | Purpose | | |
| 20 | 31 | |---|---| | |
| 21 | - | | `RepoService` | `ListRepos`, `GetRepo`, `CreateRepo`, `UpdateRepo` (field mask, merge settings), `DeleteRepo` | | |
| 22 | - | | `GitService` | `ListRefs`, `GetTree`, `ListPaths`, `GetBlob` (streamed), `ListCommits`, `GetCommit` (structured diff), `ResolveRevision` | | |
| 23 | - | | `TokenService` | `CreateToken` (secret shown once), `ListTokens`, `RevokeToken` | | |
| 24 | - | | `MergeRequestService` | `CreateMergeRequest`, `ListMergeRequests`, `GetMergeRequest` (commits, diff, comments), `AddComment`, `ResolveComment`, `CloseMergeRequest`, `MergeMergeRequest`, `MarkRead` | | |
| 25 | - | | `SessionService` | `CreateLoginLink`, `SignOutEverywhere` (owner only) | | |
| 26 | - | | `EventService` | `Watch` (streamed, resumable) | | |
| 27 | - | | `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 | | |
| 28 | - | | `RunService` | `ListRuns`, `GetRun`, `GetJob`, `GetJobLog` (streamed, follow), `ListAnnotations`, `GetStepSummaries`, `CancelRun`, `RerunRun`, `DispatchWorkflow`, `ListChecks`, `ListRunners`, `RemoveRunner` | | |
| 29 | - | | `SecretService` | `SetSecret`, `ListSecrets` (names only, never values), `DeleteSecret`; scopes instance, repository and environment | | |
| 30 | - | | `VariableService` | `SetVariable`, `GetVariable`, `ListVariables`, `DeleteVariable`; same scopes | | |
| 31 | - | | `EnvironmentService` | `CreateEnvironment`, `ListEnvironments`, `DeleteEnvironment` | | |
| 32 | - | | `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 | | |
| 33 | - | | `ArtifactService` | `ListArtifacts`, `DownloadArtifact` (streamed, resumable), `DeleteArtifact`; artifacts of a run for people | | |
| 34 | - | | `ServerService` | `GetVersion` (server version and feature list), `GetSigningKey` (commit signing key), `RotateOIDCKey` (key of the CI OIDC ID tokens, owner only) | | |
| 35 | - | ||
| 36 | - | Tokens carry scopes only; presets such as `cli` or `agent` are a client concern. | |
| 32 | + | | `RepoService` | repositories and their settings | | |
| 33 | + | | `GitService` | refs, trees, blobs, commits and diffs | | |
| 34 | + | | `TokenService` | API tokens | | |
| 35 | + | | `MergeRequestService` | merge requests, comments, merge | | |
| 36 | + | | `SessionService` | web sign-in links (owner only) | | |
| 37 | + | | `EventService` | live event stream, resumable | | |
| 38 | + | | `ServerService` | version, features, signing key, OIDC key rotation | | |
| 39 | + | | `RunService` | CI runs, jobs, logs, checks, runners | | |
| 40 | + | | `RunnerService` | used by CI runners to fetch and report jobs | | |
| 41 | + | | `SecretService`, `VariableService`, `EnvironmentService` | CI settings | | |
| 42 | + | | `ArtifactService` | CI artifacts, for people | | |
| 43 | + | | `JobArtifactService` | CI artifacts v4, for runners | | |
| 44 | + | ||
| 45 | + | Every RPC: [docs/services.md](docs/services.md). | |
| 37 | 46 | ||
| 38 | 47 | ## Layout | |
| 39 | 48 | ||
| 40 | - | - `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`. | |
| 41 | - | - `gen/ermite/`: generated Go messages. `gen/ermite/ermiteconnect/`: generated Connect clients and handlers. Committed, never edited by hand. | |
| 42 | - | ||
| 43 | - | ## Generate | |
| 49 | + | - `proto/ermite/`: one `.proto` per service, plus shared `types.proto`. | |
| 50 | + | - `gen/ermite/`: generated messages; `gen/ermite/ermiteconnect/`: Connect clients and handlers. Committed, never edited by hand. | |
| 44 | 51 | ||
| 45 | 52 | ```sh | |
| 46 | 53 | buf generate | |
| @@ -1,46 +1,53 @@ | |||||
| 1 | - | # ermite-api | 1 | + | <h1 align="center">ermite-api</h1> |
| 2 | 2 | ||||
| 3 | - | > Read-only mirror. Development happens at git.bnema.dev; issues and pull requests are closed here. | 3 | + | <p align="center"> |
| 4 | + | <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License: MIT"></a> | |||
| 5 | + | <a href="https://github.com/bnema/ermite-api/commits/main"><img src="https://badgen.net/github/last-commit/bnema/ermite-api/main?icon=github" alt="Last commit"></a> | |||
| 6 | + | <a href="https://github.com/bnema/ermite-api/stargazers"><img src="https://badgen.net/github/stars/bnema/ermite-api?icon=github" alt="GitHub stars"></a> | |||
| 7 | + | </p> | |||
| 8 | + | ||||
| 9 | + | <p align="center">The public API of <a href="https://github.com/bnema/ermite">ermite</a>: protobuf definitions and generated Go code for its ConnectRPC services.</p> | |||
| 4 | 10 | ||||
| 5 | - | The public API contract of [ermite](https://github.com/bnema/ermite), a single-user Git forge: protobuf definitions for its ConnectRPC services and the Go code generated from them. | 11 | + | > Read-only mirror. Development happens at git.bnema.dev; issues and pull requests are closed here. |
| 6 | 12 | ||||
| 7 | - | Status: early development. The contract defines fourteen services (below); the server that implements them is being built. | 13 | + | --- |
| 8 | 14 | ||||
| 9 | ```go | 15 | ```go | ||
| 10 | - | import "bnema.dev/ermite-api/gen/ermite" | 16 | + | import ( |
| 17 | + | "bnema.dev/ermite-api/gen/ermite" | |||
| 18 | + | "bnema.dev/ermite-api/gen/ermite/ermiteconnect" | |||
| 19 | + | ) | |||
| 11 | ``` | 20 | ``` | ||
| 12 | 21 | ||||
| 13 | - | 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. | 22 | + | - The server mounts the services under `/-/api/`. Errors are Connect codes. |
| 23 | + | - No version number: the contract only changes in backward-compatible ways, and CI rejects breaking changes (`buf breaking`). | |||
| 24 | + | - Tokens carry scopes only; presets such as `cli` or `agent` are a client concern. | |||
| 14 | 25 | ||||
| 15 | - | ## Services | 26 | + | Status: early development. |
| 16 | 27 | ||||
| 17 | - | Handlers are mounted under `/-/api/` by the server. Errors are Connect codes. | 28 | + | ## Services |
| 18 | 29 | ||||
| 19 | - | | Service | RPCs | | 30 | + | | Service | Purpose | |
| 20 | |---|---| | 31 | |---|---| | ||
| 21 | - | | `RepoService` | `ListRepos`, `GetRepo`, `CreateRepo`, `UpdateRepo` (field mask, merge settings), `DeleteRepo` | | 32 | + | | `RepoService` | repositories and their settings | |
| 22 | - | | `GitService` | `ListRefs`, `GetTree`, `ListPaths`, `GetBlob` (streamed), `ListCommits`, `GetCommit` (structured diff), `ResolveRevision` | | 33 | + | | `GitService` | refs, trees, blobs, commits and diffs | |
| 23 | - | | `TokenService` | `CreateToken` (secret shown once), `ListTokens`, `RevokeToken` | | 34 | + | | `TokenService` | API tokens | |
| 24 | - | | `MergeRequestService` | `CreateMergeRequest`, `ListMergeRequests`, `GetMergeRequest` (commits, diff, comments), `AddComment`, `ResolveComment`, `CloseMergeRequest`, `MergeMergeRequest`, `MarkRead` | | 35 | + | | `MergeRequestService` | merge requests, comments, merge | |
| 25 | - | | `SessionService` | `CreateLoginLink`, `SignOutEverywhere` (owner only) | | 36 | + | | `SessionService` | web sign-in links (owner only) | |
| 26 | - | | `EventService` | `Watch` (streamed, resumable) | | 37 | + | | `EventService` | live event stream, resumable | |
| 27 | - | | `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 | | 38 | + | | `ServerService` | version, features, signing key, OIDC key rotation | |
| 28 | - | | `RunService` | `ListRuns`, `GetRun`, `GetJob`, `GetJobLog` (streamed, follow), `ListAnnotations`, `GetStepSummaries`, `CancelRun`, `RerunRun`, `DispatchWorkflow`, `ListChecks`, `ListRunners`, `RemoveRunner` | | 39 | + | | `RunService` | CI runs, jobs, logs, checks, runners | |
| 29 | - | | `SecretService` | `SetSecret`, `ListSecrets` (names only, never values), `DeleteSecret`; scopes instance, repository and environment | | 40 | + | | `RunnerService` | used by CI runners to fetch and report jobs | |
| 30 | - | | `VariableService` | `SetVariable`, `GetVariable`, `ListVariables`, `DeleteVariable`; same scopes | | 41 | + | | `SecretService`, `VariableService`, `EnvironmentService` | CI settings | |
| 31 | - | | `EnvironmentService` | `CreateEnvironment`, `ListEnvironments`, `DeleteEnvironment` | | 42 | + | | `ArtifactService` | CI artifacts, for people | |
| 32 | - | | `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 | | 43 | + | | `JobArtifactService` | CI artifacts v4, for runners | |
| 33 | - | | `ArtifactService` | `ListArtifacts`, `DownloadArtifact` (streamed, resumable), `DeleteArtifact`; artifacts of a run for people | | 44 | + | |
| 34 | - | | `ServerService` | `GetVersion` (server version and feature list), `GetSigningKey` (commit signing key), `RotateOIDCKey` (key of the CI OIDC ID tokens, owner only) | | 45 | + | Every RPC: [docs/services.md](docs/services.md). |
| 35 | - | ||||
| 36 | - | Tokens carry scopes only; presets such as `cli` or `agent` are a client concern. | |||
| 37 | 46 | ||||
| 38 | ## Layout | 47 | ## Layout | ||
| 39 | 48 | ||||
| 40 | - | - `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`. | 49 | + | - `proto/ermite/`: one `.proto` per service, plus shared `types.proto`. |
| 41 | - | - `gen/ermite/`: generated Go messages. `gen/ermite/ermiteconnect/`: generated Connect clients and handlers. Committed, never edited by hand. | 50 | + | - `gen/ermite/`: generated messages; `gen/ermite/ermiteconnect/`: Connect clients and handlers. Committed, never edited by hand. |
| 42 | - | ||||
| 43 | - | ## Generate | |||
| 44 | 51 | ||||
| 45 | ```sh | 52 | ```sh | ||
| 46 | buf generate | 53 | buf generate | ||
A docs/services.md +18 -0
| @@ -0,0 +1,18 @@ | |||
| 1 | + | # Services | |
| 2 | + | ||
| 3 | + | | Service | RPCs | | |
| 4 | + | |---|---| | |
| 5 | + | | `RepoService` | `ListRepos`, `GetRepo`, `CreateRepo`, `UpdateRepo` (field mask, merge settings), `DeleteRepo` | | |
| 6 | + | | `GitService` | `ListRefs`, `GetTree`, `ListPaths`, `GetBlob` (streamed), `ListCommits`, `GetCommit` (structured diff), `ResolveRevision` | | |
| 7 | + | | `TokenService` | `CreateToken` (secret shown once), `ListTokens`, `RevokeToken` | | |
| 8 | + | | `MergeRequestService` | `CreateMergeRequest`, `ListMergeRequests`, `GetMergeRequest` (commits, diff, comments), `AddComment`, `ResolveComment`, `CloseMergeRequest`, `MergeMergeRequest`, `MarkRead` | | |
| 9 | + | | `SessionService` | `CreateLoginLink`, `SignOutEverywhere` (owner only) | | |
| 10 | + | | `EventService` | `Watch` (streamed, resumable) | | |
| 11 | + | | `ServerService` | `GetVersion` (version and features), `GetSigningKey`, `RotateOIDCKey` (owner only) | | |
| 12 | + | | `RunService` | `ListRuns`, `GetRun`, `GetJob`, `GetJobLog` (streamed, follow), `ListAnnotations`, `GetStepSummaries`, `CancelRun`, `RerunRun`, `DispatchWorkflow`, `ListChecks`, `ListRunners`, `RemoveRunner` | | |
| 13 | + | | `RunnerService` | `RegisterRunner`, `FetchJob` (long poll), `UpdateJob`, `AppendLog` (offset-idempotent), `Heartbeat`, `WatchJob` (cancel requests, streamed), `CompleteJob` (idempotent), `ResolveActions`, `UploadSummary` | | |
| 14 | + | | `SecretService` | `SetSecret`, `ListSecrets` (names only), `DeleteSecret`. Scopes: instance, repository, environment | | |
| 15 | + | | `VariableService` | `SetVariable`, `GetVariable`, `ListVariables`, `DeleteVariable`. Same scopes | | |
| 16 | + | | `EnvironmentService` | `CreateEnvironment`, `ListEnvironments`, `DeleteEnvironment` | | |
| 17 | + | | `ArtifactService` | `ListArtifacts`, `DownloadArtifact` (streamed, resumable), `DeleteArtifact` | | |
| 18 | + | | `JobArtifactService` | `CreateJobArtifact`, `UploadJobArtifactBlock` (client stream), `CommitJobArtifact`, `FinalizeJobArtifact`, `ListJobArtifacts`, `DownloadJobArtifact` (streamed, resumable), `DeleteJobArtifact`. Scoped to the run of the job token | | |
| @@ -0,0 +1,18 @@ | |||||
| 1 | + | # Services | |||
| 2 | + | ||||
| 3 | + | | Service | RPCs | | |||
| 4 | + | |---|---| | |||
| 5 | + | | `RepoService` | `ListRepos`, `GetRepo`, `CreateRepo`, `UpdateRepo` (field mask, merge settings), `DeleteRepo` | | |||
| 6 | + | | `GitService` | `ListRefs`, `GetTree`, `ListPaths`, `GetBlob` (streamed), `ListCommits`, `GetCommit` (structured diff), `ResolveRevision` | | |||
| 7 | + | | `TokenService` | `CreateToken` (secret shown once), `ListTokens`, `RevokeToken` | | |||
| 8 | + | | `MergeRequestService` | `CreateMergeRequest`, `ListMergeRequests`, `GetMergeRequest` (commits, diff, comments), `AddComment`, `ResolveComment`, `CloseMergeRequest`, `MergeMergeRequest`, `MarkRead` | | |||
| 9 | + | | `SessionService` | `CreateLoginLink`, `SignOutEverywhere` (owner only) | | |||
| 10 | + | | `EventService` | `Watch` (streamed, resumable) | | |||
| 11 | + | | `ServerService` | `GetVersion` (version and features), `GetSigningKey`, `RotateOIDCKey` (owner only) | | |||
| 12 | + | | `RunService` | `ListRuns`, `GetRun`, `GetJob`, `GetJobLog` (streamed, follow), `ListAnnotations`, `GetStepSummaries`, `CancelRun`, `RerunRun`, `DispatchWorkflow`, `ListChecks`, `ListRunners`, `RemoveRunner` | | |||
| 13 | + | | `RunnerService` | `RegisterRunner`, `FetchJob` (long poll), `UpdateJob`, `AppendLog` (offset-idempotent), `Heartbeat`, `WatchJob` (cancel requests, streamed), `CompleteJob` (idempotent), `ResolveActions`, `UploadSummary` | | |||
| 14 | + | | `SecretService` | `SetSecret`, `ListSecrets` (names only), `DeleteSecret`. Scopes: instance, repository, environment | | |||
| 15 | + | | `VariableService` | `SetVariable`, `GetVariable`, `ListVariables`, `DeleteVariable`. Same scopes | | |||
| 16 | + | | `EnvironmentService` | `CreateEnvironment`, `ListEnvironments`, `DeleteEnvironment` | | |||
| 17 | + | | `ArtifactService` | `ListArtifacts`, `DownloadArtifact` (streamed, resumable), `DeleteArtifact` | | |||
| 18 | + | | `JobArtifactService` | `CreateJobArtifact`, `UploadJobArtifactBlock` (client stream), `CommitJobArtifact`, `FinalizeJobArtifact`, `ListJobArtifacts`, `DownloadJobArtifact` (streamed, resumable), `DeleteJobArtifact`. Scoped to the run of the job token | | |||