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