Skip to content
Sign up

flagon-io/g1t

public
0
1,329 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.

API and MCP server in Rust; a public index at the API root1//! The OpenAPI document, generated from the same list the routes are.
Merge branch 'worktree-agent-ab2e39e11a6493412'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.
API and MCP server in Rust; a public index at the API root6
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step7use g1t_contracts::scopes::scope_for;
API and MCP server in Rust; a public index at the API root8use serde_json::{Map, Value, json};
9
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb9710use crate::about::AboutOp;
Actions: OIDC tokens, the toolkit's cache and artifact services, and artifacts in R211use crate::artifacts::ArtifactsOp;
Merge branch 'worktree-agent-a5a5de74d8863d554' into worktree-agent-a16631325aecf58ca12use crate::deploy_keys::DeployKeysOp;
Mirroring over REST and MCP13use crate::mirrors::MirrorsOp;
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb9714use crate::deployments::DeploymentsOp;
Merge packages: roles, Actions access, source label, soft delete, API15use crate::packages::PackagesOp;
Merge branch 'worktree-agent-a3abfcce648e87dca'16use crate::protection::ProtectionOp;
API and MCP for a workspace's personal access token rules, members' tokens and approvals17use crate::token_policy::TokenOp;
API and MCP server in Rust; a public index at the API root18use crate::operations::Op;
Merge checks: statuses and check runs on every commit19use crate::checks::ChecksOp;
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge20use crate::rules::RulesOp;
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar21use crate::security::SecurityOp;
API and MCP server in Rust; a public index at the API root22use crate::rest::{ROUTES, Route};
23
Merge branch 'worktree-agent-ab2e39e11a6493412'24/// The sections of the API reference: a name, what it covers, and its
25/// operations in the order a reader meets them.
26const SECTIONS: &[(&str, &str, &[Op])] = &[
27 (
28 "Accounts",
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look29 "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)30 &[Op::Whoami, Op::ListEmails, Op::AddEmail, Op::ConfirmEmail, Op::RemoveEmail, Op::UpdateEmailSettings],
Merge branch 'worktree-agent-ab2e39e11a6493412'31 ),
32 (
API: notifications over REST and MCP, with notifications scopes33 "Notifications",
34 "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.",
35 &[
36 Op::ListNotifications,
37 Op::MarkNotificationsRead,
38 Op::GetNotificationThread,
39 Op::MarkThreadRead,
40 Op::MarkThreadDone,
41 Op::SaveThread,
42 Op::SnoozeThread,
43 Op::GetThreadSubscription,
44 Op::SetThreadSubscription,
45 Op::DeleteThreadSubscription,
46 Op::GetRepoSubscription,
47 Op::SetRepoSubscription,
48 Op::DeleteRepoSubscription,
49 Op::ListWatchedRepos,
50 ],
51 ),
52 (
API: pinned projects over REST and MCP53 "Pinned projects",
54 "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.",
55 &[Op::ListPinnedProjects, Op::PinProject, Op::UnpinProject, Op::ReorderPinnedProjects],
56 ),
57 (
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb9758 "Projects",
59 "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.",
60 &[Op::ListProjects, Op::GetProject, Op::UpdateProject],
61 ),
62 (
Merge branch 'worktree-agent-ab2e39e11a6493412'63 "Workspaces",
64 "A workspace owns repositories and is the first part of their address. People and agents work in workspaces.",
Merge branch 'worktree-agent-ad7c6d88d93adc817'65 &[Op::GetWorkspace, Op::CreateWorkspace, Op::UpdateWorkspace, Op::DeleteWorkspace],
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look66 ),
67 (
API and MCP for a workspace's personal access token rules, members' tokens and approvals68 "Personal access tokens",
69 "A workspace's rules for its members' personal access tokens: whether classic and fine-grained tokens reach it, whether fine-grained tokens 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.",
70 &[
71 Op::Tokens(TokenOp::GetTokenPolicy),
72 Op::Tokens(TokenOp::SetTokenPolicy),
73 Op::Tokens(TokenOp::ListMemberTokens),
74 Op::Tokens(TokenOp::ListTokenRequests),
75 Op::Tokens(TokenOp::ReviewTokenRequest),
76 Op::Tokens(TokenOp::RevokeMemberToken),
77 ],
78 ),
79 (
Merge main (membership, two-factor, GitHub repo roles) into tokens80 "Members",
81 "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.",
82 &[Op::ListMembers, Op::UpdateMember, Op::RemoveMember, Op::TransferOwnership, Op::LeaveWorkspace],
83 ),
84 (
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look85 "Invites",
86 "While g1t is invite-only, every new account needs an invite. Your invites, and inviting people into a workspace by email.",
87 &[
88 Op::ListInvites,
89 Op::CreateInvite,
90 Op::RevokeInvite,
91 Op::ListWorkspaceInvites,
92 Op::InviteMember,
93 Op::RevokeWorkspaceInvite,
94 ],
Merge branch 'worktree-agent-ab2e39e11a6493412'95 ),
96 (
Usage, Billing settings and prepaid AI credit; fixes from the UX audit97 "Billing",
Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens98 "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 audit99 &[
100 Op::GetUsage,
101 Op::GetBudget,
102 Op::SetBudget,
103 Op::GetAiCredit,
104 Op::BuyAiCredit,
105 Op::ListInvoices,
106 Op::GetBillingDetails,
Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens107 Op::ListGatewayRequests,
Usage, Billing settings and prepaid AI credit; fixes from the UX audit108 ],
109 ),
110 (
Merge branch 'worktree-agent-ab2e39e11a6493412'111 "Repositories",
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look112 "A repository, how it handles pull requests, and its timeline: renaming, archiving, moving and deleting it.",
Merge branch 'worktree-agent-ab2e39e11a6493412'113 &[
114 Op::ListRepos,
115 Op::CreateRepo,
116 Op::GetRepo,
117 Op::UpdateRepo,
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look118 Op::RenameRepo,
119 Op::RenameBranch,
120 Op::SetRepoVisibility,
121 Op::ArchiveRepo,
122 Op::UnarchiveRepo,
123 Op::TransferRepo,
124 Op::DeleteRepo,
125 Op::ListDeletedRepos,
126 Op::RestoreRepo,
127 Op::PurgeRepo,
Merge branch 'worktree-agent-ab2e39e11a6493412'128 Op::GetRepoSettings,
129 Op::UpdateRepoSettings,
Fast pages, required checks on the branch, self-hosted runners, honest incidents130 Op::ListCheckNames,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar131 Op::GetCodeownersErrors,
Merge branch 'worktree-agent-ab2e39e11a6493412'132 Op::ListEvents,
133 ],
134 ),
135 (
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb97136 "Repository insights",
137 "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.",
138 &[Op::About(AboutOp::GetLanguages), Op::About(AboutOp::ListContributors), Op::About(AboutOp::GetLicense)],
139 ),
140 (
141 "Stars",
142 "Starring a repository, to keep it and to say you like it: who starred one, and what you starred.",
143 &[
144 Op::About(AboutOp::ListStargazers),
145 Op::About(AboutOp::ListStarred),
146 Op::About(AboutOp::CheckStarred),
147 Op::About(AboutOp::Star),
148 Op::About(AboutOp::Unstar),
149 ],
150 ),
151 (
152 "Releases",
153 "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.",
154 &[
155 Op::About(AboutOp::ListReleases),
156 Op::About(AboutOp::CreateRelease),
157 Op::About(AboutOp::GetLatestRelease),
158 Op::About(AboutOp::GetReleaseByTag),
159 Op::About(AboutOp::GetRelease),
160 Op::About(AboutOp::UpdateRelease),
161 Op::About(AboutOp::DeleteRelease),
162 ],
163 ),
164 (
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look165 "Access",
Merge branch 'worktree-agent-a5a5de74d8863d554' into worktree-agent-a16631325aecf58ca166 "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.",
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look167 &[
168 Op::ListCollaborators,
169 Op::AddCollaborator,
170 Op::UpdateCollaborator,
171 Op::RemoveCollaborator,
172 Op::GetCollaboratorPermission,
173 Op::ListRepoInvitations,
174 Op::RevokeRepoInvitation,
175 Op::ListMyRepoInvitations,
176 Op::AcceptRepoInvitation,
177 Op::DeclineRepoInvitation,
178 Op::SetBasePermission,
179 Op::ListOutsideCollaborators,
Merge branch 'worktree-agent-a5a5de74d8863d554' into worktree-agent-a16631325aecf58ca180 Op::DeployKeys(DeployKeysOp::ListDeployKeys),
181 Op::DeployKeys(DeployKeysOp::GetDeployKey),
182 Op::DeployKeys(DeployKeysOp::CreateDeployKey),
183 Op::DeployKeys(DeployKeysOp::DeleteDeployKey),
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look184 ],
185 ),
186 (
Mirroring over REST and MCP187 "Mirroring",
188 "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.",
189 &[
190 Op::Mirrors(MirrorsOp::GetMirror),
191 Op::Mirrors(MirrorsOp::GetHandBackPlan),
192 Op::Mirrors(MirrorsOp::TakeOver),
193 Op::Mirrors(MirrorsOp::SetCiFailover),
194 Op::Mirrors(MirrorsOp::HandBack),
195 Op::Mirrors(MirrorsOp::MoveToG1t),
196 Op::Mirrors(MirrorsOp::SyncMirror),
197 Op::Mirrors(MirrorsOp::AddRemote),
198 Op::Mirrors(MirrorsOp::UpdateRemote),
199 Op::Mirrors(MirrorsOp::RemoveRemote),
200 ],
201 ),
202 (
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar203 "Teams",
204 "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.",
205 &[
206 Op::ListTeams,
207 Op::CreateTeam,
208 Op::GetTeam,
209 Op::UpdateTeam,
210 Op::DeleteTeam,
211 Op::ListTeamMembers,
212 Op::SetTeamMember,
213 Op::RemoveTeamMember,
214 Op::ListChildTeams,
215 Op::ListTeamRepos,
216 Op::SetTeamRepo,
217 Op::RemoveTeamRepo,
218 Op::SetTeamReviewAssignment,
219 Op::ListUserTeams,
220 ],
221 ),
222 (
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily223 "Security",
224 "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.",
225 &[Op::ListSecurityAlerts, Op::DismissSecurityAlert, Op::ReopenSecurityAlert],
226 ),
227 (
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar228 "Secret scanning",
229 "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.",
230 &[
231 Op::Security(SecurityOp::ListSecretAlerts),
232 Op::Security(SecurityOp::GetSecretAlert),
233 Op::Security(SecurityOp::UpdateSecretAlert),
234 Op::Security(SecurityOp::ListSecretLocations),
235 Op::Security(SecurityOp::BypassPushProtection),
236 Op::Security(SecurityOp::CheckSecretValidity),
237 Op::Security(SecurityOp::ListBypassRequests),
238 Op::Security(SecurityOp::ReviewBypassRequest),
239 Op::Security(SecurityOp::ListCustomPatterns),
240 Op::Security(SecurityOp::CreateCustomPattern),
241 Op::Security(SecurityOp::UpdateCustomPattern),
242 Op::Security(SecurityOp::DeleteCustomPattern),
243 Op::Security(SecurityOp::DryRunCustomPattern),
244 ],
245 ),
246 (
247 "Code scanning",
248 "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.",
249 &[
250 Op::Security(SecurityOp::ListCodeAlerts),
251 Op::Security(SecurityOp::GetCodeAlert),
252 Op::Security(SecurityOp::UpdateCodeAlert),
253 Op::Security(SecurityOp::ListAnalyses),
254 Op::Security(SecurityOp::UploadSarif),
255 Op::Security(SecurityOp::GetSarifUpload),
256 Op::Security(SecurityOp::FixAlert),
257 ],
258 ),
259 (
260 "Supply chain",
261 "What a repository depends on: vulnerability alerts, the dependency graph, an SPDX SBOM of it, and comparing two commits' dependencies as dependency review does.",
262 &[
263 Op::Security(SecurityOp::ListVulnerabilityAlerts),
264 Op::Security(SecurityOp::GetVulnerabilityAlert),
265 Op::Security(SecurityOp::UpdateVulnerabilityAlert),
266 Op::Security(SecurityOp::GetDependencyGraph),
267 Op::Security(SecurityOp::GetSbom),
268 Op::Security(SecurityOp::CompareDependencies),
269 ],
270 ),
271 (
272 "Security settings",
273 "When pull request checks fail, dependency review's policy, delegated bypass and validity checks, and a workspace's security overview.",
274 &[
275 Op::Security(SecurityOp::GetSettings),
276 Op::Security(SecurityOp::UpdateSettings),
277 Op::Security(SecurityOp::GetWorkspaceSettings),
278 Op::Security(SecurityOp::UpdateWorkspaceSettings),
279 Op::Security(SecurityOp::GetOverview),
280 ],
281 ),
282 (
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge283 "Rules",
284 "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.",
285 &[
286 Op::Rules(RulesOp::ListRepoRulesets),
287 Op::Rules(RulesOp::CreateRepoRuleset),
288 Op::Rules(RulesOp::GetRepoRuleset),
289 Op::Rules(RulesOp::UpdateRepoRuleset),
290 Op::Rules(RulesOp::DeleteRepoRuleset),
291 Op::Rules(RulesOp::GetBranchRules),
292 Op::Rules(RulesOp::ListRuleEvaluations),
293 Op::Rules(RulesOp::ListWorkspaceRulesets),
294 Op::Rules(RulesOp::CreateWorkspaceRuleset),
295 Op::Rules(RulesOp::GetWorkspaceRuleset),
296 Op::Rules(RulesOp::UpdateWorkspaceRuleset),
297 Op::Rules(RulesOp::DeleteWorkspaceRuleset),
298 Op::Rules(RulesOp::ListWorkspaceRuleEvaluations),
299 ],
300 ),
301 (
Merge checks: statuses and check runs on every commit302 "Checks",
303 "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.",
304 &[
305 Op::Checks(ChecksOp::CreateCommitStatus),
306 Op::Checks(ChecksOp::ListCommitStatuses),
307 Op::Checks(ChecksOp::GetCombinedStatus),
308 Op::Checks(ChecksOp::CreateCheckRun),
309 Op::Checks(ChecksOp::UpdateCheckRun),
310 Op::Checks(ChecksOp::GetCheckRun),
311 Op::Checks(ChecksOp::ListCheckRunAnnotations),
312 Op::Checks(ChecksOp::RerequestCheckRun),
313 Op::Checks(ChecksOp::ListCheckRunsForRef),
314 Op::Checks(ChecksOp::ListCheckSuitesForRef),
315 Op::Checks(ChecksOp::GetCheckSuite),
316 Op::Checks(ChecksOp::RerequestCheckSuite),
317 ],
318 ),
319 (
Merge branch 'worktree-agent-ab2e39e11a6493412'320 "Issues",
321 "What should change in a repository, with labels and comments. Issues and pull requests share one sequence of numbers.",
322 &[
323 Op::ListIssues,
324 Op::CreateIssue,
325 Op::GetIssue,
326 Op::UpdateIssue,
327 Op::CloseIssue,
328 Op::ReopenIssue,
329 Op::AssignIssue,
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step330 Op::Delegate,
Merge branch 'worktree-agent-ab2e39e11a6493412'331 Op::AddComment,
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts332 Op::EditComment,
333 Op::DeleteComment,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar334 Op::ListIssueLabels,
335 Op::AddIssueLabels,
336 Op::SetIssueLabels,
337 Op::RemoveIssueLabels,
338 ],
339 ),
340 (
341 "Labels and milestones",
342 "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.",
343 &[
Merge branch 'worktree-agent-ab2e39e11a6493412'344 Op::ListLabels,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar345 Op::CreateLabel,
346 Op::UpdateLabel,
347 Op::DeleteLabel,
348 Op::AddDefaultLabels,
349 Op::ListMilestones,
350 Op::CreateMilestone,
351 Op::GetMilestone,
352 Op::UpdateMilestone,
353 Op::DeleteMilestone,
Merge branch 'worktree-agent-ab2e39e11a6493412'354 ],
355 ),
356 (
357 "Plans",
358 "An outcome turned into the issues that would get there, with the order they must merge in.",
359 &[Op::PlanWork, Op::GetPlan, Op::ApplyPlan],
360 ),
361 (
362 "Pull requests",
363 "A proposed change in its own fork or on a branch. Several can be made for one issue; the one merged resolves it.",
364 &[
365 Op::ListPullRequests,
366 Op::CreatePullRequest,
367 Op::GetPullRequest,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar368 Op::UpdatePullRequest,
Merge branch 'worktree-agent-ab2e39e11a6493412'369 Op::GetPullRequestChanges,
370 Op::MarkPullRequestReady,
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts371 Op::ConvertPullRequestToDraft,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar372 Op::RequestReviewers,
373 Op::RemoveRequestedReviewers,
Merge branch 'worktree-agent-ab2e39e11a6493412'374 Op::ReviewPullRequest,
375 Op::MergePullRequest,
376 Op::ClosePullRequest,
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts377 Op::ReopenPullRequest,
Merge branch 'worktree-agent-ab2e39e11a6493412'378 Op::GetMergeQueue,
379 Op::MessageAgent,
380 Op::AnswerMessage,
381 Op::TakeMessages,
382 ],
383 ),
384 (
385 "Sessions",
386 "The record of how a pull request was made: prompts, reasoning and the tools that ran.",
387 &[Op::ReadSession, Op::RecordSession],
388 ),
389 (
Agents and memory, checks and conflicts, profiles, slug renames, custom domains390 "Memory",
391 "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.",
392 &[Op::Remember, Op::Recall],
393 ),
394 (
Search across all of g1t, Explore, and a command palette395 "Search",
396 "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.",
397 &[Op::Search],
398 ),
399 (
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API400 "Context",
401 "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.",
402 &[Op::SearchContext, Op::GetEntity],
403 ),
404 (
Merge branch 'worktree-agent-ab2e39e11a6493412'405 "Actions",
406 "GitHub Actions workflows in .g1t/workflows, their runs, and their jobs' logs.",
407 &[
408 Op::ListWorkflows,
409 Op::ListWorkflowRuns,
410 Op::GetWorkflowRun,
411 Op::GetJobLogs,
412 Op::DispatchWorkflow,
413 Op::CancelWorkflowRun,
414 Op::RerunWorkflowRun,
415 Op::UpdateWorkflow,
Actions: OIDC tokens, the toolkit's cache and artifact services, and artifacts in R2416 Op::Artifacts(ArtifactsOp::ListArtifacts),
417 Op::Artifacts(ArtifactsOp::ListRunArtifacts),
418 Op::Artifacts(ArtifactsOp::GetArtifact),
419 Op::Artifacts(ArtifactsOp::DownloadArtifact),
420 Op::Artifacts(ArtifactsOp::DeleteArtifact),
421 Op::Artifacts(ArtifactsOp::GetArtifactRetention),
422 Op::Artifacts(ArtifactsOp::SetArtifactRetention),
Merge branch 'worktree-agent-ab2e39e11a6493412'423 ],
424 ),
425 (
Merge packages: roles, Actions access, source label, soft delete, API426 "Packages",
427 "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.",
428 &[
429 Op::Packages(PackagesOp::ListPackages),
430 Op::Packages(PackagesOp::GetPackage),
431 Op::Packages(PackagesOp::UpdatePackage),
432 Op::Packages(PackagesOp::DeletePackage),
433 Op::Packages(PackagesOp::RestorePackage),
434 Op::Packages(PackagesOp::ListVersions),
435 Op::Packages(PackagesOp::GetVersion),
436 Op::Packages(PackagesOp::DeleteVersion),
437 Op::Packages(PackagesOp::RestoreVersion),
438 Op::Packages(PackagesOp::LinkPackage),
439 Op::Packages(PackagesOp::UnlinkPackage),
440 Op::Packages(PackagesOp::ListAccess),
441 Op::Packages(PackagesOp::SetAccess),
442 Op::Packages(PackagesOp::RemoveAccess),
443 Op::Packages(PackagesOp::ListActionsAccess),
444 Op::Packages(PackagesOp::SetActionsAccess),
445 Op::Packages(PackagesOp::RemoveActionsAccess),
446 ],
447 ),
448 (
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb97449 "Deployments",
450 "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.",
451 &[
452 Op::Deployments(DeploymentsOp::ListDeployments),
453 Op::Deployments(DeploymentsOp::CreateDeployment),
454 Op::Deployments(DeploymentsOp::GetDeployment),
455 Op::Deployments(DeploymentsOp::ListDeploymentStatuses),
456 Op::Deployments(DeploymentsOp::CreateDeploymentStatus),
457 Op::Deployments(DeploymentsOp::ListEnvironments),
458 Op::Deployments(DeploymentsOp::GetEnvironment),
459 ],
460 ),
461 (
Merge branch 'worktree-agent-a3abfcce648e87dca'462 "Run protection",
463 "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.",
464 &[
465 Op::Protection(ProtectionOp::UpdateEnvironment),
466 Op::Protection(ProtectionOp::DeleteEnvironment),
467 Op::Protection(ProtectionOp::GetPendingDeployments),
468 Op::Protection(ProtectionOp::ReviewPendingDeployments),
469 Op::Protection(ProtectionOp::ApproveWorkflowRun),
470 Op::Protection(ProtectionOp::GetWorkflowPermissions),
471 Op::Protection(ProtectionOp::SetWorkflowPermissions),
472 Op::Protection(ProtectionOp::GetForkPrApproval),
473 Op::Protection(ProtectionOp::SetForkPrApproval),
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts474 Op::Protection(ProtectionOp::GetActionsAccess),
475 Op::Protection(ProtectionOp::SetActionsAccess),
Merge branch 'worktree-agent-a3abfcce648e87dca'476 Op::Protection(ProtectionOp::CreateRepositoryDispatch),
477 Op::Protection(ProtectionOp::GetWorkspaceWorkflowPermissions),
478 Op::Protection(ProtectionOp::SetWorkspaceWorkflowPermissions),
479 ],
480 ),
481 (
Merge branch 'worktree-agent-ab2e39e11a6493412'482 "Secrets and variables",
483 "Values that workflows and deployments read, per repository or for a whole workspace, with a row per environment.",
484 &[
485 Op::ListActionsSecrets,
486 Op::SetActionsSecret,
487 Op::DeleteActionsSecret,
488 Op::ListActionsVariables,
489 Op::SetActionsVariable,
490 Op::DeleteActionsVariable,
491 ],
492 ),
493 (
Fast pages, required checks on the branch, self-hosted runners, honest incidents494 "Runners",
495 "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.",
496 &[
497 Op::ListRunners,
498 Op::CreateRunnerRegistrationToken,
499 Op::RemoveRunner,
500 Op::ListRunnerGroups,
501 Op::CreateRunnerGroup,
502 Op::UpdateRunnerGroup,
503 Op::DeleteRunnerGroup,
504 Op::GetRunnerSettings,
505 Op::UpdateRunnerSettings,
506 ],
507 ),
508 (
Merge branch 'worktree-agent-ab2e39e11a6493412'509 "Webhooks",
510 "Signed HTTPS requests sent to your own address as things happen, for a repository or a whole workspace.",
511 &[
512 Op::ListWebhooks,
513 Op::CreateWebhook,
514 Op::UpdateWebhook,
515 Op::DeleteWebhook,
516 Op::PingWebhook,
517 Op::ListWebhookDeliveries,
518 Op::RedeliverWebhook,
519 ],
520 ),
521 (
522 "Integrations",
523 "A workspace's connections to outside systems: model providers, alert sources and issue trackers.",
524 &[
525 Op::ListIntegrations,
526 Op::ConnectIntegration,
AI Gateway: OpenAI's format, open models, and your own providers527 Op::UpdateIntegration,
Merge branch 'worktree-agent-ab2e39e11a6493412'528 Op::DisconnectIntegration,
529 Op::TestIntegration,
530 Op::GetModelRoutes,
531 Op::SetModelRoutes,
532 Op::GetContext,
533 Op::ImportIssue,
534 ],
535 ),
536];
537
API and MCP server in Rust; a public index at the API root538/// The section of the API reference an operation is listed under.
539fn tag(op: Op) -> &'static str {
Merge branch 'worktree-agent-ab2e39e11a6493412'540 SECTIONS
API and MCP server in Rust; a public index at the API root541 .iter()
Merge branch 'worktree-agent-ab2e39e11a6493412'542 .find(|(_, _, ops)| ops.contains(&op))
543 .map_or("Repositories", |(name, _, _)| name)
544}
545
546/// What an operation's page is called, as a short sentence.
547fn title(op: Op) -> &'static str {
548 match op {
549 Op::Whoami => "Get the current user",
Merge branch 'worktree-agent-ad7c6d88d93adc817'550 Op::GetWorkspace => "Get a workspace",
Merge branch 'worktree-agent-ab2e39e11a6493412'551 Op::CreateWorkspace => "Create a workspace",
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look552 Op::DeleteWorkspace => "Delete a workspace",
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily553 Op::UpdateWorkspace => "Update a workspace",
Merge main (membership, two-factor, GitHub repo roles) into tokens554 Op::ListMembers => "List a workspace's members",
555 Op::UpdateMember => "Change a member's role",
556 Op::RemoveMember => "Remove a member",
557 Op::TransferOwnership => "Transfer a workspace's ownership",
558 Op::LeaveWorkspace => "Leave a workspace",
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look559 Op::ListEmails => "List your email addresses",
560 Op::AddEmail => "Add an email address",
Merge email confirmation gate: a code and a link, nothing until confirmed (identity 0036)561 Op::ConfirmEmail => "Confirm an email address",
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look562 Op::RemoveEmail => "Remove an email address",
563 Op::UpdateEmailSettings => "Change your email settings",
564 Op::ListInvites => "List your invites",
565 Op::CreateInvite => "Create an invite",
566 Op::RevokeInvite => "Revoke an invite",
567 Op::ListWorkspaceInvites => "List a workspace's invites",
568 Op::InviteMember => "Invite someone to a workspace",
569 Op::RevokeWorkspaceInvite => "Revoke a workspace's invite",
570 Op::TransferRepo => "Transfer a repository",
571 Op::RenameRepo => "Rename a repository",
572 Op::RenameBranch => "Rename a branch",
573 Op::ArchiveRepo => "Archive a repository",
574 Op::UnarchiveRepo => "Unarchive a repository",
575 Op::SetRepoVisibility => "Change a repository's visibility",
576 Op::DeleteRepo => "Delete a repository",
577 Op::ListDeletedRepos => "List recently deleted repositories",
578 Op::RestoreRepo => "Restore a deleted repository",
579 Op::PurgeRepo => "Purge a deleted repository",
Merge branch 'worktree-agent-ab2e39e11a6493412'580 Op::ListRepos => "List repositories",
581 Op::GetRepo => "Get a repository",
582 Op::CreateRepo => "Create a repository",
583 Op::UpdateRepo => "Update a repository",
584 Op::GetRepoSettings => "Get repository settings",
585 Op::UpdateRepoSettings => "Update repository settings",
Fast pages, required checks on the branch, self-hosted runners, honest incidents586 Op::ListCheckNames => "List check names",
Merge branch 'worktree-agent-ab2e39e11a6493412'587 Op::GetMergeQueue => "Get the merge queue",
588 Op::MessageAgent => "Message an agent",
589 Op::AnswerMessage => "Answer a message",
590 Op::TakeMessages => "Take new messages",
Agents and memory, checks and conflicts, profiles, slug renames, custom domains591 Op::Remember => "Remember something",
592 Op::Recall => "Recall memory",
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API593 Op::SearchContext => "Search the context hub",
594 Op::GetEntity => "Get a catalog entry",
Search across all of g1t, Explore, and a command palette595 Op::Search => "Search g1t",
Merge branch 'worktree-agent-ab2e39e11a6493412'596 Op::ListIssues => "List issues",
597 Op::GetIssue => "Get an issue",
598 Op::CreateIssue => "Create an issue",
599 Op::UpdateIssue => "Update an issue",
600 Op::CloseIssue => "Close an issue",
601 Op::ReopenIssue => "Reopen an issue",
g1t is one name: its agent's work, commits and comments show as @g1t, and nobody can claim g1t or g1t-agent602 Op::AssignIssue => "Assign an issue to g1t",
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step603 Op::Delegate => "Put an agent on it",
Merge branch 'worktree-agent-ab2e39e11a6493412'604 Op::PlanWork => "Plan work",
605 Op::GetPlan => "Get a plan",
606 Op::ApplyPlan => "Apply a plan",
607 Op::ListLabels => "List labels",
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar608 Op::CreateLabel => "Create a label",
609 Op::UpdateLabel => "Update a label",
610 Op::DeleteLabel => "Delete a label",
611 Op::AddDefaultLabels => "Add the default labels",
612 Op::ListIssueLabels => "List an issue's labels",
613 Op::AddIssueLabels => "Add labels to an issue",
614 Op::SetIssueLabels => "Set an issue's labels",
615 Op::RemoveIssueLabels => "Remove labels from an issue",
616 Op::ListMilestones => "List milestones",
617 Op::GetMilestone => "Get a milestone",
618 Op::CreateMilestone => "Create a milestone",
619 Op::UpdateMilestone => "Update a milestone",
620 Op::DeleteMilestone => "Delete a milestone",
621 Op::UpdatePullRequest => "Update a pull request",
Merge branch 'worktree-agent-ab2e39e11a6493412'622 Op::AddComment => "Add a comment",
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts623 Op::EditComment => "Edit a comment",
624 Op::DeleteComment => "Delete a comment",
Merge branch 'worktree-agent-ab2e39e11a6493412'625 Op::ReviewPullRequest => "Review a pull request",
626 Op::ListPullRequests => "List pull requests",
627 Op::GetPullRequest => "Get a pull request",
628 Op::CreatePullRequest => "Create a pull request",
629 Op::RecordSession => "Record session entries",
630 Op::ReadSession => "Read a session",
631 Op::MarkPullRequestReady => "Mark a pull request ready",
632 Op::ClosePullRequest => "Close a pull request",
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts633 Op::ReopenPullRequest => "Reopen a pull request",
634 Op::ConvertPullRequestToDraft => "Convert a pull request to a draft",
Merge branch 'worktree-agent-ab2e39e11a6493412'635 Op::GetPullRequestChanges => "Get a pull request's changes",
636 Op::MergePullRequest => "Merge a pull request",
637 Op::ListEvents => "List repository events",
638 Op::ListIntegrations => "List integrations",
639 Op::ConnectIntegration => "Connect an integration",
AI Gateway: OpenAI's format, open models, and your own providers640 Op::UpdateIntegration => "Update an integration",
Merge branch 'worktree-agent-ab2e39e11a6493412'641 Op::DisconnectIntegration => "Disconnect an integration",
642 Op::TestIntegration => "Test an integration",
643 Op::GetContext => "Look up a ticket",
644 Op::ImportIssue => "Import an issue",
645 Op::GetModelRoutes => "Get model routes",
646 Op::SetModelRoutes => "Set model routes",
647 Op::ListWebhooks => "List webhooks",
648 Op::CreateWebhook => "Create a webhook",
649 Op::UpdateWebhook => "Update a webhook",
650 Op::DeleteWebhook => "Delete a webhook",
651 Op::PingWebhook => "Ping a webhook",
652 Op::ListWebhookDeliveries => "List webhook deliveries",
653 Op::RedeliverWebhook => "Redeliver a webhook delivery",
654 Op::ListWorkflows => "List workflows",
655 Op::ListWorkflowRuns => "List workflow runs",
656 Op::GetWorkflowRun => "Get a workflow run",
657 Op::GetJobLogs => "Get a job's log",
658 Op::DispatchWorkflow => "Run a workflow",
659 Op::CancelWorkflowRun => "Cancel a workflow run",
660 Op::RerunWorkflowRun => "Re-run a workflow run",
661 Op::UpdateWorkflow => "Turn a workflow on or off",
662 Op::ListActionsSecrets => "List secrets",
663 Op::SetActionsSecret => "Set a secret",
664 Op::DeleteActionsSecret => "Delete a secret",
665 Op::ListActionsVariables => "List variables",
666 Op::SetActionsVariable => "Set a variable",
667 Op::DeleteActionsVariable => "Delete a variable",
Fast pages, required checks on the branch, self-hosted runners, honest incidents668 Op::ListRunners => "List self-hosted runners",
669 Op::ListRunnerGroups => "List runner groups",
670 Op::GetRunnerSettings => "Get runner settings",
671 Op::CreateRunnerRegistrationToken => "Create a runner registration token",
672 Op::RemoveRunner => "Remove a self-hosted runner",
673 Op::CreateRunnerGroup => "Create a runner group",
674 Op::UpdateRunnerGroup => "Change a runner group",
675 Op::DeleteRunnerGroup => "Delete a runner group",
676 Op::UpdateRunnerSettings => "Change runner settings",
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look677 Op::ListCollaborators => "List who has access",
678 Op::AddCollaborator => "Add a collaborator",
679 Op::UpdateCollaborator => "Change a collaborator's role",
680 Op::RemoveCollaborator => "Remove a collaborator",
681 Op::GetCollaboratorPermission => "Get someone's permission",
682 Op::ListRepoInvitations => "List a repository's invitations",
683 Op::RevokeRepoInvitation => "Revoke a repository invitation",
684 Op::ListMyRepoInvitations => "List your repository invitations",
685 Op::AcceptRepoInvitation => "Accept a repository invitation",
686 Op::DeclineRepoInvitation => "Decline a repository invitation",
687 Op::SetBasePermission => "Set the base permission",
688 Op::ListOutsideCollaborators => "List outside collaborators",
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily689 Op::ListSecurityAlerts => "List security alerts",
690 Op::DismissSecurityAlert => "Dismiss a security alert",
691 Op::ReopenSecurityAlert => "Reopen a security alert",
API: notifications over REST and MCP, with notifications scopes692 Op::ListNotifications => "List notifications",
693 Op::MarkNotificationsRead => "Mark notifications read",
694 Op::GetNotificationThread => "Get a thread",
695 Op::MarkThreadRead => "Mark a thread read",
696 Op::MarkThreadDone => "Mark a thread done",
697 Op::SaveThread => "Save a thread",
698 Op::SnoozeThread => "Snooze a thread",
699 Op::GetThreadSubscription => "Get a thread subscription",
700 Op::SetThreadSubscription => "Set a thread subscription",
701 Op::DeleteThreadSubscription => "Unsubscribe from a thread",
702 Op::GetRepoSubscription => "Get how you watch a repository",
703 Op::SetRepoSubscription => "Watch a repository",
704 Op::DeleteRepoSubscription => "Stop watching a repository",
705 Op::ListWatchedRepos => "List repositories you watch",
API: pinned projects over REST and MCP706 Op::ListPinnedProjects => "List your pinned projects",
Usage, Billing settings and prepaid AI credit; fixes from the UX audit707 Op::GetUsage => "Get a workspace's usage",
708 Op::GetBudget => "Get a workspace's budget",
709 Op::SetBudget => "Change a workspace's budget",
710 Op::GetAiCredit => "Get a workspace's AI credit",
711 Op::BuyAiCredit => "Buy AI credit",
712 Op::ListInvoices => "List a workspace's invoices",
713 Op::GetBillingDetails => "Get a workspace's billing details",
Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens714 Op::ListGatewayRequests => "List a workspace's AI Gateway requests",
API: pinned projects over REST and MCP715 Op::PinProject => "Pin a project",
716 Op::UnpinProject => "Unpin a project",
717 Op::ReorderPinnedProjects => "Reorder your pinned projects",
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb97718 Op::ListProjects => "List a workspace's projects",
719 Op::GetProject => "Get a project",
720 Op::UpdateProject => "Update a project",
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar721 Op::ListTeams => "List teams",
722 Op::GetTeam => "Get a team",
723 Op::CreateTeam => "Create a team",
724 Op::UpdateTeam => "Update a team",
725 Op::DeleteTeam => "Delete a team",
726 Op::ListTeamMembers => "List a team's members",
727 Op::SetTeamMember => "Add or change a team member",
728 Op::RemoveTeamMember => "Remove a team member",
729 Op::ListChildTeams => "List child teams",
730 Op::ListTeamRepos => "List a team's repositories",
731 Op::SetTeamRepo => "Give a team a role on a repository",
732 Op::RemoveTeamRepo => "Remove a team from a repository",
733 Op::SetTeamReviewAssignment => "Set a team's review assignment",
734 Op::ListUserTeams => "List someone's teams",
735 Op::RequestReviewers => "Request reviewers",
736 Op::RemoveRequestedReviewers => "Remove requested reviewers",
737 Op::GetCodeownersErrors => "List CODEOWNERS errors",
738 Op::Security(op) => op.title(),
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge739 Op::Rules(op) => op.title(),
Merge checks: statuses and check runs on every commit740 Op::Checks(op) => op.title(),
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb97741 Op::About(op) => op.title(),
742 Op::Deployments(op) => op.title(),
Merge branch 'worktree-agent-a3abfcce648e87dca'743 Op::Protection(op) => op.title(),
API and MCP for a workspace's personal access token rules, members' tokens and approvals744 Op::Tokens(op) => op.title(),
Actions: OIDC tokens, the toolkit's cache and artifact services, and artifacts in R2745 Op::Artifacts(op) => op.title(),
Merge branch 'worktree-agent-a5a5de74d8863d554' into worktree-agent-a16631325aecf58ca746 Op::DeployKeys(op) => op.title(),
Mirroring over REST and MCP747 Op::Mirrors(op) => op.title(),
Merge packages: roles, Actions access, source label, soft delete, API748 Op::Packages(op) => op.title(),
API and MCP server in Rust; a public index at the API root749 }
750}
751
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look752/// Why an operation can be refused with `402 payment_required`, if it
753/// can: the ones that start an agent, when the workspace has no credit,
754/// and the ones that make a repository private in a workspace, when a free
755/// workspace's private storage has no room for it.
756fn may_need_payment(op: Op) -> Option<&'static str> {
757 match op {
758 Op::AssignIssue | Op::PlanWork | Op::ApplyPlan => Some("The workspace has no agent credit."),
759 Op::UpdateRepo | Op::SetRepoVisibility | Op::TransferRepo => Some(
760 "A free workspace's private storage has no room for this private repository.",
761 ),
762 _ => None,
763 }
Merge branch 'worktree-agent-ab2e39e11a6493412'764}
765
766/// What the reference says beyond each operation's own description, keyed
767/// by operation id, written by hand from what the services return: `notes`
768/// (Markdown, added to the description) and example `params` (path),
769/// `query`, `request` (body) and `response`.
770const REFERENCE: &str = include_str!("reference.json");
771
772fn examples() -> Map<String, Value> {
773 match serde_json::from_str(REFERENCE) {
774 Ok(Value::Object(examples)) => examples,
775 _ => Map::new(),
API and MCP server in Rust; a public index at the API root776 }
777}
778
Agents as a team: lifecycle, merge queue, billing and a new shell779/// `/repos/:owner/:name` as OpenAPI writes it: `/repos/{owner}/{name}`.
API and MCP server in Rust; a public index at the API root780fn openapi_path(route: &Route) -> String {
781 route
782 .path
783 .split('/')
784 .map(|segment| match segment.strip_prefix(':') {
785 Some(name) => format!("{{{name}}}"),
786 None => segment.to_owned(),
787 })
788 .collect::<Vec<_>>()
789 .join("/")
790}
791
792fn error_response(description: &str) -> Value {
793 json!({
794 "description": description,
795 "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } },
796 })
797}
798
Merge branch 'worktree-agent-ab2e39e11a6493412'799/// A parameter in the path or the query, described by the operation's
800/// input schema where it has the same name.
801fn parameter(name: &str, place: &str, required: bool, schema: Option<&Value>) -> Value {
802 let mut schema = schema.cloned().unwrap_or_else(|| json!({ "type": "string" }));
803 let description = match name {
804 "owner" => Some(Value::from("The workspace that owns the repository.")),
805 "name" => Some(Value::from("The repository's name.")),
806 _ => schema.as_object_mut().and_then(|schema| schema.remove("description")),
807 };
808 let mut parameter = json!({
809 "name": name,
810 "in": place,
811 "required": required,
812 "schema": schema,
813 });
814 if let Some(description) = description {
815 parameter["description"] = description;
816 }
817 parameter
818}
819
820/// The operation id of a route. An operation reached at a workspace's
821/// address as well as a repository's is documented once for each, with its
822/// own id; GitHub's alternative addresses for one operation keep GitHub's
823/// names.
824fn operation_id(route: &Route) -> String {
825 let op = route.op;
826 let base = match (route.method, route.path.rsplit('/').next().unwrap_or_default()) {
827 ("PUT", "enable") => "enable_workflow".to_owned(),
828 ("PUT", "disable") => "disable_workflow".to_owned(),
829 ("POST", "rerun-failed-jobs") => "rerun_failed_jobs".to_owned(),
Merge Actions runs: summaries, attempts and re-runs, graceful cancel, log downloads, badges (actions 0009)830 ("POST", "rerun") if route.path.contains("/jobs/:job/") => "rerun_job".to_owned(),
831 ("POST", "force-cancel") => "force_cancel_workflow_run".to_owned(),
832 ("GET", ":attempt") => "get_workflow_run_attempt".to_owned(),
Merge branch 'worktree-agent-ab2e39e11a6493412'833 ("PATCH", ":setting") => "update_actions_variable".to_owned(),
834 ("GET", "runs") if route.path.contains("/workflows/:workflow/") => "list_runs_of_workflow".to_owned(),
API: notifications over REST and MCP, with notifications scopes835 // One repository's notifications, and an issue's subscription by
836 // its number rather than a thread's id.
837 (_, "notifications") if route.path.starts_with("/repos/") => match op {
838 Op::ListNotifications => "list_repo_notifications".to_owned(),
839 _ => "mark_repo_notifications_read".to_owned(),
840 },
841 (method, "subscription") if route.path.contains("/issues/:number/") => match method {
842 "GET" => "get_issue_subscription".to_owned(),
843 "PUT" => "set_issue_subscription".to_owned(),
844 _ => "delete_issue_subscription".to_owned(),
845 },
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar846 // One label off an issue, by its name in the path.
847 ("DELETE", ":label") if route.path.contains("/issues/:number/") => "remove_issue_label".to_owned(),
API: notifications over REST and MCP, with notifications scopes848 ("DELETE", "saved") => "unsave_thread".to_owned(),
849 ("DELETE", "snooze") => "unsnooze_thread".to_owned(),
Merge branch 'worktree-agent-ab2e39e11a6493412'850 _ => op.name().to_owned(),
851 };
852 if route.path.starts_with("/workspaces/") && ROUTES.iter().any(|other| other.op == op && other.path.starts_with("/repos/")) {
853 format!("{base}_for_workspace")
854 } else {
855 base
856 }
857}
858
859/// The summary of a route: its operation's title, or for one of GitHub's
860/// alternative addresses, what that address does.
861fn summary(route: &Route, id: &str) -> String {
862 let base = match id.trim_end_matches("_for_workspace") {
863 "enable_workflow" => "Turn a workflow on",
864 "disable_workflow" => "Turn a workflow off",
865 "rerun_failed_jobs" => "Re-run failed jobs",
Merge Actions runs: summaries, attempts and re-runs, graceful cancel, log downloads, badges (actions 0009)866 "rerun_job" => "Re-run a job",
867 "force_cancel_workflow_run" => "Force-cancel a workflow run",
868 "get_workflow_run_attempt" => "Get a workflow run attempt",
Merge branch 'worktree-agent-ab2e39e11a6493412'869 "update_actions_variable" => "Update a variable",
870 "list_runs_of_workflow" => "List a workflow's runs",
API: notifications over REST and MCP, with notifications scopes871 "list_repo_notifications" => "List a repository's notifications",
872 "mark_repo_notifications_read" => "Mark a repository's notifications read",
873 "get_issue_subscription" => "Get your subscription to an issue",
874 "set_issue_subscription" => "Subscribe to an issue",
875 "delete_issue_subscription" => "Unsubscribe from an issue",
876 "unsave_thread" => "Unsave a thread",
877 "unsnooze_thread" => "Bring a snoozed thread back",
Merge branch 'worktree-agent-ab2e39e11a6493412'878 _ => title(route.op),
879 };
880 if id.ends_with("_for_workspace") {
881 format!("{base} for a workspace")
882 } else {
883 base.to_owned()
884 }
885}
886
API and MCP server in Rust; a public index at the API root887fn operation(route: &Route) -> Value {
888 let op = route.op;
889 let path_params: Vec<&str> = route.params().collect();
Merge checks: statuses and check runs on every commit890 // `owner` and `name` in the path stand for the operation's `repo` input,
891 // so a `name` in the body, such as a check run's, is the body's own.
892 let stands_for_repo =
893 |name: &str| matches!(name, "owner" | "name") && path_params.contains(&"owner") && path_params.contains(&"name");
894 let covered = |name: &str| name == "repo" || (path_params.contains(&name) && !stands_for_repo(name));
Merge branch 'worktree-agent-ab2e39e11a6493412'895 let all_properties = op.properties();
896 let mut properties = all_properties.clone();
API and MCP server in Rust; a public index at the API root897 properties.retain(|name, _| !covered(name));
898 let required: Vec<String> = op
899 .required()
900 .into_iter()
901 .filter(|name| !covered(name))
902 .collect();
903
904 let mut parameters: Vec<Value> = path_params
905 .iter()
Merge checks: statuses and check runs on every commit906 .map(|name| parameter(name, "path", true, if stands_for_repo(name) { None } else { all_properties.get(*name) }))
API and MCP server in Rust; a public index at the API root907 .collect();
908 let mut body = Value::Null;
909 if route.method == "GET" {
910 for (name, key) in route.query {
Merge branch 'worktree-agent-ab2e39e11a6493412'911 parameters.push(parameter(
912 name,
913 "query",
914 required.iter().any(|required| required == key),
915 properties.get(*key),
916 ));
API and MCP server in Rust; a public index at the API root917 }
918 } else if !properties.is_empty() {
919 let mut schema = json!({ "type": "object", "properties": properties });
920 if !required.is_empty() {
921 schema["required"] = json!(required);
922 }
923 body = json!({
924 "required": !required.is_empty(),
925 "content": { "application/json": { "schema": schema } },
926 });
927 }
928
Merge branch 'worktree-agent-ab2e39e11a6493412'929 let id = operation_id(route);
930 let mut responses = Map::new();
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts931 if route.no_content() {
932 responses.insert("204".into(), json!({ "description": "Success. There is no body." }));
933 } else {
934 responses.insert(
935 "200".into(),
936 json!({
937 "description": "Success.",
938 "content": { "application/json": { "schema": {} } },
939 }),
940 );
941 }
Merge branch 'worktree-agent-ab2e39e11a6493412'942 responses.insert(
943 "401".into(),
944 error_response("A token is required, or the one sent is not valid."),
945 );
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look946 if let Some(reason) = may_need_payment(op) {
947 responses.insert("402".into(), error_response(reason));
Merge branch 'worktree-agent-ab2e39e11a6493412'948 }
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step949 responses.insert(
950 "403".into(),
951 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."),
952 );
Search across all of g1t, Explore, and a command palette953 if !matches!(op, Op::Whoami | Op::ListRepos | Op::Search) {
Merge branch 'worktree-agent-ab2e39e11a6493412'954 responses.insert("404".into(), error_response("It does not exist, or you cannot see it."));
955 }
956 if route.method != "GET" {
957 responses.insert(
958 "409".into(),
959 error_response("The request conflicts with the current state."),
960 );
961 }
962 if op != Op::Whoami {
963 responses.insert("422".into(), error_response("The input is not valid."));
964 }
965 // Public data can be read without a token; everything else needs one.
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step966 let scope: Vec<&str> = scope_for(op.name()).map(|scope| scope.as_str()).into_iter().collect();
Merge branch 'worktree-agent-ab2e39e11a6493412'967 let security = if op.needs_user() {
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step968 json!([{ "token": scope }])
Webhooks: every event, to your own addresses, signed and retried969 } else {
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step970 json!([{ "token": scope }, {}])
Webhooks: every event, to your own addresses, signed and retried971 };
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step972 let (tool, action) = crate::tools::TOOLS
973 .iter()
974 .find_map(|tool| {
975 tool.actions
976 .iter()
977 .find(|action| action.op == op)
978 .map(|action| (tool.name, action.name))
979 })
980 .unwrap_or_default();
API and MCP server in Rust; a public index at the API root981 let mut described = json!({
Webhooks: every event, to your own addresses, signed and retried982 "operationId": id,
API and MCP server in Rust; a public index at the API root983 "tags": [tag(op)],
Merge branch 'worktree-agent-ab2e39e11a6493412'984 "summary": summary(route, &id),
API and MCP server in Rust; a public index at the API root985 "description": op.description(),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step986 "x-operation": op.name(),
987 "x-mcp-tool": tool,
988 "x-mcp-action": action,
989 "x-scope": scope.first().copied(),
Merge branch 'worktree-agent-ab2e39e11a6493412'990 "security": security,
API and MCP server in Rust; a public index at the API root991 "parameters": parameters,
Merge branch 'worktree-agent-ab2e39e11a6493412'992 "responses": responses,
API and MCP server in Rust; a public index at the API root993 });
994 if !body.is_null() {
995 described["requestBody"] = body;
996 }
997 described
998}
999
1000/// Entries for device sign-in, which is not an operation.
1001fn onboarding() -> Map<String, Value> {
1002 let paths = json!({
Agents as a team: lifecycle, merge queue, billing and a new shell1003 "/device/code": {
API and MCP server in Rust; a public index at the API root1004 "post": {
1005 "operationId": "device_code",
1006 "tags": ["Accounts"],
1007 "summary": "Start signing in",
Agents as a team: lifecycle, merge queue, billing and a new shell1008 "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`.",
API and MCP server in Rust; a public index at the API root1009 "security": [],
1010 "requestBody": {
1011 "content": { "application/json": { "schema": {
1012 "type": "object",
1013 "properties": {
1014 "client_name": {
1015 "type": "string",
1016 "description": "What is asking, shown to the person approving. For example, Claude Code.",
1017 },
1018 },
1019 } } },
1020 },
1021 "responses": { "200": {
1022 "description": "The codes for this sign-in.",
1023 "content": { "application/json": { "schema": {
1024 "type": "object",
1025 "properties": {
Agents as a team: lifecycle, merge queue, billing and a new shell1026 "device_code": { "type": "string", "description": "Secret. Send it to /device/token." },
API and MCP server in Rust; a public index at the API root1027 "user_code": { "type": "string", "description": "Shown to the person, like WDJB-MJHT." },
1028 "verification_uri": { "type": "string" },
1029 "verification_uri_complete": {
1030 "type": "string",
1031 "description": "The link to give the person; it carries the code.",
1032 },
1033 "expires_in": { "type": "integer", "description": "Seconds until the codes expire." },
1034 "interval": { "type": "integer", "description": "Seconds to wait between polls." },
1035 },
1036 } } },
1037 } },
1038 },
1039 },
Agents as a team: lifecycle, merge queue, billing and a new shell1040 "/device/token": {
API and MCP server in Rust; a public index at the API root1041 "post": {
1042 "operationId": "device_token",
1043 "tags": ["Accounts"],
1044 "summary": "Finish signing in",
1045 "description": "Asks whether the person has approved. Poll no faster than the interval. The token is returned once.",
1046 "security": [],
1047 "requestBody": {
1048 "required": true,
1049 "content": { "application/json": { "schema": {
1050 "type": "object",
1051 "required": ["device_code"],
1052 "properties": { "device_code": { "type": "string" } },
1053 } } },
1054 },
1055 "responses": { "200": {
1056 "description": "The state of the sign-in.",
1057 "content": { "application/json": { "schema": {
1058 "type": "object",
1059 "required": ["status"],
1060 "properties": {
1061 "status": { "type": "string", "enum": ["pending", "approved", "denied", "expired"] },
1062 "token": { "type": "string", "description": "Present when approved." },
1063 "username": { "type": "string" },
1064 "verified": {
1065 "type": "boolean",
1066 "description": "Whether the account's email is confirmed.",
1067 },
1068 },
1069 } } },
1070 } },
1071 },
1072 },
1073 });
1074 match paths {
1075 Value::Object(paths) => paths,
1076 _ => Map::new(),
1077 }
1078}
1079
Merge branch 'worktree-agent-ab2e39e11a6493412'1080
1081/// Puts each operation's examples, where it has them, into its request
1082/// and response. Path and query values go under `x-example-params` and
1083/// `x-example-query`, which tools that build a request can use.
1084fn attach_examples(paths: &mut Map<String, Value>) {
1085 let examples = examples();
1086 for methods in paths.values_mut() {
1087 let Some(methods) = methods.as_object_mut() else { continue };
1088 for operation in methods.values_mut() {
1089 let id = operation["operationId"].as_str().unwrap_or_default().to_owned();
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step1090 let name = operation["x-operation"].as_str().unwrap_or_default().to_owned();
1091 let Some(example) = examples.get(&id).or_else(|| examples.get(&name)) else {
Merge branch 'worktree-agent-ab2e39e11a6493412'1092 continue;
1093 };
1094 if let Some(notes) = example.get("notes").and_then(Value::as_str) {
1095 let description = operation["description"].as_str().unwrap_or_default();
1096 operation["description"] = json!(format!("{description}\n\n{notes}"));
1097 }
1098 if let Some(response) = example.get("response") {
1099 let content = &mut operation["responses"]["200"]["content"]["application/json"];
1100 if content.is_object() {
1101 content["example"] = response.clone();
1102 }
1103 }
1104 if let Some(request) = example.get("request") {
1105 let content = &mut operation["requestBody"]["content"]["application/json"];
1106 if content.is_object() {
1107 content["example"] = request.clone();
1108 }
1109 }
1110 for (key, extension) in [("params", "x-example-params"), ("query", "x-example-query")] {
1111 if let Some(values) = example.get(key) {
1112 operation[extension] = values.clone();
1113 }
1114 }
1115 }
1116 }
1117}
1118
API and MCP server in Rust; a public index at the API root1119pub fn document() -> Value {
1120 let mut paths = onboarding();
1121 for route in ROUTES {
1122 let entry = paths
1123 .entry(openapi_path(route))
1124 .or_insert_with(|| json!({}));
1125 entry[route.method.to_lowercase()] = operation(route);
1126 }
Merge branch 'worktree-agent-ab2e39e11a6493412'1127 attach_examples(&mut paths);
1128 let tags: Vec<Value> = SECTIONS
1129 .iter()
1130 .map(|(name, description, ops)| {
1131 json!({
1132 "name": name,
1133 "description": description,
1134 // The section's operations in reading order, by MCP tool name.
1135 "x-tools": ops.iter().map(|op| op.name()).collect::<Vec<_>>(),
1136 })
1137 })
1138 .collect();
1139 let codes = ["unauthenticated", "payment_required", "forbidden", "not_found", "conflict", "invalid"];
API and MCP server in Rust; a public index at the API root1140 json!({
1141 "openapi": "3.1.0",
1142 "info": {
1143 "title": "g1t API",
1144 "version": "1",
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API1145 "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.",
API and MCP server in Rust; a public index at the API root1146 "license": { "name": "MIT", "identifier": "MIT" },
1147 },
1148 "servers": [{ "url": "https://api.g1t.sh" }],
1149 "security": [{ "token": [] }, {}],
Merge branch 'worktree-agent-ab2e39e11a6493412'1150 "tags": tags,
API and MCP server in Rust; a public index at the API root1151 "paths": paths,
1152 "components": {
1153 "securitySchemes": {
1154 "token": {
1155 "type": "http",
1156 "scheme": "bearer",
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step1157 "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.",
API and MCP server in Rust; a public index at the API root1158 },
1159 },
1160 "schemas": {
1161 "Error": {
1162 "type": "object",
1163 "required": ["error"],
1164 "properties": {
1165 "error": {
1166 "type": "object",
1167 "required": ["code", "message"],
1168 "properties": {
Merge branch 'worktree-agent-ab2e39e11a6493412'1169 "code": { "type": "string", "enum": codes },
API and MCP server in Rust; a public index at the API root1170 "message": { "type": "string" },
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step1171 "needed_scope": {
1172 "type": "string",
1173 "description": "On a 403 for an access token without the scope the call needs: that scope, such as `issues:write`.",
1174 },
API and MCP server in Rust; a public index at the API root1175 },
1176 },
1177 },
1178 },
1179 },
1180 },
1181 })
1182}
1183
1184#[cfg(test)]
1185mod tests {
1186 use super::*;
1187
1188 #[test]
1189 fn every_route_is_documented_once() {
1190 let document = document();
1191 let mut ids = Vec::new();
1192 for (_, methods) in document["paths"].as_object().unwrap() {
1193 for (_, operation) in methods.as_object().unwrap() {
1194 ids.push(operation["operationId"].as_str().unwrap().to_owned());
1195 }
1196 }
1197 for op in Op::ALL {
1198 assert_eq!(
1199 ids.iter().filter(|id| *id == op.name()).count(),
1200 1,
1201 "{}",
1202 op.name()
1203 );
1204 }
Webhooks: every event, to your own addresses, signed and retried1205 let mut unique = ids.clone();
1206 unique.sort();
1207 unique.dedup();
1208 assert_eq!(unique.len(), ids.len(), "operation ids repeat");
API and MCP server in Rust; a public index at the API root1209 }
1210
1211 #[test]
1212 fn path_and_query_inputs_are_not_repeated_in_the_body() {
1213 let document = document();
Agents as a team: lifecycle, merge queue, billing and a new shell1214 let merge = &document["paths"]["/repos/{owner}/{name}/pulls/{number}/merge"]["post"];
API and MCP server in Rust; a public index at the API root1215 let body = &merge["requestBody"]["content"]["application/json"]["schema"]["properties"];
1216 assert!(body.get("keep_issue_open").is_some());
1217 assert!(body.get("repo").is_none() && body.get("number").is_none());
Agents as a team: lifecycle, merge queue, billing and a new shell1218 let list = &document["paths"]["/repos"]["get"];
API and MCP server in Rust; a public index at the API root1219 assert_eq!(list["parameters"][0]["name"], "q");
1220 assert!(list.get("requestBody").is_none());
1221 }
1222
1223 #[test]
Merge branch 'worktree-agent-ab2e39e11a6493412'1224 fn every_operation_is_in_one_section() {
1225 for op in Op::ALL {
1226 let sections = SECTIONS
1227 .iter()
1228 .filter(|(_, _, ops)| ops.contains(&op))
1229 .count();
1230 assert_eq!(sections, 1, "{}", op.name());
1231 }
1232 }
1233
1234 #[test]
API and MCP server in Rust; a public index at the API root1235 fn titles_read_as_sentences() {
Merge branch 'worktree-agent-ab2e39e11a6493412'1236 assert_eq!(title(Op::CreateIssue), "Create an issue");
API and MCP server in Rust; a public index at the API root1237 assert_eq!(title(Op::Whoami), "Get the current user");
1238 }
Merge branch 'worktree-agent-ab2e39e11a6493412'1239
1240 #[test]
1241 fn every_operation_has_an_example_response() {
1242 let examples = examples();
1243 assert!(!examples.is_empty(), "reference.json does not parse");
1244 let document = document();
1245 let mut known = Vec::new();
1246 for (path, methods) in document["paths"].as_object().unwrap() {
1247 for (method, operation) in methods.as_object().unwrap() {
1248 known.push(operation["operationId"].as_str().unwrap().to_owned());
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts1249 // Nothing to show for a success without a body.
1250 if operation["responses"]["204"].is_object() {
1251 continue;
1252 }
Merge branch 'worktree-agent-ab2e39e11a6493412'1253 let example = &operation["responses"]["200"]["content"]["application/json"]["example"];
1254 assert!(!example.is_null(), "{method} {path} has no example response");
1255 }
1256 }
1257 for id in examples.keys() {
1258 assert!(known.contains(id), "reference.json names {id}, which is not an operation");
1259 }
1260 }
1261
1262 #[test]
1263 fn example_requests_send_only_what_the_body_takes() {
1264 let document = document();
1265 for (path, methods) in document["paths"].as_object().unwrap() {
1266 for (method, operation) in methods.as_object().unwrap() {
1267 let content = &operation["requestBody"]["content"]["application/json"];
1268 let Some(example) = content["example"].as_object() else { continue };
1269 let properties = &content["schema"]["properties"];
1270 for key in example.keys() {
1271 assert!(!properties[key].is_null(), "{method} {path}: {key} is not in the body");
1272 }
1273 }
1274 }
1275 }
1276
1277 /// The docs site's copy of the document. Run with `G1T_WRITE_OPENAPI=1`
1278 /// to rewrite it after changing an operation.
1279 #[test]
1280 fn the_docs_copy_is_current() {
1281 let path = concat!(env!("CARGO_MANIFEST_DIR"), "/../docs/src/data/openapi.json");
1282 let current = serde_json::to_string_pretty(&document()).unwrap() + "\n";
1283 if std::env::var_os("G1T_WRITE_OPENAPI").is_some() {
1284 std::fs::write(path, &current).unwrap();
1285 return;
1286 }
1287 let copy = std::fs::read_to_string(path).unwrap_or_default().replace("\r\n", "\n");
1288 assert!(
1289 copy == current,
1290 "apps/docs/src/data/openapi.json is out of date: run G1T_WRITE_OPENAPI=1 cargo test -p g1t-api openapi"
1291 );
1292 }
API reference: no example reads as a real secret1293
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API1294 /// The reference shows responses as they are sent: `snake_case`.
1295 #[test]
1296 fn example_responses_are_snake_case() {
1297 let document = document();
1298 for (path, methods) in document["paths"].as_object().unwrap() {
1299 for (method, operation) in methods.as_object().unwrap() {
1300 let example = &operation["responses"]["200"]["content"]["application/json"]["example"];
1301 let leaked = g1t_kit::wire::camel_case_keys(example);
1302 assert!(leaked.is_empty(), "{method} {path} shows {leaked:?}");
1303 }
1304 }
1305 }
1306
API reference: no example reads as a real secret1307 /// Examples never hold anything that reads as a real credential, which
1308 /// secret scanners rightly flag in a public repository: they end in `…`
1309 /// after the prefix, as `whsec_…` and `g1t_…` do.
1310 #[test]
1311 fn examples_hold_no_real_looking_secrets() {
Fast pages, required checks on the branch, self-hosted runners, honest incidents1312 let prefixes = ["whsec_", "g1t_", "g1tr_", "g1trt_", "sk_live_", "sk_test_", "ghp_", "github_pat_", "xoxb-", "AKIA"];
API reference: no example reads as a real secret1313 for (line, text) in REFERENCE.lines().enumerate() {
1314 for prefix in prefixes {
1315 let mut rest = text;
1316 while let Some(at) = rest.find(prefix) {
1317 let after = &rest[at + prefix.len()..];
1318 let run = after.chars().take_while(|c| c.is_ascii_alphanumeric()).count();
1319 assert!(
1320 run < 12,
1321 "reference.json line {}: `{prefix}` followed by {run} characters reads as a real secret; write `{prefix}…`",
1322 line + 1
1323 );
1324 rest = after;
1325 }
1326 }
1327 }
1328 }
API and MCP server in Rust; a public index at the API root1329}

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