Skip to content
Sign up

flagon-io/g1t

public
0
1,462 linesCodeBlameRaw

Pick any line to see why it is the way it is: the commit, the pull request and issue it came from, and what the agent was thinking.

g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights1//! The OpenAPI document, generated from the same list the routes are.
2//!
3//! The docs site builds its API reference from a copy of this document,
4//! `apps/docs/src/data/openapi.json`. A test keeps the copy current: run
5//! `G1T_WRITE_OPENAPI=1 cargo test -p g1t-api openapi` to rewrite it.
6
7use g1t_contracts::scopes::scope_for;
8use serde_json::{Map, Value, json};
9
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb9710use crate::about::AboutOp;
The artifacts service is services/artifacts, the Worker g1t-artifacts, bound as ARTIFACTS by the API, the site and the agents; its live rooms move to it with a Durable Object transfer from g1t-docs-service, and its database, bucket, indexes and queue keep their names. The git store's binding and settings are GITSTORE, its ops scripts gitstore-*, and workflow run artifacts keep their compatible API under run_artifacts modules. The deploy tool puts a Worker that has never deployed before the Workers in its stage that bind to it, and the deploy guide gives the cutover runbook.11use crate::run_artifacts::ArtifactsOp;
Merge GitHub pull request #8 (claude/cool-newton-7nm8r9): Docker deployments on g1t.page behind a switch that stays off until Cloudflare's container APIs are checked live, workflows a workspace manages in its repositories, tarball and zipball downloads, refs/pull/* kept to g1t alone, framework detection for g1t.page builds, and a workflow's event payload matching GitHub's.12use crate::archives::ArchiveOp;
Merge remote-tracking branch 'origin/claude/cool-newton-7nm8r9' into claude/cool-newton-7nm8r913use crate::customize::CustomizeOp;
Merge branch 'worktree-agent-a5a5de74d8863d554' into worktree-agent-a16631325aecf58ca14use crate::deploy_keys::DeployKeysOp;
Merge branch 'mirroring' into artifacts-mode15use crate::mirrors::MirrorsOp;
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb9716use crate::deployments::DeploymentsOp;
Projects have Observability: their requests, logs, traces, metrics and errors, from apps on g1t.page with nothing to set up, and from software anywhere else over OpenTelemetry.17use crate::telemetry::TelemetryOp;
Merge packages: roles, Actions access, source label, soft delete, API18use crate::packages::PackagesOp;
Merge main into Artifacts Phase 219use crate::folios::FoliosOp;
Merge branch 'worktree-agent-a3abfcce648e87dca'20use crate::protection::ProtectionOp;
API and MCP for a workspace's personal access token rules, members' tokens and approvals21use crate::token_policy::TokenOp;
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights22use crate::operations::Op;
Merge checks: statuses and check runs on every commit23use crate::checks::ChecksOp;
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge24use crate::rules::RulesOp;
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar25use crate::security::SecurityOp;
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights26use crate::rest::{ROUTES, Route};
27
28/// The sections of the API reference: a name, what it covers, and its
29/// operations in the order a reader meets them.
30const SECTIONS: &[(&str, &str, &[Op])] = &[
31 (
32 "Accounts",
33 "Signing in from a tool, who a token acts as, and your email addresses.",
Merge email confirmation gate: a code and a link, nothing until confirmed (identity 0036)34 &[Op::Whoami, Op::ListEmails, Op::AddEmail, Op::ConfirmEmail, Op::RemoveEmail, Op::UpdateEmailSettings],
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights35 ),
36 (
API: notifications over REST and MCP, with notifications scopes37 "Notifications",
38 "Your inbox: a thread for each thing you were told about (an issue, a pull request, a workflow on a branch, a deployment), why you were told, and what you subscribe to and watch. Your own: personal tokens and sessions only.",
39 &[
40 Op::ListNotifications,
41 Op::MarkNotificationsRead,
42 Op::GetNotificationThread,
43 Op::MarkThreadRead,
44 Op::MarkThreadDone,
45 Op::SaveThread,
46 Op::SnoozeThread,
47 Op::GetThreadSubscription,
48 Op::SetThreadSubscription,
49 Op::DeleteThreadSubscription,
50 Op::GetRepoSubscription,
51 Op::SetRepoSubscription,
52 Op::DeleteRepoSubscription,
53 Op::ListWatchedRepos,
54 ],
55 ),
56 (
API: pinned projects over REST and MCP57 "Pinned projects",
58 "The projects you keep at the top of a workspace's sidebar, in your order, up to eight a workspace. Your own: personal tokens and sessions only.",
59 &[Op::ListPinnedProjects, Op::PinProject, Op::UnpinProject, Op::ReorderPinnedProjects],
60 ),
61 (
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb9762 "Projects",
63 "A project is what a workspace builds and runs, from a repository or a root directory in one. Each says what it is, where it runs and where to find it: its homepage, docs and other links.",
64 &[Op::ListProjects, Op::GetProject, Op::UpdateProject],
65 ),
66 (
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights67 "Workspaces",
68 "A workspace owns repositories and is the first part of their address. People and agents work in workspaces.",
Merge branch 'worktree-agent-ad7c6d88d93adc817'69 &[Op::GetWorkspace, Op::CreateWorkspace, Op::UpdateWorkspace, Op::DeleteWorkspace],
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights70 ),
71 (
API and MCP for a workspace's personal access token rules, members' tokens and approvals72 "Personal access tokens",
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers73 "A workspace's rules for its members' personal access tokens: whether tokens made for all of a member's workspaces reach it, whether tokens may be made for it alone and wait for an owner's approval, and how long a token may last; the tokens that reach it, approving or denying the ones that wait, and revoking one there. Owners only, as people.",
API and MCP for a workspace's personal access token rules, members' tokens and approvals74 &[
75 Op::Tokens(TokenOp::GetTokenPolicy),
76 Op::Tokens(TokenOp::SetTokenPolicy),
77 Op::Tokens(TokenOp::ListMemberTokens),
78 Op::Tokens(TokenOp::ListTokenRequests),
79 Op::Tokens(TokenOp::ReviewTokenRequest),
80 Op::Tokens(TokenOp::RevokeMemberToken),
81 ],
82 ),
83 (
Merge main (membership, two-factor, GitHub repo roles) into tokens84 "Members",
85 "A workspace's members and owners: who belongs to it, their roles (owner or member, with billing manager and security manager on top), handing it to another member, and leaving it.",
86 &[Op::ListMembers, Op::UpdateMember, Op::RemoveMember, Op::TransferOwnership, Op::LeaveWorkspace],
87 ),
88 (
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights89 "Invites",
Merge workspace invitations: nobody joins a workspace without saying yes, people are found by username, your own invites can bring someone in, and nobody is left without a workspace (identity 0040)90 "While g1t is invite-only, every new account needs an invite. Your invites, inviting people into a workspace by username or email, and answering the invitations to workspaces sent to you.",
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights91 &[
92 Op::ListInvites,
93 Op::CreateInvite,
94 Op::RevokeInvite,
95 Op::ListWorkspaceInvites,
96 Op::InviteMember,
97 Op::RevokeWorkspaceInvite,
Merge workspace invitations: nobody joins a workspace without saying yes, people are found by username, your own invites can bring someone in, and nobody is left without a workspace (identity 0040)98 Op::ListInvitations,
99 Op::AcceptInvitation,
100 Op::DeclineInvitation,
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights101 ],
102 ),
103 (
Usage, Billing settings and prepaid AI credit; fixes from the UX audit104 "Billing",
Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens105 "A workspace's usage, its budget, its AI credit, its invoices and its AI Gateway requests. Members read them; owners change the budget and buy credit, as people. g1t's agents never change billing.",
Usage, Billing settings and prepaid AI credit; fixes from the UX audit106 &[
107 Op::GetUsage,
108 Op::GetBudget,
109 Op::SetBudget,
110 Op::GetAiCredit,
111 Op::BuyAiCredit,
112 Op::ListInvoices,
113 Op::GetBillingDetails,
Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens114 Op::ListGatewayRequests,
Usage, Billing settings and prepaid AI credit; fixes from the UX audit115 ],
116 ),
117 (
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights118 "Repositories",
Merge GitHub pull request #8 (claude/cool-newton-7nm8r9): Docker deployments on g1t.page behind a switch that stays off until Cloudflare's container APIs are checked live, workflows a workspace manages in its repositories, tarball and zipball downloads, refs/pull/* kept to g1t alone, framework detection for g1t.page builds, and a workflow's event payload matching GitHub's.119 "A repository, how it handles pull requests, and its timeline: renaming, archiving, moving and deleting it; and its files at a branch, tag or commit as a tarball or zipball.",
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights120 &[
121 Op::ListRepos,
122 Op::CreateRepo,
123 Op::GetRepo,
Merge GitHub pull request #8 (claude/cool-newton-7nm8r9): Docker deployments on g1t.page behind a switch that stays off until Cloudflare's container APIs are checked live, workflows a workspace manages in its repositories, tarball and zipball downloads, refs/pull/* kept to g1t alone, framework detection for g1t.page builds, and a workflow's event payload matching GitHub's.124 Op::Archives(ArchiveOp::DownloadTarball),
125 Op::Archives(ArchiveOp::DownloadZipball),
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights126 Op::UpdateRepo,
127 Op::RenameRepo,
128 Op::RenameBranch,
The Branches page does things to branches now. It has tabs (Overview, Yours, Active, Stale, All, kept in the address as ?tab=) and search; Overview shows the default branch, then the first five of your branches, the active ones and the stale ones, each linking to the rest. Each branch is a row with its name in a code chip with a copy button, who made its latest commit and when, that commit's checks, behind and ahead counts with bars drawn against the largest shown, and its pull request (the open one, else the newest merged or closed) with its state; on a phone the columns fold under the name. Yours is branches whose latest commit is the viewer's; stale is no commit in 90 days.129 Op::CreateBranch,
130 Op::DeleteBranch,
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights131 Op::SetRepoVisibility,
132 Op::ArchiveRepo,
133 Op::UnarchiveRepo,
134 Op::TransferRepo,
135 Op::DeleteRepo,
136 Op::ListDeletedRepos,
137 Op::RestoreRepo,
138 Op::PurgeRepo,
139 Op::GetRepoSettings,
140 Op::UpdateRepoSettings,
141 Op::ListCheckNames,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar142 Op::GetCodeownersErrors,
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights143 Op::ListEvents,
144 ],
145 ),
146 (
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb97147 "Repository insights",
148 "What a repository's default branch says about it, read in the background and kept by commit: the languages it is written in, who made it, and its license.",
149 &[Op::About(AboutOp::GetLanguages), Op::About(AboutOp::ListContributors), Op::About(AboutOp::GetLicense)],
150 ),
151 (
152 "Stars",
153 "Starring a repository, to keep it and to say you like it: who starred one, and what you starred.",
154 &[
155 Op::About(AboutOp::ListStargazers),
156 Op::About(AboutOp::ListStarred),
157 Op::About(AboutOp::CheckStarred),
158 Op::About(AboutOp::Star),
159 Op::About(AboutOp::Unstar),
160 ],
161 ),
162 (
163 "Releases",
164 "A release is a tag published with a title and notes. The latest is the newest published one that is neither a draft nor a prerelease.",
165 &[
166 Op::About(AboutOp::ListReleases),
167 Op::About(AboutOp::CreateRelease),
168 Op::About(AboutOp::GetLatestRelease),
169 Op::About(AboutOp::GetReleaseByTag),
170 Op::About(AboutOp::GetRelease),
171 Op::About(AboutOp::UpdateRelease),
172 Op::About(AboutOp::DeleteRelease),
173 ],
174 ),
175 (
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights176 "Access",
Merge branch 'worktree-agent-a5a5de74d8863d554' into worktree-agent-a16631325aecf58ca177 "Who can do what in a repository: repository roles, people given a role on one repository (outside collaborators when they are not members), invitations, a workspace's base permission, and deploy keys: SSH keys that reach one repository.",
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights178 &[
179 Op::ListCollaborators,
180 Op::AddCollaborator,
181 Op::UpdateCollaborator,
182 Op::RemoveCollaborator,
183 Op::GetCollaboratorPermission,
184 Op::ListRepoInvitations,
185 Op::RevokeRepoInvitation,
186 Op::ListMyRepoInvitations,
187 Op::AcceptRepoInvitation,
188 Op::DeclineRepoInvitation,
189 Op::SetBasePermission,
190 Op::ListOutsideCollaborators,
Merge branch 'worktree-agent-a5a5de74d8863d554' into worktree-agent-a16631325aecf58ca191 Op::DeployKeys(DeployKeysOp::ListDeployKeys),
192 Op::DeployKeys(DeployKeysOp::GetDeployKey),
193 Op::DeployKeys(DeployKeysOp::CreateDeployKey),
194 Op::DeployKeys(DeployKeysOp::DeleteDeployKey),
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights195 ],
196 ),
197 (
Merge branch 'mirroring' into artifacts-mode198 "Mirroring",
199 "A repository's links to copies of it on other hosts: a mirror stands by as a read-only copy of a remote that leads, until someone takes over on g1t and later hands back, or moves it to g1t for good. A repository g1t leads can be mirrored to other hosts.",
200 &[
201 Op::Mirrors(MirrorsOp::GetMirror),
202 Op::Mirrors(MirrorsOp::GetHandBackPlan),
203 Op::Mirrors(MirrorsOp::TakeOver),
204 Op::Mirrors(MirrorsOp::SetCiFailover),
205 Op::Mirrors(MirrorsOp::HandBack),
206 Op::Mirrors(MirrorsOp::MoveToG1t),
207 Op::Mirrors(MirrorsOp::SyncMirror),
208 Op::Mirrors(MirrorsOp::AddRemote),
209 Op::Mirrors(MirrorsOp::UpdateRemote),
210 Op::Mirrors(MirrorsOp::RemoveRemote),
211 ],
212 ),
213 (
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar214 "Teams",
215 "Groups of a workspace's members: given a role on repositories together, mentioned together as @workspace/team, and asked to review together. Any member may create a team; the workspace's owners and the team's maintainers manage it.",
216 &[
217 Op::ListTeams,
218 Op::CreateTeam,
219 Op::GetTeam,
220 Op::UpdateTeam,
221 Op::DeleteTeam,
222 Op::ListTeamMembers,
223 Op::SetTeamMember,
224 Op::RemoveTeamMember,
225 Op::ListChildTeams,
226 Op::ListTeamRepos,
227 Op::SetTeamRepo,
228 Op::RemoveTeamRepo,
229 Op::SetTeamReviewAssignment,
230 Op::ListUserTeams,
231 ],
232 ),
233 (
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights234 "Security",
235 "Secrets found in what is pushed and in a repository's history, and dependencies with known vulnerabilities: listing the alerts, and dismissing or reopening them.",
236 &[Op::ListSecurityAlerts, Op::DismissSecurityAlert, Op::ReopenSecurityAlert],
237 ),
238 (
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar239 "Secret scanning",
240 "Secrets found in pushes and history, where each one is, pushing past push protection with a reason (and asking for approval when the workspace delegates bypasses), checking with a secret's issuer whether it still works, and custom patterns.",
241 &[
242 Op::Security(SecurityOp::ListSecretAlerts),
243 Op::Security(SecurityOp::GetSecretAlert),
244 Op::Security(SecurityOp::UpdateSecretAlert),
245 Op::Security(SecurityOp::ListSecretLocations),
246 Op::Security(SecurityOp::BypassPushProtection),
247 Op::Security(SecurityOp::CheckSecretValidity),
248 Op::Security(SecurityOp::ListBypassRequests),
249 Op::Security(SecurityOp::ReviewBypassRequest),
250 Op::Security(SecurityOp::ListCustomPatterns),
251 Op::Security(SecurityOp::CreateCustomPattern),
252 Op::Security(SecurityOp::UpdateCustomPattern),
253 Op::Security(SecurityOp::DeleteCustomPattern),
254 Op::Security(SecurityOp::DryRunCustomPattern),
255 ],
256 ),
257 (
258 "Code scanning",
259 "Results of static analysis tools, uploaded as SARIF: alerts on the default branch, the analyses that made them, uploads, and putting g1t on an alert to fix it.",
260 &[
261 Op::Security(SecurityOp::ListCodeAlerts),
262 Op::Security(SecurityOp::GetCodeAlert),
263 Op::Security(SecurityOp::UpdateCodeAlert),
264 Op::Security(SecurityOp::ListAnalyses),
265 Op::Security(SecurityOp::UploadSarif),
266 Op::Security(SecurityOp::GetSarifUpload),
267 Op::Security(SecurityOp::FixAlert),
268 ],
269 ),
270 (
271 "Supply chain",
272 "What a repository depends on: vulnerability alerts, the dependency graph, an SPDX SBOM of it, and comparing two commits' dependencies as dependency review does.",
273 &[
274 Op::Security(SecurityOp::ListVulnerabilityAlerts),
275 Op::Security(SecurityOp::GetVulnerabilityAlert),
276 Op::Security(SecurityOp::UpdateVulnerabilityAlert),
277 Op::Security(SecurityOp::GetDependencyGraph),
278 Op::Security(SecurityOp::GetSbom),
279 Op::Security(SecurityOp::CompareDependencies),
280 ],
281 ),
282 (
283 "Security settings",
284 "When pull request checks fail, dependency review's policy, delegated bypass and validity checks, and a workspace's security overview.",
285 &[
286 Op::Security(SecurityOp::GetSettings),
287 Op::Security(SecurityOp::UpdateSettings),
288 Op::Security(SecurityOp::GetWorkspaceSettings),
289 Op::Security(SecurityOp::UpdateWorkspaceSettings),
290 Op::Security(SecurityOp::GetOverview),
291 ],
292 ),
293 (
Merge remote-tracking branch 'origin/claude/cool-newton-7nm8r9' into claude/cool-newton-7nm8r9294 "Security advisories",
295 "What a repository says about vulnerabilities in what it ships: advisories drafted, published and withdrawn by its maintainers, and the vulnerability reports people send them privately when the repository takes them.",
296 &[
297 Op::Security(SecurityOp::ListAdvisories),
298 Op::Security(SecurityOp::CreateAdvisory),
299 Op::Security(SecurityOp::GetAdvisory),
300 Op::Security(SecurityOp::UpdateAdvisory),
301 Op::Security(SecurityOp::SetAdvisoryState),
302 Op::Security(SecurityOp::ListReports),
303 Op::Security(SecurityOp::ReportVulnerability),
304 Op::Security(SecurityOp::ReviewReport),
305 ],
306 ),
307 (
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge308 "Rules",
309 "Rulesets: what may happen to a repository's branches and tags and what a pull request needs before it merges, for a repository or across a workspace; the rules that hold for one branch; and how they judged each push and merge, with insights.",
310 &[
311 Op::Rules(RulesOp::ListRepoRulesets),
312 Op::Rules(RulesOp::CreateRepoRuleset),
313 Op::Rules(RulesOp::GetRepoRuleset),
314 Op::Rules(RulesOp::UpdateRepoRuleset),
315 Op::Rules(RulesOp::DeleteRepoRuleset),
316 Op::Rules(RulesOp::GetBranchRules),
317 Op::Rules(RulesOp::ListRuleEvaluations),
318 Op::Rules(RulesOp::ListWorkspaceRulesets),
319 Op::Rules(RulesOp::CreateWorkspaceRuleset),
320 Op::Rules(RulesOp::GetWorkspaceRuleset),
321 Op::Rules(RulesOp::UpdateWorkspaceRuleset),
322 Op::Rules(RulesOp::DeleteWorkspaceRuleset),
323 Op::Rules(RulesOp::ListWorkspaceRuleEvaluations),
324 ],
325 ),
326 (
Merge checks: statuses and check runs on every commit327 "Checks",
328 "What CI, integrations and g1t Actions say about a commit, in the shapes CI tools already send: statuses (a state per context) and check runs (a lifecycle, a conclusion, a Markdown report, annotations on lines and buttons), grouped per reporter into check suites. g1t Actions jobs are check runs too. Required checks are met by either.",
329 &[
330 Op::Checks(ChecksOp::CreateCommitStatus),
331 Op::Checks(ChecksOp::ListCommitStatuses),
332 Op::Checks(ChecksOp::GetCombinedStatus),
333 Op::Checks(ChecksOp::CreateCheckRun),
334 Op::Checks(ChecksOp::UpdateCheckRun),
335 Op::Checks(ChecksOp::GetCheckRun),
336 Op::Checks(ChecksOp::ListCheckRunAnnotations),
337 Op::Checks(ChecksOp::RerequestCheckRun),
338 Op::Checks(ChecksOp::ListCheckRunsForRef),
339 Op::Checks(ChecksOp::ListCheckSuitesForRef),
340 Op::Checks(ChecksOp::GetCheckSuite),
341 Op::Checks(ChecksOp::RerequestCheckSuite),
342 ],
343 ),
344 (
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights345 "Issues",
346 "What should change in a repository, with labels and comments. Issues and pull requests share one sequence of numbers.",
347 &[
348 Op::ListIssues,
349 Op::CreateIssue,
350 Op::GetIssue,
351 Op::UpdateIssue,
352 Op::CloseIssue,
353 Op::ReopenIssue,
354 Op::AssignIssue,
355 Op::Delegate,
356 Op::AddComment,
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts357 Op::EditComment,
358 Op::DeleteComment,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar359 Op::ListIssueLabels,
360 Op::AddIssueLabels,
361 Op::SetIssueLabels,
362 Op::RemoveIssueLabels,
363 ],
364 ),
365 (
366 "Labels and milestones",
367 "A repository's labels, which issues and pull requests carry by name, and its milestones, which gather them under a goal and a due date.",
368 &[
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights369 Op::ListLabels,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar370 Op::CreateLabel,
371 Op::UpdateLabel,
372 Op::DeleteLabel,
373 Op::AddDefaultLabels,
374 Op::ListMilestones,
375 Op::CreateMilestone,
376 Op::GetMilestone,
377 Op::UpdateMilestone,
378 Op::DeleteMilestone,
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights379 ],
380 ),
381 (
382 "Plans",
383 "An outcome turned into the issues that would get there, with the order they must merge in.",
384 &[Op::PlanWork, Op::GetPlan, Op::ApplyPlan],
385 ),
386 (
387 "Pull requests",
388 "A proposed change in its own fork or on a branch. Several can be made for one issue; the one merged resolves it.",
389 &[
390 Op::ListPullRequests,
391 Op::CreatePullRequest,
392 Op::GetPullRequest,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar393 Op::UpdatePullRequest,
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights394 Op::GetPullRequestChanges,
395 Op::MarkPullRequestReady,
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts396 Op::ConvertPullRequestToDraft,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar397 Op::RequestReviewers,
398 Op::RemoveRequestedReviewers,
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights399 Op::ReviewPullRequest,
400 Op::MergePullRequest,
401 Op::ClosePullRequest,
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts402 Op::ReopenPullRequest,
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights403 Op::GetMergeQueue,
404 Op::MessageAgent,
405 Op::AnswerMessage,
406 Op::TakeMessages,
407 ],
408 ),
409 (
410 "Sessions",
411 "The record of how a pull request was made: prompts, reasoning and the tools that ran.",
412 &[Op::ReadSession, Op::RecordSession],
413 ),
414 (
415 "Memory",
416 "What agents and people learned that the next agent should know, for one project or across a workspace. Members and g1t's agents only; never a secret.",
417 &[Op::Remember, Op::Recall],
418 ),
419 (
420 "Search",
421 "One search across all of g1t: repositories, code, issues, pull requests, people and workspaces. Public content for everyone, and private content in workspaces you belong to.",
422 &[Op::Search],
423 ),
424 (
425 "Context",
426 "A workspace's context hub: a catalog of what it builds and runs, built from its repositories, deployments and integrations, and one search across the catalog, docs, issues, pull requests and memory.",
427 &[Op::SearchContext, Op::GetEntity],
428 ),
429 (
430 "Actions",
431 "GitHub Actions workflows in .g1t/workflows, their runs, and their jobs' logs.",
432 &[
433 Op::ListWorkflows,
434 Op::ListWorkflowRuns,
435 Op::GetWorkflowRun,
436 Op::GetJobLogs,
437 Op::DispatchWorkflow,
438 Op::CancelWorkflowRun,
439 Op::RerunWorkflowRun,
440 Op::UpdateWorkflow,
Actions: OIDC tokens, the toolkit's cache and artifact services, and artifacts in R2441 Op::Artifacts(ArtifactsOp::ListArtifacts),
442 Op::Artifacts(ArtifactsOp::ListRunArtifacts),
443 Op::Artifacts(ArtifactsOp::GetArtifact),
444 Op::Artifacts(ArtifactsOp::DownloadArtifact),
445 Op::Artifacts(ArtifactsOp::DeleteArtifact),
446 Op::Artifacts(ArtifactsOp::GetArtifactRetention),
447 Op::Artifacts(ArtifactsOp::SetArtifactRetention),
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights448 ],
449 ),
450 (
Merge packages: roles, Actions access, source label, soft delete, API451 "Packages",
452 "A workspace's packages in every registry: their versions and download counts, deleting and restoring them within 30 days, their visibility and repository, the people and teams with a role on them, and which repositories' workflows may use them (Manage Actions access). A package is named by its type and its name, URL-encoded where it holds a slash.",
453 &[
454 Op::Packages(PackagesOp::ListPackages),
455 Op::Packages(PackagesOp::GetPackage),
456 Op::Packages(PackagesOp::UpdatePackage),
457 Op::Packages(PackagesOp::DeletePackage),
458 Op::Packages(PackagesOp::RestorePackage),
459 Op::Packages(PackagesOp::ListVersions),
460 Op::Packages(PackagesOp::GetVersion),
461 Op::Packages(PackagesOp::DeleteVersion),
462 Op::Packages(PackagesOp::RestoreVersion),
463 Op::Packages(PackagesOp::LinkPackage),
464 Op::Packages(PackagesOp::UnlinkPackage),
465 Op::Packages(PackagesOp::ListAccess),
466 Op::Packages(PackagesOp::SetAccess),
467 Op::Packages(PackagesOp::RemoveAccess),
468 Op::Packages(PackagesOp::ListActionsAccess),
469 Op::Packages(PackagesOp::SetActionsAccess),
470 Op::Packages(PackagesOp::RemoveActionsAccess),
471 ],
472 ),
473 (
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb97474 "Deployments",
475 "A repository's deployments wherever they run: reported from any CI with these routes, made by g1t Actions jobs with an `environment:`, or built on g1t.page. Each has statuses, shows on its commit as the check `deploy / <environment>`, and belongs to an environment.",
476 &[
477 Op::Deployments(DeploymentsOp::ListDeployments),
478 Op::Deployments(DeploymentsOp::CreateDeployment),
479 Op::Deployments(DeploymentsOp::GetDeployment),
480 Op::Deployments(DeploymentsOp::ListDeploymentStatuses),
481 Op::Deployments(DeploymentsOp::CreateDeploymentStatus),
482 Op::Deployments(DeploymentsOp::ListEnvironments),
483 Op::Deployments(DeploymentsOp::GetEnvironment),
Merge branch 'worktree-agent-a4d35ee70c50683d0' into claude/cool-newton-7nm8r9484 Op::Deployments(DeploymentsOp::StartDeploymentBuild),
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb97485 ],
486 ),
487 (
Projects have Observability: their requests, logs, traces, metrics and errors, from apps on g1t.page with nothing to set up, and from software anywhere else over OpenTelemetry.488 "Observability",
489 "What a project's running software did: its requests, logs, traces, grouped errors and metrics, from its apps on g1t.page with nothing to set up and from OpenTelemetry (OTLP over HTTP) sent from anywhere with an ingest token. Reading needs a role of your own on the project's repository; resolving errors, Triage; settings, ingest tokens, exports and usage, Admin.",
490 &[
491 Op::Telemetry(TelemetryOp::GetOverview),
492 Op::Telemetry(TelemetryOp::ListRequests),
493 Op::Telemetry(TelemetryOp::GetRequest),
494 Op::Telemetry(TelemetryOp::ListLogs),
495 Op::Telemetry(TelemetryOp::ListTraces),
496 Op::Telemetry(TelemetryOp::GetTrace),
497 Op::Telemetry(TelemetryOp::ListErrors),
498 Op::Telemetry(TelemetryOp::UpdateError),
499 Op::Telemetry(TelemetryOp::ListMetrics),
500 Op::Telemetry(TelemetryOp::GetMetric),
501 Op::Telemetry(TelemetryOp::GetSettings),
502 Op::Telemetry(TelemetryOp::UpdateSettings),
503 Op::Telemetry(TelemetryOp::ListTokens),
504 Op::Telemetry(TelemetryOp::CreateToken),
505 Op::Telemetry(TelemetryOp::DeleteToken),
506 Op::Telemetry(TelemetryOp::ListExports),
507 Op::Telemetry(TelemetryOp::CreateExport),
508 Op::Telemetry(TelemetryOp::UpdateExport),
509 Op::Telemetry(TelemetryOp::DeleteExport),
510 Op::Telemetry(TelemetryOp::GetUsage),
511 ],
512 ),
513 (
Merge branch 'worktree-agent-a3abfcce648e87dca'514 "Run protection",
515 "What keeps workflow runs safe: environments' protection rules (required reviewers, a wait timer, which branches may deploy) and the reviews of the jobs they hold, approving a pull request's run from outside, what a job's token gets when its workflow writes no `permissions:`, and repository_dispatch, which a job's own token may send.",
516 &[
517 Op::Protection(ProtectionOp::UpdateEnvironment),
518 Op::Protection(ProtectionOp::DeleteEnvironment),
519 Op::Protection(ProtectionOp::GetPendingDeployments),
520 Op::Protection(ProtectionOp::ReviewPendingDeployments),
521 Op::Protection(ProtectionOp::ApproveWorkflowRun),
522 Op::Protection(ProtectionOp::GetWorkflowPermissions),
523 Op::Protection(ProtectionOp::SetWorkflowPermissions),
524 Op::Protection(ProtectionOp::GetForkPrApproval),
525 Op::Protection(ProtectionOp::SetForkPrApproval),
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts526 Op::Protection(ProtectionOp::GetActionsAccess),
527 Op::Protection(ProtectionOp::SetActionsAccess),
Merge branch 'worktree-agent-a3abfcce648e87dca'528 Op::Protection(ProtectionOp::CreateRepositoryDispatch),
529 Op::Protection(ProtectionOp::GetWorkspaceWorkflowPermissions),
530 Op::Protection(ProtectionOp::SetWorkspaceWorkflowPermissions),
Merge GitHub pull request #8 (claude/cool-newton-7nm8r9): Docker deployments on g1t.page behind a switch that stays off until Cloudflare's container APIs are checked live, workflows a workspace manages in its repositories, tarball and zipball downloads, refs/pull/* kept to g1t alone, framework detection for g1t.page builds, and a workflow's event payload matching GitHub's.531 Op::Protection(ProtectionOp::ListWorkspaceManagedWorkflows),
532 Op::Protection(ProtectionOp::CreateWorkspaceManagedWorkflow),
533 Op::Protection(ProtectionOp::UpdateWorkspaceManagedWorkflow),
534 Op::Protection(ProtectionOp::DeleteWorkspaceManagedWorkflow),
Merge branch 'worktree-agent-a3abfcce648e87dca'535 ],
536 ),
537 (
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights538 "Secrets and variables",
539 "Values that workflows and deployments read, per repository or for a whole workspace, with a row per environment.",
540 &[
541 Op::ListActionsSecrets,
542 Op::SetActionsSecret,
543 Op::DeleteActionsSecret,
544 Op::ListActionsVariables,
545 Op::SetActionsVariable,
546 Op::DeleteActionsVariable,
547 ],
548 ),
549 (
550 "Runners",
551 "Self-hosted runners: your own machines, which run your workflow jobs (and, if you choose, your agents' work) for $0 of g1t compute. They register with a short-lived token and only ever connect out.",
552 &[
553 Op::ListRunners,
554 Op::CreateRunnerRegistrationToken,
555 Op::RemoveRunner,
556 Op::ListRunnerGroups,
557 Op::CreateRunnerGroup,
558 Op::UpdateRunnerGroup,
559 Op::DeleteRunnerGroup,
560 Op::GetRunnerSettings,
561 Op::UpdateRunnerSettings,
562 ],
563 ),
564 (
Every agent can have its own computer. A session that needs one wakes it: a home of its own on g1t cloud, one per agent and never shared, where it runs commands, reads and writes files and keeps what it made, with each session working in its own folder under a shared home; after ten idle minutes it sleeps, its home kept as a snapshot and restored when it wakes, and Reset wipes the home while memory and artifacts stay. Its shell and files are abilities with the usual choices, Alone, Alone when asked, Ask first or Never, offered only inside sessions and never to a chat reply; every command shows on the session with its output, and the agent's new Computer tab shows the state, the disk used of the five gigabytes included, the recent commands, and Wake, Put to sleep and Reset. Machine time counts only while it is awake, on the sandbox lines of the ledger that name the agent and who asked, held to the same spend caps as the session; the disk itself costs nothing in this version. The runner gained a long-lived supervisor that answers the computer's requests inside the container, and the runner service a computer per agent that keeps its snapshot in the agent homes bucket when one is attached, and says so when none is. The REST API and the agent tool can read a computer, wake it, put it to sleep and reset it. The agents, abilities, sessions, runners, billing and deploy guides say how it works and what an operator sets up; pinning a computer to your own runner, its browser and take-over come next.565 "Agents' computers",
566 "Each workspace agent has a computer of its own on g1t cloud: a persistent home its sessions run commands on, which sleeps when idle and is saved as it was. Its state and recent commands, and waking, sleeping and resetting it.",
567 &[
568 Op::GetAgentComputer,
569 Op::WakeAgentComputer,
570 Op::SleepAgentComputer,
571 Op::ResetAgentComputer,
572 Op::ListAgentComputerCommands,
573 ],
574 ),
575 (
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights576 "Webhooks",
577 "Signed HTTPS requests sent to your own address as things happen, for a repository or a whole workspace.",
578 &[
579 Op::ListWebhooks,
580 Op::CreateWebhook,
581 Op::UpdateWebhook,
582 Op::DeleteWebhook,
583 Op::PingWebhook,
584 Op::ListWebhookDeliveries,
585 Op::RedeliverWebhook,
586 ],
587 ),
588 (
589 "Integrations",
590 "A workspace's connections to outside systems: model providers, alert sources and issue trackers.",
591 &[
592 Op::ListIntegrations,
593 Op::ConnectIntegration,
AI Gateway: OpenAI's format, open models, and your own providers594 Op::UpdateIntegration,
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights595 Op::DisconnectIntegration,
596 Op::TestIntegration,
597 Op::GetModelRoutes,
598 Op::SetModelRoutes,
599 Op::GetContext,
600 Op::ImportIssue,
601 ],
602 ),
Merge main into Artifacts Phase 2603 (
Merge remote-tracking branch 'origin/claude/cool-newton-7nm8r9' into claude/cool-newton-7nm8r9604 "Customize",
605 "What shapes how a workspace's agents work, in the formats Claude Code reads: the marketplaces it reads plugins from, what Discover lists, the plugins it installed (their skills, subagents and remote MCP servers reach g1t's agents; the rest reaches Claude Code on a runner), and its connectors: MCP servers connected once, then given to every agent, a team or one agent. The bundle is what a job's Claude Code loads on a runner.",
606 &[
607 Op::Customize(CustomizeOp::ListMarketplaces),
608 Op::Customize(CustomizeOp::AddMarketplace),
609 Op::Customize(CustomizeOp::RemoveMarketplace),
610 Op::Customize(CustomizeOp::RefreshMarketplace),
611 Op::Customize(CustomizeOp::Discover),
612 Op::Customize(CustomizeOp::ListPlugins),
613 Op::Customize(CustomizeOp::GetPlugin),
614 Op::Customize(CustomizeOp::InstallPlugin),
615 Op::Customize(CustomizeOp::SetPluginEnabled),
616 Op::Customize(CustomizeOp::UninstallPlugin),
617 Op::Customize(CustomizeOp::UpdatePlugin),
618 Op::Customize(CustomizeOp::ListPluginAgents),
619 Op::Customize(CustomizeOp::ListConnectors),
620 Op::Customize(CustomizeOp::GetConnector),
621 Op::Customize(CustomizeOp::AddConnector),
622 Op::Customize(CustomizeOp::SetConnectorKey),
623 Op::Customize(CustomizeOp::RemoveConnector),
624 Op::Customize(CustomizeOp::RefreshConnector),
625 Op::Customize(CustomizeOp::GrantConnector),
626 Op::Customize(CustomizeOp::RevokeConnector),
627 Op::Customize(CustomizeOp::Bundle),
628 ],
629 ),
630 (
Merge main into Artifacts Phase 2631 "Artifacts",
632 "A workspace's docs, slides, designs and dashboards (Artifacts mode): listing and searching the ones you can open, reading and editing their content in Markdown, making, moving, trashing and restoring them, their versions, and who can open them. Each answers for your own role on it. Not workflow runs' artifacts, which are under Actions. Slides, designs and dashboards answer that they are not here yet.",
633 &[
634 Op::Folios(FoliosOp::List),
635 Op::Folios(FoliosOp::Search),
636 Op::Folios(FoliosOp::Get),
637 Op::Folios(FoliosOp::GetContent),
638 Op::Folios(FoliosOp::ListVersions),
639 Op::Folios(FoliosOp::GetAccess),
640 Op::Folios(FoliosOp::ListTemplates),
641 Op::Folios(FoliosOp::ListSpaces),
642 Op::Folios(FoliosOp::QueryDataset),
643 Op::Folios(FoliosOp::Create),
644 Op::Folios(FoliosOp::Update),
645 Op::Folios(FoliosOp::Edit),
646 Op::Folios(FoliosOp::Trash),
647 Op::Folios(FoliosOp::Restore),
648 Op::Folios(FoliosOp::RestoreVersion),
649 Op::Folios(FoliosOp::SetAccess),
650 Op::Folios(FoliosOp::Purge),
651 ],
652 ),
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights653];
654
655/// The section of the API reference an operation is listed under.
656fn tag(op: Op) -> &'static str {
657 SECTIONS
658 .iter()
659 .find(|(_, _, ops)| ops.contains(&op))
660 .map_or("Repositories", |(name, _, _)| name)
661}
662
663/// What an operation's page is called, as a short sentence.
664fn title(op: Op) -> &'static str {
665 match op {
666 Op::Whoami => "Get the current user",
Merge branch 'worktree-agent-ad7c6d88d93adc817'667 Op::GetWorkspace => "Get a workspace",
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights668 Op::CreateWorkspace => "Create a workspace",
669 Op::DeleteWorkspace => "Delete a workspace",
670 Op::UpdateWorkspace => "Update a workspace",
Merge main (membership, two-factor, GitHub repo roles) into tokens671 Op::ListMembers => "List a workspace's members",
672 Op::UpdateMember => "Change a member's role",
673 Op::RemoveMember => "Remove a member",
674 Op::TransferOwnership => "Transfer a workspace's ownership",
675 Op::LeaveWorkspace => "Leave a workspace",
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights676 Op::ListEmails => "List your email addresses",
677 Op::AddEmail => "Add an email address",
Merge email confirmation gate: a code and a link, nothing until confirmed (identity 0036)678 Op::ConfirmEmail => "Confirm an email address",
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights679 Op::RemoveEmail => "Remove an email address",
680 Op::UpdateEmailSettings => "Change your email settings",
681 Op::ListInvites => "List your invites",
682 Op::CreateInvite => "Create an invite",
683 Op::RevokeInvite => "Revoke an invite",
684 Op::ListWorkspaceInvites => "List a workspace's invites",
685 Op::InviteMember => "Invite someone to a workspace",
Merge workspace invitations: nobody joins a workspace without saying yes, people are found by username, your own invites can bring someone in, and nobody is left without a workspace (identity 0040)686 Op::ListInvitations => "List your workspace invitations",
687 Op::AcceptInvitation => "Accept a workspace invitation",
688 Op::DeclineInvitation => "Decline a workspace invitation",
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights689 Op::RevokeWorkspaceInvite => "Revoke a workspace's invite",
690 Op::TransferRepo => "Transfer a repository",
691 Op::RenameRepo => "Rename a repository",
692 Op::RenameBranch => "Rename a branch",
The Branches page does things to branches now. It has tabs (Overview, Yours, Active, Stale, All, kept in the address as ?tab=) and search; Overview shows the default branch, then the first five of your branches, the active ones and the stale ones, each linking to the rest. Each branch is a row with its name in a code chip with a copy button, who made its latest commit and when, that commit's checks, behind and ahead counts with bars drawn against the largest shown, and its pull request (the open one, else the newest merged or closed) with its state; on a phone the columns fold under the name. Yours is branches whose latest commit is the viewer's; stale is no commit in 90 days.693 Op::CreateBranch => "Create a branch",
694 Op::DeleteBranch => "Delete a branch",
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights695 Op::ArchiveRepo => "Archive a repository",
696 Op::UnarchiveRepo => "Unarchive a repository",
697 Op::SetRepoVisibility => "Change a repository's visibility",
698 Op::DeleteRepo => "Delete a repository",
699 Op::ListDeletedRepos => "List recently deleted repositories",
700 Op::RestoreRepo => "Restore a deleted repository",
701 Op::PurgeRepo => "Purge a deleted repository",
702 Op::ListRepos => "List repositories",
703 Op::GetRepo => "Get a repository",
704 Op::CreateRepo => "Create a repository",
705 Op::UpdateRepo => "Update a repository",
706 Op::GetRepoSettings => "Get repository settings",
707 Op::UpdateRepoSettings => "Update repository settings",
708 Op::ListCheckNames => "List check names",
709 Op::GetMergeQueue => "Get the merge queue",
710 Op::MessageAgent => "Message an agent",
711 Op::AnswerMessage => "Answer a message",
712 Op::TakeMessages => "Take new messages",
713 Op::Remember => "Remember something",
714 Op::Recall => "Recall memory",
715 Op::SearchContext => "Search the context hub",
716 Op::GetEntity => "Get a catalog entry",
717 Op::Search => "Search g1t",
718 Op::ListIssues => "List issues",
719 Op::GetIssue => "Get an issue",
720 Op::CreateIssue => "Create an issue",
721 Op::UpdateIssue => "Update an issue",
722 Op::CloseIssue => "Close an issue",
723 Op::ReopenIssue => "Reopen an issue",
724 Op::AssignIssue => "Assign an issue to g1t",
725 Op::Delegate => "Put an agent on it",
726 Op::PlanWork => "Plan work",
727 Op::GetPlan => "Get a plan",
728 Op::ApplyPlan => "Apply a plan",
729 Op::ListLabels => "List labels",
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar730 Op::CreateLabel => "Create a label",
731 Op::UpdateLabel => "Update a label",
732 Op::DeleteLabel => "Delete a label",
733 Op::AddDefaultLabels => "Add the default labels",
734 Op::ListIssueLabels => "List an issue's labels",
735 Op::AddIssueLabels => "Add labels to an issue",
736 Op::SetIssueLabels => "Set an issue's labels",
737 Op::RemoveIssueLabels => "Remove labels from an issue",
738 Op::ListMilestones => "List milestones",
739 Op::GetMilestone => "Get a milestone",
740 Op::CreateMilestone => "Create a milestone",
741 Op::UpdateMilestone => "Update a milestone",
742 Op::DeleteMilestone => "Delete a milestone",
743 Op::UpdatePullRequest => "Update a pull request",
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights744 Op::AddComment => "Add a comment",
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts745 Op::EditComment => "Edit a comment",
746 Op::DeleteComment => "Delete a comment",
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights747 Op::ReviewPullRequest => "Review a pull request",
748 Op::ListPullRequests => "List pull requests",
749 Op::GetPullRequest => "Get a pull request",
750 Op::CreatePullRequest => "Create a pull request",
751 Op::RecordSession => "Record session entries",
752 Op::ReadSession => "Read a session",
753 Op::MarkPullRequestReady => "Mark a pull request ready",
754 Op::ClosePullRequest => "Close a pull request",
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts755 Op::ReopenPullRequest => "Reopen a pull request",
756 Op::ConvertPullRequestToDraft => "Convert a pull request to a draft",
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights757 Op::GetPullRequestChanges => "Get a pull request's changes",
758 Op::MergePullRequest => "Merge a pull request",
759 Op::ListEvents => "List repository events",
760 Op::ListIntegrations => "List integrations",
761 Op::ConnectIntegration => "Connect an integration",
AI Gateway: OpenAI's format, open models, and your own providers762 Op::UpdateIntegration => "Update an integration",
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights763 Op::DisconnectIntegration => "Disconnect an integration",
764 Op::TestIntegration => "Test an integration",
765 Op::GetContext => "Look up a ticket",
766 Op::ImportIssue => "Import an issue",
767 Op::GetModelRoutes => "Get model routes",
768 Op::SetModelRoutes => "Set model routes",
769 Op::ListWebhooks => "List webhooks",
770 Op::CreateWebhook => "Create a webhook",
771 Op::UpdateWebhook => "Update a webhook",
772 Op::DeleteWebhook => "Delete a webhook",
773 Op::PingWebhook => "Ping a webhook",
774 Op::ListWebhookDeliveries => "List webhook deliveries",
775 Op::RedeliverWebhook => "Redeliver a webhook delivery",
776 Op::ListWorkflows => "List workflows",
777 Op::ListWorkflowRuns => "List workflow runs",
778 Op::GetWorkflowRun => "Get a workflow run",
779 Op::GetJobLogs => "Get a job's log",
780 Op::DispatchWorkflow => "Run a workflow",
781 Op::CancelWorkflowRun => "Cancel a workflow run",
782 Op::RerunWorkflowRun => "Re-run a workflow run",
783 Op::UpdateWorkflow => "Turn a workflow on or off",
784 Op::ListActionsSecrets => "List secrets",
785 Op::SetActionsSecret => "Set a secret",
786 Op::DeleteActionsSecret => "Delete a secret",
787 Op::ListActionsVariables => "List variables",
788 Op::SetActionsVariable => "Set a variable",
789 Op::DeleteActionsVariable => "Delete a variable",
790 Op::ListRunners => "List self-hosted runners",
791 Op::ListRunnerGroups => "List runner groups",
Every agent can have its own computer. A session that needs one wakes it: a home of its own on g1t cloud, one per agent and never shared, where it runs commands, reads and writes files and keeps what it made, with each session working in its own folder under a shared home; after ten idle minutes it sleeps, its home kept as a snapshot and restored when it wakes, and Reset wipes the home while memory and artifacts stay. Its shell and files are abilities with the usual choices, Alone, Alone when asked, Ask first or Never, offered only inside sessions and never to a chat reply; every command shows on the session with its output, and the agent's new Computer tab shows the state, the disk used of the five gigabytes included, the recent commands, and Wake, Put to sleep and Reset. Machine time counts only while it is awake, on the sandbox lines of the ledger that name the agent and who asked, held to the same spend caps as the session; the disk itself costs nothing in this version. The runner gained a long-lived supervisor that answers the computer's requests inside the container, and the runner service a computer per agent that keeps its snapshot in the agent homes bucket when one is attached, and says so when none is. The REST API and the agent tool can read a computer, wake it, put it to sleep and reset it. The agents, abilities, sessions, runners, billing and deploy guides say how it works and what an operator sets up; pinning a computer to your own runner, its browser and take-over come next.792 Op::GetAgentComputer => "Get an agent's computer",
793 Op::WakeAgentComputer => "Wake an agent's computer",
794 Op::SleepAgentComputer => "Put an agent's computer to sleep",
795 Op::ResetAgentComputer => "Reset an agent's computer",
796 Op::ListAgentComputerCommands => "List an agent's computer's commands",
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights797 Op::GetRunnerSettings => "Get runner settings",
798 Op::CreateRunnerRegistrationToken => "Create a runner registration token",
799 Op::RemoveRunner => "Remove a self-hosted runner",
800 Op::CreateRunnerGroup => "Create a runner group",
801 Op::UpdateRunnerGroup => "Change a runner group",
802 Op::DeleteRunnerGroup => "Delete a runner group",
803 Op::UpdateRunnerSettings => "Change runner settings",
804 Op::ListCollaborators => "List who has access",
805 Op::AddCollaborator => "Add a collaborator",
806 Op::UpdateCollaborator => "Change a collaborator's role",
807 Op::RemoveCollaborator => "Remove a collaborator",
808 Op::GetCollaboratorPermission => "Get someone's permission",
809 Op::ListRepoInvitations => "List a repository's invitations",
810 Op::RevokeRepoInvitation => "Revoke a repository invitation",
811 Op::ListMyRepoInvitations => "List your repository invitations",
812 Op::AcceptRepoInvitation => "Accept a repository invitation",
813 Op::DeclineRepoInvitation => "Decline a repository invitation",
814 Op::SetBasePermission => "Set the base permission",
815 Op::ListOutsideCollaborators => "List outside collaborators",
816 Op::ListSecurityAlerts => "List security alerts",
817 Op::DismissSecurityAlert => "Dismiss a security alert",
818 Op::ReopenSecurityAlert => "Reopen a security alert",
API: notifications over REST and MCP, with notifications scopes819 Op::ListNotifications => "List notifications",
820 Op::MarkNotificationsRead => "Mark notifications read",
821 Op::GetNotificationThread => "Get a thread",
822 Op::MarkThreadRead => "Mark a thread read",
823 Op::MarkThreadDone => "Mark a thread done",
824 Op::SaveThread => "Save a thread",
825 Op::SnoozeThread => "Snooze a thread",
826 Op::GetThreadSubscription => "Get a thread subscription",
827 Op::SetThreadSubscription => "Set a thread subscription",
828 Op::DeleteThreadSubscription => "Unsubscribe from a thread",
829 Op::GetRepoSubscription => "Get how you watch a repository",
830 Op::SetRepoSubscription => "Watch a repository",
831 Op::DeleteRepoSubscription => "Stop watching a repository",
832 Op::ListWatchedRepos => "List repositories you watch",
API: pinned projects over REST and MCP833 Op::ListPinnedProjects => "List your pinned projects",
Usage, Billing settings and prepaid AI credit; fixes from the UX audit834 Op::GetUsage => "Get a workspace's usage",
835 Op::GetBudget => "Get a workspace's budget",
836 Op::SetBudget => "Change a workspace's budget",
837 Op::GetAiCredit => "Get a workspace's AI credit",
838 Op::BuyAiCredit => "Buy AI credit",
839 Op::ListInvoices => "List a workspace's invoices",
840 Op::GetBillingDetails => "Get a workspace's billing details",
Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens841 Op::ListGatewayRequests => "List a workspace's AI Gateway requests",
API: pinned projects over REST and MCP842 Op::PinProject => "Pin a project",
843 Op::UnpinProject => "Unpin a project",
844 Op::ReorderPinnedProjects => "Reorder your pinned projects",
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb97845 Op::ListProjects => "List a workspace's projects",
846 Op::GetProject => "Get a project",
847 Op::UpdateProject => "Update a project",
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar848 Op::ListTeams => "List teams",
849 Op::GetTeam => "Get a team",
850 Op::CreateTeam => "Create a team",
851 Op::UpdateTeam => "Update a team",
852 Op::DeleteTeam => "Delete a team",
853 Op::ListTeamMembers => "List a team's members",
854 Op::SetTeamMember => "Add or change a team member",
855 Op::RemoveTeamMember => "Remove a team member",
856 Op::ListChildTeams => "List child teams",
857 Op::ListTeamRepos => "List a team's repositories",
858 Op::SetTeamRepo => "Give a team a role on a repository",
859 Op::RemoveTeamRepo => "Remove a team from a repository",
860 Op::SetTeamReviewAssignment => "Set a team's review assignment",
861 Op::ListUserTeams => "List someone's teams",
862 Op::RequestReviewers => "Request reviewers",
863 Op::RemoveRequestedReviewers => "Remove requested reviewers",
864 Op::GetCodeownersErrors => "List CODEOWNERS errors",
865 Op::Security(op) => op.title(),
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge866 Op::Rules(op) => op.title(),
Merge checks: statuses and check runs on every commit867 Op::Checks(op) => op.title(),
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb97868 Op::About(op) => op.title(),
869 Op::Deployments(op) => op.title(),
Projects have Observability: their requests, logs, traces, metrics and errors, from apps on g1t.page with nothing to set up, and from software anywhere else over OpenTelemetry.870 Op::Telemetry(op) => op.title(),
Merge branch 'worktree-agent-a3abfcce648e87dca'871 Op::Protection(op) => op.title(),
API and MCP for a workspace's personal access token rules, members' tokens and approvals872 Op::Tokens(op) => op.title(),
Actions: OIDC tokens, the toolkit's cache and artifact services, and artifacts in R2873 Op::Artifacts(op) => op.title(),
Merge GitHub pull request #8 (claude/cool-newton-7nm8r9): Docker deployments on g1t.page behind a switch that stays off until Cloudflare's container APIs are checked live, workflows a workspace manages in its repositories, tarball and zipball downloads, refs/pull/* kept to g1t alone, framework detection for g1t.page builds, and a workflow's event payload matching GitHub's.874 Op::Archives(op) => op.title(),
Merge branch 'worktree-agent-a5a5de74d8863d554' into worktree-agent-a16631325aecf58ca875 Op::DeployKeys(op) => op.title(),
Merge branch 'mirroring' into artifacts-mode876 Op::Mirrors(op) => op.title(),
Merge packages: roles, Actions access, source label, soft delete, API877 Op::Packages(op) => op.title(),
Merge main into Artifacts Phase 2878 Op::Folios(op) => op.title(),
Merge remote-tracking branch 'origin/claude/cool-newton-7nm8r9' into claude/cool-newton-7nm8r9879 Op::Customize(op) => op.title(),
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights880 }
881}
882
883/// Why an operation can be refused with `402 payment_required`, if it
884/// can: the ones that start an agent, when the workspace has no credit,
885/// and the ones that make a repository private in a workspace, when a free
886/// workspace's private storage has no room for it.
887fn may_need_payment(op: Op) -> Option<&'static str> {
888 match op {
889 Op::AssignIssue | Op::PlanWork | Op::ApplyPlan => Some("The workspace has no agent credit."),
Every agent can have its own computer. A session that needs one wakes it: a home of its own on g1t cloud, one per agent and never shared, where it runs commands, reads and writes files and keeps what it made, with each session working in its own folder under a shared home; after ten idle minutes it sleeps, its home kept as a snapshot and restored when it wakes, and Reset wipes the home while memory and artifacts stay. Its shell and files are abilities with the usual choices, Alone, Alone when asked, Ask first or Never, offered only inside sessions and never to a chat reply; every command shows on the session with its output, and the agent's new Computer tab shows the state, the disk used of the five gigabytes included, the recent commands, and Wake, Put to sleep and Reset. Machine time counts only while it is awake, on the sandbox lines of the ledger that name the agent and who asked, held to the same spend caps as the session; the disk itself costs nothing in this version. The runner gained a long-lived supervisor that answers the computer's requests inside the container, and the runner service a computer per agent that keeps its snapshot in the agent homes bucket when one is attached, and says so when none is. The REST API and the agent tool can read a computer, wake it, put it to sleep and reset it. The agents, abilities, sessions, runners, billing and deploy guides say how it works and what an operator sets up; pinning a computer to your own runner, its browser and take-over come next.890 Op::WakeAgentComputer => Some("The workspace's plan refuses compute: it is paused, or over its limit."),
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights891 Op::UpdateRepo | Op::SetRepoVisibility | Op::TransferRepo => Some(
892 "A free workspace's private storage has no room for this private repository.",
893 ),
894 _ => None,
895 }
896}
897
898/// What the reference says beyond each operation's own description, keyed
899/// by operation id, written by hand from what the services return: `notes`
900/// (Markdown, added to the description) and example `params` (path),
901/// `query`, `request` (body) and `response`.
902const REFERENCE: &str = include_str!("reference.json");
903
904fn examples() -> Map<String, Value> {
905 match serde_json::from_str(REFERENCE) {
906 Ok(Value::Object(examples)) => examples,
907 _ => Map::new(),
908 }
909}
910
911/// `/repos/:owner/:name` as OpenAPI writes it: `/repos/{owner}/{name}`.
912fn openapi_path(route: &Route) -> String {
913 route
914 .path
915 .split('/')
916 .map(|segment| match segment.strip_prefix(':') {
917 Some(name) => format!("{{{name}}}"),
918 None => segment.to_owned(),
919 })
920 .collect::<Vec<_>>()
921 .join("/")
922}
923
924fn error_response(description: &str) -> Value {
925 json!({
926 "description": description,
927 "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } },
928 })
929}
930
931/// A parameter in the path or the query, described by the operation's
932/// input schema where it has the same name.
933fn parameter(name: &str, place: &str, required: bool, schema: Option<&Value>) -> Value {
934 let mut schema = schema.cloned().unwrap_or_else(|| json!({ "type": "string" }));
935 let description = match name {
936 "owner" => Some(Value::from("The workspace that owns the repository.")),
937 "name" => Some(Value::from("The repository's name.")),
938 _ => schema.as_object_mut().and_then(|schema| schema.remove("description")),
939 };
940 let mut parameter = json!({
941 "name": name,
942 "in": place,
943 "required": required,
944 "schema": schema,
945 });
946 if let Some(description) = description {
947 parameter["description"] = description;
948 }
949 parameter
950}
951
952/// The operation id of a route. An operation reached at a workspace's
953/// address as well as a repository's is documented once for each, with its
954/// own id; GitHub's alternative addresses for one operation keep GitHub's
955/// names.
956fn operation_id(route: &Route) -> String {
957 let op = route.op;
958 let base = match (route.method, route.path.rsplit('/').next().unwrap_or_default()) {
959 ("PUT", "enable") => "enable_workflow".to_owned(),
960 ("PUT", "disable") => "disable_workflow".to_owned(),
961 ("POST", "rerun-failed-jobs") => "rerun_failed_jobs".to_owned(),
Merge Actions runs: summaries, attempts and re-runs, graceful cancel, log downloads, badges (actions 0009)962 ("POST", "rerun") if route.path.contains("/jobs/:job/") => "rerun_job".to_owned(),
963 ("POST", "force-cancel") => "force_cancel_workflow_run".to_owned(),
964 ("GET", ":attempt") => "get_workflow_run_attempt".to_owned(),
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights965 ("PATCH", ":setting") => "update_actions_variable".to_owned(),
966 ("GET", "runs") if route.path.contains("/workflows/:workflow/") => "list_runs_of_workflow".to_owned(),
API: notifications over REST and MCP, with notifications scopes967 // One repository's notifications, and an issue's subscription by
968 // its number rather than a thread's id.
969 (_, "notifications") if route.path.starts_with("/repos/") => match op {
970 Op::ListNotifications => "list_repo_notifications".to_owned(),
971 _ => "mark_repo_notifications_read".to_owned(),
972 },
973 (method, "subscription") if route.path.contains("/issues/:number/") => match method {
974 "GET" => "get_issue_subscription".to_owned(),
975 "PUT" => "set_issue_subscription".to_owned(),
976 _ => "delete_issue_subscription".to_owned(),
977 },
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar978 // One label off an issue, by its name in the path.
979 ("DELETE", ":label") if route.path.contains("/issues/:number/") => "remove_issue_label".to_owned(),
API: notifications over REST and MCP, with notifications scopes980 ("DELETE", "saved") => "unsave_thread".to_owned(),
981 ("DELETE", "snooze") => "unsnooze_thread".to_owned(),
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights982 _ => op.name().to_owned(),
983 };
984 if route.path.starts_with("/workspaces/") && ROUTES.iter().any(|other| other.op == op && other.path.starts_with("/repos/")) {
985 format!("{base}_for_workspace")
986 } else {
987 base
988 }
989}
990
991/// The summary of a route: its operation's title, or for one of GitHub's
992/// alternative addresses, what that address does.
993fn summary(route: &Route, id: &str) -> String {
994 let base = match id.trim_end_matches("_for_workspace") {
995 "enable_workflow" => "Turn a workflow on",
996 "disable_workflow" => "Turn a workflow off",
997 "rerun_failed_jobs" => "Re-run failed jobs",
Merge Actions runs: summaries, attempts and re-runs, graceful cancel, log downloads, badges (actions 0009)998 "rerun_job" => "Re-run a job",
999 "force_cancel_workflow_run" => "Force-cancel a workflow run",
1000 "get_workflow_run_attempt" => "Get a workflow run attempt",
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights1001 "update_actions_variable" => "Update a variable",
1002 "list_runs_of_workflow" => "List a workflow's runs",
API: notifications over REST and MCP, with notifications scopes1003 "list_repo_notifications" => "List a repository's notifications",
1004 "mark_repo_notifications_read" => "Mark a repository's notifications read",
1005 "get_issue_subscription" => "Get your subscription to an issue",
1006 "set_issue_subscription" => "Subscribe to an issue",
1007 "delete_issue_subscription" => "Unsubscribe from an issue",
1008 "unsave_thread" => "Unsave a thread",
1009 "unsnooze_thread" => "Bring a snoozed thread back",
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights1010 _ => title(route.op),
1011 };
1012 if id.ends_with("_for_workspace") {
1013 format!("{base} for a workspace")
1014 } else {
1015 base.to_owned()
1016 }
1017}
1018
1019fn operation(route: &Route) -> Value {
1020 let op = route.op;
1021 let path_params: Vec<&str> = route.params().collect();
Merge checks: statuses and check runs on every commit1022 // `owner` and `name` in the path stand for the operation's `repo` input,
1023 // so a `name` in the body, such as a check run's, is the body's own.
1024 let stands_for_repo =
1025 |name: &str| matches!(name, "owner" | "name") && path_params.contains(&"owner") && path_params.contains(&"name");
1026 let covered = |name: &str| name == "repo" || (path_params.contains(&name) && !stands_for_repo(name));
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights1027 let all_properties = op.properties();
1028 let mut properties = all_properties.clone();
1029 properties.retain(|name, _| !covered(name));
1030 let required: Vec<String> = op
1031 .required()
1032 .into_iter()
1033 .filter(|name| !covered(name))
1034 .collect();
1035
1036 let mut parameters: Vec<Value> = path_params
1037 .iter()
Merge checks: statuses and check runs on every commit1038 .map(|name| parameter(name, "path", true, if stands_for_repo(name) { None } else { all_properties.get(*name) }))
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights1039 .collect();
1040 let mut body = Value::Null;
1041 if route.method == "GET" {
1042 for (name, key) in route.query {
1043 parameters.push(parameter(
1044 name,
1045 "query",
1046 required.iter().any(|required| required == key),
1047 properties.get(*key),
1048 ));
1049 }
1050 } else if !properties.is_empty() {
1051 let mut schema = json!({ "type": "object", "properties": properties });
1052 if !required.is_empty() {
1053 schema["required"] = json!(required);
1054 }
1055 body = json!({
1056 "required": !required.is_empty(),
1057 "content": { "application/json": { "schema": schema } },
1058 });
1059 }
1060
1061 let id = operation_id(route);
1062 let mut responses = Map::new();
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts1063 if route.no_content() {
1064 responses.insert("204".into(), json!({ "description": "Success. There is no body." }));
1065 } else {
1066 responses.insert(
1067 "200".into(),
1068 json!({
1069 "description": "Success.",
1070 "content": { "application/json": { "schema": {} } },
1071 }),
1072 );
1073 }
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights1074 responses.insert(
1075 "401".into(),
1076 error_response("A token is required, or the one sent is not valid."),
1077 );
1078 if let Some(reason) = may_need_payment(op) {
1079 responses.insert("402".into(), error_response(reason));
1080 }
1081 responses.insert(
1082 "403".into(),
1083 error_response("Signed in, but not allowed to do this: the role you have is not enough, or the token lacks the scope it needs, which `needed_scope` names."),
1084 );
1085 if !matches!(op, Op::Whoami | Op::ListRepos | Op::Search) {
1086 responses.insert("404".into(), error_response("It does not exist, or you cannot see it."));
1087 }
1088 if route.method != "GET" {
1089 responses.insert(
1090 "409".into(),
1091 error_response("The request conflicts with the current state."),
1092 );
1093 }
1094 if op != Op::Whoami {
1095 responses.insert("422".into(), error_response("The input is not valid."));
1096 }
1097 // Public data can be read without a token; everything else needs one.
1098 let scope: Vec<&str> = scope_for(op.name()).map(|scope| scope.as_str()).into_iter().collect();
1099 let security = if op.needs_user() {
1100 json!([{ "token": scope }])
1101 } else {
1102 json!([{ "token": scope }, {}])
1103 };
1104 let (tool, action) = crate::tools::TOOLS
1105 .iter()
1106 .find_map(|tool| {
1107 tool.actions
1108 .iter()
1109 .find(|action| action.op == op)
1110 .map(|action| (tool.name, action.name))
1111 })
1112 .unwrap_or_default();
1113 let mut described = json!({
1114 "operationId": id,
1115 "tags": [tag(op)],
1116 "summary": summary(route, &id),
1117 "description": op.description(),
1118 "x-operation": op.name(),
1119 "x-mcp-tool": tool,
1120 "x-mcp-action": action,
1121 "x-scope": scope.first().copied(),
1122 "security": security,
1123 "parameters": parameters,
1124 "responses": responses,
1125 });
1126 if !body.is_null() {
1127 described["requestBody"] = body;
1128 }
1129 described
1130}
1131
1132/// Entries for device sign-in, which is not an operation.
1133fn onboarding() -> Map<String, Value> {
1134 let paths = json!({
1135 "/device/code": {
1136 "post": {
1137 "operationId": "device_code",
1138 "tags": ["Accounts"],
1139 "summary": "Start signing in",
1140 "description": "Begins a device sign-in. Show the person `verification_uri_complete` and have them open it in a browser, where they sign in or register and approve the code. Then poll `/device/token`.",
1141 "security": [],
1142 "requestBody": {
1143 "content": { "application/json": { "schema": {
1144 "type": "object",
1145 "properties": {
1146 "client_name": {
1147 "type": "string",
1148 "description": "What is asking, shown to the person approving. For example, Claude Code.",
1149 },
1150 },
1151 } } },
1152 },
1153 "responses": { "200": {
1154 "description": "The codes for this sign-in.",
1155 "content": { "application/json": { "schema": {
1156 "type": "object",
1157 "properties": {
1158 "device_code": { "type": "string", "description": "Secret. Send it to /device/token." },
1159 "user_code": { "type": "string", "description": "Shown to the person, like WDJB-MJHT." },
1160 "verification_uri": { "type": "string" },
1161 "verification_uri_complete": {
1162 "type": "string",
1163 "description": "The link to give the person; it carries the code.",
1164 },
1165 "expires_in": { "type": "integer", "description": "Seconds until the codes expire." },
1166 "interval": { "type": "integer", "description": "Seconds to wait between polls." },
1167 },
1168 } } },
1169 } },
1170 },
1171 },
1172 "/device/token": {
1173 "post": {
1174 "operationId": "device_token",
1175 "tags": ["Accounts"],
1176 "summary": "Finish signing in",
1177 "description": "Asks whether the person has approved. Poll no faster than the interval. The token is returned once.",
1178 "security": [],
1179 "requestBody": {
1180 "required": true,
1181 "content": { "application/json": { "schema": {
1182 "type": "object",
1183 "required": ["device_code"],
1184 "properties": { "device_code": { "type": "string" } },
1185 } } },
1186 },
1187 "responses": { "200": {
1188 "description": "The state of the sign-in.",
1189 "content": { "application/json": { "schema": {
1190 "type": "object",
1191 "required": ["status"],
1192 "properties": {
1193 "status": { "type": "string", "enum": ["pending", "approved", "denied", "expired"] },
1194 "token": { "type": "string", "description": "Present when approved." },
Cards you act on in chat; agents comment and review as themselves; names shown cleanly; commits on the calendar1195 "username": { "type": "string", "description": "Lowercased: what the account is found and linked by." },
1196 "display_username": { "type": "string", "description": "The username as its owner wrote it; the same as username when they chose no case." },
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights1197 "verified": {
1198 "type": "boolean",
1199 "description": "Whether the account's email is confirmed.",
1200 },
1201 },
1202 } } },
1203 } },
1204 },
1205 },
1206 });
1207 match paths {
1208 Value::Object(paths) => paths,
1209 _ => Map::new(),
1210 }
1211}
1212
1213
1214/// Puts each operation's examples, where it has them, into its request
1215/// and response. Path and query values go under `x-example-params` and
1216/// `x-example-query`, which tools that build a request can use.
1217fn attach_examples(paths: &mut Map<String, Value>) {
1218 let examples = examples();
1219 for methods in paths.values_mut() {
1220 let Some(methods) = methods.as_object_mut() else { continue };
1221 for operation in methods.values_mut() {
1222 let id = operation["operationId"].as_str().unwrap_or_default().to_owned();
1223 let name = operation["x-operation"].as_str().unwrap_or_default().to_owned();
1224 let Some(example) = examples.get(&id).or_else(|| examples.get(&name)) else {
1225 continue;
1226 };
1227 if let Some(notes) = example.get("notes").and_then(Value::as_str) {
1228 let description = operation["description"].as_str().unwrap_or_default();
1229 operation["description"] = json!(format!("{description}\n\n{notes}"));
1230 }
1231 if let Some(response) = example.get("response") {
1232 let content = &mut operation["responses"]["200"]["content"]["application/json"];
1233 if content.is_object() {
1234 content["example"] = response.clone();
1235 }
1236 }
1237 if let Some(request) = example.get("request") {
1238 let content = &mut operation["requestBody"]["content"]["application/json"];
1239 if content.is_object() {
1240 content["example"] = request.clone();
1241 }
1242 }
1243 for (key, extension) in [("params", "x-example-params"), ("query", "x-example-query")] {
1244 if let Some(values) = example.get(key) {
1245 operation[extension] = values.clone();
1246 }
1247 }
1248 }
1249 }
1250}
1251
1252pub fn document() -> Value {
1253 let mut paths = onboarding();
1254 for route in ROUTES {
1255 let entry = paths
1256 .entry(openapi_path(route))
1257 .or_insert_with(|| json!({}));
1258 entry[route.method.to_lowercase()] = operation(route);
1259 }
1260 attach_examples(&mut paths);
1261 let tags: Vec<Value> = SECTIONS
1262 .iter()
1263 .map(|(name, description, ops)| {
1264 json!({
1265 "name": name,
1266 "description": description,
1267 // The section's operations in reading order, by MCP tool name.
1268 "x-tools": ops.iter().map(|op| op.name()).collect::<Vec<_>>(),
1269 })
1270 })
1271 .collect();
1272 let codes = ["unauthenticated", "payment_required", "forbidden", "not_found", "conflict", "invalid"];
1273 json!({
1274 "openapi": "3.1.0",
1275 "info": {
1276 "title": "g1t API",
1277 "version": "1",
1278 "description": "The REST API for g1t, a git forge built for agents. The same operations are available to agents as MCP tools at https://mcp.g1t.sh. Every name in a request or response body is `snake_case`; names you chose, such as a workflow's inputs or a secret's name, are returned as you wrote them.",
1279 "license": { "name": "MIT", "identifier": "MIT" },
1280 },
1281 "servers": [{ "url": "https://api.g1t.sh" }],
1282 "security": [{ "token": [] }, {}],
1283 "tags": tags,
1284 "paths": paths,
1285 "components": {
1286 "securitySchemes": {
1287 "token": {
1288 "type": "http",
1289 "scheme": "bearer",
1290 "description": "An access token, `g1t_…`. Public data needs none. Each operation names the scope a token needs for it; see https://docs.g1t.sh/guides/authentication/#scopes.",
1291 },
1292 },
1293 "schemas": {
1294 "Error": {
1295 "type": "object",
1296 "required": ["error"],
1297 "properties": {
1298 "error": {
1299 "type": "object",
1300 "required": ["code", "message"],
1301 "properties": {
1302 "code": { "type": "string", "enum": codes },
1303 "message": { "type": "string" },
1304 "needed_scope": {
1305 "type": "string",
1306 "description": "On a 403 for an access token without the scope the call needs: that scope, such as `issues:write`.",
1307 },
1308 },
1309 },
1310 },
1311 },
1312 },
1313 },
1314 })
1315}
1316
1317#[cfg(test)]
1318mod tests {
1319 use super::*;
1320
1321 #[test]
1322 fn every_route_is_documented_once() {
1323 let document = document();
1324 let mut ids = Vec::new();
1325 for (_, methods) in document["paths"].as_object().unwrap() {
1326 for (_, operation) in methods.as_object().unwrap() {
1327 ids.push(operation["operationId"].as_str().unwrap().to_owned());
1328 }
1329 }
1330 for op in Op::ALL {
1331 assert_eq!(
1332 ids.iter().filter(|id| *id == op.name()).count(),
1333 1,
1334 "{}",
1335 op.name()
1336 );
1337 }
1338 let mut unique = ids.clone();
1339 unique.sort();
1340 unique.dedup();
1341 assert_eq!(unique.len(), ids.len(), "operation ids repeat");
1342 }
1343
1344 #[test]
1345 fn path_and_query_inputs_are_not_repeated_in_the_body() {
1346 let document = document();
1347 let merge = &document["paths"]["/repos/{owner}/{name}/pulls/{number}/merge"]["post"];
1348 let body = &merge["requestBody"]["content"]["application/json"]["schema"]["properties"];
1349 assert!(body.get("keep_issue_open").is_some());
1350 assert!(body.get("repo").is_none() && body.get("number").is_none());
1351 let list = &document["paths"]["/repos"]["get"];
1352 assert_eq!(list["parameters"][0]["name"], "q");
1353 assert!(list.get("requestBody").is_none());
1354 }
1355
1356 #[test]
1357 fn every_operation_is_in_one_section() {
1358 for op in Op::ALL {
1359 let sections = SECTIONS
1360 .iter()
1361 .filter(|(_, _, ops)| ops.contains(&op))
1362 .count();
1363 assert_eq!(sections, 1, "{}", op.name());
1364 }
1365 }
1366
1367 #[test]
1368 fn titles_read_as_sentences() {
1369 assert_eq!(title(Op::CreateIssue), "Create an issue");
1370 assert_eq!(title(Op::Whoami), "Get the current user");
1371 }
1372
1373 #[test]
1374 fn every_operation_has_an_example_response() {
1375 let examples = examples();
1376 assert!(!examples.is_empty(), "reference.json does not parse");
1377 let document = document();
1378 let mut known = Vec::new();
1379 for (path, methods) in document["paths"].as_object().unwrap() {
1380 for (method, operation) in methods.as_object().unwrap() {
1381 known.push(operation["operationId"].as_str().unwrap().to_owned());
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts1382 // Nothing to show for a success without a body.
1383 if operation["responses"]["204"].is_object() {
1384 continue;
1385 }
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights1386 let example = &operation["responses"]["200"]["content"]["application/json"]["example"];
1387 assert!(!example.is_null(), "{method} {path} has no example response");
1388 }
1389 }
1390 for id in examples.keys() {
1391 assert!(known.contains(id), "reference.json names {id}, which is not an operation");
1392 }
1393 }
1394
1395 #[test]
1396 fn example_requests_send_only_what_the_body_takes() {
1397 let document = document();
1398 for (path, methods) in document["paths"].as_object().unwrap() {
1399 for (method, operation) in methods.as_object().unwrap() {
1400 let content = &operation["requestBody"]["content"]["application/json"];
1401 let Some(example) = content["example"].as_object() else { continue };
1402 let properties = &content["schema"]["properties"];
1403 for key in example.keys() {
1404 assert!(!properties[key].is_null(), "{method} {path}: {key} is not in the body");
1405 }
1406 }
1407 }
1408 }
1409
1410 /// The docs site's copy of the document. Run with `G1T_WRITE_OPENAPI=1`
1411 /// to rewrite it after changing an operation.
1412 #[test]
1413 fn the_docs_copy_is_current() {
1414 let path = concat!(env!("CARGO_MANIFEST_DIR"), "/../docs/src/data/openapi.json");
1415 let current = serde_json::to_string_pretty(&document()).unwrap() + "\n";
1416 if std::env::var_os("G1T_WRITE_OPENAPI").is_some() {
1417 std::fs::write(path, &current).unwrap();
1418 return;
1419 }
1420 let copy = std::fs::read_to_string(path).unwrap_or_default().replace("\r\n", "\n");
1421 assert!(
1422 copy == current,
1423 "apps/docs/src/data/openapi.json is out of date: run G1T_WRITE_OPENAPI=1 cargo test -p g1t-api openapi"
1424 );
1425 }
1426
1427 /// The reference shows responses as they are sent: `snake_case`.
1428 #[test]
1429 fn example_responses_are_snake_case() {
1430 let document = document();
1431 for (path, methods) in document["paths"].as_object().unwrap() {
1432 for (method, operation) in methods.as_object().unwrap() {
1433 let example = &operation["responses"]["200"]["content"]["application/json"]["example"];
1434 let leaked = g1t_kit::wire::camel_case_keys(example);
1435 assert!(leaked.is_empty(), "{method} {path} shows {leaked:?}");
1436 }
1437 }
1438 }
1439
1440 /// Examples never hold anything that reads as a real credential, which
1441 /// secret scanners rightly flag in a public repository: they end in `…`
1442 /// after the prefix, as `whsec_…` and `g1t_…` do.
1443 #[test]
1444 fn examples_hold_no_real_looking_secrets() {
1445 let prefixes = ["whsec_", "g1t_", "g1tr_", "g1trt_", "sk_live_", "sk_test_", "ghp_", "github_pat_", "xoxb-", "AKIA"];
1446 for (line, text) in REFERENCE.lines().enumerate() {
1447 for prefix in prefixes {
1448 let mut rest = text;
1449 while let Some(at) = rest.find(prefix) {
1450 let after = &rest[at + prefix.len()..];
1451 let run = after.chars().take_while(|c| c.is_ascii_alphanumeric()).count();
1452 assert!(
1453 run < 12,
1454 "reference.json line {}: `{prefix}` followed by {run} characters reads as a real secret; write `{prefix}…`",
1455 line + 1
1456 );
1457 rest = after;
1458 }
1459 }
1460 }
1461 }
1462}

This file's history is long; its oldest lines are credited to the oldest commit read.