Skip to content
Sign up

flagon-io/g1t

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

Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step1//! The MCP server's tools: a few resource tools, each with an `action`.
2//!
3//! Every operation is one action of one tool. A call is dispatched to the
4//! operation it names, so permissions, the audit log, billing and outcomes
5//! are exactly those of the REST API. A token sees only the actions its
6//! scopes allow, and a tool none of whose actions it may use is not listed.
7//!
8//! The listed input schema is one flat object: `action`, then every field
9//! any of its actions takes. Which fields each action needs is in the
10//! `action` field's description and checked on every call. Claude's API,
11//! and so most MCP clients, refuse a tool whose input schema has `oneOf`
12//! at its top level, so the schema keyed by action, with each action's
13//! required fields, is [`discriminated`], published on the server's card
14//! and in the docs.
15
16use g1t_contracts::credentials::NEVER;
17use g1t_contracts::identity::AgentScope;
18use g1t_contracts::scopes::{Level, NO_SCOPE, TokenAccess, scope_for};
19use serde_json::{Map, Value, json};
20
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb9721use crate::about::AboutOp;
Actions: OIDC tokens, the toolkit's cache and artifact services, and artifacts in R222use crate::artifacts::ArtifactsOp;
Merge branch 'worktree-agent-a5a5de74d8863d554' into worktree-agent-a16631325aecf58ca23use crate::deploy_keys::DeployKeysOp;
Mirroring over REST and MCP24use crate::mirrors::MirrorsOp;
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb9725use crate::deployments::DeploymentsOp;
Merge packages: roles, Actions access, source label, soft delete, API26use crate::packages::PackagesOp;
Merge branch 'worktree-agent-a3abfcce648e87dca'27use crate::protection::ProtectionOp;
API and MCP for a workspace's personal access token rules, members' tokens and approvals28use crate::token_policy::TokenOp;
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step29use crate::operations::Op;
Merge checks: statuses and check runs on every commit30use crate::checks::ChecksOp;
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge31use crate::rules::RulesOp;
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar32use crate::security::SecurityOp;
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step33
34pub struct Action {
35 pub name: &'static str,
36 pub op: Op,
37 /// One line, for the `action` field's description.
38 pub summary: &'static str,
39}
40
41pub struct Tool {
42 pub name: &'static str,
43 pub title: &'static str,
44 /// What it is for, in a sentence or two.
45 pub description: &'static str,
46 pub actions: &'static [Action],
47 /// The action a call without one runs.
48 pub default_action: Option<&'static str>,
49}
50
51const fn a(name: &'static str, op: Op, summary: &'static str) -> Action {
52 Action { name, op, summary }
53}
54
55pub const TOOLS: &[Tool] = &[
56 Tool {
57 name: "search",
58 title: "Search",
59 description: "Find things. `code` (the default) searches all of g1t you can see: repositories, code, issues, pull requests and people, with qualifiers like repo:owner/name, language:rust, is:issue. `context` searches one workspace's catalog, docs, issues and memory by meaning.",
60 default_action: Some("code"),
61 actions: &[
62 a("code", Op::Search, "Search all of g1t: repositories, code, issues, pull requests, people"),
63 a("context", Op::SearchContext, "Search a workspace's context hub by meaning"),
64 a("entity", Op::GetEntity, "One catalog entry and its relations"),
65 a("ticket", Op::GetContext, "A Jira, Linear or Sentry item the work refers to, as it is now"),
66 ],
67 },
68 Tool {
69 name: "repository",
70 title: "Repositories",
Mirroring over REST and MCP71 description: "Repositories: find, read and create them, change their settings and rulesets (what may happen to branches and tags, and what a pull request needs to merge), check their CODEOWNERS file, manage their labels and milestones, see and dismiss their security alerts (secrets and vulnerable dependencies), read what their default branch says (languages, contributors, license), star them, publish releases, and look after their mirroring (take a mirror over, hand it back, or move it to g1t for good). Name one as \"owner/name\". Deleting, transferring and changing visibility need `confirm`.",
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step72 default_action: None,
73 actions: &[
74 a("list", Op::ListRepos, "Repositories you can see"),
75 a("get", Op::GetRepo, "One repository"),
76 a("create", Op::CreateRepo, "Create one, empty or copied from a public git URL"),
77 a("update", Op::UpdateRepo, "Change description, website, topics, default branch, protection"),
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge78 a("get_settings", Op::GetRepoSettings, "How pull requests merge, and the default branch's protection as its rules stack"),
79 a("update_settings", Op::UpdateRepoSettings, "Change how pull requests merge and the default branch protection ruleset"),
80 a("check_names", Op::ListCheckNames, "Check names reported lately, to require in a ruleset"),
81 a("list_rulesets", Op::Rules(RulesOp::ListRepoRulesets), "Its rulesets, and its workspace's that hold in it"),
82 a("get_ruleset", Op::Rules(RulesOp::GetRepoRuleset), "One ruleset"),
83 a("create_ruleset", Op::Rules(RulesOp::CreateRepoRuleset), "Create a ruleset for its branches or tags"),
84 a("update_ruleset", Op::Rules(RulesOp::UpdateRepoRuleset), "Change a ruleset"),
85 a("delete_ruleset", Op::Rules(RulesOp::DeleteRepoRuleset), "Delete a ruleset"),
86 a("branch_rules", Op::Rules(RulesOp::GetBranchRules), "Every rule that holds for a branch or tag, and where it comes from"),
87 a("rule_evaluations", Op::Rules(RulesOp::ListRuleEvaluations), "How its rules judged pushes and merges, with insights"),
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar88 a("codeowners", Op::GetCodeownersErrors, "Problems in its CODEOWNERS file, by line"),
89 a("list_labels", Op::ListLabels, "Labels, with colors and how many issues and pull requests carry each"),
90 a("create_label", Op::CreateLabel, "Create a label"),
91 a("update_label", Op::UpdateLabel, "Rename a label or change its color or description"),
92 a("delete_label", Op::DeleteLabel, "Delete a label, from everything that carries it"),
93 a("add_default_labels", Op::AddDefaultLabels, "Add the default labels it is missing"),
94 a("list_milestones", Op::ListMilestones, "Milestones, with progress and due dates"),
95 a("get_milestone", Op::GetMilestone, "One milestone with its issues and pull requests"),
96 a("create_milestone", Op::CreateMilestone, "Create a milestone"),
97 a("update_milestone", Op::UpdateMilestone, "Change a milestone's title, description, due date or state"),
98 a("delete_milestone", Op::DeleteMilestone, "Delete a milestone"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step99 a("list_events", Op::ListEvents, "Timeline: pushes, issues, pull requests, comments"),
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb97100 a("languages", Op::About(AboutOp::GetLanguages), "Its languages by bytes, with colors and percentages"),
101 a("contributors", Op::About(AboutOp::ListContributors), "Who made it: commits per person, agent and author, by week"),
102 a("license", Op::About(AboutOp::GetLicense), "The license its LICENSE file holds"),
103 a("stargazers", Op::About(AboutOp::ListStargazers), "Who starred it"),
104 a("starred", Op::About(AboutOp::CheckStarred), "Whether you starred it, and how many have"),
105 a("star", Op::About(AboutOp::Star), "Star it"),
106 a("unstar", Op::About(AboutOp::Unstar), "Take your star back"),
107 a("list_starred", Op::About(AboutOp::ListStarred), "Repositories you starred"),
108 a("list_releases", Op::About(AboutOp::ListReleases), "Releases, newest first"),
109 a("latest_release", Op::About(AboutOp::GetLatestRelease), "The latest release"),
110 a("get_release", Op::About(AboutOp::GetRelease), "One release by id"),
111 a("get_release_by_tag", Op::About(AboutOp::GetReleaseByTag), "The release of a tag"),
112 a("create_release", Op::About(AboutOp::CreateRelease), "Publish a release of a tag, making the tag if needed"),
113 a("update_release", Op::About(AboutOp::UpdateRelease), "Change a release's title, notes, draft or prerelease"),
114 a("delete_release", Op::About(AboutOp::DeleteRelease), "Delete a release; its tag stays"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step115 a("rename_branch", Op::RenameBranch, "Rename a branch"),
116 a("rename", Op::RenameRepo, "Rename it; old addresses redirect"),
117 a("transfer", Op::TransferRepo, "Move it to another workspace you own"),
Mirroring over REST and MCP118 a("mirror", Op::Mirrors(MirrorsOp::GetMirror), "Its remotes: what it mirrors or is mirrored to"),
119 a("mirror_hand_back_plan", Op::Mirrors(MirrorsOp::GetHandBackPlan), "What handing a takeover back would do, ref by ref"),
120 a("mirror_take_over", Op::Mirrors(MirrorsOp::TakeOver), "Make g1t lead a mirror for now"),
121 a("mirror_ci", Op::Mirrors(MirrorsOp::SetCiFailover), "Run a mirror's workflows on g1t (on), or stop (off)"),
122 a("mirror_hand_back", Op::Mirrors(MirrorsOp::HandBack), "Send a takeover back, deciding diverged refs"),
123 a("mirror_move_to_g1t", Op::Mirrors(MirrorsOp::MoveToG1t), "Stop tracking the remote; g1t leads for good"),
124 a("mirror_sync", Op::Mirrors(MirrorsOp::SyncMirror), "Bring its remotes in step now"),
125 a("mirror_add_remote", Op::Mirrors(MirrorsOp::AddRemote), "Link another g1t or git host"),
126 a("mirror_update_remote", Op::Mirrors(MirrorsOp::UpdateRemote), "Change a remote's settings"),
127 a("mirror_remove_remote", Op::Mirrors(MirrorsOp::RemoveRemote), "Unlink a remote"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step128 a("archive", Op::ArchiveRepo, "Make it read-only"),
129 a("unarchive", Op::UnarchiveRepo, "Make it writable again"),
130 a("set_visibility", Op::SetRepoVisibility, "Make it public or private"),
131 a("delete", Op::DeleteRepo, "Delete it; restorable for 30 days"),
132 a("list_deleted", Op::ListDeletedRepos, "A workspace's deleted repositories"),
133 a("restore", Op::RestoreRepo, "Restore a deleted one"),
134 a("purge", Op::PurgeRepo, "Remove a deleted one for good"),
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily135 a("security_alerts", Op::ListSecurityAlerts, "Secret and dependency alerts, filtered by state"),
136 a("dismiss_alert", Op::DismissSecurityAlert, "Dismiss an alert with a reason"),
137 a("reopen_alert", Op::ReopenSecurityAlert, "Reopen a dismissed alert"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step138 ],
139 },
140 Tool {
141 name: "issue",
142 title: "Issues",
143 description: "Issues: what should change. Read one before working on it to see the pull requests already made for it. Issues and pull requests share numbers; `comment` works on either.",
144 default_action: None,
145 actions: &[
146 a("list", Op::ListIssues, "Issues on a repository, newest first"),
Fast pages, required checks on the branch, self-hosted runners, honest incidents147 a("get", Op::GetIssue, "One issue with comments and its pull requests"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step148 a("create", Op::CreateIssue, "Open an issue"),
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar149 a("update", Op::UpdateIssue, "Change title, body, labels, milestone or assignees"),
150 a("labels", Op::ListIssueLabels, "The labels an issue or pull request carries"),
151 a("add_labels", Op::AddIssueLabels, "Add labels to an issue or pull request"),
152 a("set_labels", Op::SetIssueLabels, "Replace the labels of an issue or pull request"),
153 a("remove_labels", Op::RemoveIssueLabels, "Take labels off an issue or pull request"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step154 a("close", Op::CloseIssue, "Close it without a pull request"),
155 a("reopen", Op::ReopenIssue, "Reopen it"),
156 a("comment", Op::AddComment, "Comment on an issue or pull request; path and line for one line of a change"),
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts157 a("edit_comment", Op::EditComment, "Change a comment's text: your own, or any with the Maintain role"),
158 a("delete_comment", Op::DeleteComment, "Delete a comment: your own, or any with the Maintain role"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step159 a("import", Op::ImportIssue, "Open an issue from a Jira, Linear or Sentry item"),
160 ],
161 },
162 Tool {
163 name: "pull_request",
164 title: "Pull requests",
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar165 description: "Pull requests: start a change for an issue, record your session, mark it ready, ask people and teams to review, review and merge. Read `overlaps` and `behind` on `get` before going far, and `code_owners` for whose approval it needs.",
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step166 default_action: None,
167 actions: &[
168 a("list", Op::ListPullRequests, "Pull requests on a repository, newest first"),
Fast pages, required checks on the branch, self-hosted runners, honest incidents169 a("get", Op::GetPullRequest, "Status, checks and required checks, reviews, overlaps, whether it is behind"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step170 a("changes", Op::GetPullRequestChanges, "Files and line-by-line diff"),
171 a("create", Op::CreatePullRequest, "Start a draft with its own fork to push to, or open one from a pushed branch"),
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar172 a("update", Op::UpdatePullRequest, "Change its base branch, labels, milestone, assignees or reviewers"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step173 a("record_session", Op::RecordSession, "Append prompt, reasoning and tool entries to its session"),
174 a("read_session", Op::ReadSession, "Its recorded session"),
175 a("ready", Op::MarkPullRequestReady, "Mark a draft ready, with a summary"),
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts176 a("draft", Op::ConvertPullRequestToDraft, "Turn it back into a draft"),
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar177 a("request_reviewers", Op::RequestReviewers, "Ask people or teams to review it"),
178 a("remove_requested_reviewers", Op::RemoveRequestedReviewers, "Stop asking people or teams to review it"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step179 a("review", Op::ReviewPullRequest, "Approve or request changes"),
180 a("close", Op::ClosePullRequest, "Close without merging"),
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts181 a("reopen", Op::ReopenPullRequest, "Reopen a closed one"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step182 a("merge", Op::MergePullRequest, "Land it, or join the merge queue"),
183 a("merge_queue", Op::GetMergeQueue, "The repository's merge queue"),
184 ],
185 },
186 Tool {
187 name: "agent",
188 title: "g1t agents",
189 description: "Put g1t's agent to work and talk to it. One agent per issue; to do more at once, use more issues. Starting an agent uses the workspace's money.",
190 default_action: None,
191 actions: &[
192 a("delegate", Op::Delegate, "Open an issue and put an agent on it in one step"),
193 a("assign", Op::AssignIssue, "Put an agent on an existing issue"),
194 a("message", Op::MessageAgent, "Tell the agent on a pull request something, or ask another agent"),
195 a("answer", Op::AnswerMessage, "Answer a question or handoff sent to you"),
196 a("take_messages", Op::TakeMessages, "For a g1t agent: messages not seen yet"),
197 ],
198 },
199 Tool {
200 name: "plan",
201 title: "Plans",
Fast pages, required checks on the branch, self-hosted runners, honest incidents202 description: "Turn an outcome into issues: an agent proposes them with what done means and their dependencies; nothing opens until you apply the plan.",
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step203 default_action: None,
204 actions: &[
205 a("create", Op::PlanWork, "Ask an agent for a plan; read it with get until ready"),
206 a("get", Op::GetPlan, "A plan and the issues it proposes"),
207 a("apply", Op::ApplyPlan, "Open its issues; with assign, agents start in dependency order"),
208 ],
209 },
210 Tool {
211 name: "memory",
212 title: "Memory",
213 description: "What the project and its workspace remember for the next agent: how to build, conventions, decisions, traps. Recall before you start; remember one short fact at a time, never a secret.",
214 default_action: None,
215 actions: &[
216 a("recall", Op::Recall, "Search memory, or list it all"),
217 a("remember", Op::Remember, "Save one fact"),
218 ],
219 },
220 Tool {
221 name: "workflow",
222 title: "Workflows",
Merge branch 'worktree-agent-a3abfcce648e87dca'223 description: "GitHub Actions workflows from .g1t/workflows: their runs, jobs and logs, and running, cancelling or rerunning them. Runs' artifacts: listing, a download link, deleting, and how long they are kept. Deployments wherever they run (reported from any CI, made by jobs with an `environment:`, or built on g1t.page), their statuses and environments, and reporting your own; environments' protection rules, approving or rejecting the jobs they hold, approving a pull request's run from outside, the token's default permissions and repository dispatch. Checks on commits: statuses, check runs (a g1t Actions job is one) and check suites, to read where a commit stands or report on it from CI or an integration. Also the self-hosted runners they run on: a workspace's (`workspace`) or a repository's own (`repo`), their groups, and where agent work runs.",
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step224 default_action: None,
225 actions: &[
226 a("list", Op::ListWorkflows, "Workflows on the default branch"),
227 a("list_runs", Op::ListWorkflowRuns, "Runs, newest first"),
Merge Actions runs: summaries, attempts and re-runs, graceful cancel, log downloads, badges (actions 0009)228 a("get_run", Op::GetWorkflowRun, "One run with its jobs and steps; an earlier attempt with attempt"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step229 a("job_logs", Op::GetJobLogs, "A job's log after a sequence number"),
230 a("dispatch", Op::DispatchWorkflow, "Run a workflow_dispatch workflow"),
Merge Actions runs: summaries, attempts and re-runs, graceful cancel, log downloads, badges (actions 0009)231 a("cancel", Op::CancelWorkflowRun, "Cancel a run, letting its jobs clean up; force stops them outright"),
232 a("rerun", Op::RerunWorkflowRun, "Run a finished run again: all, failed_only, or one job; debug for debug logging"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step233 a("update", Op::UpdateWorkflow, "Turn a workflow on or off"),
Actions: OIDC tokens, the toolkit's cache and artifact services, and artifacts in R2234 a("list_artifacts", Op::Artifacts(ArtifactsOp::ListArtifacts), "A repository's artifacts, newest first; or a run's with run_artifacts"),
235 a("run_artifacts", Op::Artifacts(ArtifactsOp::ListRunArtifacts), "One run's artifacts"),
236 a("get_artifact", Op::Artifacts(ArtifactsOp::GetArtifact), "One artifact: size, digest, expiry, run"),
237 a("download_artifact", Op::Artifacts(ArtifactsOp::DownloadArtifact), "A 10-minute link to an artifact's zip"),
238 a("delete_artifact", Op::Artifacts(ArtifactsOp::DeleteArtifact), "Delete an artifact before it expires"),
239 a("artifact_retention", Op::Artifacts(ArtifactsOp::GetArtifactRetention), "Days the repository keeps artifacts"),
240 a("set_artifact_retention", Op::Artifacts(ArtifactsOp::SetArtifactRetention), "Change the days the repository keeps artifacts"),
Merge checks: statuses and check runs on every commit241 a("combined_status", Op::Checks(ChecksOp::GetCombinedStatus), "A commit's statuses and the state they add up to"),
242 a("list_statuses", Op::Checks(ChecksOp::ListCommitStatuses), "A commit's statuses, newest first"),
243 a("set_status", Op::Checks(ChecksOp::CreateCommitStatus), "Set a status on a commit"),
244 a("list_check_runs", Op::Checks(ChecksOp::ListCheckRunsForRef), "A commit's check runs, g1t Actions jobs included"),
245 a("get_check_run", Op::Checks(ChecksOp::GetCheckRun), "One check run with its report"),
246 a("check_run_annotations", Op::Checks(ChecksOp::ListCheckRunAnnotations), "What a check run says about lines of files"),
247 a("create_check_run", Op::Checks(ChecksOp::CreateCheckRun), "Report a check run on a commit"),
248 a("update_check_run", Op::Checks(ChecksOp::UpdateCheckRun), "Move a check run on, complete it, add annotations"),
249 a("rerequest_check_run", Op::Checks(ChecksOp::RerequestCheckRun), "Ask for a check run to run again"),
250 a("list_check_suites", Op::Checks(ChecksOp::ListCheckSuitesForRef), "A commit's check suites, one per reporter or workflow run"),
251 a("get_check_suite", Op::Checks(ChecksOp::GetCheckSuite), "One check suite"),
252 a("rerequest_check_suite", Op::Checks(ChecksOp::RerequestCheckSuite), "Ask for a check suite to run again"),
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb97253 a("list_deployments", Op::Deployments(DeploymentsOp::ListDeployments), "Deployments wherever they run, newest first, filtered"),
254 a("get_deployment", Op::Deployments(DeploymentsOp::GetDeployment), "One deployment with every status it has had"),
255 a("create_deployment", Op::Deployments(DeploymentsOp::CreateDeployment), "Report a deployment of a ref to an environment"),
256 a("deployment_statuses", Op::Deployments(DeploymentsOp::ListDeploymentStatuses), "A deployment's statuses, newest first"),
257 a("create_deployment_status", Op::Deployments(DeploymentsOp::CreateDeploymentStatus), "Report where a deployment is: in_progress, success, failure"),
258 a("list_environments", Op::Deployments(DeploymentsOp::ListEnvironments), "Environments with their current and latest deployments"),
Merge branch 'worktree-agent-a3abfcce648e87dca'259 a("get_environment", Op::Deployments(DeploymentsOp::GetEnvironment), "One environment by name, with its protection rules"),
260 a("update_environment", Op::Protection(ProtectionOp::UpdateEnvironment), "Set an environment's reviewers, wait timer and branches"),
261 a("delete_environment", Op::Protection(ProtectionOp::DeleteEnvironment), "Remove an environment's protection rules"),
262 a("pending_deployments", Op::Protection(ProtectionOp::GetPendingDeployments), "The environments holding a run's jobs"),
263 a("review_deployments", Op::Protection(ProtectionOp::ReviewPendingDeployments), "Approve or reject a run's jobs for its environments"),
264 a("approve_run", Op::Protection(ProtectionOp::ApproveWorkflowRun), "Let a run of a pull request from outside start"),
265 a("get_permissions", Op::Protection(ProtectionOp::GetWorkflowPermissions), "What a job's token gets without `permissions:`"),
266 a("set_permissions", Op::Protection(ProtectionOp::SetWorkflowPermissions), "Set it: read or write"),
267 a("get_approval_policy", Op::Protection(ProtectionOp::GetForkPrApproval), "Which pull requests' runs wait for approval"),
268 a("set_approval_policy", Op::Protection(ProtectionOp::SetForkPrApproval), "Set which pull requests' runs wait for approval"),
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts269 a("get_access", Op::Protection(ProtectionOp::GetActionsAccess), "Which repositories may use this one's actions and workflows"),
270 a("set_access", Op::Protection(ProtectionOp::SetActionsAccess), "Let the workspace's private repositories use them, or not"),
Merge branch 'worktree-agent-a3abfcce648e87dca'271 a("repository_dispatch", Op::Protection(ProtectionOp::CreateRepositoryDispatch), "Start repository_dispatch workflows with an event"),
272 a("get_workspace_permissions", Op::Protection(ProtectionOp::GetWorkspaceWorkflowPermissions), "A workspace's default and maximum token permissions"),
273 a("set_workspace_permissions", Op::Protection(ProtectionOp::SetWorkspaceWorkflowPermissions), "Set them, and whether jobs may open pull requests"),
Fast pages, required checks on the branch, self-hosted runners, honest incidents274 a("list_runners", Op::ListRunners, "Self-hosted runners, with status, labels and what each is doing"),
275 a("create_runner_token", Op::CreateRunnerRegistrationToken, "A one-hour token for g1t-runner register"),
276 a("remove_runner", Op::RemoveRunner, "Remove a self-hosted runner"),
277 a("list_runner_groups", Op::ListRunnerGroups, "A workspace's runner groups"),
278 a("create_runner_group", Op::CreateRunnerGroup, "Make a group, for some repositories"),
279 a("update_runner_group", Op::UpdateRunnerGroup, "Rename a group or change its repositories"),
280 a("delete_runner_group", Op::DeleteRunnerGroup, "Delete a group; its runners join the default"),
281 a("get_runner_settings", Op::GetRunnerSettings, "Where agent work runs; whether forks may use runners"),
282 a("update_runner_settings", Op::UpdateRunnerSettings, "Change them"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step283 ],
284 },
285 Tool {
Merge packages: roles, Actions access, source label, soft delete, API286 name: "package",
287 title: "Packages",
288 description: "A workspace's packages in every registry (container images, npm, Cargo, Maven, NuGet, RubyGems, Composer): their versions and downloads, deleting and restoring them within 30 days, their visibility and repository, who has a role on them, and which repositories' workflows may use them (Manage Actions access). Name one by workspace, package_type and package_name.",
289 default_action: None,
290 actions: &[
291 a("list", Op::Packages(PackagesOp::ListPackages), "A workspace's packages; state deleted for restorable ones"),
292 a("get", Op::Packages(PackagesOp::GetPackage), "One package: address, visibility, repository, downloads"),
293 a("versions", Op::Packages(PackagesOp::ListVersions), "Its versions with tags and downloads; state deleted too"),
294 a("get_version", Op::Packages(PackagesOp::GetVersion), "One version by id, version, digest or tag"),
295 a("update", Op::Packages(PackagesOp::UpdatePackage), "Set visibility, or inherit_access for a linked one"),
296 a("link", Op::Packages(PackagesOp::LinkPackage), "Link it to a repository of its workspace"),
297 a("unlink", Op::Packages(PackagesOp::UnlinkPackage), "Unlink it: the workspace's, private"),
298 a("access", Op::Packages(PackagesOp::ListAccess), "People and teams with a role on it"),
299 a("set_access", Op::Packages(PackagesOp::SetAccess), "Give a person or team read, write or admin"),
300 a("remove_access", Op::Packages(PackagesOp::RemoveAccess), "Take a person's or team's role away"),
301 a("actions_access", Op::Packages(PackagesOp::ListActionsAccess), "Repositories whose workflows may use it"),
302 a("set_actions_access", Op::Packages(PackagesOp::SetActionsAccess), "Let a repository's workflows read or write it"),
303 a("remove_actions_access", Op::Packages(PackagesOp::RemoveActionsAccess), "Stop a repository's workflows using it"),
304 a("delete", Op::Packages(PackagesOp::DeletePackage), "Delete it; restorable for 30 days"),
305 a("restore", Op::Packages(PackagesOp::RestorePackage), "Restore a deleted package"),
306 a("delete_version", Op::Packages(PackagesOp::DeleteVersion), "Delete a version; restorable for 30 days"),
307 a("restore_version", Op::Packages(PackagesOp::RestoreVersion), "Restore a deleted version"),
308 ],
309 },
310 Tool {
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step311 name: "secret",
312 title: "Secrets and variables",
313 description: "A repository's or workspace's secrets and variables, read by workflows and deployments. Secret values are never returned.",
314 default_action: None,
315 actions: &[
316 a("list_secrets", Op::ListActionsSecrets, "Secrets, without values"),
317 a("set_secret", Op::SetActionsSecret, "Add or change a secret"),
318 a("delete_secret", Op::DeleteActionsSecret, "Remove a secret"),
319 a("list_variables", Op::ListActionsVariables, "Variables, with values"),
320 a("set_variable", Op::SetActionsVariable, "Add or change a variable"),
321 a("delete_variable", Op::DeleteActionsVariable, "Remove a variable"),
322 ],
323 },
324 Tool {
325 name: "webhook",
326 title: "Webhooks",
327 description: "HTTPS addresses sent signed events as they happen, for a repository or a whole workspace.",
328 default_action: None,
329 actions: &[
330 a("list", Op::ListWebhooks, "Webhooks, without secrets"),
331 a("create", Op::CreateWebhook, "Register one; a ping is sent"),
332 a("update", Op::UpdateWebhook, "Change address, events or active"),
333 a("delete", Op::DeleteWebhook, "Remove one"),
334 a("ping", Op::PingWebhook, "Send a ping"),
335 a("list_deliveries", Op::ListWebhookDeliveries, "Latest deliveries"),
336 a("redeliver", Op::RedeliverWebhook, "Send a delivery again"),
337 ],
338 },
339 Tool {
340 name: "access",
341 title: "Who has access",
Merge branch 'worktree-agent-a5a5de74d8863d554' into worktree-agent-a16631325aecf58ca342 description: "Who has access to a repository and with which role (read, triage, write, maintain, admin), outside collaborators, a workspace's base permission, and a repository's deploy keys.",
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step343 default_action: None,
344 actions: &[
345 a("list_collaborators", Op::ListCollaborators, "Everyone with a role, and pending invitations"),
346 a("get_permission", Op::GetCollaboratorPermission, "One person's role and capabilities"),
347 a("add_collaborator", Op::AddCollaborator, "Give someone a role, by username or email"),
348 a("update_collaborator", Op::UpdateCollaborator, "Change a direct role"),
349 a("remove_collaborator", Op::RemoveCollaborator, "Take away a direct role"),
350 a("list_invitations", Op::ListRepoInvitations, "Pending invitations to a repository"),
351 a("revoke_invitation", Op::RevokeRepoInvitation, "Withdraw one"),
352 a("set_base_permission", Op::SetBasePermission, "What every member gets on each repository"),
353 a("list_outside_collaborators", Op::ListOutsideCollaborators, "People with roles who are not members"),
Merge branch 'worktree-agent-a5a5de74d8863d554' into worktree-agent-a16631325aecf58ca354 a("list_deploy_keys", Op::DeployKeys(DeployKeysOp::ListDeployKeys), "SSH keys that reach this one repository"),
355 a("get_deploy_key", Op::DeployKeys(DeployKeysOp::GetDeployKey), "One deploy key, by id"),
356 a("add_deploy_key", Op::DeployKeys(DeployKeysOp::CreateDeployKey), "Add one; read-only unless read_only is false"),
357 a("remove_deploy_key", Op::DeployKeys(DeployKeysOp::DeleteDeployKey), "Delete one"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step358 ],
359 },
360 Tool {
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar361 name: "team",
362 title: "Teams",
363 description: "Teams: groups of a workspace's members, given roles on repositories together, mentioned as @workspace/team and asked to review together. Name one by `workspace` and its slug (`team`). Any member may create a team; the workspace's owners and the team's maintainers manage it. A secret team is seen only by its people and the owners.",
364 default_action: None,
365 actions: &[
366 a("list", Op::ListTeams, "A workspace's teams you can see"),
367 a("get", Op::GetTeam, "One team"),
368 a("create", Op::CreateTeam, "Create a team; you become its maintainer"),
369 a("update", Op::UpdateTeam, "Change its name, slug, description, visibility, parent or notifications"),
370 a("delete", Op::DeleteTeam, "Delete it; its child teams move up"),
371 a("list_members", Op::ListTeamMembers, "Its people and their roles, child teams' with include_child_teams"),
372 a("set_member", Op::SetTeamMember, "Add a member of the workspace, or change their role"),
373 a("remove_member", Op::RemoveTeamMember, "Take someone out of it"),
374 a("list_child_teams", Op::ListChildTeams, "The teams nested under it"),
375 a("list_repos", Op::ListTeamRepos, "The repositories it has a role on"),
376 a("set_repo", Op::SetTeamRepo, "Give it a role on a repository"),
377 a("remove_repo", Op::RemoveTeamRepo, "Take its role on a repository away"),
378 a("set_review_assignment", Op::SetTeamReviewAssignment, "Whom it picks when asked to review"),
379 a("list_user_teams", Op::ListUserTeams, "The teams someone is in"),
380 ],
381 },
382 Tool {
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step383 name: "workspace",
384 title: "Workspaces",
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb97385 description: "Workspaces own repositories (g1t.sh/{workspace}/{repo}): create, update or delete one, invite members, connect integrations and model providers, set rulesets that hold across its repositories, read and change its projects (what each is, where it runs, its links), and keep your own pinned projects at the top of its sidebar.",
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step386 default_action: None,
387 actions: &[
Merge branch 'worktree-agent-ad7c6d88d93adc817'388 a("get", Op::GetWorkspace, "A workspace's details and settings"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step389 a("create", Op::CreateWorkspace, "Create a workspace"),
Packages, with a container registry on g1t.sh; workspaces deleted whole and kept 30 days; Members for every member390 a("delete", Op::DeleteWorkspace, "Delete a workspace and everything in it (support can restore it for 30 days)"),
Merge main (membership, two-factor, GitHub repo roles) into tokens391 a("update", Op::UpdateWorkspace, "Change its name, description, base permission, who may create teams, member privileges or the two-factor requirement"),
392 a("list_members", Op::ListMembers, "Its members, owners first, with their roles"),
393 a("update_member", Op::UpdateMember, "Make someone an owner or a member, billing manager or security manager"),
394 a("remove_member", Op::RemoveMember, "Remove someone from it"),
395 a("transfer_ownership", Op::TransferOwnership, "Hand it to another member: they become an owner, you a member"),
396 a("leave", Op::LeaveWorkspace, "Leave it yourself"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step397 a("list_invites", Op::ListWorkspaceInvites, "Its invites"),
398 a("invite_member", Op::InviteMember, "Invite an email address"),
399 a("revoke_invite", Op::RevokeWorkspaceInvite, "Revoke a pending invite"),
400 a("list_integrations", Op::ListIntegrations, "Model providers, alert sources, trackers"),
401 a("connect_integration", Op::ConnectIntegration, "Connect one"),
AI Gateway: OpenAI's format, open models, and your own providers402 a("update_integration", Op::UpdateIntegration, "Change one: rotate its key, choose its AI Gateway models"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step403 a("disconnect_integration", Op::DisconnectIntegration, "Remove one"),
404 a("test_integration", Op::TestIntegration, "Check its credentials"),
405 a("get_model_routes", Op::GetModelRoutes, "Where each kind of work's model requests go"),
406 a("set_model_routes", Op::SetModelRoutes, "Replace them"),
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb97407 a("list_projects", Op::ListProjects, "Its projects you can see: what each is, where it runs, its links"),
408 a("get_project", Op::GetProject, "One project"),
409 a("update_project", Op::UpdateProject, "Change a project's name, description, kind, where it runs or its links"),
API: pinned projects over REST and MCP410 a("list_pinned_projects", Op::ListPinnedProjects, "Your pinned projects in it, in your order"),
411 a("pin_project", Op::PinProject, "Pin a project, at a position or the end"),
412 a("unpin_project", Op::UnpinProject, "Unpin a project"),
413 a("reorder_pinned_projects", Op::ReorderPinnedProjects, "Put your pins in a new order"),
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge414 a("list_rulesets", Op::Rules(RulesOp::ListWorkspaceRulesets), "Its rulesets, which hold across its repositories"),
415 a("get_ruleset", Op::Rules(RulesOp::GetWorkspaceRuleset), "One of its rulesets"),
416 a("create_ruleset", Op::Rules(RulesOp::CreateWorkspaceRuleset), "Create a ruleset for some or all of its repositories"),
417 a("update_ruleset", Op::Rules(RulesOp::UpdateWorkspaceRuleset), "Change one of its rulesets"),
418 a("delete_ruleset", Op::Rules(RulesOp::DeleteWorkspaceRuleset), "Delete one of its rulesets"),
419 a("rule_evaluations", Op::Rules(RulesOp::ListWorkspaceRuleEvaluations), "How rules judged changes across its repositories"),
API and MCP for a workspace's personal access token rules, members' tokens and approvals420 a("get_token_policy", Op::Tokens(TokenOp::GetTokenPolicy), "Its rules for personal access tokens"),
421 a("set_token_policy", Op::Tokens(TokenOp::SetTokenPolicy), "Change them: kinds allowed, approval, lifetime"),
422 a("list_member_tokens", Op::Tokens(TokenOp::ListMemberTokens), "Members' personal access tokens that reach it"),
423 a("list_token_requests", Op::Tokens(TokenOp::ListTokenRequests), "Fine-grained tokens waiting for approval"),
424 a("review_token_request", Op::Tokens(TokenOp::ReviewTokenRequest), "Approve or deny one"),
425 a("revoke_member_token", Op::Tokens(TokenOp::RevokeMemberToken), "Revoke a member's token in it"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step426 ],
427 },
428 Tool {
Usage, Billing settings and prepaid AI credit; fixes from the UX audit429 name: "billing",
430 title: "Billing",
Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens431 description: "A workspace's billing: its usage by product, project and day, its budget (the monthly spend limit, alerts and whether usage pauses at it), its AI credit, its invoices, and its AI Gateway requests. Amounts are whole millionths of a dollar (`_micros`), or cents (`_cents`) where named. Members read it; changing the budget and buying credit are for owners, as people, and never for g1t's agents.",
Usage, Billing settings and prepaid AI credit; fixes from the UX audit432 default_action: Some("usage"),
433 actions: &[
434 a("usage", Op::GetUsage, "Usage over a range of days, by product, meter, project and day, and what paid for it"),
435 a("budget", Op::GetBudget, "The monthly spend limit, what was spent, alerts and whether usage pauses at the limit"),
436 a("set_budget", Op::SetBudget, "Change the spend limit, alerts, pausing or the alert webhook"),
437 a("ai_credit", Op::GetAiCredit, "AI credit left, its grants, auto-reload and how to buy more"),
438 a("buy_ai_credit", Op::BuyAiCredit, "A payment page to buy AI credit, for a person to open"),
439 a("invoices", Op::ListInvoices, "Every invoice, the itemised usage invoices, and the next one so far"),
440 a("billing_details", Op::GetBillingDetails, "Who invoices are made out to and the payment method on file"),
Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens441 a("gateway_requests", Op::ListGatewayRequests, "Recent AI Gateway requests: model, tokens, cost, status and token"),
Usage, Billing settings and prepaid AI credit; fixes from the UX audit442 ],
443 },
444 Tool {
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar445 name: "security",
446 title: "Security",
447 description: "A repository's security: secret scanning alerts and push protection bypasses, custom secret patterns, code scanning alerts and SARIF uploads, vulnerability alerts, the dependency graph and its SBOM, dependency review, settings, and a workspace's overview. Fix an alert with g1t. Findings are shown to those who can change the code only. Give `repo` (owner/name), or `workspace` for lists across one.",
448 default_action: Some("secret_alerts"),
449 actions: &[
450 a("secret_alerts", Op::Security(SecurityOp::ListSecretAlerts), "Secret scanning alerts; by state, secret_type, validity, bypassed"),
451 a("secret_alert", Op::Security(SecurityOp::GetSecretAlert), "One secret alert, with where it was found and its bypass requests"),
452 a("update_secret_alert", Op::Security(SecurityOp::UpdateSecretAlert), "Dismiss a secret alert with a reason, or reopen it"),
453 a("secret_locations", Op::Security(SecurityOp::ListSecretLocations), "Every file, line and commit a secret is in"),
454 a("bypass", Op::Security(SecurityOp::BypassPushProtection), "Push past push protection with a reason, or ask to"),
455 a("check_validity", Op::Security(SecurityOp::CheckSecretValidity), "Ask a secret's issuer whether it still works"),
456 a("bypass_requests", Op::Security(SecurityOp::ListBypassRequests), "A workspace's push protection bypass requests"),
457 a("review_bypass", Op::Security(SecurityOp::ReviewBypassRequest), "Approve, deny or cancel a bypass request"),
458 a("patterns", Op::Security(SecurityOp::ListCustomPatterns), "Custom secret patterns of a repository or workspace"),
459 a("create_pattern", Op::Security(SecurityOp::CreateCustomPattern), "Create a custom secret pattern, as a draft or published"),
460 a("update_pattern", Op::Security(SecurityOp::UpdateCustomPattern), "Change, publish or unpublish a custom pattern"),
461 a("delete_pattern", Op::Security(SecurityOp::DeleteCustomPattern), "Delete a custom pattern"),
462 a("dry_run_pattern", Op::Security(SecurityOp::DryRunCustomPattern), "Run a pattern over the default branch without saving it"),
463 a("code_alerts", Op::Security(SecurityOp::ListCodeAlerts), "Code scanning alerts; by state, severity, tool, rule_id"),
464 a("code_alert", Op::Security(SecurityOp::GetCodeAlert), "One code scanning alert by number"),
465 a("update_code_alert", Op::Security(SecurityOp::UpdateCodeAlert), "Dismiss a code scanning alert with a reason, or reopen it"),
466 a("analyses", Op::Security(SecurityOp::ListAnalyses), "Code scanning analyses, newest first"),
467 a("upload_sarif", Op::Security(SecurityOp::UploadSarif), "Upload a SARIF file, gzipped and base64-encoded"),
468 a("sarif_upload", Op::Security(SecurityOp::GetSarifUpload), "Whether a SARIF upload was read, and its analyses"),
469 a("vulnerability_alerts", Op::Security(SecurityOp::ListVulnerabilityAlerts), "Vulnerable dependencies; by state, severity, ecosystem, package"),
470 a("vulnerability_alert", Op::Security(SecurityOp::GetVulnerabilityAlert), "One vulnerability alert"),
471 a("update_vulnerability_alert", Op::Security(SecurityOp::UpdateVulnerabilityAlert), "Dismiss a vulnerability alert with a reason, or reopen it"),
472 a("fix", Op::Security(SecurityOp::FixAlert), "Put g1t on an issue to fix an alert"),
473 a("dependency_graph", Op::Security(SecurityOp::GetDependencyGraph), "Every package the lockfiles resolve, direct or transitive"),
474 a("sbom", Op::Security(SecurityOp::GetSbom), "The dependency graph as an SPDX 2.3 document"),
475 a("compare_dependencies", Op::Security(SecurityOp::CompareDependencies), "What changes in dependencies between base...head"),
476 a("settings", Op::Security(SecurityOp::GetSettings), "A repository's security settings"),
477 a("update_settings", Op::Security(SecurityOp::UpdateSettings), "Change when checks fail and dependency review's policy"),
478 a("workspace_settings", Op::Security(SecurityOp::GetWorkspaceSettings), "A workspace's delegated bypass and validity checks"),
479 a("update_workspace_settings", Op::Security(SecurityOp::UpdateWorkspaceSettings), "Turn delegated bypass or validity checks on or off"),
480 a("overview", Op::Security(SecurityOp::GetOverview), "A workspace's alerts, trends and coverage"),
481 ],
482 },
483 Tool {
API: notifications over REST and MCP, with notifications scopes484 name: "notifications",
485 title: "Notifications",
486 description: "Your inbox: what needs you, and what you follow. One thread per issue, pull request, workflow or deployment, with why you were told (`reason`): an agent waiting on you, a review asked of you, an assignment, a mention, your work's checks, or what you subscribe to and watch. Mark threads read or done once handled, and choose what you hear of with subscribe, unsubscribe and watch. Your own: a personal token.",
487 default_action: Some("list"),
488 actions: &[
489 a("list", Op::ListNotifications, "Unread threads, latest first; all, a view, a reason, a repository"),
490 a("get", Op::GetNotificationThread, "One thread with its recent activity and your subscription"),
491 a("mark_read", Op::MarkThreadRead, "Mark a thread read, or unread"),
492 a("mark_all_read", Op::MarkNotificationsRead, "Mark everything read up to a time, or one repository's"),
493 a("done", Op::MarkThreadDone, "Mark a thread done; new activity brings it back"),
494 a("save", Op::SaveThread, "Save a thread, or unsave it"),
495 a("snooze", Op::SnoozeThread, "Snooze a thread until a time, or bring it back"),
496 a("subscription", Op::GetThreadSubscription, "Your subscription to an issue or pull request"),
497 a("subscribe", Op::SetThreadSubscription, "Subscribe to an issue or pull request, or ignore it"),
498 a("unsubscribe", Op::DeleteThreadSubscription, "Unsubscribe until you comment or are mentioned"),
499 a("watching", Op::GetRepoSubscription, "How you watch a repository"),
500 a("watch", Op::SetRepoSubscription, "Watch a repository: participating, all, ignore or custom"),
501 a("unwatch", Op::DeleteRepoSubscription, "Stop watching a repository"),
502 a("watched", Op::ListWatchedRepos, "Repositories you watch other than the default way"),
503 ],
504 },
505 Tool {
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step506 name: "account",
507 title: "Your account",
508 description: "Who this token acts as and its workspaces (`whoami`), your email addresses, your invites, and invitations to repositories waiting for you.",
509 default_action: Some("whoami"),
510 actions: &[
511 a("whoami", Op::Whoami, "Who the token acts as, and its workspaces"),
512 a("list_emails", Op::ListEmails, "Your addresses"),
513 a("add_email", Op::AddEmail, "Add an address"),
Merge email confirmation gate: a code and a link, nothing until confirmed (identity 0036)514 a("confirm_email", Op::ConfirmEmail, "Confirm an address with the code from its email"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step515 a("remove_email", Op::RemoveEmail, "Remove an address"),
516 a("update_email_settings", Op::UpdateEmailSettings, "Primary, backup and privacy"),
517 a("list_invites", Op::ListInvites, "Your invites to g1t"),
518 a("create_invite", Op::CreateInvite, "Make an invite"),
519 a("revoke_invite", Op::RevokeInvite, "Revoke one"),
520 a("list_repository_invitations", Op::ListMyRepoInvitations, "Invitations to repositories for you"),
521 a("accept_repository_invitation", Op::AcceptRepoInvitation, "Accept one"),
522 a("decline_repository_invitation", Op::DeclineRepoInvitation, "Decline one"),
523 ],
524 },
525];
526
527/// Operations that cannot be undone, or reach beyond g1t's own records:
528/// clients ask before running a tool that has any of them.
529fn destructive(op: Op) -> bool {
530 matches!(
531 op,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar532 Op::Security(SecurityOp::DeleteCustomPattern | SecurityOp::BypassPushProtection)
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge533 | Op::Rules(RulesOp::DeleteRepoRuleset | RulesOp::DeleteWorkspaceRuleset)
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar534 | Op::DeleteWorkspace
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily535 | Op::UpdateWorkspace
API and MCP for a workspace's personal access token rules, members' tokens and approvals536 | Op::Tokens(TokenOp::RevokeMemberToken | TokenOp::SetTokenPolicy)
Merge main (membership, two-factor, GitHub repo roles) into tokens537 | Op::RemoveMember
538 | Op::TransferOwnership
539 | Op::LeaveWorkspace
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step540 | Op::DeleteRepo
541 | Op::PurgeRepo
542 | Op::TransferRepo
543 | Op::SetRepoVisibility
544 | Op::RemoveEmail
545 | Op::RemoveCollaborator
546 | Op::DisconnectIntegration
AI Gateway: OpenAI's format, open models, and your own providers547 | Op::UpdateIntegration
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step548 | Op::DeleteWebhook
549 | Op::DeleteActionsSecret
550 | Op::DeleteActionsVariable
551 | Op::SetActionsSecret
552 | Op::SetActionsVariable
553 | Op::SetModelRoutes
554 | Op::SetBasePermission
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar555 | Op::DeleteTeam
556 | Op::RemoveTeamRepo
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step557 | Op::MergePullRequest
Fast pages, required checks on the branch, self-hosted runners, honest incidents558 | Op::RemoveRunner
559 | Op::DeleteRunnerGroup
560 | Op::UpdateRunnerSettings
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step561 )
562}
563
564/// Whether an operation only reads.
565pub fn reads_only(op: Op) -> bool {
566 NO_SCOPE.contains(&op.name())
567 || scope_for(op.name()).is_some_and(|scope| scope.level() == Level::Read)
568}
569
570/// What decides which actions a caller sees.
571pub enum Gate<'a> {
572 /// No limit beyond the person's own role.
573 Everything,
574 /// A g1t agent's token: the operations its run lists.
575 Agent(&'a AgentScope),
576 /// An access token with scopes.
577 Token(&'a TokenAccess),
578}
579
580impl Gate<'_> {
581 pub fn allows(&self, op: Op) -> bool {
582 match self {
583 Gate::Everything => true,
584 Gate::Agent(scope) => op.allowed_by(scope) && !NEVER.contains(&op.name()),
585 Gate::Token(access) => {
586 if NO_SCOPE.contains(&op.name()) {
587 return true;
588 }
589 match scope_for(op.name()) {
590 Some(scope) => access.allows(scope),
591 None => access.scopes.is_none(),
592 }
593 }
594 }
595 }
596}
597
598impl Tool {
599 pub fn by_name(name: &str) -> Option<&'static Tool> {
600 TOOLS.iter().find(|tool| tool.name == name)
601 }
602
603 pub fn action(&self, name: &str) -> Option<&'static Action> {
604 // The tools are 'static; find through TOOLS to keep the lifetime.
605 TOOLS
606 .iter()
607 .find(|tool| tool.name == self.name)
608 .and_then(|tool| tool.actions.iter().find(|action| action.name == name))
609 }
610
611 pub fn visible(&self, gate: &Gate) -> Vec<&'static Action> {
612 TOOLS
613 .iter()
614 .find(|tool| tool.name == self.name)
615 .map(|tool| tool.actions.iter().filter(|action| gate.allows(action.op)).collect())
616 .unwrap_or_default()
617 }
618
619 /// The flat input schema of the actions given.
620 pub fn input_schema(&self, actions: &[&Action]) -> Value {
621 let mut properties = Map::new();
622 let lines: Vec<String> = actions
623 .iter()
624 .map(|action| {
625 let required: Vec<String> = action.op.required();
626 if required.is_empty() {
627 format!("{}: {}.", action.name, action.summary)
628 } else {
629 format!("{} ({}): {}.", action.name, required.join(", "), action.summary)
630 }
631 })
632 .collect();
633 let mut action_schema = json!({
634 "type": "string",
635 "enum": actions.iter().map(|action| action.name).collect::<Vec<_>>(),
636 "description": lines.join("\n"),
637 });
638 if let Some(default) = self.default_action.filter(|name| actions.iter().any(|action| action.name == *name)) {
639 action_schema["default"] = json!(default);
640 }
641 properties.insert("action".to_owned(), action_schema);
642 for action in actions {
643 for (name, schema) in action.op.properties() {
644 merge_property(&mut properties, name, schema);
645 }
646 }
647 let mut required = vec![];
648 if self.default_action.is_none() {
649 required.push("action");
650 }
651 let mut schema = json!({ "type": "object", "properties": properties });
652 if !required.is_empty() {
653 schema["required"] = json!(required);
654 }
655 schema
656 }
657
658 /// The input schema keyed by action: one `oneOf` branch per action,
659 /// each with its own fields and the ones it needs.
660 pub fn discriminated(&self, actions: &[&Action]) -> Value {
661 let branches: Vec<Value> = actions
662 .iter()
663 .map(|action| {
664 let mut properties = Map::new();
665 properties.insert("action".to_owned(), json!({ "const": action.name }));
666 properties.extend(action.op.properties());
667 let mut required = vec![Value::String("action".to_owned())];
668 // The default action may leave `action` out.
669 if self.default_action == Some(action.name) {
670 required.clear();
671 }
672 required.extend(action.op.required().into_iter().map(Value::String));
673 json!({
674 "title": action.name,
675 "description": action.summary,
676 "type": "object",
677 "properties": properties,
678 "required": required,
679 })
680 })
681 .collect();
682 json!({ "type": "object", "oneOf": branches })
683 }
684
685 /// MCP's hints about the actions given: whether the tool only reads,
686 /// whether it can destroy something, and whether calling it twice is
687 /// the same as once.
688 pub fn annotations(&self, actions: &[&Action]) -> Value {
689 let read_only = actions.iter().all(|action| reads_only(action.op));
690 json!({
691 "title": self.title,
692 "readOnlyHint": read_only,
693 "destructiveHint": !read_only && actions.iter().any(|action| destructive(action.op)),
694 "idempotentHint": read_only,
695 "openWorldHint": false,
696 })
697 }
698
699 /// The tool as `tools/list` gives it, for a caller behind `gate`, or
700 /// `None` when it may use none of its actions.
701 pub fn listed(&self, gate: &Gate) -> Option<Value> {
702 let actions = self.visible(gate);
703 if actions.is_empty() {
704 return None;
705 }
706 Some(json!({
707 "name": self.name,
708 "title": self.title,
709 "description": self.description,
710 "inputSchema": self.input_schema(&actions),
711 "annotations": self.annotations(&actions),
712 }))
713 }
714}
715
716/// Adds a property to a tool's flat schema. The first action to use a name
717/// describes it; a later one with other allowed values adds them.
718fn merge_property(properties: &mut Map<String, Value>, name: String, schema: Value) {
719 match properties.get_mut(&name) {
720 None => {
721 properties.insert(name, schema);
722 }
723 Some(existing) => {
724 if let (Some(Value::Array(had)), Some(Value::Array(more))) =
725 (existing.get("enum").cloned(), schema.get("enum"))
726 {
727 let mut merged = had;
728 for value in more {
729 if !merged.contains(value) {
730 merged.push(value.clone());
731 }
732 }
733 existing["enum"] = Value::Array(merged);
734 }
735 // Different kinds of value under one name: say less, accept both.
736 if existing.get("type") != schema.get("type")
737 && let Some(fields) = existing.as_object_mut()
738 {
739 fields.remove("type");
740 fields.remove("items");
741 }
742 }
743 }
744}
745
746/// What a call to a tool runs: the operation its action names, or why not.
747pub fn resolve(tool: &Tool, arguments: &Value) -> Result<Op, String> {
748 let names = || {
749 tool.actions
750 .iter()
751 .map(|action| action.name)
752 .collect::<Vec<_>>()
753 .join(", ")
754 };
755 let Some(name) = arguments["action"].as_str().or(tool.default_action) else {
756 return Err(format!("Give an action: one of {}.", names()));
757 };
758 let Some(action) = tool.action(name) else {
759 return Err(format!("{} has no action {name}. Its actions: {}.", tool.name, names()));
760 };
761 let missing: Vec<String> = action
762 .op
763 .required()
764 .into_iter()
765 .filter(|field| arguments.get(field).is_none_or(Value::is_null))
766 .collect();
767 if !missing.is_empty() {
768 return Err(format!("{}.{name} needs {}.", tool.name, missing.join(", ")));
769 }
770 Ok(action.op)
771}
772
773#[cfg(test)]
774mod tests {
775 use super::*;
776 use g1t_contracts::scopes::{Preset, Scope};
777
778 fn listed(gate: &Gate) -> Vec<Value> {
779 TOOLS.iter().filter_map(|tool| tool.listed(gate)).collect()
780 }
781
782 fn token(scopes: Option<Vec<Scope>>) -> TokenAccess {
783 TokenAccess {
784 token_id: "tok_1".to_owned(),
785 scopes: scopes.map(|scopes| scopes.iter().map(|scope| scope.as_str().to_owned()).collect()),
786 legacy: false,
Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens787 name: None,
Merge branch 'worktree-agent-a3abfcce648e87dca'788 ..TokenAccess::default()
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step789 }
790 }
791
792 #[test]
793 fn every_operation_is_exactly_one_action_of_one_tool() {
794 for op in Op::ALL {
795 let count = TOOLS
796 .iter()
797 .flat_map(|tool| tool.actions.iter())
798 .filter(|action| action.op == op)
799 .count();
800 assert_eq!(count, 1, "{} is {count} actions", op.name());
801 }
802 for tool in TOOLS {
803 let mut names = std::collections::HashSet::new();
804 for action in tool.actions {
805 assert!(names.insert(action.name), "{}.{} twice", tool.name, action.name);
806 }
807 if let Some(default) = tool.default_action {
808 assert!(tool.action(default).is_some(), "{}", tool.name);
809 }
810 }
Merge packages: roles, Actions access, source label, soft delete, API811 assert!(TOOLS.len() <= 18, "{} tools", TOOLS.len());
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step812 }
813
814 #[test]
815 fn every_operation_needs_exactly_one_scope_or_none() {
816 use g1t_contracts::scopes::OPERATIONS;
817 for op in Op::ALL {
818 let mapped = OPERATIONS.iter().filter(|(name, _)| *name == op.name()).count();
819 let free = NO_SCOPE.contains(&op.name());
820 assert_eq!(mapped + usize::from(free), 1, "{}", op.name());
821 }
822 for (name, _) in OPERATIONS {
823 assert!(Op::by_name(name).is_some(), "{name} is not an operation");
824 }
825 }
826
827 #[test]
828 fn each_tool_schema_is_valid_with_one_branch_per_action() {
829 for tool in TOOLS {
830 let actions: Vec<&Action> = tool.actions.iter().collect();
831 let flat = tool.input_schema(&actions);
832 assert_eq!(flat["type"], "object");
833 assert!(flat.get("oneOf").is_none(), "no oneOf at the top level");
834 let listed: Vec<&str> = flat["properties"]["action"]["enum"]
835 .as_array()
836 .unwrap()
837 .iter()
838 .map(|name| name.as_str().unwrap())
839 .collect();
840 assert_eq!(listed, tool.actions.iter().map(|action| action.name).collect::<Vec<_>>());
841 for action in tool.actions {
842 for field in action.op.required() {
843 assert!(flat["properties"].get(&field).is_some(), "{}.{}: {field}", tool.name, action.name);
844 }
845 }
846 let keyed = tool.discriminated(&actions);
847 let branches = keyed["oneOf"].as_array().unwrap();
848 assert_eq!(branches.len(), tool.actions.len());
849 for (branch, action) in branches.iter().zip(tool.actions) {
850 assert_eq!(branch["properties"]["action"]["const"], action.name);
851 for field in branch["required"].as_array().unwrap() {
852 assert!(branch["properties"].get(field.as_str().unwrap()).is_some(), "{}.{}: {field}", tool.name, action.name);
853 }
854 }
855 // A well-formed JSON Schema object throughout.
856 let text = serde_json::to_string(&flat).unwrap();
857 assert!(serde_json::from_str::<Value>(&text).is_ok());
858 }
859 }
860
861 #[test]
862 fn a_read_only_token_sees_read_actions_only() {
863 let access = token(Preset::ReadOnly.scopes());
864 let gate = Gate::Token(&access);
865 for tool in TOOLS {
866 for action in tool.visible(&gate) {
867 assert!(reads_only(action.op), "{}.{}", tool.name, action.name);
868 }
869 }
870 let tools = listed(&gate);
871 for tool in &tools {
872 assert_eq!(tool["annotations"]["readOnlyHint"], true, "{}", tool["name"]);
873 assert_eq!(tool["annotations"]["destructiveHint"], false);
874 }
875 let issue = tools.iter().find(|tool| tool["name"] == "issue").unwrap();
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar876 assert_eq!(issue["inputSchema"]["properties"]["action"]["enum"], json!(["list", "get", "labels"]));
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step877 // Nothing of the agent tool is a read.
878 assert!(!tools.iter().any(|tool| tool["name"] == "agent"));
879 }
880
881 #[test]
882 fn a_narrow_token_sees_only_its_tools() {
883 let access = token(Some(vec![Scope::IssuesWrite]));
884 let names: Vec<Value> = listed(&Gate::Token(&access)).into_iter().map(|tool| tool["name"].clone()).collect();
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar885 // Labels and milestones are the repository's, managed with issues:write.
886 assert_eq!(names, vec![json!("repository"), json!("issue"), json!("plan"), json!("account")]);
API: notifications over REST and MCP, with notifications scopes887 // Notifications are a resource of their own: reading them lists
888 // only what reads.
889 let reader = token(Some(vec![Scope::NotificationsRead]));
890 let tools = listed(&Gate::Token(&reader));
891 let notifications = tools.iter().find(|tool| tool["name"] == "notifications").unwrap();
892 assert_eq!(
893 notifications["inputSchema"]["properties"]["action"]["enum"],
894 json!(["list", "get", "subscription", "watching", "watched"])
895 );
896 assert_eq!(notifications["annotations"]["readOnlyHint"], true);
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step897 let full = token(None);
898 assert_eq!(listed(&Gate::Token(&full)).len(), TOOLS.len());
899 assert_eq!(listed(&Gate::Everything).len(), TOOLS.len());
900 }
901
902 #[test]
903 fn a_tool_that_can_destroy_says_so() {
904 let tools = listed(&Gate::Everything);
905 let repository = tools.iter().find(|tool| tool["name"] == "repository").unwrap();
906 assert_eq!(repository["annotations"]["destructiveHint"], true);
907 assert_eq!(repository["annotations"]["readOnlyHint"], false);
908 let memory = tools.iter().find(|tool| tool["name"] == "memory").unwrap();
909 assert_eq!(memory["annotations"]["destructiveHint"], false);
910 }
911
912 #[test]
913 fn calls_resolve_to_their_operation_or_say_what_is_missing() {
914 let issue = Tool::by_name("issue").unwrap();
915 assert_eq!(resolve(issue, &json!({ "action": "get", "repo": "a/b", "number": 1 })), Ok(Op::GetIssue));
916 assert_eq!(resolve(issue, &json!({ "action": "get", "repo": "a/b" })), Err("issue.get needs number.".to_owned()));
917 assert!(resolve(issue, &json!({})).unwrap_err().starts_with("Give an action"));
918 assert!(resolve(issue, &json!({ "action": "explode" })).unwrap_err().contains("no action explode"));
919 let search = Tool::by_name("search").unwrap();
920 assert_eq!(resolve(search, &json!({ "query": "x" })), Ok(Op::Search));
921 let account = Tool::by_name("account").unwrap();
922 assert_eq!(resolve(account, &json!({})), Ok(Op::Whoami));
923 }
924
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar925 #[test]
926 fn teams_are_one_tool_and_a_workspace_reader_sees_only_its_reads() {
927 let team = Tool::by_name("team").unwrap();
928 let names: Vec<&str> = team.actions.iter().map(|action| action.name).collect();
929 assert_eq!(
930 names,
931 [
932 "list",
933 "get",
934 "create",
935 "update",
936 "delete",
937 "list_members",
938 "set_member",
939 "remove_member",
940 "list_child_teams",
941 "list_repos",
942 "set_repo",
943 "remove_repo",
944 "set_review_assignment",
945 "list_user_teams",
946 ]
947 );
948 let reader = token(Some(vec![Scope::WorkspaceRead]));
949 let tools = listed(&Gate::Token(&reader));
950 let listed_team = tools.iter().find(|tool| tool["name"] == "team").unwrap();
951 assert_eq!(
952 listed_team["inputSchema"]["properties"]["action"]["enum"],
953 json!(["list", "get", "list_members", "list_child_teams", "list_repos", "list_user_teams"])
954 );
955 assert_eq!(listed_team["annotations"]["readOnlyHint"], true);
956 // A team's role on a repository is who has access.
957 let admin = token(Some(vec![Scope::WorkspaceAdmin]));
958 let tools = listed(&Gate::Token(&admin));
959 let listed_team = tools.iter().find(|tool| tool["name"] == "team").unwrap();
960 let actions = listed_team["inputSchema"]["properties"]["action"]["enum"].as_array().unwrap();
961 assert!(actions.contains(&json!("set_review_assignment")) && !actions.contains(&json!("set_repo")));
962 let access = token(Some(vec![Scope::AccessAdmin]));
963 let tools = listed(&Gate::Token(&access));
964 let listed_team = tools.iter().find(|tool| tool["name"] == "team").unwrap();
965 assert_eq!(listed_team["inputSchema"]["properties"]["action"]["enum"], json!(["set_repo", "remove_repo"]));
966 // Both kinds of role a schema names are offered.
967 let roles = &listed(&Gate::Everything).into_iter().find(|tool| tool["name"] == "team").unwrap()["inputSchema"]
968 ["properties"]["role"]["enum"];
969 for role in ["member", "maintainer", "read", "admin"] {
970 assert!(roles.as_array().unwrap().contains(&json!(role)), "{role}");
971 }
972 assert_eq!(
973 resolve(team, &json!({ "action": "set_repo", "workspace": "acme", "team": "backend", "repo": "rocket" })),
974 Err("team.set_repo needs role.".to_owned())
975 );
976 }
977
978 #[test]
979 fn reviewers_and_code_owners_are_actions_of_their_tools() {
980 let pull = Tool::by_name("pull_request").unwrap();
981 assert_eq!(
982 resolve(pull, &json!({ "action": "request_reviewers", "repo": "a/b", "number": 1, "team_reviewers": ["backend"] })),
983 Ok(Op::RequestReviewers)
984 );
985 assert_eq!(pull.action("remove_requested_reviewers").map(|action| action.op), Some(Op::RemoveRequestedReviewers));
986 let repository = Tool::by_name("repository").unwrap();
987 assert_eq!(resolve(repository, &json!({ "action": "codeowners", "repo": "a/b" })), Ok(Op::GetCodeownersErrors));
988 assert!(reads_only(Op::GetCodeownersErrors));
989 assert!(!reads_only(Op::RequestReviewers));
990 }
991
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step992 /// How much smaller `tools/list` is than one tool per operation. Run
993 /// with `--nocapture` to see the numbers.
994 #[test]
995 fn the_tool_list_is_much_smaller_than_one_tool_per_operation() {
996 let before: Vec<Value> = Op::ALL
997 .into_iter()
998 .map(|op| json!({ "name": op.name(), "description": op.description(), "inputSchema": op.input() }))
999 .collect();
1000 let after = listed(&Gate::Everything);
1001 let before_bytes = serde_json::to_string(&json!({ "tools": before })).unwrap().len();
1002 let after_bytes = serde_json::to_string(&json!({ "tools": after })).unwrap().len();
1003 let agent = token(Preset::Agent.scopes());
1004 let agent_bytes = serde_json::to_string(&json!({ "tools": listed(&Gate::Token(&agent)) })).unwrap().len();
1005 let read = token(Preset::ReadOnly.scopes());
1006 let read_bytes = serde_json::to_string(&json!({ "tools": listed(&Gate::Token(&read)) })).unwrap().len();
1007 println!(
1008 "tools/list: before {} tools, {before_bytes} bytes (~{} tokens); after {} tools, {after_bytes} bytes (~{} tokens); agent preset {agent_bytes} bytes (~{} tokens); read only {read_bytes} bytes (~{} tokens)",
1009 before.len(),
1010 before_bytes / 4,
1011 after.len(),
1012 after_bytes / 4,
1013 agent_bytes / 4,
1014 read_bytes / 4,
1015 );
1016 assert!(after_bytes * 2 < before_bytes, "{after_bytes} vs {before_bytes}");
1017 }
1018}

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