Skip to content
Sign up

flagon-io/g1t

public
0

Where people and agents ship software together. The open-source git platform for the whole job: issues, agents, checks and deploys to the edge.

g1t.sh
gitagentscloudflarerustforgemcp
1,444 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.

The code page reads like a forge: a branch menu, search and a Code button above the files1//! 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 'main' into worktree-agent-a69aeabc4b0deeb9715use 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.16use crate::telemetry::TelemetryOp;
Merge packages: roles, Actions access, source label, soft delete, API17use crate::packages::PackagesOp;
Merge main into Artifacts Phase 218use crate::folios::FoliosOp;
Merge branch 'worktree-agent-a3abfcce648e87dca'19use crate::protection::ProtectionOp;
API and MCP for a workspace's personal access token rules, members' tokens and approvals20use crate::token_policy::TokenOp;
The code page reads like a forge: a branch menu, search and a Code button above the files21use crate::operations::Op;
Merge checks: statuses and check runs on every commit22use crate::checks::ChecksOp;
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge23use crate::rules::RulesOp;
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar24use crate::security::SecurityOp;
The code page reads like a forge: a branch menu, search and a Code button above the files25use crate::rest::{ROUTES, Route};
26
27/// The sections of the API reference: a name, what it covers, and its
28/// operations in the order a reader meets them.
29const SECTIONS: &[(&str, &str, &[Op])] = &[
30 (
31 "Accounts",
32 "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)33 &[Op::Whoami, Op::ListEmails, Op::AddEmail, Op::ConfirmEmail, Op::RemoveEmail, Op::UpdateEmailSettings],
The code page reads like a forge: a branch menu, search and a Code button above the files34 ),
35 (
API: notifications over REST and MCP, with notifications scopes36 "Notifications",
37 "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.",
38 &[
39 Op::ListNotifications,
40 Op::MarkNotificationsRead,
41 Op::GetNotificationThread,
42 Op::MarkThreadRead,
43 Op::MarkThreadDone,
44 Op::SaveThread,
45 Op::SnoozeThread,
46 Op::GetThreadSubscription,
47 Op::SetThreadSubscription,
48 Op::DeleteThreadSubscription,
49 Op::GetRepoSubscription,
50 Op::SetRepoSubscription,
51 Op::DeleteRepoSubscription,
52 Op::ListWatchedRepos,
53 ],
54 ),
55 (
API: pinned projects over REST and MCP56 "Pinned projects",
57 "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.",
58 &[Op::ListPinnedProjects, Op::PinProject, Op::UnpinProject, Op::ReorderPinnedProjects],
59 ),
60 (
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb9761 "Projects",
62 "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.",
63 &[Op::ListProjects, Op::GetProject, Op::UpdateProject],
64 ),
65 (
The code page reads like a forge: a branch menu, search and a Code button above the files66 "Workspaces",
67 "A workspace owns repositories and is the first part of their address. People and agents work in workspaces.",
Merge branch 'worktree-agent-ad7c6d88d93adc817'68 &[Op::GetWorkspace, Op::CreateWorkspace, Op::UpdateWorkspace, Op::DeleteWorkspace],
The code page reads like a forge: a branch menu, search and a Code button above the files69 ),
70 (
API and MCP for a workspace's personal access token rules, members' tokens and approvals71 "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 managers72 "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 approvals73 &[
74 Op::Tokens(TokenOp::GetTokenPolicy),
75 Op::Tokens(TokenOp::SetTokenPolicy),
76 Op::Tokens(TokenOp::ListMemberTokens),
77 Op::Tokens(TokenOp::ListTokenRequests),
78 Op::Tokens(TokenOp::ReviewTokenRequest),
79 Op::Tokens(TokenOp::RevokeMemberToken),
80 ],
81 ),
82 (
Merge main (membership, two-factor, GitHub repo roles) into tokens83 "Members",
84 "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.",
85 &[Op::ListMembers, Op::UpdateMember, Op::RemoveMember, Op::TransferOwnership, Op::LeaveWorkspace],
86 ),
87 (
The code page reads like a forge: a branch menu, search and a Code button above the files88 "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)89 "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.",
The code page reads like a forge: a branch menu, search and a Code button above the files90 &[
91 Op::ListInvites,
92 Op::CreateInvite,
93 Op::RevokeInvite,
94 Op::ListWorkspaceInvites,
95 Op::InviteMember,
96 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)97 Op::ListInvitations,
98 Op::AcceptInvitation,
99 Op::DeclineInvitation,
The code page reads like a forge: a branch menu, search and a Code button above the files100 ],
101 ),
102 (
Usage, Billing settings and prepaid AI credit; fixes from the UX audit103 "Billing",
Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens104 "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 audit105 &[
106 Op::GetUsage,
107 Op::GetBudget,
108 Op::SetBudget,
109 Op::GetAiCredit,
110 Op::BuyAiCredit,
111 Op::ListInvoices,
112 Op::GetBillingDetails,
Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens113 Op::ListGatewayRequests,
Usage, Billing settings and prepaid AI credit; fixes from the UX audit114 ],
115 ),
116 (
The code page reads like a forge: a branch menu, search and a Code button above the files117 "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.118 "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.",
The code page reads like a forge: a branch menu, search and a Code button above the files119 &[
120 Op::ListRepos,
121 Op::CreateRepo,
122 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.123 Op::Archives(ArchiveOp::DownloadTarball),
124 Op::Archives(ArchiveOp::DownloadZipball),
The code page reads like a forge: a branch menu, search and a Code button above the files125 Op::UpdateRepo,
126 Op::RenameRepo,
127 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.128 Op::CreateBranch,
129 Op::DeleteBranch,
The code page reads like a forge: a branch menu, search and a Code button above the files130 Op::SetRepoVisibility,
131 Op::ArchiveRepo,
132 Op::UnarchiveRepo,
133 Op::TransferRepo,
134 Op::DeleteRepo,
135 Op::ListDeletedRepos,
136 Op::RestoreRepo,
137 Op::PurgeRepo,
138 Op::GetRepoSettings,
139 Op::UpdateRepoSettings,
140 Op::ListCheckNames,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar141 Op::GetCodeownersErrors,
The code page reads like a forge: a branch menu, search and a Code button above the files142 Op::ListEvents,
143 ],
144 ),
145 (
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb97146 "Repository insights",
147 "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.",
148 &[Op::About(AboutOp::GetLanguages), Op::About(AboutOp::ListContributors), Op::About(AboutOp::GetLicense)],
149 ),
150 (
151 "Stars",
152 "Starring a repository, to keep it and to say you like it: who starred one, and what you starred.",
153 &[
154 Op::About(AboutOp::ListStargazers),
155 Op::About(AboutOp::ListStarred),
156 Op::About(AboutOp::CheckStarred),
157 Op::About(AboutOp::Star),
158 Op::About(AboutOp::Unstar),
159 ],
160 ),
161 (
162 "Releases",
163 "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.",
164 &[
165 Op::About(AboutOp::ListReleases),
166 Op::About(AboutOp::CreateRelease),
167 Op::About(AboutOp::GetLatestRelease),
168 Op::About(AboutOp::GetReleaseByTag),
169 Op::About(AboutOp::GetRelease),
170 Op::About(AboutOp::UpdateRelease),
171 Op::About(AboutOp::DeleteRelease),
172 ],
173 ),
174 (
The code page reads like a forge: a branch menu, search and a Code button above the files175 "Access",
Merge branch 'worktree-agent-a5a5de74d8863d554' into worktree-agent-a16631325aecf58ca176 "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.",
The code page reads like a forge: a branch menu, search and a Code button above the files177 &[
178 Op::ListCollaborators,
179 Op::AddCollaborator,
180 Op::UpdateCollaborator,
181 Op::RemoveCollaborator,
182 Op::GetCollaboratorPermission,
183 Op::ListRepoInvitations,
184 Op::RevokeRepoInvitation,
185 Op::ListMyRepoInvitations,
186 Op::AcceptRepoInvitation,
187 Op::DeclineRepoInvitation,
188 Op::SetBasePermission,
189 Op::ListOutsideCollaborators,
Merge branch 'worktree-agent-a5a5de74d8863d554' into worktree-agent-a16631325aecf58ca190 Op::DeployKeys(DeployKeysOp::ListDeployKeys),
191 Op::DeployKeys(DeployKeysOp::GetDeployKey),
192 Op::DeployKeys(DeployKeysOp::CreateDeployKey),
193 Op::DeployKeys(DeployKeysOp::DeleteDeployKey),
Merge branch 'mirroring' into artifacts-mode194 ],
195 ),
196 (
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar197 "Teams",
198 "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.",
199 &[
200 Op::ListTeams,
201 Op::CreateTeam,
202 Op::GetTeam,
203 Op::UpdateTeam,
204 Op::DeleteTeam,
205 Op::ListTeamMembers,
206 Op::SetTeamMember,
207 Op::RemoveTeamMember,
208 Op::ListChildTeams,
209 Op::ListTeamRepos,
210 Op::SetTeamRepo,
211 Op::RemoveTeamRepo,
212 Op::SetTeamReviewAssignment,
213 Op::ListUserTeams,
214 ],
215 ),
216 (
The code page reads like a forge: a branch menu, search and a Code button above the files217 "Security",
218 "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.",
219 &[Op::ListSecurityAlerts, Op::DismissSecurityAlert, Op::ReopenSecurityAlert],
220 ),
221 (
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar222 "Secret scanning",
223 "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.",
224 &[
225 Op::Security(SecurityOp::ListSecretAlerts),
226 Op::Security(SecurityOp::GetSecretAlert),
227 Op::Security(SecurityOp::UpdateSecretAlert),
228 Op::Security(SecurityOp::ListSecretLocations),
229 Op::Security(SecurityOp::BypassPushProtection),
230 Op::Security(SecurityOp::CheckSecretValidity),
231 Op::Security(SecurityOp::ListBypassRequests),
232 Op::Security(SecurityOp::ReviewBypassRequest),
233 Op::Security(SecurityOp::ListCustomPatterns),
234 Op::Security(SecurityOp::CreateCustomPattern),
235 Op::Security(SecurityOp::UpdateCustomPattern),
236 Op::Security(SecurityOp::DeleteCustomPattern),
237 Op::Security(SecurityOp::DryRunCustomPattern),
238 ],
239 ),
240 (
241 "Code scanning",
242 "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.",
243 &[
244 Op::Security(SecurityOp::ListCodeAlerts),
245 Op::Security(SecurityOp::GetCodeAlert),
246 Op::Security(SecurityOp::UpdateCodeAlert),
247 Op::Security(SecurityOp::ListAnalyses),
248 Op::Security(SecurityOp::UploadSarif),
249 Op::Security(SecurityOp::GetSarifUpload),
250 Op::Security(SecurityOp::FixAlert),
251 ],
252 ),
253 (
254 "Supply chain",
255 "What a repository depends on: vulnerability alerts, the dependency graph, an SPDX SBOM of it, and comparing two commits' dependencies as dependency review does.",
256 &[
257 Op::Security(SecurityOp::ListVulnerabilityAlerts),
258 Op::Security(SecurityOp::GetVulnerabilityAlert),
259 Op::Security(SecurityOp::UpdateVulnerabilityAlert),
260 Op::Security(SecurityOp::GetDependencyGraph),
261 Op::Security(SecurityOp::GetSbom),
262 Op::Security(SecurityOp::CompareDependencies),
263 ],
264 ),
265 (
266 "Security settings",
267 "When pull request checks fail, dependency review's policy, delegated bypass and validity checks, and a workspace's security overview.",
268 &[
269 Op::Security(SecurityOp::GetSettings),
270 Op::Security(SecurityOp::UpdateSettings),
271 Op::Security(SecurityOp::GetWorkspaceSettings),
272 Op::Security(SecurityOp::UpdateWorkspaceSettings),
273 Op::Security(SecurityOp::GetOverview),
274 ],
275 ),
276 (
Merge remote-tracking branch 'origin/claude/cool-newton-7nm8r9' into claude/cool-newton-7nm8r9277 "Security advisories",
278 "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.",
279 &[
280 Op::Security(SecurityOp::ListAdvisories),
281 Op::Security(SecurityOp::CreateAdvisory),
282 Op::Security(SecurityOp::GetAdvisory),
283 Op::Security(SecurityOp::UpdateAdvisory),
284 Op::Security(SecurityOp::SetAdvisoryState),
285 Op::Security(SecurityOp::ListReports),
286 Op::Security(SecurityOp::ReportVulnerability),
287 Op::Security(SecurityOp::ReviewReport),
288 ],
289 ),
290 (
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge291 "Rules",
292 "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.",
293 &[
294 Op::Rules(RulesOp::ListRepoRulesets),
295 Op::Rules(RulesOp::CreateRepoRuleset),
296 Op::Rules(RulesOp::GetRepoRuleset),
297 Op::Rules(RulesOp::UpdateRepoRuleset),
298 Op::Rules(RulesOp::DeleteRepoRuleset),
299 Op::Rules(RulesOp::GetBranchRules),
300 Op::Rules(RulesOp::ListRuleEvaluations),
301 Op::Rules(RulesOp::ListWorkspaceRulesets),
302 Op::Rules(RulesOp::CreateWorkspaceRuleset),
303 Op::Rules(RulesOp::GetWorkspaceRuleset),
304 Op::Rules(RulesOp::UpdateWorkspaceRuleset),
305 Op::Rules(RulesOp::DeleteWorkspaceRuleset),
306 Op::Rules(RulesOp::ListWorkspaceRuleEvaluations),
307 ],
308 ),
309 (
Merge checks: statuses and check runs on every commit310 "Checks",
311 "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.",
312 &[
313 Op::Checks(ChecksOp::CreateCommitStatus),
314 Op::Checks(ChecksOp::ListCommitStatuses),
315 Op::Checks(ChecksOp::GetCombinedStatus),
316 Op::Checks(ChecksOp::CreateCheckRun),
317 Op::Checks(ChecksOp::UpdateCheckRun),
318 Op::Checks(ChecksOp::GetCheckRun),
319 Op::Checks(ChecksOp::ListCheckRunAnnotations),
320 Op::Checks(ChecksOp::RerequestCheckRun),
321 Op::Checks(ChecksOp::ListCheckRunsForRef),
322 Op::Checks(ChecksOp::ListCheckSuitesForRef),
323 Op::Checks(ChecksOp::GetCheckSuite),
324 Op::Checks(ChecksOp::RerequestCheckSuite),
325 ],
326 ),
327 (
The code page reads like a forge: a branch menu, search and a Code button above the files328 "Issues",
329 "What should change in a repository, with labels and comments. Issues and pull requests share one sequence of numbers.",
330 &[
331 Op::ListIssues,
332 Op::CreateIssue,
333 Op::GetIssue,
334 Op::UpdateIssue,
335 Op::CloseIssue,
336 Op::ReopenIssue,
337 Op::AssignIssue,
338 Op::Delegate,
339 Op::AddComment,
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts340 Op::EditComment,
341 Op::DeleteComment,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar342 Op::ListIssueLabels,
343 Op::AddIssueLabels,
344 Op::SetIssueLabels,
345 Op::RemoveIssueLabels,
346 ],
347 ),
348 (
349 "Labels and milestones",
350 "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.",
351 &[
The code page reads like a forge: a branch menu, search and a Code button above the files352 Op::ListLabels,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar353 Op::CreateLabel,
354 Op::UpdateLabel,
355 Op::DeleteLabel,
356 Op::AddDefaultLabels,
357 Op::ListMilestones,
358 Op::CreateMilestone,
359 Op::GetMilestone,
360 Op::UpdateMilestone,
361 Op::DeleteMilestone,
The code page reads like a forge: a branch menu, search and a Code button above the files362 ],
363 ),
364 (
365 "Plans",
366 "An outcome turned into the issues that would get there, with the order they must merge in.",
367 &[Op::PlanWork, Op::GetPlan, Op::ApplyPlan],
368 ),
369 (
370 "Pull requests",
371 "A proposed change in its own fork or on a branch. Several can be made for one issue; the one merged resolves it.",
372 &[
373 Op::ListPullRequests,
374 Op::CreatePullRequest,
375 Op::GetPullRequest,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar376 Op::UpdatePullRequest,
The code page reads like a forge: a branch menu, search and a Code button above the files377 Op::GetPullRequestChanges,
378 Op::MarkPullRequestReady,
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts379 Op::ConvertPullRequestToDraft,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar380 Op::RequestReviewers,
381 Op::RemoveRequestedReviewers,
The code page reads like a forge: a branch menu, search and a Code button above the files382 Op::ReviewPullRequest,
383 Op::MergePullRequest,
384 Op::ClosePullRequest,
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts385 Op::ReopenPullRequest,
The code page reads like a forge: a branch menu, search and a Code button above the files386 Op::GetMergeQueue,
387 Op::MessageAgent,
388 Op::AnswerMessage,
389 Op::TakeMessages,
390 ],
391 ),
392 (
393 "Sessions",
394 "The record of how a pull request was made: prompts, reasoning and the tools that ran.",
395 &[Op::ReadSession, Op::RecordSession],
396 ),
397 (
398 "Memory",
399 "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.",
400 &[Op::Remember, Op::Recall],
401 ),
402 (
403 "Search",
404 "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.",
405 &[Op::Search],
406 ),
407 (
408 "Context",
409 "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.",
410 &[Op::SearchContext, Op::GetEntity],
411 ),
412 (
413 "Actions",
414 "GitHub Actions workflows in .g1t/workflows, their runs, and their jobs' logs.",
415 &[
416 Op::ListWorkflows,
417 Op::ListWorkflowRuns,
418 Op::GetWorkflowRun,
419 Op::GetJobLogs,
420 Op::DispatchWorkflow,
421 Op::CancelWorkflowRun,
422 Op::RerunWorkflowRun,
423 Op::UpdateWorkflow,
Actions: OIDC tokens, the toolkit's cache and artifact services, and artifacts in R2424 Op::Artifacts(ArtifactsOp::ListArtifacts),
425 Op::Artifacts(ArtifactsOp::ListRunArtifacts),
426 Op::Artifacts(ArtifactsOp::GetArtifact),
427 Op::Artifacts(ArtifactsOp::DownloadArtifact),
428 Op::Artifacts(ArtifactsOp::DeleteArtifact),
429 Op::Artifacts(ArtifactsOp::GetArtifactRetention),
430 Op::Artifacts(ArtifactsOp::SetArtifactRetention),
The code page reads like a forge: a branch menu, search and a Code button above the files431 ],
432 ),
433 (
Merge packages: roles, Actions access, source label, soft delete, API434 "Packages",
435 "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.",
436 &[
437 Op::Packages(PackagesOp::ListPackages),
438 Op::Packages(PackagesOp::GetPackage),
439 Op::Packages(PackagesOp::UpdatePackage),
440 Op::Packages(PackagesOp::DeletePackage),
441 Op::Packages(PackagesOp::RestorePackage),
442 Op::Packages(PackagesOp::ListVersions),
443 Op::Packages(PackagesOp::GetVersion),
444 Op::Packages(PackagesOp::DeleteVersion),
445 Op::Packages(PackagesOp::RestoreVersion),
446 Op::Packages(PackagesOp::LinkPackage),
447 Op::Packages(PackagesOp::UnlinkPackage),
448 Op::Packages(PackagesOp::ListAccess),
449 Op::Packages(PackagesOp::SetAccess),
450 Op::Packages(PackagesOp::RemoveAccess),
451 Op::Packages(PackagesOp::ListActionsAccess),
452 Op::Packages(PackagesOp::SetActionsAccess),
453 Op::Packages(PackagesOp::RemoveActionsAccess),
454 ],
455 ),
456 (
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb97457 "Deployments",
458 "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.",
459 &[
460 Op::Deployments(DeploymentsOp::ListDeployments),
461 Op::Deployments(DeploymentsOp::CreateDeployment),
462 Op::Deployments(DeploymentsOp::GetDeployment),
463 Op::Deployments(DeploymentsOp::ListDeploymentStatuses),
464 Op::Deployments(DeploymentsOp::CreateDeploymentStatus),
465 Op::Deployments(DeploymentsOp::ListEnvironments),
466 Op::Deployments(DeploymentsOp::GetEnvironment),
Merge branch 'worktree-agent-a4d35ee70c50683d0' into claude/cool-newton-7nm8r9467 Op::Deployments(DeploymentsOp::StartDeploymentBuild),
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb97468 ],
469 ),
470 (
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.471 "Observability",
472 "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.",
473 &[
474 Op::Telemetry(TelemetryOp::GetOverview),
475 Op::Telemetry(TelemetryOp::ListRequests),
476 Op::Telemetry(TelemetryOp::GetRequest),
477 Op::Telemetry(TelemetryOp::ListLogs),
478 Op::Telemetry(TelemetryOp::ListTraces),
479 Op::Telemetry(TelemetryOp::GetTrace),
480 Op::Telemetry(TelemetryOp::ListErrors),
481 Op::Telemetry(TelemetryOp::UpdateError),
482 Op::Telemetry(TelemetryOp::ListMetrics),
483 Op::Telemetry(TelemetryOp::GetMetric),
484 Op::Telemetry(TelemetryOp::GetSettings),
485 Op::Telemetry(TelemetryOp::UpdateSettings),
486 Op::Telemetry(TelemetryOp::ListTokens),
487 Op::Telemetry(TelemetryOp::CreateToken),
488 Op::Telemetry(TelemetryOp::DeleteToken),
489 Op::Telemetry(TelemetryOp::ListExports),
490 Op::Telemetry(TelemetryOp::CreateExport),
491 Op::Telemetry(TelemetryOp::UpdateExport),
492 Op::Telemetry(TelemetryOp::DeleteExport),
493 Op::Telemetry(TelemetryOp::GetUsage),
494 ],
495 ),
496 (
Merge branch 'worktree-agent-a3abfcce648e87dca'497 "Run protection",
498 "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.",
499 &[
500 Op::Protection(ProtectionOp::UpdateEnvironment),
501 Op::Protection(ProtectionOp::DeleteEnvironment),
502 Op::Protection(ProtectionOp::GetPendingDeployments),
503 Op::Protection(ProtectionOp::ReviewPendingDeployments),
504 Op::Protection(ProtectionOp::ApproveWorkflowRun),
505 Op::Protection(ProtectionOp::GetWorkflowPermissions),
506 Op::Protection(ProtectionOp::SetWorkflowPermissions),
507 Op::Protection(ProtectionOp::GetForkPrApproval),
508 Op::Protection(ProtectionOp::SetForkPrApproval),
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts509 Op::Protection(ProtectionOp::GetActionsAccess),
510 Op::Protection(ProtectionOp::SetActionsAccess),
Merge branch 'worktree-agent-a3abfcce648e87dca'511 Op::Protection(ProtectionOp::CreateRepositoryDispatch),
512 Op::Protection(ProtectionOp::GetWorkspaceWorkflowPermissions),
513 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.514 Op::Protection(ProtectionOp::ListWorkspaceManagedWorkflows),
515 Op::Protection(ProtectionOp::CreateWorkspaceManagedWorkflow),
516 Op::Protection(ProtectionOp::UpdateWorkspaceManagedWorkflow),
517 Op::Protection(ProtectionOp::DeleteWorkspaceManagedWorkflow),
Merge branch 'worktree-agent-a3abfcce648e87dca'518 ],
519 ),
520 (
The code page reads like a forge: a branch menu, search and a Code button above the files521 "Secrets and variables",
522 "Values that workflows and deployments read, per repository or for a whole workspace, with a row per environment.",
523 &[
524 Op::ListActionsSecrets,
525 Op::SetActionsSecret,
526 Op::DeleteActionsSecret,
527 Op::ListActionsVariables,
528 Op::SetActionsVariable,
529 Op::DeleteActionsVariable,
530 ],
531 ),
532 (
533 "Runners",
534 "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.",
535 &[
536 Op::ListRunners,
537 Op::CreateRunnerRegistrationToken,
538 Op::RemoveRunner,
539 Op::ListRunnerGroups,
540 Op::CreateRunnerGroup,
541 Op::UpdateRunnerGroup,
542 Op::DeleteRunnerGroup,
543 Op::GetRunnerSettings,
544 Op::UpdateRunnerSettings,
545 ],
546 ),
547 (
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.548 "Agents' computers",
549 "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.",
550 &[
551 Op::GetAgentComputer,
552 Op::WakeAgentComputer,
553 Op::SleepAgentComputer,
554 Op::ResetAgentComputer,
555 Op::ListAgentComputerCommands,
556 ],
557 ),
558 (
The code page reads like a forge: a branch menu, search and a Code button above the files559 "Webhooks",
560 "Signed HTTPS requests sent to your own address as things happen, for a repository or a whole workspace.",
561 &[
562 Op::ListWebhooks,
563 Op::CreateWebhook,
564 Op::UpdateWebhook,
565 Op::DeleteWebhook,
566 Op::PingWebhook,
567 Op::ListWebhookDeliveries,
568 Op::RedeliverWebhook,
569 ],
570 ),
571 (
572 "Integrations",
573 "A workspace's connections to outside systems: model providers, alert sources and issue trackers.",
574 &[
575 Op::ListIntegrations,
576 Op::ConnectIntegration,
AI Gateway: OpenAI's format, open models, and your own providers577 Op::UpdateIntegration,
The code page reads like a forge: a branch menu, search and a Code button above the files578 Op::DisconnectIntegration,
579 Op::TestIntegration,
580 Op::GetModelRoutes,
581 Op::SetModelRoutes,
582 Op::GetContext,
583 Op::ImportIssue,
584 ],
585 ),
Merge main into Artifacts Phase 2586 (
Merge remote-tracking branch 'origin/claude/cool-newton-7nm8r9' into claude/cool-newton-7nm8r9587 "Customize",
588 "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.",
589 &[
590 Op::Customize(CustomizeOp::ListMarketplaces),
591 Op::Customize(CustomizeOp::AddMarketplace),
592 Op::Customize(CustomizeOp::RemoveMarketplace),
593 Op::Customize(CustomizeOp::RefreshMarketplace),
594 Op::Customize(CustomizeOp::Discover),
595 Op::Customize(CustomizeOp::ListPlugins),
596 Op::Customize(CustomizeOp::GetPlugin),
597 Op::Customize(CustomizeOp::InstallPlugin),
598 Op::Customize(CustomizeOp::SetPluginEnabled),
599 Op::Customize(CustomizeOp::UninstallPlugin),
600 Op::Customize(CustomizeOp::UpdatePlugin),
601 Op::Customize(CustomizeOp::ListPluginAgents),
602 Op::Customize(CustomizeOp::ListConnectors),
603 Op::Customize(CustomizeOp::GetConnector),
604 Op::Customize(CustomizeOp::AddConnector),
605 Op::Customize(CustomizeOp::SetConnectorKey),
606 Op::Customize(CustomizeOp::RemoveConnector),
607 Op::Customize(CustomizeOp::RefreshConnector),
608 Op::Customize(CustomizeOp::GrantConnector),
609 Op::Customize(CustomizeOp::RevokeConnector),
610 Op::Customize(CustomizeOp::Bundle),
611 ],
612 ),
613 (
Merge main into Artifacts Phase 2614 "Artifacts",
615 "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.",
616 &[
617 Op::Folios(FoliosOp::List),
618 Op::Folios(FoliosOp::Search),
619 Op::Folios(FoliosOp::Get),
620 Op::Folios(FoliosOp::GetContent),
621 Op::Folios(FoliosOp::ListVersions),
622 Op::Folios(FoliosOp::GetAccess),
623 Op::Folios(FoliosOp::ListTemplates),
624 Op::Folios(FoliosOp::ListSpaces),
625 Op::Folios(FoliosOp::QueryDataset),
626 Op::Folios(FoliosOp::Create),
627 Op::Folios(FoliosOp::Update),
628 Op::Folios(FoliosOp::Edit),
629 Op::Folios(FoliosOp::Trash),
630 Op::Folios(FoliosOp::Restore),
631 Op::Folios(FoliosOp::RestoreVersion),
632 Op::Folios(FoliosOp::SetAccess),
633 Op::Folios(FoliosOp::Purge),
634 ],
635 ),
The code page reads like a forge: a branch menu, search and a Code button above the files636];
637
638/// The section of the API reference an operation is listed under.
639fn tag(op: Op) -> &'static str {
640 SECTIONS
641 .iter()
642 .find(|(_, _, ops)| ops.contains(&op))
643 .map_or("Repositories", |(name, _, _)| name)
644}
645
646/// What an operation's page is called, as a short sentence.
647fn title(op: Op) -> &'static str {
648 match op {
649 Op::Whoami => "Get the current user",
Merge branch 'worktree-agent-ad7c6d88d93adc817'650 Op::GetWorkspace => "Get a workspace",
The code page reads like a forge: a branch menu, search and a Code button above the files651 Op::CreateWorkspace => "Create a workspace",
652 Op::DeleteWorkspace => "Delete a workspace",
653 Op::UpdateWorkspace => "Update a workspace",
Merge main (membership, two-factor, GitHub repo roles) into tokens654 Op::ListMembers => "List a workspace's members",
655 Op::UpdateMember => "Change a member's role",
656 Op::RemoveMember => "Remove a member",
657 Op::TransferOwnership => "Transfer a workspace's ownership",
658 Op::LeaveWorkspace => "Leave a workspace",
The code page reads like a forge: a branch menu, search and a Code button above the files659 Op::ListEmails => "List your email addresses",
660 Op::AddEmail => "Add an email address",
Merge email confirmation gate: a code and a link, nothing until confirmed (identity 0036)661 Op::ConfirmEmail => "Confirm an email address",
The code page reads like a forge: a branch menu, search and a Code button above the files662 Op::RemoveEmail => "Remove an email address",
663 Op::UpdateEmailSettings => "Change your email settings",
664 Op::ListInvites => "List your invites",
665 Op::CreateInvite => "Create an invite",
666 Op::RevokeInvite => "Revoke an invite",
667 Op::ListWorkspaceInvites => "List a workspace's invites",
668 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)669 Op::ListInvitations => "List your workspace invitations",
670 Op::AcceptInvitation => "Accept a workspace invitation",
671 Op::DeclineInvitation => "Decline a workspace invitation",
The code page reads like a forge: a branch menu, search and a Code button above the files672 Op::RevokeWorkspaceInvite => "Revoke a workspace's invite",
673 Op::TransferRepo => "Transfer a repository",
674 Op::RenameRepo => "Rename a repository",
675 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.676 Op::CreateBranch => "Create a branch",
677 Op::DeleteBranch => "Delete a branch",
The code page reads like a forge: a branch menu, search and a Code button above the files678 Op::ArchiveRepo => "Archive a repository",
679 Op::UnarchiveRepo => "Unarchive a repository",
680 Op::SetRepoVisibility => "Change a repository's visibility",
681 Op::DeleteRepo => "Delete a repository",
682 Op::ListDeletedRepos => "List recently deleted repositories",
683 Op::RestoreRepo => "Restore a deleted repository",
684 Op::PurgeRepo => "Purge a deleted repository",
685 Op::ListRepos => "List repositories",
686 Op::GetRepo => "Get a repository",
687 Op::CreateRepo => "Create a repository",
688 Op::UpdateRepo => "Update a repository",
689 Op::GetRepoSettings => "Get repository settings",
690 Op::UpdateRepoSettings => "Update repository settings",
691 Op::ListCheckNames => "List check names",
692 Op::GetMergeQueue => "Get the merge queue",
693 Op::MessageAgent => "Message an agent",
694 Op::AnswerMessage => "Answer a message",
695 Op::TakeMessages => "Take new messages",
696 Op::Remember => "Remember something",
697 Op::Recall => "Recall memory",
698 Op::SearchContext => "Search the context hub",
699 Op::GetEntity => "Get a catalog entry",
700 Op::Search => "Search g1t",
701 Op::ListIssues => "List issues",
702 Op::GetIssue => "Get an issue",
703 Op::CreateIssue => "Create an issue",
704 Op::UpdateIssue => "Update an issue",
705 Op::CloseIssue => "Close an issue",
706 Op::ReopenIssue => "Reopen an issue",
707 Op::AssignIssue => "Assign an issue to g1t",
708 Op::Delegate => "Put an agent on it",
709 Op::PlanWork => "Plan work",
710 Op::GetPlan => "Get a plan",
711 Op::ApplyPlan => "Apply a plan",
712 Op::ListLabels => "List labels",
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar713 Op::CreateLabel => "Create a label",
714 Op::UpdateLabel => "Update a label",
715 Op::DeleteLabel => "Delete a label",
716 Op::AddDefaultLabels => "Add the default labels",
717 Op::ListIssueLabels => "List an issue's labels",
718 Op::AddIssueLabels => "Add labels to an issue",
719 Op::SetIssueLabels => "Set an issue's labels",
720 Op::RemoveIssueLabels => "Remove labels from an issue",
721 Op::ListMilestones => "List milestones",
722 Op::GetMilestone => "Get a milestone",
723 Op::CreateMilestone => "Create a milestone",
724 Op::UpdateMilestone => "Update a milestone",
725 Op::DeleteMilestone => "Delete a milestone",
726 Op::UpdatePullRequest => "Update a pull request",
The code page reads like a forge: a branch menu, search and a Code button above the files727 Op::AddComment => "Add a comment",
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts728 Op::EditComment => "Edit a comment",
729 Op::DeleteComment => "Delete a comment",
The code page reads like a forge: a branch menu, search and a Code button above the files730 Op::ReviewPullRequest => "Review a pull request",
731 Op::ListPullRequests => "List pull requests",
732 Op::GetPullRequest => "Get a pull request",
733 Op::CreatePullRequest => "Create a pull request",
734 Op::RecordSession => "Record session entries",
735 Op::ReadSession => "Read a session",
736 Op::MarkPullRequestReady => "Mark a pull request ready",
737 Op::ClosePullRequest => "Close a pull request",
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts738 Op::ReopenPullRequest => "Reopen a pull request",
739 Op::ConvertPullRequestToDraft => "Convert a pull request to a draft",
The code page reads like a forge: a branch menu, search and a Code button above the files740 Op::GetPullRequestChanges => "Get a pull request's changes",
741 Op::MergePullRequest => "Merge a pull request",
742 Op::ListEvents => "List repository events",
743 Op::ListIntegrations => "List integrations",
744 Op::ConnectIntegration => "Connect an integration",
AI Gateway: OpenAI's format, open models, and your own providers745 Op::UpdateIntegration => "Update an integration",
The code page reads like a forge: a branch menu, search and a Code button above the files746 Op::DisconnectIntegration => "Disconnect an integration",
747 Op::TestIntegration => "Test an integration",
748 Op::GetContext => "Look up a ticket",
749 Op::ImportIssue => "Import an issue",
750 Op::GetModelRoutes => "Get model routes",
751 Op::SetModelRoutes => "Set model routes",
752 Op::ListWebhooks => "List webhooks",
753 Op::CreateWebhook => "Create a webhook",
754 Op::UpdateWebhook => "Update a webhook",
755 Op::DeleteWebhook => "Delete a webhook",
756 Op::PingWebhook => "Ping a webhook",
757 Op::ListWebhookDeliveries => "List webhook deliveries",
758 Op::RedeliverWebhook => "Redeliver a webhook delivery",
759 Op::ListWorkflows => "List workflows",
760 Op::ListWorkflowRuns => "List workflow runs",
761 Op::GetWorkflowRun => "Get a workflow run",
762 Op::GetJobLogs => "Get a job's log",
763 Op::DispatchWorkflow => "Run a workflow",
764 Op::CancelWorkflowRun => "Cancel a workflow run",
765 Op::RerunWorkflowRun => "Re-run a workflow run",
766 Op::UpdateWorkflow => "Turn a workflow on or off",
767 Op::ListActionsSecrets => "List secrets",
768 Op::SetActionsSecret => "Set a secret",
769 Op::DeleteActionsSecret => "Delete a secret",
770 Op::ListActionsVariables => "List variables",
771 Op::SetActionsVariable => "Set a variable",
772 Op::DeleteActionsVariable => "Delete a variable",
773 Op::ListRunners => "List self-hosted runners",
774 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.775 Op::GetAgentComputer => "Get an agent's computer",
776 Op::WakeAgentComputer => "Wake an agent's computer",
777 Op::SleepAgentComputer => "Put an agent's computer to sleep",
778 Op::ResetAgentComputer => "Reset an agent's computer",
779 Op::ListAgentComputerCommands => "List an agent's computer's commands",
The code page reads like a forge: a branch menu, search and a Code button above the files780 Op::GetRunnerSettings => "Get runner settings",
781 Op::CreateRunnerRegistrationToken => "Create a runner registration token",
782 Op::RemoveRunner => "Remove a self-hosted runner",
783 Op::CreateRunnerGroup => "Create a runner group",
784 Op::UpdateRunnerGroup => "Change a runner group",
785 Op::DeleteRunnerGroup => "Delete a runner group",
786 Op::UpdateRunnerSettings => "Change runner settings",
787 Op::ListCollaborators => "List who has access",
788 Op::AddCollaborator => "Add a collaborator",
789 Op::UpdateCollaborator => "Change a collaborator's role",
790 Op::RemoveCollaborator => "Remove a collaborator",
791 Op::GetCollaboratorPermission => "Get someone's permission",
792 Op::ListRepoInvitations => "List a repository's invitations",
793 Op::RevokeRepoInvitation => "Revoke a repository invitation",
794 Op::ListMyRepoInvitations => "List your repository invitations",
795 Op::AcceptRepoInvitation => "Accept a repository invitation",
796 Op::DeclineRepoInvitation => "Decline a repository invitation",
797 Op::SetBasePermission => "Set the base permission",
798 Op::ListOutsideCollaborators => "List outside collaborators",
799 Op::ListSecurityAlerts => "List security alerts",
800 Op::DismissSecurityAlert => "Dismiss a security alert",
801 Op::ReopenSecurityAlert => "Reopen a security alert",
API: notifications over REST and MCP, with notifications scopes802 Op::ListNotifications => "List notifications",
803 Op::MarkNotificationsRead => "Mark notifications read",
804 Op::GetNotificationThread => "Get a thread",
805 Op::MarkThreadRead => "Mark a thread read",
806 Op::MarkThreadDone => "Mark a thread done",
807 Op::SaveThread => "Save a thread",
808 Op::SnoozeThread => "Snooze a thread",
809 Op::GetThreadSubscription => "Get a thread subscription",
810 Op::SetThreadSubscription => "Set a thread subscription",
811 Op::DeleteThreadSubscription => "Unsubscribe from a thread",
812 Op::GetRepoSubscription => "Get how you watch a repository",
813 Op::SetRepoSubscription => "Watch a repository",
814 Op::DeleteRepoSubscription => "Stop watching a repository",
815 Op::ListWatchedRepos => "List repositories you watch",
API: pinned projects over REST and MCP816 Op::ListPinnedProjects => "List your pinned projects",
Usage, Billing settings and prepaid AI credit; fixes from the UX audit817 Op::GetUsage => "Get a workspace's usage",
818 Op::GetBudget => "Get a workspace's budget",
819 Op::SetBudget => "Change a workspace's budget",
820 Op::GetAiCredit => "Get a workspace's AI credit",
821 Op::BuyAiCredit => "Buy AI credit",
822 Op::ListInvoices => "List a workspace's invoices",
823 Op::GetBillingDetails => "Get a workspace's billing details",
Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens824 Op::ListGatewayRequests => "List a workspace's AI Gateway requests",
API: pinned projects over REST and MCP825 Op::PinProject => "Pin a project",
826 Op::UnpinProject => "Unpin a project",
827 Op::ReorderPinnedProjects => "Reorder your pinned projects",
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb97828 Op::ListProjects => "List a workspace's projects",
829 Op::GetProject => "Get a project",
830 Op::UpdateProject => "Update a project",
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar831 Op::ListTeams => "List teams",
832 Op::GetTeam => "Get a team",
833 Op::CreateTeam => "Create a team",
834 Op::UpdateTeam => "Update a team",
835 Op::DeleteTeam => "Delete a team",
836 Op::ListTeamMembers => "List a team's members",
837 Op::SetTeamMember => "Add or change a team member",
838 Op::RemoveTeamMember => "Remove a team member",
839 Op::ListChildTeams => "List child teams",
840 Op::ListTeamRepos => "List a team's repositories",
841 Op::SetTeamRepo => "Give a team a role on a repository",
842 Op::RemoveTeamRepo => "Remove a team from a repository",
843 Op::SetTeamReviewAssignment => "Set a team's review assignment",
844 Op::ListUserTeams => "List someone's teams",
845 Op::RequestReviewers => "Request reviewers",
846 Op::RemoveRequestedReviewers => "Remove requested reviewers",
847 Op::GetCodeownersErrors => "List CODEOWNERS errors",
848 Op::Security(op) => op.title(),
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge849 Op::Rules(op) => op.title(),
Merge checks: statuses and check runs on every commit850 Op::Checks(op) => op.title(),
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb97851 Op::About(op) => op.title(),
852 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.853 Op::Telemetry(op) => op.title(),
Merge branch 'worktree-agent-a3abfcce648e87dca'854 Op::Protection(op) => op.title(),
API and MCP for a workspace's personal access token rules, members' tokens and approvals855 Op::Tokens(op) => op.title(),
Actions: OIDC tokens, the toolkit's cache and artifact services, and artifacts in R2856 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.857 Op::Archives(op) => op.title(),
Merge branch 'worktree-agent-a5a5de74d8863d554' into worktree-agent-a16631325aecf58ca858 Op::DeployKeys(op) => op.title(),
Merge packages: roles, Actions access, source label, soft delete, API859 Op::Packages(op) => op.title(),
Merge main into Artifacts Phase 2860 Op::Folios(op) => op.title(),
Merge remote-tracking branch 'origin/claude/cool-newton-7nm8r9' into claude/cool-newton-7nm8r9861 Op::Customize(op) => op.title(),
The code page reads like a forge: a branch menu, search and a Code button above the files862 }
863}
864
865/// Why an operation can be refused with `402 payment_required`, if it
866/// can: the ones that start an agent, when the workspace has no credit,
867/// and the ones that make a repository private in a workspace, when a free
868/// workspace's private storage has no room for it.
869fn may_need_payment(op: Op) -> Option<&'static str> {
870 match op {
871 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.872 Op::WakeAgentComputer => Some("The workspace's plan refuses compute: it is paused, or over its limit."),
The code page reads like a forge: a branch menu, search and a Code button above the files873 Op::UpdateRepo | Op::SetRepoVisibility | Op::TransferRepo => Some(
874 "A free workspace's private storage has no room for this private repository.",
875 ),
876 _ => None,
877 }
878}
879
880/// What the reference says beyond each operation's own description, keyed
881/// by operation id, written by hand from what the services return: `notes`
882/// (Markdown, added to the description) and example `params` (path),
883/// `query`, `request` (body) and `response`.
884const REFERENCE: &str = include_str!("reference.json");
885
886fn examples() -> Map<String, Value> {
887 match serde_json::from_str(REFERENCE) {
888 Ok(Value::Object(examples)) => examples,
889 _ => Map::new(),
890 }
891}
892
893/// `/repos/:owner/:name` as OpenAPI writes it: `/repos/{owner}/{name}`.
894fn openapi_path(route: &Route) -> String {
895 route
896 .path
897 .split('/')
898 .map(|segment| match segment.strip_prefix(':') {
899 Some(name) => format!("{{{name}}}"),
900 None => segment.to_owned(),
901 })
902 .collect::<Vec<_>>()
903 .join("/")
904}
905
906fn error_response(description: &str) -> Value {
907 json!({
908 "description": description,
909 "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } },
910 })
911}
912
913/// A parameter in the path or the query, described by the operation's
914/// input schema where it has the same name.
915fn parameter(name: &str, place: &str, required: bool, schema: Option<&Value>) -> Value {
916 let mut schema = schema.cloned().unwrap_or_else(|| json!({ "type": "string" }));
917 let description = match name {
918 "owner" => Some(Value::from("The workspace that owns the repository.")),
919 "name" => Some(Value::from("The repository's name.")),
920 _ => schema.as_object_mut().and_then(|schema| schema.remove("description")),
921 };
922 let mut parameter = json!({
923 "name": name,
924 "in": place,
925 "required": required,
926 "schema": schema,
927 });
928 if let Some(description) = description {
929 parameter["description"] = description;
930 }
931 parameter
932}
933
934/// The operation id of a route. An operation reached at a workspace's
935/// address as well as a repository's is documented once for each, with its
936/// own id; GitHub's alternative addresses for one operation keep GitHub's
937/// names.
938fn operation_id(route: &Route) -> String {
939 let op = route.op;
940 let base = match (route.method, route.path.rsplit('/').next().unwrap_or_default()) {
941 ("PUT", "enable") => "enable_workflow".to_owned(),
942 ("PUT", "disable") => "disable_workflow".to_owned(),
943 ("POST", "rerun-failed-jobs") => "rerun_failed_jobs".to_owned(),
Merge Actions runs: summaries, attempts and re-runs, graceful cancel, log downloads, badges (actions 0009)944 ("POST", "rerun") if route.path.contains("/jobs/:job/") => "rerun_job".to_owned(),
945 ("POST", "force-cancel") => "force_cancel_workflow_run".to_owned(),
946 ("GET", ":attempt") => "get_workflow_run_attempt".to_owned(),
The code page reads like a forge: a branch menu, search and a Code button above the files947 ("PATCH", ":setting") => "update_actions_variable".to_owned(),
948 ("GET", "runs") if route.path.contains("/workflows/:workflow/") => "list_runs_of_workflow".to_owned(),
API: notifications over REST and MCP, with notifications scopes949 // One repository's notifications, and an issue's subscription by
950 // its number rather than a thread's id.
951 (_, "notifications") if route.path.starts_with("/repos/") => match op {
952 Op::ListNotifications => "list_repo_notifications".to_owned(),
953 _ => "mark_repo_notifications_read".to_owned(),
954 },
955 (method, "subscription") if route.path.contains("/issues/:number/") => match method {
956 "GET" => "get_issue_subscription".to_owned(),
957 "PUT" => "set_issue_subscription".to_owned(),
958 _ => "delete_issue_subscription".to_owned(),
959 },
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar960 // One label off an issue, by its name in the path.
961 ("DELETE", ":label") if route.path.contains("/issues/:number/") => "remove_issue_label".to_owned(),
API: notifications over REST and MCP, with notifications scopes962 ("DELETE", "saved") => "unsave_thread".to_owned(),
963 ("DELETE", "snooze") => "unsnooze_thread".to_owned(),
The code page reads like a forge: a branch menu, search and a Code button above the files964 _ => op.name().to_owned(),
965 };
966 if route.path.starts_with("/workspaces/") && ROUTES.iter().any(|other| other.op == op && other.path.starts_with("/repos/")) {
967 format!("{base}_for_workspace")
968 } else {
969 base
970 }
971}
972
973/// The summary of a route: its operation's title, or for one of GitHub's
974/// alternative addresses, what that address does.
975fn summary(route: &Route, id: &str) -> String {
976 let base = match id.trim_end_matches("_for_workspace") {
977 "enable_workflow" => "Turn a workflow on",
978 "disable_workflow" => "Turn a workflow off",
979 "rerun_failed_jobs" => "Re-run failed jobs",
Merge Actions runs: summaries, attempts and re-runs, graceful cancel, log downloads, badges (actions 0009)980 "rerun_job" => "Re-run a job",
981 "force_cancel_workflow_run" => "Force-cancel a workflow run",
982 "get_workflow_run_attempt" => "Get a workflow run attempt",
The code page reads like a forge: a branch menu, search and a Code button above the files983 "update_actions_variable" => "Update a variable",
984 "list_runs_of_workflow" => "List a workflow's runs",
API: notifications over REST and MCP, with notifications scopes985 "list_repo_notifications" => "List a repository's notifications",
986 "mark_repo_notifications_read" => "Mark a repository's notifications read",
987 "get_issue_subscription" => "Get your subscription to an issue",
988 "set_issue_subscription" => "Subscribe to an issue",
989 "delete_issue_subscription" => "Unsubscribe from an issue",
990 "unsave_thread" => "Unsave a thread",
991 "unsnooze_thread" => "Bring a snoozed thread back",
The code page reads like a forge: a branch menu, search and a Code button above the files992 _ => title(route.op),
993 };
994 if id.ends_with("_for_workspace") {
995 format!("{base} for a workspace")
996 } else {
997 base.to_owned()
998 }
999}
1000
1001fn operation(route: &Route) -> Value {
1002 let op = route.op;
1003 let path_params: Vec<&str> = route.params().collect();
Merge checks: statuses and check runs on every commit1004 // `owner` and `name` in the path stand for the operation's `repo` input,
1005 // so a `name` in the body, such as a check run's, is the body's own.
1006 let stands_for_repo =
1007 |name: &str| matches!(name, "owner" | "name") && path_params.contains(&"owner") && path_params.contains(&"name");
1008 let covered = |name: &str| name == "repo" || (path_params.contains(&name) && !stands_for_repo(name));
The code page reads like a forge: a branch menu, search and a Code button above the files1009 let all_properties = op.properties();
1010 let mut properties = all_properties.clone();
1011 properties.retain(|name, _| !covered(name));
1012 let required: Vec<String> = op
1013 .required()
1014 .into_iter()
1015 .filter(|name| !covered(name))
1016 .collect();
1017
1018 let mut parameters: Vec<Value> = path_params
1019 .iter()
Merge checks: statuses and check runs on every commit1020 .map(|name| parameter(name, "path", true, if stands_for_repo(name) { None } else { all_properties.get(*name) }))
The code page reads like a forge: a branch menu, search and a Code button above the files1021 .collect();
1022 let mut body = Value::Null;
1023 if route.method == "GET" {
1024 for (name, key) in route.query {
1025 parameters.push(parameter(
1026 name,
1027 "query",
1028 required.iter().any(|required| required == key),
1029 properties.get(*key),
1030 ));
1031 }
1032 } else if !properties.is_empty() {
1033 let mut schema = json!({ "type": "object", "properties": properties });
1034 if !required.is_empty() {
1035 schema["required"] = json!(required);
1036 }
1037 body = json!({
1038 "required": !required.is_empty(),
1039 "content": { "application/json": { "schema": schema } },
1040 });
1041 }
1042
1043 let id = operation_id(route);
1044 let mut responses = Map::new();
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts1045 if route.no_content() {
1046 responses.insert("204".into(), json!({ "description": "Success. There is no body." }));
1047 } else {
1048 responses.insert(
1049 "200".into(),
1050 json!({
1051 "description": "Success.",
1052 "content": { "application/json": { "schema": {} } },
1053 }),
1054 );
1055 }
The code page reads like a forge: a branch menu, search and a Code button above the files1056 responses.insert(
1057 "401".into(),
1058 error_response("A token is required, or the one sent is not valid."),
1059 );
1060 if let Some(reason) = may_need_payment(op) {
1061 responses.insert("402".into(), error_response(reason));
1062 }
1063 responses.insert(
1064 "403".into(),
1065 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."),
1066 );
1067 if !matches!(op, Op::Whoami | Op::ListRepos | Op::Search) {
1068 responses.insert("404".into(), error_response("It does not exist, or you cannot see it."));
1069 }
1070 if route.method != "GET" {
1071 responses.insert(
1072 "409".into(),
1073 error_response("The request conflicts with the current state."),
1074 );
1075 }
1076 if op != Op::Whoami {
1077 responses.insert("422".into(), error_response("The input is not valid."));
1078 }
1079 // Public data can be read without a token; everything else needs one.
1080 let scope: Vec<&str> = scope_for(op.name()).map(|scope| scope.as_str()).into_iter().collect();
1081 let security = if op.needs_user() {
1082 json!([{ "token": scope }])
1083 } else {
1084 json!([{ "token": scope }, {}])
1085 };
1086 let (tool, action) = crate::tools::TOOLS
1087 .iter()
1088 .find_map(|tool| {
1089 tool.actions
1090 .iter()
1091 .find(|action| action.op == op)
1092 .map(|action| (tool.name, action.name))
1093 })
1094 .unwrap_or_default();
1095 let mut described = json!({
1096 "operationId": id,
1097 "tags": [tag(op)],
1098 "summary": summary(route, &id),
1099 "description": op.description(),
1100 "x-operation": op.name(),
1101 "x-mcp-tool": tool,
1102 "x-mcp-action": action,
1103 "x-scope": scope.first().copied(),
1104 "security": security,
1105 "parameters": parameters,
1106 "responses": responses,
1107 });
1108 if !body.is_null() {
1109 described["requestBody"] = body;
1110 }
1111 described
1112}
1113
1114/// Entries for device sign-in, which is not an operation.
1115fn onboarding() -> Map<String, Value> {
1116 let paths = json!({
1117 "/device/code": {
1118 "post": {
1119 "operationId": "device_code",
1120 "tags": ["Accounts"],
1121 "summary": "Start signing in",
1122 "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`.",
1123 "security": [],
1124 "requestBody": {
1125 "content": { "application/json": { "schema": {
1126 "type": "object",
1127 "properties": {
1128 "client_name": {
1129 "type": "string",
1130 "description": "What is asking, shown to the person approving. For example, Claude Code.",
1131 },
1132 },
1133 } } },
1134 },
1135 "responses": { "200": {
1136 "description": "The codes for this sign-in.",
1137 "content": { "application/json": { "schema": {
1138 "type": "object",
1139 "properties": {
1140 "device_code": { "type": "string", "description": "Secret. Send it to /device/token." },
1141 "user_code": { "type": "string", "description": "Shown to the person, like WDJB-MJHT." },
1142 "verification_uri": { "type": "string" },
1143 "verification_uri_complete": {
1144 "type": "string",
1145 "description": "The link to give the person; it carries the code.",
1146 },
1147 "expires_in": { "type": "integer", "description": "Seconds until the codes expire." },
1148 "interval": { "type": "integer", "description": "Seconds to wait between polls." },
1149 },
1150 } } },
1151 } },
1152 },
1153 },
1154 "/device/token": {
1155 "post": {
1156 "operationId": "device_token",
1157 "tags": ["Accounts"],
1158 "summary": "Finish signing in",
1159 "description": "Asks whether the person has approved. Poll no faster than the interval. The token is returned once.",
1160 "security": [],
1161 "requestBody": {
1162 "required": true,
1163 "content": { "application/json": { "schema": {
1164 "type": "object",
1165 "required": ["device_code"],
1166 "properties": { "device_code": { "type": "string" } },
1167 } } },
1168 },
1169 "responses": { "200": {
1170 "description": "The state of the sign-in.",
1171 "content": { "application/json": { "schema": {
1172 "type": "object",
1173 "required": ["status"],
1174 "properties": {
1175 "status": { "type": "string", "enum": ["pending", "approved", "denied", "expired"] },
1176 "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 calendar1177 "username": { "type": "string", "description": "Lowercased: what the account is found and linked by." },
1178 "display_username": { "type": "string", "description": "The username as its owner wrote it; the same as username when they chose no case." },
The code page reads like a forge: a branch menu, search and a Code button above the files1179 "verified": {
1180 "type": "boolean",
1181 "description": "Whether the account's email is confirmed.",
1182 },
1183 },
1184 } } },
1185 } },
1186 },
1187 },
1188 });
1189 match paths {
1190 Value::Object(paths) => paths,
1191 _ => Map::new(),
1192 }
1193}
1194
1195
1196/// Puts each operation's examples, where it has them, into its request
1197/// and response. Path and query values go under `x-example-params` and
1198/// `x-example-query`, which tools that build a request can use.
1199fn attach_examples(paths: &mut Map<String, Value>) {
1200 let examples = examples();
1201 for methods in paths.values_mut() {
1202 let Some(methods) = methods.as_object_mut() else { continue };
1203 for operation in methods.values_mut() {
1204 let id = operation["operationId"].as_str().unwrap_or_default().to_owned();
1205 let name = operation["x-operation"].as_str().unwrap_or_default().to_owned();
1206 let Some(example) = examples.get(&id).or_else(|| examples.get(&name)) else {
1207 continue;
1208 };
1209 if let Some(notes) = example.get("notes").and_then(Value::as_str) {
1210 let description = operation["description"].as_str().unwrap_or_default();
1211 operation["description"] = json!(format!("{description}\n\n{notes}"));
1212 }
1213 if let Some(response) = example.get("response") {
1214 let content = &mut operation["responses"]["200"]["content"]["application/json"];
1215 if content.is_object() {
1216 content["example"] = response.clone();
1217 }
1218 }
1219 if let Some(request) = example.get("request") {
1220 let content = &mut operation["requestBody"]["content"]["application/json"];
1221 if content.is_object() {
1222 content["example"] = request.clone();
1223 }
1224 }
1225 for (key, extension) in [("params", "x-example-params"), ("query", "x-example-query")] {
1226 if let Some(values) = example.get(key) {
1227 operation[extension] = values.clone();
1228 }
1229 }
1230 }
1231 }
1232}
1233
1234pub fn document() -> Value {
1235 let mut paths = onboarding();
1236 for route in ROUTES {
1237 let entry = paths
1238 .entry(openapi_path(route))
1239 .or_insert_with(|| json!({}));
1240 entry[route.method.to_lowercase()] = operation(route);
1241 }
1242 attach_examples(&mut paths);
1243 let tags: Vec<Value> = SECTIONS
1244 .iter()
1245 .map(|(name, description, ops)| {
1246 json!({
1247 "name": name,
1248 "description": description,
1249 // The section's operations in reading order, by MCP tool name.
1250 "x-tools": ops.iter().map(|op| op.name()).collect::<Vec<_>>(),
1251 })
1252 })
1253 .collect();
1254 let codes = ["unauthenticated", "payment_required", "forbidden", "not_found", "conflict", "invalid"];
1255 json!({
1256 "openapi": "3.1.0",
1257 "info": {
1258 "title": "g1t API",
1259 "version": "1",
1260 "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.",
1261 "license": { "name": "MIT", "identifier": "MIT" },
1262 },
1263 "servers": [{ "url": "https://api.g1t.sh" }],
1264 "security": [{ "token": [] }, {}],
1265 "tags": tags,
1266 "paths": paths,
1267 "components": {
1268 "securitySchemes": {
1269 "token": {
1270 "type": "http",
1271 "scheme": "bearer",
1272 "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.",
1273 },
1274 },
1275 "schemas": {
1276 "Error": {
1277 "type": "object",
1278 "required": ["error"],
1279 "properties": {
1280 "error": {
1281 "type": "object",
1282 "required": ["code", "message"],
1283 "properties": {
1284 "code": { "type": "string", "enum": codes },
1285 "message": { "type": "string" },
1286 "needed_scope": {
1287 "type": "string",
1288 "description": "On a 403 for an access token without the scope the call needs: that scope, such as `issues:write`.",
1289 },
1290 },
1291 },
1292 },
1293 },
1294 },
1295 },
1296 })
1297}
1298
1299#[cfg(test)]
1300mod tests {
1301 use super::*;
1302
1303 #[test]
1304 fn every_route_is_documented_once() {
1305 let document = document();
1306 let mut ids = Vec::new();
1307 for (_, methods) in document["paths"].as_object().unwrap() {
1308 for (_, operation) in methods.as_object().unwrap() {
1309 ids.push(operation["operationId"].as_str().unwrap().to_owned());
1310 }
1311 }
1312 for op in Op::ALL {
1313 assert_eq!(
1314 ids.iter().filter(|id| *id == op.name()).count(),
1315 1,
1316 "{}",
1317 op.name()
1318 );
1319 }
1320 let mut unique = ids.clone();
1321 unique.sort();
1322 unique.dedup();
1323 assert_eq!(unique.len(), ids.len(), "operation ids repeat");
1324 }
1325
1326 #[test]
1327 fn path_and_query_inputs_are_not_repeated_in_the_body() {
1328 let document = document();
1329 let merge = &document["paths"]["/repos/{owner}/{name}/pulls/{number}/merge"]["post"];
1330 let body = &merge["requestBody"]["content"]["application/json"]["schema"]["properties"];
1331 assert!(body.get("keep_issue_open").is_some());
1332 assert!(body.get("repo").is_none() && body.get("number").is_none());
1333 let list = &document["paths"]["/repos"]["get"];
1334 assert_eq!(list["parameters"][0]["name"], "q");
1335 assert!(list.get("requestBody").is_none());
1336 }
1337
1338 #[test]
1339 fn every_operation_is_in_one_section() {
1340 for op in Op::ALL {
1341 let sections = SECTIONS
1342 .iter()
1343 .filter(|(_, _, ops)| ops.contains(&op))
1344 .count();
1345 assert_eq!(sections, 1, "{}", op.name());
1346 }
1347 }
1348
1349 #[test]
1350 fn titles_read_as_sentences() {
1351 assert_eq!(title(Op::CreateIssue), "Create an issue");
1352 assert_eq!(title(Op::Whoami), "Get the current user");
1353 }
1354
1355 #[test]
1356 fn every_operation_has_an_example_response() {
1357 let examples = examples();
1358 assert!(!examples.is_empty(), "reference.json does not parse");
1359 let document = document();
1360 let mut known = Vec::new();
1361 for (path, methods) in document["paths"].as_object().unwrap() {
1362 for (method, operation) in methods.as_object().unwrap() {
1363 known.push(operation["operationId"].as_str().unwrap().to_owned());
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts1364 // Nothing to show for a success without a body.
1365 if operation["responses"]["204"].is_object() {
1366 continue;
1367 }
The code page reads like a forge: a branch menu, search and a Code button above the files1368 let example = &operation["responses"]["200"]["content"]["application/json"]["example"];
1369 assert!(!example.is_null(), "{method} {path} has no example response");
1370 }
1371 }
1372 for id in examples.keys() {
1373 assert!(known.contains(id), "reference.json names {id}, which is not an operation");
1374 }
1375 }
1376
1377 #[test]
1378 fn example_requests_send_only_what_the_body_takes() {
1379 let document = document();
1380 for (path, methods) in document["paths"].as_object().unwrap() {
1381 for (method, operation) in methods.as_object().unwrap() {
1382 let content = &operation["requestBody"]["content"]["application/json"];
1383 let Some(example) = content["example"].as_object() else { continue };
1384 let properties = &content["schema"]["properties"];
1385 for key in example.keys() {
1386 assert!(!properties[key].is_null(), "{method} {path}: {key} is not in the body");
1387 }
1388 }
1389 }
1390 }
1391
1392 /// The docs site's copy of the document. Run with `G1T_WRITE_OPENAPI=1`
1393 /// to rewrite it after changing an operation.
1394 #[test]
1395 fn the_docs_copy_is_current() {
1396 let path = concat!(env!("CARGO_MANIFEST_DIR"), "/../docs/src/data/openapi.json");
1397 let current = serde_json::to_string_pretty(&document()).unwrap() + "\n";
1398 if std::env::var_os("G1T_WRITE_OPENAPI").is_some() {
1399 std::fs::write(path, &current).unwrap();
1400 return;
1401 }
1402 let copy = std::fs::read_to_string(path).unwrap_or_default().replace("\r\n", "\n");
1403 assert!(
1404 copy == current,
1405 "apps/docs/src/data/openapi.json is out of date: run G1T_WRITE_OPENAPI=1 cargo test -p g1t-api openapi"
1406 );
1407 }
1408
1409 /// The reference shows responses as they are sent: `snake_case`.
1410 #[test]
1411 fn example_responses_are_snake_case() {
1412 let document = document();
1413 for (path, methods) in document["paths"].as_object().unwrap() {
1414 for (method, operation) in methods.as_object().unwrap() {
1415 let example = &operation["responses"]["200"]["content"]["application/json"]["example"];
1416 let leaked = g1t_kit::wire::camel_case_keys(example);
1417 assert!(leaked.is_empty(), "{method} {path} shows {leaked:?}");
1418 }
1419 }
1420 }
1421
1422 /// Examples never hold anything that reads as a real credential, which
1423 /// secret scanners rightly flag in a public repository: they end in `…`
1424 /// after the prefix, as `whsec_…` and `g1t_…` do.
1425 #[test]
1426 fn examples_hold_no_real_looking_secrets() {
1427 let prefixes = ["whsec_", "g1t_", "g1tr_", "g1trt_", "sk_live_", "sk_test_", "ghp_", "github_pat_", "xoxb-", "AKIA"];
1428 for (line, text) in REFERENCE.lines().enumerate() {
1429 for prefix in prefixes {
1430 let mut rest = text;
1431 while let Some(at) = rest.find(prefix) {
1432 let after = &rest[at + prefix.len()..];
1433 let run = after.chars().take_while(|c| c.is_ascii_alphanumeric()).count();
1434 assert!(
1435 run < 12,
1436 "reference.json line {}: `{prefix}` followed by {run} characters reads as a real secret; write `{prefix}…`",
1437 line + 1
1438 );
1439 rest = after;
1440 }
1441 }
1442 }
1443 }
1444}

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