Skip to content
Sign in

flagon-io/g1t

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

Merge checks: statuses and check runs on every commit1import type { ChecksApi } from "./checks";
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar2import type { CodeownersReport, PullCodeOwners } from "./codeowners";
Initial g1t: services, event bus, intents and attempts3import type { User, Viewer } from "./identity";
Catching up with main takes seconds when the two sides touched different files4import type { PullBranchUpdate, RepoPath } from "./repos";
Initial g1t: services, event bus, intents and attempts5import type { Result } from "./result";
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge6import type { MergeRules, RulesApi } from "./rules";
Initial g1t: services, event bus, intents and attempts7
Issues and pull requests replace intents and attempts8/**
9 * The filter on lists of issues and pull requests. An open pull request is
10 * a draft or one ready for review; a closed one was merged or closed
11 * without merging.
12 */
13export type State = "open" | "closed";
14
15/** Why an issue was closed. */
16export type IssueReason = "completed" | "not_planned";
Initial g1t: services, event bus, intents and attempts17
Issues and pull requests replace intents and attempts18/**
19 * Something that should change in a repository: a bug, a feature, a
20 * question. Opened by a person, an agent or an integration. Pull requests
21 * are made against it; the one that is merged resolves it.
22 *
23 * Issues and pull requests share one sequence of numbers per repository.
24 */
25export type Issue = {
Initial g1t: services, event bus, intents and attempts26 id: string;
27 repoId: string;
Issues and pull requests replace intents and attempts28 /** Shown as `#12`. */
Initial g1t: services, event bus, intents and attempts29 number: number;
30 title: string;
Issues and pull requests replace intents and attempts31 /** Markdown. Also what an agent is given to work from. */
32 body: string;
33 labels: string[];
34 state: State;
35 /** Set when closed. */
36 reason: IssueReason | null;
37 /** The number of the pull request whose merge closed this issue. */
38 resolvedBy: number | null;
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights39 /** Who opened it: a person, an integration, or g1t (`kind` `agent`) for one its agent filed while at work. */
Initial g1t: services, event bus, intents and attempts40 author: User;
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights41 /**
42 * For an issue g1t's agent filed: the person it was working for. They may
43 * manage it as its author could. See `workOwner`.
44 */
45 requestedBy: User | null;
Work service in Rust, with RFC 3339 timestamps46 /** RFC 3339. */
47 createdAt: string;
Issues and pull requests replace intents and attempts48 /** RFC 3339. */
49 updatedAt: string;
50 /** RFC 3339. */
51 closedAt: string | null;
52 /** Pull requests made against this issue, in any state. */
53 pullCount: number;
54 commentCount: number;
Agents as a team: lifecycle, merge queue, billing and a new shell55 /** Usernames of the people it is assigned to. */
56 assignees: string[];
57 /** The numbers of the issues that have to be merged before this one is worked on. */
58 blockedBy: number[];
59 /**
60 * Whether a g1t agent takes it as soon as it can: at once, or when what it
61 * is blocked by has merged.
62 */
63 queued: boolean;
64 /**
65 * The agent working on it now: the one behind its newest pull request
g1t is one name: its agent's work, commits and comments show as @g1t, and nobody can claim g1t or g1t-agent66 * that is still in progress in a fork, such as `g1t`.
Agents as a team: lifecycle, merge queue, billing and a new shell67 */
68 agent: string | null;
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar69 /** The milestone it is in, if any. */
70 milestone?: MilestoneRef | null;
Initial g1t: services, event bus, intents and attempts71};
72
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights73/**
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar74 * A label of a repository: a name, a color and what it means. Issues and
75 * pull requests carry labels by name; names are lowercase.
76 */
77export type Label = {
78 name: string;
79 /** Six hex digits, without `#`. */
80 color: string;
81 description: string;
82 /** How many issues carry it, open or closed. */
83 issues: number;
84 /** How many pull requests carry it, in any state. */
85 pulls: number;
86};
87
88/** A milestone, as an issue or pull request names it. */
89export type MilestoneRef = { number: number; title: string };
90
91/**
92 * A goal, with an optional due date, that issues and pull requests are
93 * gathered under. Its progress is how many of them are closed.
94 */
95export type Milestone = {
96 /** Numbered from 1 in each repository, apart from issues. */
97 number: number;
98 title: string;
99 /** Markdown. */
100 description: string;
101 /** `YYYY-MM-DD`. */
102 dueOn: string | null;
103 state: State;
104 /** Open issues and pull requests in it. */
105 openItems: number;
106 /** Closed issues, and merged or closed pull requests, in it. */
107 closedItems: number;
108 createdAt: string;
109 updatedAt: string;
110 closedAt: string | null;
111};
112
113/** One milestone and what is in it, newest first. */
114export type MilestoneDetail = { milestone: Milestone; issues: Issue[]; pulls: Pull[] };
115
116/** How `setLabels` changes an item's labels. */
117export type LabelChange = "set" | "add" | "remove";
118
119/**
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights120 * Whose an issue or a pull request is to answer for: whoever asked g1t for
121 * it, or its author. They may change, close and steer it, are never asked to
122 * review it and cannot approve it, and see it as theirs. Mirrors
123 * `Pull::owner` in the Rust contracts.
124 */
125export function workOwner(item: Pick<Pull, "author" | "requestedBy">): User {
126 return item.requestedBy ?? item.author;
127}
128
Issues and pull requests replace intents and attempts129/** `draft` is still being worked on; `open` is ready for review. */
130export type PullStatus = "draft" | "open" | "merged" | "closed";
Initial g1t: services, event bus, intents and attempts131
132/** Where the agent runs: on g1t's sandboxes, or in someone's own session. */
Issues and pull requests replace intents and attempts133export type Runtime = "hosted" | "external";
Initial g1t: services, event bus, intents and attempts134
Pull requests from branches135/**
136 * A proposed change. It is made either in a fork created for it, which is
137 * how agents work, or on a branch pushed to the repository itself.
138 */
Issues and pull requests replace intents and attempts139export type Pull = {
Initial g1t: services, event bus, intents and attempts140 id: string;
141 repoId: string;
Issues and pull requests replace intents and attempts142 /** Shown as `#12`. */
Initial g1t: services, event bus, intents and attempts143 number: number;
Issues and pull requests replace intents and attempts144 /** The number of the issue this is for, if any. */
145 issue: number | null;
146 title: string;
147 /** Markdown: what changed and why. Set when marked ready. */
148 body: string | null;
Initial g1t: services, event bus, intents and attempts149 /** A label for the agent doing the work, e.g. `claude-code`. */
150 agent: string;
Issues and pull requests replace intents and attempts151 runtime: Runtime;
152 status: PullStatus;
Pull requests from branches153 /** The fork holding the change, unless it is on a branch. */
154 fork: RepoPath | null;
Diffs on attempts; hosted agent presented as the g1t agent155 /** The fork's repository id. */
Pull requests from branches156 forkRepoId: string | null;
157 /** The branch of the repository holding the change, unless it is in a fork. */
158 branch: string | null;
Initial g1t: services, event bus, intents and attempts159 headCommit: string | null;
Diffs on attempts; hosted agent presented as the g1t agent160 /**
Issues and pull requests replace intents and attempts161 * For a merged pull request, what the branch pointed to before the merge.
162 * Comparing against it shows what the pull request changed.
163 */
164 mergeBase: string | null;
165 /** Username of whoever merged it. */
166 mergedBy: string | null;
167 /** RFC 3339. */
168 mergedAt: string | null;
169 /**
170 * Set on a pull request closed because another one for the same issue was
171 * merged: that one's number.
Diffs on attempts; hosted agent presented as the g1t agent172 */
Issues and pull requests replace intents and attempts173 supersededBy: number | null;
Acceptance checks in sandboxes, line comments and review verdicts174 /**
175 * Where the latest run of the issue's acceptance checks stands, if there
176 * has been one against the current head.
177 */
178 checkStatus: CheckStatus | null;
Agents as a team: lifecycle, merge queue, billing and a new shell179 /** The files it changes, as of its latest push. */
180 files: ChangedFile[];
181 /** Usernames of the people it is assigned to. */
182 assignees: string[];
183 /**
g1t is one name: its agent's work, commits and comments show as @g1t, and nobody can claim g1t or g1t-agent184 * Those whose review was asked for: usernames, and `g1t` when a g1t
Agents as a team: lifecycle, merge queue, billing and a new shell185 * agent was asked.
186 */
187 reviewers: string[];
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar188 /**
189 * Teams whose review was asked for, as `workspace/slug`. A team stays here
190 * after review assignment picks people from it, who are in `reviewers`.
191 */
192 teamReviewers?: string[];
193 /** The labels it carries, by name. */
194 labels?: string[];
195 /** The milestone it is in, if any. */
196 milestone?: MilestoneRef | null;
197 /**
198 * The branch it merges into. Lists and `getPull` name it; null only in
199 * what services pass between themselves, for the default branch.
200 */
201 base?: string | null;
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights202 /** Who opened it: a person, or g1t (`kind` `agent`, username `g1t`) for a change g1t made. */
Issues and pull requests replace intents and attempts203 author: User;
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights204 /**
205 * For a change g1t made: the person who asked for it, by assigning an issue
206 * or handing g1t the work. They answer for it as its author would. See
207 * `workOwner`.
208 */
209 requestedBy: User | null;
Work service in Rust, with RFC 3339 timestamps210 /** RFC 3339. */
211 createdAt: string;
212 /** RFC 3339. */
213 updatedAt: string;
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step214 /**
215 * How sure g1t is of a g1t agent's change, from what it can observe, once
216 * the agent has finished it. Absent before then, and on changes g1t is
217 * not seeing through.
218 */
219 confidence?: Confidence | null;
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge220 /** Who last moved its head (a user id), and when; absent until a push after rulesets arrived. */
221 headPushedBy?: string;
222 headPushedAt?: string;
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step223};
224
225/** How sure g1t is that an agent's change is right. */
226export type ConfidenceLevel = "low" | "medium" | "high";
227
228/**
229 * How sure g1t is of a change an agent made, worked out from what can be
230 * observed: its checks, how often it was sent back, the reviewer agent's
231 * verdict, whether it touched tests, its size, where it reached, how close
232 * it came to its guardrails, and what it asked without an answer. The
233 * agent's own word can only lower it.
234 */
235export type Confidence = {
236 level: ConfidenceLevel;
237 /** A few words each, most telling first: what lowered it, or for `high`, what it rests on. */
238 reasons: string[];
239 /** What the agent said of its own change, if it said. */
240 selfReported: ConfidenceLevel | null;
241 /** What the agent said it was unsure about. */
242 uncertainAbout: string[];
243 /** The agent run it was worked out after. */
244 runId: string | null;
245 /** RFC 3339. */
246 assessedAt: string;
247};
248
249/** What became of the agent when an issue was opened and handed to it in one step. */
250export type AgentStartStatus = "started" | "queued" | "not_started";
251
252/** Whether the agent started, and if not, why and what fixes it. */
253export type AgentStart = {
254 status: AgentStartStatus;
255 /**
256 * Why it did not start: `not_paid`, `trial_used`, `limit`, `paused`,
257 * `issue_cap`, `billing_unavailable` or `no_model`; `waiting` when queued.
258 */
259 code: string | null;
260 /** What happened, in a sentence or two, with what to do. */
261 message: string | null;
262 /** Where the fix is: the workspace's billing or model settings. */
263 fixUrl: string | null;
Initial g1t: services, event bus, intents and attempts264};
265
g1t is one name: its agent's work, commits and comments show as @g1t, and nobody can claim g1t or g1t-agent266/** An issue opened and handed to g1t in one step. The issue exists whatever became of the agent. */
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step267export type Delegated = {
268 issue: Issue;
269 /** The pull request the agent opened, when it started. */
270 pull: Pull | null;
271 agent: AgentStart;
272};
273
Fast pages, required checks on the branch, self-hosted runners, honest incidents274/**
275 * What to put an agent on: an issue's title, and what to do in plain words,
276 * with what done means if you like (a "Definition of done" section). What
277 * has to pass before it merges is the branch's required checks.
278 */
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step279export type DelegateInput = {
280 title: string;
281 body: string;
282 labels?: string[];
Fast pages, required checks on the branch, self-hosted runners, honest incidents283 /** Deprecated: commands, added to the body under "Definition of done". */
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step284 checks?: string[];
285};
286
Agents as a team: lifecycle, merge queue, billing and a new shell287/** One file a pull request changes, and by how much. */
288export type ChangedFile = { path: string; additions: number; deletions: number };
289
290/**
291 * Another pull request in progress that changes some of the same files. Two
292 * for the same issue are alternatives; two for different issues are heading
293 * for a conflict.
294 */
295export type Overlap = {
296 number: number;
297 title: string;
298 /** The number of the issue the other pull request is for. */
299 issue: number | null;
300 /** The files both change. */
301 paths: string[];
302};
303
Fast pages, required checks on the branch, self-hosted runners, honest incidents304/**
305 * On a pull request, `failed` means the merge queue took it out, until its
306 * head moves. The other states are from runs of commands written on issues,
307 * which g1t no longer runs.
308 */
Acceptance checks in sandboxes, line comments and review verdicts309export type CheckStatus = "queued" | "running" | "passed" | "failed" | "errored";
310
Fast pages, required checks on the branch, self-hosted runners, honest incidents311/** How one command went, in a run recorded before checks were workflows. */
Acceptance checks in sandboxes, line comments and review verdicts312export type CheckResult = {
313 command: string;
314 passed: boolean;
315 /** Null when the command was stopped for taking too long. */
316 exitCode: number | null;
317 /** What the command printed; the end of it, when there was a lot. */
318 output: string;
319 durationMs: number;
320};
321
322/**
Fast pages, required checks on the branch, self-hosted runners, honest incidents323 * A record against a pull request's head: the merge queue taking it out,
324 * with why, or an earlier run of commands written on its issue.
Acceptance checks in sandboxes, line comments and review verdicts325 */
326export type CheckRun = {
327 id: string;
328 /** The commit that was checked. */
329 headCommit: string;
330 status: CheckStatus;
331 results: CheckResult[];
332 /** Why the checks could not be run, when `status` is `errored`. */
333 error: string | null;
334 /** RFC 3339. */
335 createdAt: string;
336 /** RFC 3339. */
337 finishedAt: string | null;
338};
339
340/** A reviewer's decision on a pull request. */
341export type Verdict = "approve" | "request_changes";
342
343/**
344 * A comment on an issue or a pull request. On a pull request it can sit on
345 * one line of the change, and it can carry a reviewer's verdict.
346 */
Issues and pull requests replace intents and attempts347export type Comment = {
348 id: string;
Agents as a team: lifecycle, merge queue, billing and a new shell349 /**
350 * Something a person or an agent wrote, or something that happened: an
351 * assignment, a review asked for, a close.
352 */
353 kind: "comment" | "event";
Issues and pull requests replace intents and attempts354 author: User;
Agents as a team: lifecycle, merge queue, billing and a new shell355 /**
356 * Markdown. For an event, what its author did, as the rest of a sentence
357 * that starts with their name: "assigned ana".
358 */
Issues and pull requests replace intents and attempts359 body: string;
Acceptance checks in sandboxes, line comments and review verdicts360 /** The file commented on, for a comment on a line. */
361 path: string | null;
362 /** The line of that file, as numbered after the change. */
363 line: number | null;
364 verdict: Verdict | null;
Issues and pull requests replace intents and attempts365 /** RFC 3339. */
366 createdAt: string;
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts367 /** When its text was last edited, RFC 3339; absent if it never was. */
368 editedAt?: string;
Issues and pull requests replace intents and attempts369};
370
Acceptance checks in sandboxes, line comments and review verdicts371export type NewComment = {
372 /** May be empty when approving. */
373 body: string;
374 path?: string;
375 line?: number;
376 verdict?: Verdict;
377};
378
379/** What a sandbox needs to carry out a check run. */
380export type CheckJob = {
381 runId: string;
382 /** Lets the sandbox, and nothing else, report this run's results. */
383 token: string;
384 commands: string[];
385 /** The repository holding the commit: the fork, or the repository itself. */
386 source: RepoPath;
387 commit: string;
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights388 /** Who the pull request is for (`workOwner`: whoever asked g1t for it, or its author), and so can read its source. */
Acceptance checks in sandboxes, line comments and review verdicts389 author: User;
390 /** Username of whoever wrote the checks: the issue's author. */
391 requestedBy: string;
392 repo: RepoPath;
393 number: number;
394};
395
396export type CheckReport = { results?: CheckResult[]; error?: string; skip?: boolean };
397
Initial g1t: services, event bus, intents and attempts398export type SessionEntryKind = "prompt" | "message" | "tool_call" | "tool_result" | "note";
399
Issues and pull requests replace intents and attempts400/** One step of an agent's session: the "why" behind a pull request's commits. */
Initial g1t: services, event bus, intents and attempts401export type SessionEntry = {
402 seq: number;
403 kind: SessionEntryKind;
404 text: string;
405 /** For tool calls and results. */
406 tool: string | null;
407 /** The fork's head commit when this entry was recorded, if known. */
408 commit: string | null;
Work service in Rust, with RFC 3339 timestamps409 /** RFC 3339. */
410 at: string;
Initial g1t: services, event bus, intents and attempts411};
412
413export type NewSessionEntry = Pick<SessionEntry, "kind" | "text"> &
Work service in Rust, with RFC 3339 timestamps414 Partial<Pick<SessionEntry, "tool" | "commit">>;
Initial g1t: services, event bus, intents and attempts415
Issues and pull requests replace intents and attempts416export type IssueDetail = {
417 issue: Issue;
418 /** Every pull request made against it, oldest first. */
419 pulls: Pull[];
420 comments: Comment[];
421};
Initial g1t: services, event bus, intents and attempts422
Issues and pull requests replace intents and attempts423export type PullDetail = {
424 pull: Pull;
425 /** The issue it is for, if any. */
426 issue: Issue | null;
427 comments: Comment[];
Fast pages, required checks on the branch, self-hosted runners, honest incidents428 /** The latest record against its head: the merge queue taking it out. */
Acceptance checks in sandboxes, line comments and review verdicts429 checks: CheckRun | null;
Agents as a team: lifecycle, merge queue, billing and a new shell430 /** Other pull requests in progress that change the same files. */
431 overlaps: Overlap[];
432 /**
433 * Whether the branch it would merge into has moved on without it, so that
434 * it has to catch up before it can merge.
435 */
436 behind: boolean;
437 /** Whether a g1t agent is reviewing it right now. */
438 reviewPending: boolean;
439 /**
440 * Where it stands on its way to being merged, for a pull request g1t is
441 * seeing through. Null on anyone else's.
442 */
443 lifecycle: Lifecycle | null;
444 /**
445 * A merge was asked for while it was behind: g1t is bringing it up to
446 * date and will then land it.
447 */
448 landing: boolean;
449 /** Why g1t stopped working on it, if it did. */
450 stalled: string | null;
Usage, like a hosting provider's: what agents cost, per day, task, repository and pull request451 /** Messages people sent the agent while it worked, oldest first. */
452 messages: AgentMessage[];
GitHub Actions on g1t, part three: .g1t/workflows, the pages, the docs453 /** What workflow runs said about its head commit, one per workflow. */
454 statuses?: CommitStatus[];
Agents and memory, checks and conflicts, profiles, slug renames, custom domains455 /**
456 * Whether it merges cleanly into the branch it targets, worked out ahead
457 * of time whenever either side moves.
458 */
459 mergeable?: Mergeable;
460 /** When `mergeable` is `conflicting`: the files that conflict. */
461 conflicts?: string[];
Fast pages, required checks on the branch, self-hosted runners, honest incidents462 /** Earlier records like `checks`, newest first, without their output. */
Agents and memory, checks and conflicts, profiles, slug renames, custom domains463 earlierChecks?: CheckRun[];
Fast pages, required checks on the branch, self-hosted runners, honest incidents464 /**
465 * The checks the default branch's protection requires, each as it stands
466 * on the head commit. Empty when none are required.
467 */
468 requiredChecks?: RequiredCheck[];
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar469 /**
470 * Who owns the files it changes (the CODEOWNERS file of the branch it
471 * merges into) and whose approval is still needed. Absent without one.
472 */
473 codeOwners?: PullCodeOwners | null;
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge474 /**
475 * The rules of the branch it merges into it does not meet yet, for whoever
476 * is looking: what refuses the merge, what they may bypass, and what rulesets
477 * in evaluate would refuse. Absent once it is closed or merged.
478 */
479 rules?: MergeRules | null;
Fast pages, required checks on the branch, self-hosted runners, honest incidents480};
481
482/** Where a required check stands on a commit; `expected` when nothing has reported it yet. */
483export type RequiredState = "success" | "failure" | "pending" | "expected";
484
485/** One check a branch's protection requires, as it stands on a commit. */
486export type RequiredCheck = {
487 /** A workflow's name, such as `CI`, or another status's context. */
488 name: string;
489 state: RequiredState;
490 description: string | null;
491 /** Where to see more: the workflow run, for one a workflow reported. */
492 targetUrl: string | null;
Agents and memory, checks and conflicts, profiles, slug renames, custom domains493};
494
Fast pages, required checks on the branch, self-hosted runners, honest incidents495/** A check name reported on a repository's commits lately, for choosing required checks. */
496export type SeenCheck = {
497 name: string;
498 /** The events it was reported for, such as `pull_request`; empty for a status that names none. */
499 events: string[];
500 /** RFC 3339. */
501 lastSeen: string;
502};
503
Agents and memory, checks and conflicts, profiles, slug renames, custom domains504/**
Fast pages, required checks on the branch, self-hosted runners, honest incidents505 * A status context's check name: `CI / pull_request` is the `CI` check,
506 * reported for a `pull_request` event. A context that does not end in an
507 * event, such as `g1t / deploy`, is its own name. As the work service reads it.
508 */
509export function checkName(context: string): string {
510 const at = context.lastIndexOf(" / ");
511 if (at <= 0) return context;
512 return STATUS_EVENTS.has(context.slice(at + 3)) ? context.slice(0, at) : context;
513}
514
515const STATUS_EVENTS = new Set([
516 "push",
517 "pull_request",
518 "pull_request_target",
519 "pull_request_review",
520 "merge_group",
521 "workflow_dispatch",
522 "workflow_run",
523 "workflow_call",
524 "schedule",
525 "release",
526 "issues",
527 "issue_comment",
528 "repository_dispatch",
529]);
530
531/**
Agents and memory, checks and conflicts, profiles, slug renames, custom domains532 * Whether a pull request merges cleanly into the branch it targets:
533 * `unknown` when it was never worked out or could not be, `checking` while
534 * a probe merges the two.
535 */
536export type Mergeable = "clean" | "conflicting" | "unknown" | "checking";
537
538/** What a sandbox needs to find out whether a pull request merges cleanly. */
539export type MergecheckJob = {
540 pullId: string;
541 /** Lets the sandbox, and nothing else, report this probe. */
542 token: string;
543 repo: RepoPath;
544 number: number;
545 defaultBranch: string;
546 /** The default branch's commit to merge into. */
547 base: string;
548 /** The repository holding the change: its fork, or the repository. */
549 source: RepoPath;
550 /** The branch of `source` holding it. */
551 branch: string;
552 /** The change's commit. */
553 head: string;
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights554 /** Who the pull request is for (`workOwner`: whoever asked g1t for it, or its author), and so can read its source. */
Agents and memory, checks and conflicts, profiles, slug renames, custom domains555 author: User;
GitHub Actions on g1t, part three: .g1t/workflows, the pages, the docs556};
557
558/** What a workflow run (or another tool) says about a commit. */
559export type CommitStatus = {
560 /** What reported it, such as `CI / push`. */
561 context: string;
562 state: "pending" | "success" | "failure" | "error";
563 description: string | null;
564 targetUrl: string | null;
565 updatedAt: string;
Merge checks: statuses and check runs on every commit566 /** The integration that reported it: `actions`, `deployments`, `security`, `g1t` or `api`. */
567 source?: string;
568 /** Set on the status a check run stands as: the check run's id. */
569 checkRunId?: string;
Agents as a team: lifecycle, merge queue, billing and a new shell570};
571
572/**
573 * A step on the way from an assigned issue to a pull request that is ready
574 * to merge. g1t takes each one without being asked: `working` (the agent is
575 * making the change), `checking`, `reviewing`, `revising` (the agent is
576 * addressing failed checks or a review), `catching_up` (merging in the
Agents asked while not at work are woken to answer577 * branch it would land on), `answering` (woken to answer another agent),
578 * then `ready` for a person to merge. `needs_you`
Agents as a team: lifecycle, merge queue, billing and a new shell579 * means g1t has stopped and a person decides what happens next.
580 */
581export type Stage =
582 | "working"
583 | "checking"
584 | "reviewing"
585 | "revising"
586 | "catching_up"
Agents asked while not at work are woken to answer587 | "answering"
Agents as a team: lifecycle, merge queue, billing and a new shell588 | "queued"
589 | "ready"
590 | "needs_you";
591
592export type Lifecycle = {
593 stage: Stage;
594 /** One sentence saying what is happening, or why it stopped. */
595 detail: string;
596 /** How many times the agent has been sent back to revise it. */
597 revisions: number;
598};
599
600/** What the runner needs to carry out a step of a pull request's lifecycle. */
601export type LifecycleJob = {
602 pullId: string;
603 repo: RepoPath;
604 number: number;
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights605 /** Who the pull request belongs to (`workOwner`: whoever asked g1t for it, or its author). Sandboxes act as them. */
Agents as a team: lifecycle, merge queue, billing and a new shell606 author: User;
607 /** The repository holding the change: its fork, or the repository itself. */
608 source: RepoPath;
609 /** The branch of the source holding the change; its default branch when null. */
610 branch: string | null;
611 defaultBranch: string;
612 title: string;
613 description: string;
614 issue: Issue | null;
615 /** For a revision: the failed checks or the review to address. */
616 feedback: string;
617 /** For a revision: which one this is, from 1. */
618 round: number;
619};
620
Agents asked while not at work are woken to answer621/** An agent woken to answer what other agents sent it while it was not at work. */
622export type Wake = { job: LifecycleJob; messages: AgentMessage[] };
623
Agents as a team: lifecycle, merge queue, billing and a new shell624/**
625 * `planning` while an agent reads the repository and writes it; `ready` for
626 * a person to read and apply; `failed` if it could not be written;
627 * `applied` once its issues are open.
628 */
629export type PlanStatus = "planning" | "ready" | "failed" | "applied";
630
631/** One issue a plan proposes. */
632export type PlannedIssue = {
633 title: string;
634 /** Markdown: what to change, where, and why. */
635 body: string;
636 labels: string[];
Fast pages, required checks on the branch, self-hosted runners, honest incidents637 /** What is true once it is done, in plain words; added to the issue's body under "Definition of done". */
638 done: string[];
Agents as a team: lifecycle, merge queue, billing and a new shell639 /** The files it will most likely change. */
640 files: string[];
641 /**
642 * The positions, counting from 1, of earlier issues in the plan that have
643 * to be merged first.
644 */
645 dependsOn: number[];
646 /** Its number, once the plan has been applied and it was kept. */
647 number: number | null;
648};
649
650/** An outcome someone wrote, and the issues an agent proposes to get there. */
651export type Plan = {
652 id: string;
653 repoId: string;
654 /** The outcome wanted, as written. */
655 brief: string;
656 status: PlanStatus;
657 /** The agent's account of how it split the work. */
658 summary: string;
659 issues: PlannedIssue[];
660 /** Why it could not be written, when `status` is `failed`. */
661 error: string | null;
662 author: User;
663 /** RFC 3339. */
664 createdAt: string;
665 /** RFC 3339. */
666 finishedAt: string | null;
Dark gray base with lavender as an accent, and a live outcome view for plans667 /** Once applied: where each issue it opened stands now, in plan order. */
668 progress: IssueProgress[];
Agents ask each other, hand each other work, and answer669 /** Questions and handoffs between its pull requests' agents, newest first. */
670 exchanges: AgentMessage[];
Agents as a team: lifecycle, merge queue, billing and a new shell671};
672
673/** What a sandbox needs to write a plan. */
674export type PlanJob = {
675 planId: string;
676 /** Lets the sandbox, and nothing else, report this plan. */
677 token: string;
678 brief: string;
679 repo: RepoPath;
Issues and pull requests replace intents and attempts680};
Initial g1t: services, event bus, intents and attempts681
Agents as a team: lifecycle, merge queue, billing and a new shell682/** An issue waiting for a g1t agent that can be given one now. */
683export type ReadyIssue = {
684 repo: RepoPath;
685 number: number;
686 /** Who queued it, on whose say-so the agent works. */
687 actor: User;
688};
689
690/**
691 * How a repository wants its pull requests handled. A repository that has
692 * changed nothing has the defaults.
693 */
694export type RepoSettings = {
695 /**
696 * Land a g1t agent's pull request without a person once it is ready:
697 * checks passed and approved as the settings below require.
698 */
699 autoMerge: boolean;
700 /**
Fast pages, required checks on the branch, self-hosted runners, honest incidents701 * The checks that must pass on a pull request's head before it may merge
702 * into the default branch, by name: a workflow's name (`CI`) or another
703 * status's context (`g1t / deploy`). The same for people and agents, and
704 * for the merge queue.
705 */
706 requiredChecks: string[];
707 /**
Agents as a team: lifecycle, merge queue, billing and a new shell708 * Refuse to merge a pull request that does not contain the default
709 * branch's latest commits, so that what merges is what was checked. When
710 * off, merging one that is behind brings it up to date first.
711 */
712 requireUpToDate: boolean;
713 /**
714 * How many approving reviews a pull request needs before it may merge. A
715 * reviewer who has since asked for changes blocks it.
716 */
717 requiredApprovals: number;
718 /** Whether a g1t agent's approval counts towards `requiredApprovals`. */
719 countAgentApprovals: boolean;
Fast pages, required checks on the branch, self-hosted runners, honest incidents720 /** Whether someone who may merge can bypass required checks that have not passed. */
Agents as a team: lifecycle, merge queue, billing and a new shell721 allowIgnoringChecks: boolean;
722 /** Whether a g1t agent's pull request is reviewed by a second agent unasked. */
723 agentReview: boolean;
724 /**
725 * How many times a g1t agent is sent back to its pull request before a
726 * person is asked instead.
727 */
728 maxRevisions: number;
729 /**
730 * Merge through a queue: pull requests are tested together with those
731 * ahead of them, and only a combination that passed reaches the default
732 * branch.
733 */
734 mergeQueue: boolean;
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step735 /**
736 * Ask a person before merging a g1t agent's change whose confidence is
737 * low: auto-merge and the merge queue leave it until a person approves it.
738 */
739 holdLowConfidence: boolean;
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar740 /**
741 * Refuse to merge until the code owners of every file it changes have
742 * approved, as many as each section asks. People only; `g1t` only where
743 * the file names `@g1t`.
744 */
745 requireCodeOwnerReview?: boolean;
Agents as a team: lifecycle, merge queue, billing and a new shell746 /** Username of the member who last changed the settings, if anyone has. */
747 updatedBy: string | null;
748 /** RFC 3339. */
749 updatedAt: string | null;
750};
751
752/** The settings a member can change. */
753export type RepoSettingsInput = Omit<RepoSettings, "updatedBy" | "updatedAt">;
754
755/** The next step for a pull request g1t is seeing through, already claimed. */
756export type Advance =
757 | { action: "none" }
758 | { action: "review" | "revise" | "catch_up"; job: LifecycleJob };
759
760/** What a sandbox needs to review a pull request. */
761export type ReviewJob = {
762 runId: string;
763 /** Lets the sandbox, and nothing else, report this review. */
764 token: string;
765 /** The repository holding the commit: the fork, or the repository itself. */
766 source: RepoPath;
767 commit: string;
768 repo: RepoPath;
769 defaultBranch: string;
770 number: number;
771 title: string;
772 description: string;
773 /** The issue the pull request is for, which says what it should achieve. */
774 issue: Issue | null;
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights775 /** Who the pull request is for (`workOwner`: whoever asked g1t for it, or its author), and so can read its source. */
Agents as a team: lifecycle, merge queue, billing and a new shell776 author: User;
Auto model routing: the cheapest tier that can do each piece of work, a retry goes up a tier, and each run records its tier777 /**
778 * The files it changes, as of its latest push: how large the change is,
779 * which decides the model that reviews it.
780 */
781 files: ChangedFile[];
782 /**
783 * What among them runs, configures or guards things (CI workflows,
784 * secrets, infrastructure), once each. Any sends the review to the
785 * larger model.
786 */
787 sensitive: string[];
Agents as a team: lifecycle, merge queue, billing and a new shell788};
789
Issues and pull requests replace intents and attempts790export type OpenIssueInput = {
791 title: string;
792 body: string;
793 labels?: string[];
Fast pages, required checks on the branch, self-hosted runners, honest incidents794 /** Deprecated: commands, added to the body under "Definition of done". */
Issues and pull requests replace intents and attempts795 checks?: string[];
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar796 /** The number of the milestone to put it in. Needs the Triage role. */
797 milestone?: number;
Issues and pull requests replace intents and attempts798};
799
Agents as a team: lifecycle, merge queue, billing and a new shell800export type UpdateIssueInput = {
801 title?: string;
802 body?: string;
803 labels?: string[];
804 /** Usernames of the people it is assigned to; replaces the whole set. */
805 assignees?: string[];
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar806 /** The number of the milestone to put it in; 0 takes it out. */
807 milestone?: number;
Agents as a team: lifecycle, merge queue, billing and a new shell808};
Issues and pull requests replace intents and attempts809
810export type OpenPullInput = {
811 /** The number of the issue this is for. */
812 issue?: number;
813 /** Defaults to the issue's title; required without an issue. */
814 title?: string;
Pull requests from branches815 /** What changed and why. Usually set later, when a draft is marked ready. */
816 body?: string;
817 /**
818 * A branch of the repository that already holds the change. The pull
819 * request is then ready for review at once and has no fork.
820 */
821 branch?: string;
Issues and pull requests replace intents and attempts822 agent: string;
823 runtime: Runtime;
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar824 /** The branch to merge into: the default branch when left out. */
825 base?: string;
Issues and pull requests replace intents and attempts826};
Initial g1t: services, event bus, intents and attempts827
Fast pages, required checks on the branch, self-hosted runners, honest incidents828/** One repository's pull requests from `pullsForRepos`, newest first. */
829export type RepoPulls = {
830 repoId: string;
831 /** Draft and open. */
832 open: Pull[];
833 /** Merged and closed. */
834 closed: Pull[];
835};
836
Issues and pull requests replace intents and attempts837/** Issues, pull requests, comments and sessions. */
Merge checks: statuses and check runs on every commit838export interface WorkApi extends RulesApi, ChecksApi {
Issues and pull requests replace intents and attempts839 openIssue(actor: User, repo: RepoPath, input: OpenIssueInput): Promise<Result<Issue>>;
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step840 /**
g1t is one name: its agent's work, commits and comments show as @g1t, and nobody can claim g1t or g1t-agent841 * Opens an issue to put g1t on at once: refused, with nothing
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step842 * opened, unless `actor` may put agents to work in `repo`. The runner's
843 * `delegate` calls it, then starts the agent.
844 */
845 delegateIssue(actor: User, repo: RepoPath, input: DelegateInput): Promise<Result<Issue>>;
Issues and pull requests replace intents and attempts846 /** Newest first. */
847 listIssues(
848 repo: RepoPath,
849 viewer: Viewer,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar850 filter?: { state?: State; label?: string; milestone?: number },
Issues and pull requests replace intents and attempts851 ): Promise<Result<Issue[]>>;
852 getIssue(repo: RepoPath, number: number, viewer: Viewer): Promise<Result<IssueDetail>>;
853 /** The author or a member of the workspace may. */
854 updateIssue(actor: User, repo: RepoPath, number: number, input: UpdateIssueInput): Promise<Result<Issue>>;
855 closeIssue(actor: User, repo: RepoPath, number: number, reason?: IssueReason): Promise<Result<Issue>>;
856 reopenIssue(actor: User, repo: RepoPath, number: number): Promise<Result<Issue>>;
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar857 /** A repository's labels, by name, each with how many issues and pull requests carry it. */
858 listLabels(repo: RepoPath, viewer: Viewer): Promise<Result<Label[]>>;
859 /**
860 * Creates a label, or with `name` changes one; renaming it renames it on
861 * everything that carries it. Needs the Triage role.
862 */
863 saveLabel(
864 actor: User,
865 repo: RepoPath,
866 label: { name?: string; newName?: string; color?: string; description?: string },
867 ): Promise<Result<Label>>;
868 /** Removes a label from the repository and everything carrying it. */
869 deleteLabel(actor: User, repo: RepoPath, name: string): Promise<Result<boolean>>;
870 /** Adds the default labels the repository does not have yet; returns them all. */
871 addDefaultLabels(actor: User, repo: RepoPath): Promise<Result<Label[]>>;
872 /**
873 * The labels of an issue or a pull request, replaced, added to or taken
874 * from. Labels the repository lacks are created for someone with the
875 * Triage role. Returns its labels now.
876 */
877 setLabels(
878 actor: User,
879 repo: RepoPath,
880 number: number,
881 labels: string[],
882 change?: LabelChange,
883 ): Promise<Result<string[]>>;
884 /** Open ones by due date, then closed ones; both unless `state` says. */
885 listMilestones(repo: RepoPath, viewer: Viewer, state?: State): Promise<Result<Milestone[]>>;
886 getMilestone(repo: RepoPath, number: number, viewer: Viewer): Promise<Result<MilestoneDetail>>;
887 /** Creates a milestone, or with `number` changes the fields given. Needs the Triage role. */
888 saveMilestone(
889 actor: User,
890 repo: RepoPath,
891 milestone: { number?: number; title?: string; description?: string; dueOn?: string; state?: State },
892 ): Promise<Result<Milestone>>;
893 deleteMilestone(actor: User, repo: RepoPath, number: number): Promise<Result<boolean>>;
Issues and pull requests replace intents and attempts894 /** How many issues and pull requests are open. */
895 counts(repo: RepoPath, viewer: Viewer): Promise<Result<{ issues: number; pulls: number }>>;
Initial g1t: services, event bus, intents and attempts896
Acceptance checks in sandboxes, line comments and review verdicts897 /**
898 * On an issue or a pull request. On a pull request it may name a line of
899 * the change and carry a verdict; nobody can give a verdict on their own.
900 */
901 addComment(actor: User, repo: RepoPath, number: number, comment: NewComment): Promise<Result<Comment>>;
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts902 /**
903 * Changes a comment's text. Its author may, and so may anyone with the
904 * Maintain role or higher; notes of what happened cannot be changed.
905 */
906 editComment(actor: User, repo: RepoPath, commentId: string, body: string): Promise<Result<Comment>>;
907 /**
908 * Deletes a comment: its author, or anyone with the Maintain role or
909 * higher. A review that gave a verdict cannot be deleted, only edited.
910 */
911 deleteComment(actor: User, repo: RepoPath, commentId: string): Promise<Result<boolean>>;
Acceptance checks in sandboxes, line comments and review verdicts912
913 /**
Fast pages, required checks on the branch, self-hosted runners, honest incidents914 * Always refused now: a pull request's checks are the workflows run on
915 * it. Kept for a runner from before.
Acceptance checks in sandboxes, line comments and review verdicts916 */
917 startChecks(pullId: string): Promise<Result<CheckJob>>;
918 /**
Fast pages, required checks on the branch, self-hosted runners, honest incidents919 * What a sandbox says about a run from before checks were workflows: so
920 * one still finishing is recorded.
Acceptance checks in sandboxes, line comments and review verdicts921 */
922 reportChecks(runId: string, token: string, report: CheckReport): Promise<Result<CheckRun>>;
Agents as a team: lifecycle, merge queue, billing and a new shell923 /** Begins a review by a g1t agent. For the runner service. */
924 startReview(pullId: string): Promise<Result<ReviewJob>>;
925 /** Records that a review could not be written. For the runner service. */
926 failReview(runId: string, token: string, error: string): Promise<Result<boolean>>;
Agents and memory, checks and conflicts, profiles, slug renames, custom domains927 /**
928 * Claims the probe of whether a pull request merges cleanly that a
929 * `pull.mergecheck` event asked for. Refused when it is no longer wanted
930 * or the repository has as many running as it may. For the runner service.
931 */
932 startMergecheck(pullId: string): Promise<Result<MergecheckJob>>;
933 /** Records that a probe could not be carried out. For the runner service. */
934 failMergecheck(pullId: string, token: string, error: string): Promise<Result<Mergeable>>;
Agents as a team: lifecycle, merge queue, billing and a new shell935
936 /**
937 * Works out the next step for a pull request g1t is seeing through and,
938 * if there is one to take now, claims it, so that it is taken once
939 * however often this is called. For the runner service.
940 */
941 advance(pullId: string): Promise<Advance>;
942 /** Records that a step could not be carried out, so a person is asked. */
943 stall(pullId: string, reason: string): Promise<boolean>;
944 /** Ids of the open pull requests g1t is seeing through. */
945 managedPulls(repoId?: string): Promise<string[]>;
Issues and pull requests replace intents and attempts946
Agents as a team: lifecycle, merge queue, billing and a new shell947 /** A repository's merge queue: what is in it, in order, and what recently left. */
948 queue(repo: RepoPath, viewer: Viewer): Promise<Result<QueueView>>;
Pull requests from branches949 /**
Agents as a team: lifecycle, merge queue, billing and a new shell950 * The next batch of combined states to test for a repository, one per
951 * entry; empty while a batch is being tested or nothing waits.
952 */
953 queueBuild(repoId: string): Promise<QueueJob[]>;
954 /** Reports that a combined state could not be built or checked. */
955 failQueue(entryId: string, token: string, error: string): Promise<Result<QueueState>>;
Usage, like a hosting provider's: what agents cost, per day, task, repository and pull request956 /** Sends the agent working on a pull request a message, for its next step. */
957 messageAgent(actor: User, repo: RepoPath, number: number, body: string): Promise<Result<AgentMessage>>;
Agents as a team: lifecycle, merge queue, billing and a new shell958 /** Takes a pull request out of the merge queue. Members only. */
959 removeFromQueue(actor: User, repo: RepoPath, number: number): Promise<Result<Pull>>;
960
961 getSettings(repo: RepoPath, viewer: Viewer): Promise<Result<RepoSettings>>;
Fast pages, required checks on the branch, self-hosted runners, honest incidents962 /** The check names reported on the repository's commits in the last 30 days, most recent first. */
963 seenChecks(repo: RepoPath, viewer: Viewer): Promise<Result<SeenCheck[]>>;
Agents as a team: lifecycle, merge queue, billing and a new shell964 /** Members of the repository's workspace only. */
965 updateSettings(actor: User, repo: RepoPath, settings: RepoSettingsInput): Promise<Result<RepoSettings>>;
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar966 /** The CODEOWNERS file at a branch (the default when left out), checked. Needs Read. */
967 codeownersErrors(repo: RepoPath, viewer: Viewer, ref?: string | null): Promise<Result<CodeownersReport>>;
Agents as a team: lifecycle, merge queue, billing and a new shell968 /**
969 * What the runner needs to bring a pull request up to date because a
970 * merge of it was asked for. Null if none was.
971 */
972 catchUpJob(pullId: string): Promise<LifecycleJob | null>;
Agents asked while not at work are woken to answer973 /**
974 * Claims a short step for the agent on a pull request to answer the
975 * questions and handoffs it was sent while not at work, and hands them
976 * over, marked read. Null when there is nothing waiting or it cannot
977 * take a step now.
978 */
979 wakeForMessages(pullId: string): Promise<Wake | null>;
Agents as a team: lifecycle, merge queue, billing and a new shell980
981 /**
Pull requests from branches982 * Opens a pull request: a draft with a fork to push to, or, given a
983 * branch, one ready for review.
984 */
Issues and pull requests replace intents and attempts985 openPull(actor: User, repo: RepoPath, input: OpenPullInput): Promise<Result<Pull>>;
986 /** Newest first. */
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar987 listPulls(
988 repo: RepoPath,
989 viewer: Viewer,
990 state?: State,
991 filter?: { label?: string; milestone?: number; base?: string },
992 ): Promise<Result<Pull[]>>;
Fast pages, required checks on the branch, self-hosted runners, honest incidents993 /**
994 * The newest `limit` open and closed pull requests of each repository,
995 * in one call. Repositories the viewer cannot read, and forks, are left
996 * out: ask those with `listPulls`.
997 */
998 pullsForRepos(repoIds: string[], viewer: Viewer, limit: number): Promise<RepoPulls[]>;
Issues and pull requests replace intents and attempts999 getPull(repo: RepoPath, number: number, viewer: Viewer): Promise<Result<PullDetail>>;
Agents as a team: lifecycle, merge queue, billing and a new shell1000 /**
1001 * Changes who a pull request is assigned to and whose review is asked
g1t is one name: its agent's work, commits and comments show as @g1t, and nobody can claim g1t or g1t-agent1002 * for; each list given replaces the whole set. Asking for `g1t`'s
Agents as a team: lifecycle, merge queue, billing and a new shell1003 * review does not by itself start one: the runner's `review` does.
1004 */
1005 updatePull(
1006 actor: User,
1007 repo: RepoPath,
1008 number: number,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar1009 changes: {
1010 assignees?: string[];
1011 reviewers?: string[];
1012 labels?: string[];
1013 /** 0 takes it out of its milestone. */
1014 milestone?: number;
1015 /** The branch it merges into. Needs the Write role. */
1016 base?: string;
1017 },
Agents as a team: lifecycle, merge queue, billing and a new shell1018 ): Promise<Result<Pull>>;
Catching up with main takes seconds when the two sides touched different files1019 /**
1020 * Brings a pull request up to date with the default branch in seconds,
1021 * without a sandbox, when the two changed different files: the merge
1022 * commit is pushed to its branch as `actor`, who must be whoever opened
1023 * it (for a fork) or a member (for a branch). Otherwise `needs_agent`, and
1024 * nothing is pushed: the runner's `update` is the way on.
1025 */
1026 catchUpPull(actor: User, repo: RepoPath, number: number): Promise<Result<PullBranchUpdate>>;
Issues and pull requests replace intents and attempts1027 /** Marks a draft ready for review and sets its description. */
1028 readyPull(actor: User, repo: RepoPath, number: number, summary: string): Promise<Result<Pull>>;
1029 closePull(actor: User, repo: RepoPath, number: number): Promise<Result<Pull>>;
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts1030 /** Opens a closed pull request again, as the draft it was if it was closed as one. Never a merged one. */
1031 reopenPull(actor: User, repo: RepoPath, number: number): Promise<Result<Pull>>;
1032 /** Turns an open pull request back into a draft; it leaves the merge queue. */
1033 convertPullToDraft(actor: User, repo: RepoPath, number: number): Promise<Result<Pull>>;
Rust repos service with shipping; pull requests kept in the model1034 /**
Issues and pull requests replace intents and attempts1035 * Lands the pull request on the repository's default branch. Unless
1036 * `keepIssueOpen`, that resolves the issue it was for: the issue closes
1037 * naming this pull request, and the others still in progress for it close
1038 * as superseded. Only members of the repository's workspace may merge.
Agents as a team: lifecycle, merge queue, billing and a new shell1039 *
1040 * If the default branch has moved, the pull request is brought up to date
1041 * first and lands when that is done; it comes back still open, and
1042 * `PullDetail.landing` is true meanwhile. A repository that requires pull
1043 * requests to be up to date refuses instead.
Rust repos service with shipping; pull requests kept in the model1044 */
Acceptance checks in sandboxes, line comments and review verdicts1045 mergePull(
1046 actor: User,
1047 repo: RepoPath,
1048 number: number,
1049 options?: {
1050 keepIssueOpen?: boolean;
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge1051 /** Merge although required checks have not passed, where the rule requiring them allows it. */
Acceptance checks in sandboxes, line comments and review verdicts1052 ignoreChecks?: boolean;
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge1053 /** Merge past rules a ruleset lets the actor bypass. Recorded as a bypass. */
1054 bypassRules?: boolean;
Acceptance checks in sandboxes, line comments and review verdicts1055 },
1056 ): Promise<Result<Pull>>;
Agents as a team: lifecycle, merge queue, billing and a new shell1057 /**
1058 * Drafts and open pull requests the viewer started, most recently active
1059 * first, each with where it stands if g1t is seeing it through.
1060 */
1061 listActivePulls(
1062 viewer: Viewer,
1063 ): Promise<{ pull: Pull; issue: Issue | null; lifecycle: Lifecycle | null }[]>;
Agents and memory, checks and conflicts, profiles, slug renames, custom domains1064 /**
1065 * The issues and pull requests a person opened, a page at a time, only
1066 * on repositories the viewer may read. Not found for no such account.
1067 */
1068 byAuthor(username: string, viewer: Viewer, filter?: AuthoredFilter): Promise<Result<Authored>>;
Initial g1t: services, event bus, intents and attempts1069
Agents as a team: lifecycle, merge queue, billing and a new shell1070 /**
1071 * Records an outcome to plan for. Members only. For the runner service,
1072 * which starts the sandbox in which an agent writes the plan.
1073 */
1074 startPlan(actor: User, repo: RepoPath, brief: string): Promise<Result<PlanJob>>;
1075 /** Records that a plan could not be written. For the runner service. */
1076 failPlan(planId: string, token: string, error: string): Promise<Result<boolean>>;
1077 /** Members only. */
1078 getPlan(repo: RepoPath, viewer: Viewer, id: string): Promise<Result<Plan>>;
1079 /** Newest first. Members only. */
1080 listPlans(repo: RepoPath, viewer: Viewer): Promise<Result<Plan[]>>;
1081 /**
1082 * Opens a plan's issues, each blocked by the ones it depends on. With
1083 * `assign`, each is queued for a g1t agent. `keep` holds the positions,
1084 * from 1, of the issues to open; all of them when absent. Once.
1085 */
1086 applyPlan(
1087 actor: User,
1088 repo: RepoPath,
1089 id: string,
1090 options?: { assign?: boolean; keep?: number[] },
1091 ): Promise<Result<Plan>>;
1092 /** Asks for a g1t agent to take an issue as soon as it can, or withdraws that. */
1093 queueIssue(actor: User, repo: RepoPath, number: number, queued: boolean): Promise<Result<boolean>>;
1094 /** Issues waiting for a g1t agent that can be given one now. For the runner. */
1095 readyIssues(repoId?: string): Promise<ReadyIssue[]>;
1096
1097 /** Open issues assigned to the viewer, most recently changed first. */
1098 listAssignedIssues(viewer: Viewer): Promise<Issue[]>;
1099
Issues and pull requests replace intents and attempts1100 appendSession(actor: User, repo: RepoPath, number: number, entries: NewSessionEntry[]): Promise<Result<{ count: number }>>;
1101 readSession(repo: RepoPath, number: number, viewer: Viewer, afterSeq?: number): Promise<Result<SessionEntry[]>>;
Initial g1t: services, event bus, intents and attempts1102}
Pull requests from branches1103
1104/**
1105 * What to pass `ReposApi.compare` to see what a pull request changes.
1106 *
1107 * A fork is compared as a whole. A branch is compared by name while the
1108 * pull request is open, and by the commit it was merged or closed at
1109 * afterwards, so later pushes to the branch do not change the record.
1110 */
1111export function pullComparison(pull: Pull): {
1112 repoId: string;
1113 base: string | null;
1114 head: string | null;
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar1115 /** The branch it merges into, which it is compared from. */
1116 baseBranch: string | null;
Pull requests from branches1117} {
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar1118 const baseBranch = pull.base ?? null;
1119 if (pull.forkRepoId) return { repoId: pull.forkRepoId, base: pull.mergeBase, head: null, baseBranch };
Pull requests from branches1120 const settled = pull.status === "merged" || pull.status === "closed";
1121 return {
1122 repoId: pull.repoId,
1123 base: pull.mergeBase,
1124 head: (settled && pull.headCommit) || pull.branch,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar1125 baseBranch,
Pull requests from branches1126 };
1127}
Agents as a team: lifecycle, merge queue, billing and a new shell1128
1129
1130/** Where a pull request in a merge queue stands. */
Dark gray base with lavender as an accent, and a live outcome view for plans1131/** Where one issue of an applied plan stands. */
1132export type IssueProgress = {
1133 number: number;
1134 title: string;
1135 /**
1136 * `blocked`, `waiting` (for an agent), `open`, a lifecycle stage,
1137 * `landed` or `closed`.
1138 */
1139 state: string;
1140 detail: string;
1141 /** The issues it is waiting on that are still open. */
1142 blockedBy: number[];
1143 pull: number | null;
1144 agent: string | null;
1145};
1146
Usage, like a hosting provider's: what agents cost, per day, task, repository and pull request1147/** A message a person sent an agent at work on a pull request. */
1148export type AgentMessage = {
1149 id: string;
1150 author: string;
1151 body: string;
1152 createdAt: string;
1153 /** When the agent received it; null until then. */
1154 deliveredAt: string | null;
Agents ask each other, hand each other work, and answer1155 /** `message` from a person; from an agent a `question`, `handoff` or `answer`. */
1156 kind: "message" | "question" | "handoff" | "answer";
1157 /** The pull request whose agent sent it, when an agent did. */
1158 fromNumber: number | null;
1159 /** The pull request it was sent to. */
1160 toNumber: number;
1161 /** The reply to a question or handoff, once there is one. */
1162 answer: string | null;
1163 declined: boolean;
1164 /** For the sending agent: what to expect when the one it asked is not at work. */
1165 hint?: string;
Usage, like a hosting provider's: what agents cost, per day, task, repository and pull request1166};
1167
Agents as a team: lifecycle, merge queue, billing and a new shell1168export type QueueState = "waiting" | "testing" | "passed" | "failed" | "landed" | "removed";
1169
1170/** One pull request's place in a merge queue. */
1171export type QueueEntry = {
1172 id: string;
1173 number: number;
1174 title: string;
1175 agent: string;
1176 state: QueueState;
1177 /** The pull requests merged ahead of it in the state being tested, in order. */
1178 ahead: number[];
1179 baseCommit: string | null;
1180 combinedCommit: string | null;
1181 error: string | null;
1182 results: CheckResult[];
1183 /** Username of whoever merged it into the queue: a person, or `g1t`. */
1184 enqueuedBy: string;
1185 /** RFC 3339. */
1186 createdAt: string;
1187 /** RFC 3339. */
1188 finishedAt: string | null;
1189};
1190
1191/** A repository's merge queue: what is in it, in order, and what recently left. */
1192export type QueueView = {
1193 enabled: boolean;
1194 active: QueueEntry[];
1195 /** Newest first. */
1196 recent: QueueEntry[];
1197};
1198
1199export type QueueStackItem = {
1200 number: number;
1201 title: string;
1202 /** The repository holding the change, and its branch. */
1203 source: RepoPath;
1204 branch: string;
1205 commit: string;
1206};
1207
1208/** What a sandbox needs to build and check one combined state. */
1209export type QueueJob = {
1210 entryId: string;
1211 token: string;
1212 repo: RepoPath;
1213 defaultBranch: string;
1214 baseCommit: string;
1215 branch: string;
1216 stack: QueueStackItem[];
Fast pages, required checks on the branch, self-hosted runners, honest incidents1217 /** Always empty: the state is checked by the merge_group workflows run on it. */
Agents as a team: lifecycle, merge queue, billing and a new shell1218 checks: string[];
Fast pages, required checks on the branch, self-hosted runners, honest incidents1219 /** Always empty, as `checks`. */
Agents as a team: lifecycle, merge queue, billing and a new shell1220 contractChecks: string[];
1221 actor: User;
1222};
Agents and memory, checks and conflicts, profiles, slug renames, custom domains1223
1224// --- A person's work ---------------------------------------------------------
1225// Mirrors the `Authored*` types in `crates/contracts/src/work.rs`.
1226
1227export type AuthoredKind = "issue" | "pull";
1228/** `closed` takes in merged pull requests too; `merged` is only those. */
1229export type AuthoredState = "open" | "closed" | "merged";
1230/** `created` is newest first, `updated` most recently changed, `oldest` oldest first. */
1231export type AuthoredSort = "created" | "updated" | "oldest";
1232
1233/** The most items one `byAuthor` page holds. */
1234export const AUTHORED_PAGE = 25;
1235
1236export type AuthoredFilter = {
1237 kind?: AuthoredKind;
1238 state?: AuthoredState;
1239 /** `namespace/name`. */
1240 repo?: string;
1241 sort?: AuthoredSort;
1242 /** The `next` of the page before. */
1243 before?: string;
1244 limit?: number;
1245};
1246
1247export type AuthoredItem = {
1248 kind: AuthoredKind;
1249 repo: RepoPath;
1250 number: number;
1251 title: string;
1252 /** A merged pull request is closed. */
1253 state: State;
1254 /** A pull request's own status; null on an issue. */
1255 status: PullStatus | null;
1256 /** Why an issue was closed. */
1257 reason: IssueReason | null;
1258 draft: boolean;
1259 merged: boolean;
1260 /** RFC 3339. */
1261 createdAt: string;
1262 /** RFC 3339. */
1263 updatedAt: string;
1264 /** RFC 3339. */
1265 mergedAt: string | null;
1266};
1267
1268/** Over every repository the viewer may read, whatever the filters. */
1269export type AuthoredCounts = {
1270 pullsMerged: number;
1271 pullsOpen: number;
1272 pulls: number;
1273 issues: number;
1274 issuesOpen: number;
1275};
1276
1277export type Authored = {
1278 items: AuthoredItem[];
1279 /** Pass as `before` for the next page; null on the last. */
1280 next: string | null;
1281 counts: AuthoredCounts;
1282 /** The repositories they worked in that the viewer may read, most work first. */
1283 repos: { repo: RepoPath; count: number }[];
1284};

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