Skip to content
Sign in

flagon-io/g1t

public
0

g1t/crates/contracts/src/lib.rs

269 lines10,181 bytesCodeBlame

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

API and MCP server, Rust identity service, registration, site redesign1//! Types and service interfaces shared by every g1t service.
2//!
3//! Each service has a module here holding the data it exchanges and the
4//! arguments of each of its methods. Services and their callers depend on
5//! this crate, never on each other's code.
6
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb977pub mod about;
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look8pub mod access;
9pub mod accounts;
GitHub Actions on g1t, part two: running workflows10pub mod actions;
Agents and memory, checks and conflicts, profiles, slug renames, custom domains11pub mod agents;
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API12pub mod audit;
Merge branch 'worktree-agent-ac5b181a013e54348'13pub mod backups;
Agents as a team: lifecycle, merge queue, billing and a new shell14pub mod billing;
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API15pub mod capture;
Merge checks: statuses and check runs on every commit16pub mod checks;
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar17pub mod codeowners;
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API18pub mod credentials;
Rust repos service with shipping; pull requests kept in the model19pub mod events;
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look20pub mod github;
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API21pub mod guardrails;
API and MCP server, Rust identity service, registration, site redesign22pub mod identity;
Inbox: the events service tells people what needs them as events arrive23pub mod inbox;
Integrations: your own model provider, alerts that open issues, tickets agents read24pub mod integrations;
Merge membership: owners, org roles, GitHub's repo roles, privileges, 2FA25pub mod members;
API and MCP server, Rust identity service, registration, site redesign26mod ids;
27mod names;
28mod outcome;
Packages, with a container registry on g1t.sh; workspaces deleted whole and kept 30 days; Members for every member29pub mod packages;
Projects: what a workspace builds and runs, first on every page30pub mod projects;
Rust repos service with shipping; pull requests kept in the model31pub mod repos;
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge32pub mod rules;
Fast pages, required checks on the branch, self-hosted runners, honest incidents33pub mod runners;
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step34pub mod scopes;
Search across all of g1t, Explore, and a command palette35pub mod search;
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API36pub mod security;
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar37pub mod teams;
38pub mod security_suite;
RFC 3339 timestamps in identity and repos39pub mod time;
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar40pub mod updates;
Webhooks: every event, to your own addresses, signed and retried41pub mod webhooks;
Work service in Rust, with RFC 3339 timestamps42pub mod work;
API and MCP server, Rust identity service, registration, site redesign43
44pub use ids::new_id;
Merge branch 'worktree-agent-a8385d293d42c913a'45pub use names::{
46 aliasable_name, claimable_namespace, is_namespace_shaped, is_reserved_name, is_route_name, is_valid_namespace,
47 is_valid_repo_name,
48};
API and MCP server, Rust identity service, registration, site redesign49pub use outcome::{Failure, FailureCode, Outcome};
50
51use serde::{Deserialize, Serialize};
52
Merge membership: owners, org roles, GitHub's repo roles, privileges, 2FA53/// What a member may do in a workspace. A member may also hold
54/// [`members::OrgRole`]s, which add to it.
Workspaces own repositories55#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
56#[serde(rename_all = "lowercase")]
57pub enum Role {
Merge membership: owners, org roles, GitHub's repo roles, privileges, 2FA58 /// Everything: Admin on every repository, the workspace's members,
59 /// settings, billing and security.
Workspaces own repositories60 Owner,
Merge membership: owners, org roles, GitHub's repo roles, privileges, 2FA61 /// The workspace's base permission on each repository, and what its
62 /// member privileges allow (see [`members::MemberPrivileges`]).
Workspaces own repositories63 Member,
64}
65
Merge membership: owners, org roles, GitHub's repo roles, privileges, 2FA66pub use members::{MemberPrivileges, OrgRole};
67
Workspaces own repositories68/// One workspace a user belongs to.
API and MCP server, Rust identity service, registration, site redesign69#[derive(Clone, Debug, Serialize, Deserialize)]
Workspaces own repositories70pub struct Membership {
71 /// The workspace's name in URLs: `g1t.sh/<slug>`.
72 pub slug: String,
73 pub role: Role,
Workspace names and icons, and a component kit for every control74 /// The workspace's display name, for showing it to people. Set when a
75 /// user is resolved from credentials; absent on principals made up by
76 /// a service.
77 #[serde(default, skip_serializing_if = "Option::is_none")]
78 pub name: Option<String>,
79 /// The workspace's uploaded icon: the SHA-256 of its bytes, served at
80 /// `/avatars/<avatar>`. Absent means the generated letter avatar.
81 #[serde(default, skip_serializing_if = "Option::is_none")]
82 pub avatar: Option<String>,
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look83 /// What a member gets on each of the workspace's repositories: the
84 /// workspace's base permission. Set when a user is resolved from
85 /// credentials; absent means the default, Write. Owners have Admin
86 /// whatever it says. See [`access`].
87 #[serde(default, skip_serializing_if = "Option::is_none")]
88 pub base_permission: Option<access::BasePermission>,
Merge branch 'worktree-agent-ad7c6d88d93adc817'89 /// Who may create the workspace's teams. Set when a user is resolved
90 /// from credentials; absent means the default, any member. See
91 /// [`teams::TeamCreation`].
92 #[serde(default, skip_serializing_if = "Option::is_none")]
93 pub team_creation: Option<teams::TeamCreation>,
Merge membership: owners, org roles, GitHub's repo roles, privileges, 2FA94 /// The roles the member holds besides `role`: billing manager,
95 /// security manager. Set when a user is resolved from credentials.
96 #[serde(default, skip_serializing_if = "Vec::is_empty")]
97 pub org_roles: Vec<OrgRole>,
98 /// What the workspace lets members (and repository admins) do. Set
99 /// when a user is resolved from credentials; absent means the
100 /// defaults. See [`members::MemberPrivileges`].
101 #[serde(default, skip_serializing_if = "Option::is_none")]
102 pub privileges: Option<MemberPrivileges>,
Workspaces own repositories103}
104
Workspace names and icons, and a component kit for every control105impl Membership {
106 /// A plain member of `slug`, as services act inside one workspace.
107 pub fn member(slug: impl Into<String>) -> Self {
108 Membership {
109 slug: slug.into(),
110 role: Role::Member,
111 name: None,
112 avatar: None,
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look113 base_permission: None,
Merge branch 'worktree-agent-ad7c6d88d93adc817'114 team_creation: None,
Merge membership: owners, org roles, GitHub's repo roles, privileges, 2FA115 org_roles: Vec::new(),
116 privileges: None,
Workspace names and icons, and a component kit for every control117 }
118 }
Merge membership: owners, org roles, GitHub's repo roles, privileges, 2FA119
120 /// Whether the member holds `role` besides owner or member.
121 pub fn has(&self, role: OrgRole) -> bool {
122 self.org_roles.contains(&role)
123 }
Workspace names and icons, and a component kit for every control124}
125
Agents as a team: lifecycle, merge queue, billing and a new shell126/// What a set of credentials resolved to.
127#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
128#[serde(rename_all = "lowercase")]
129pub enum PrincipalKind {
130 /// A person's account.
131 #[default]
132 User,
133 /// A workspace, acting through one of its own access tokens. Its `id`
134 /// is the workspace's, its `username` the workspace's slug, and it is a
135 /// member of that workspace and no other.
136 Workspace,
137 /// A g1t agent at work in a sandbox, acting through a token that lives
138 /// as long as its run and can do only what that token's scope lists, in
g1t is one name: its agent's work, commits and comments show as @g1t, and nobody can claim g1t or g1t-agent139 /// one repository. Its `username` is `g1t`.
Agents as a team: lifecycle, merge queue, billing and a new shell140 Agent,
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily141 /// g1t itself: the platform acting on its own, as when it opens a
142 /// pull request to upgrade a vulnerable dependency or merges from the
143 /// queue. Never resolved from credentials: only services make one,
144 /// with [`User::system`]. Its `username` is `g1t`, which nobody can
145 /// register.
146 System,
147}
148
149/// g1t's own identity, as [`PrincipalKind::System`] work is recorded.
150pub mod system {
151 /// Its id wherever an author or actor id is stored.
152 pub const ID: &str = "g1t";
153 /// Its name, shown as the author of what it does.
154 pub const USERNAME: &str = "g1t";
155 /// The address on the commits it makes, which no mailbox receives.
156 pub const EMAIL: &str = "g1t@users.noreply.g1t.sh";
157 /// Ids that earlier versions stored for g1t's own actions, such as a
158 /// merge its settings made. Read as g1t too.
159 pub const LEGACY_IDS: [&str; 3] = ["g1t_policy", "svc_runner", "g1t_runner"];
160
161 /// Whether `id` is g1t's own.
162 pub fn is_system_id(id: &str) -> bool {
163 id == ID || LEGACY_IDS.contains(&id)
164 }
Agents as a team: lifecycle, merge queue, billing and a new shell165}
166
Workspaces own repositories167#[derive(Clone, Debug, Default, Serialize, Deserialize)]
API and MCP server, Rust identity service, registration, site redesign168pub struct User {
169 pub id: String,
170 pub username: String,
Agents as a team: lifecycle, merge queue, billing and a new shell171 #[serde(default)]
172 pub kind: PrincipalKind,
Email verification, password reset, and Git for AI scale positioning173 /// Whether the account's email address has been confirmed. Unverified
174 /// accounts can sign in but cannot create or change anything.
175 #[serde(default)]
176 pub verified: bool,
Workspaces own repositories177 /// The workspaces this user belongs to. Filled in when a user is
178 /// resolved from credentials, so any service can authorize from it.
179 #[serde(default)]
180 pub workspaces: Vec<Membership>,
Workspace names and icons, and a component kit for every control181 /// The person's uploaded avatar: the SHA-256 of its bytes, served at
182 /// `/avatars/<avatar>`. Absent means the generated letter avatar.
183 #[serde(default, skip_serializing_if = "Option::is_none")]
184 pub avatar: Option<String>,
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API185 /// Set on an agent resolved from its token: who it acts for, with which
186 /// credential, and what it may do. See [`credentials`].
187 #[serde(default, skip_serializing_if = "Option::is_none")]
188 pub acting: Option<Box<credentials::Acting>>,
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look189 /// The repositories this user has been given a role on directly,
190 /// whether or not they belong to its workspace. Filled in with
191 /// `workspaces`; see [`access`].
192 #[serde(default, skip_serializing_if = "Vec::is_empty")]
193 pub grants: Vec<access::RepoGrant>,
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step194 /// Set on a user resolved from an access token: its scopes and the
195 /// workspaces or repositories it is limited to. Absent on a signed-in
196 /// session and on an agent (whose `acting` scope applies instead).
197 /// See [`scopes`].
198 #[serde(default, skip_serializing_if = "Option::is_none")]
199 pub token: Option<Box<scopes::TokenAccess>>,
Merge membership: owners, org roles, GitHub's repo roles, privileges, 2FA200 /// The workspaces this person belongs to but cannot use until they
201 /// meet its policy, such as turning on two-factor authentication.
202 /// They are left out of `workspaces` and `grants` meanwhile. Set when
203 /// a person is resolved from a session.
204 #[serde(default, skip_serializing_if = "Vec::is_empty")]
205 pub held: Vec<members::PolicyHold>,
Workspaces own repositories206}
207
208impl User {
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily209 /// g1t itself, acting in `workspace`: what the platform's own work,
210 /// such as security updates, is done and recorded as.
211 pub fn system(workspace: &str) -> User {
212 User {
213 id: system::ID.to_owned(),
214 username: system::USERNAME.to_owned(),
215 kind: PrincipalKind::System,
216 verified: true,
217 workspaces: vec![Membership::member(workspace.to_lowercase())],
218 ..User::default()
219 }
220 }
221
222 /// Whether this is g1t itself.
223 pub fn is_system(&self) -> bool {
224 self.kind == PrincipalKind::System
225 }
226
Workspaces own repositories227 pub fn role_in(&self, slug: &str) -> Option<Role> {
228 self.workspaces
229 .iter()
230 .find(|membership| membership.slug == slug)
231 .map(|membership| membership.role)
232 }
233
234 pub fn is_member(&self, slug: &str) -> bool {
235 self.role_in(slug).is_some()
236 }
Merge membership: owners, org roles, GitHub's repo roles, privileges, 2FA237
238 /// The membership in `slug`, if any.
239 pub fn membership(&self, slug: &str) -> Option<&Membership> {
240 self.workspaces.iter().find(|membership| membership.slug.eq_ignore_ascii_case(slug))
241 }
242
243 /// Whether this is a person who owns `slug`, or holds `role` in it.
244 pub fn owns_or_has(&self, slug: &str, role: OrgRole) -> bool {
245 self.membership(slug)
246 .is_some_and(|membership| membership.role == Role::Owner || membership.has(role))
247 }
248
249 /// Whether the user may manage `slug`'s billing: an owner or a billing
250 /// manager.
251 pub fn manages_billing(&self, slug: &str) -> bool {
252 self.owns_or_has(slug, OrgRole::BillingManager)
253 }
254
255 /// Whether the user may see and manage security across `slug`: an
256 /// owner or a security manager.
257 pub fn manages_security(&self, slug: &str) -> bool {
258 self.owns_or_has(slug, OrgRole::SecurityManager)
259 }
260
261 /// The workspace's member privileges as this user sees them: the
262 /// defaults when the membership does not say.
263 pub fn privileges_in(&self, slug: &str) -> MemberPrivileges {
264 self.membership(slug).and_then(|membership| membership.privileges).unwrap_or_default()
265 }
API and MCP server, Rust identity service, registration, site redesign266}
267
268/// Who is asking. Every read and write in every service takes one.
269pub type Viewer = Option<User>;

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