GitForge
Defined in: src/forge/types.ts:239
Properties
Section titled “Properties”deployWorkflow
Section titled “deployWorkflow”
readonlydeployWorkflow:string|null
Defined in: src/forge/types.ts:245
Configured deploy workflow filename, or null if redeploy is unavailable.
isFork?
Section titled “isFork?”
readonlyoptionalisFork?:boolean
Defined in: src/forge/types.ts:251
True when this forge runs in fork mode — origin is a fork and slug is the
upstream it was forked from (the gh repo fork --clone topology). Drives the
repo picker’s per-fork “Sync fork” affordance. Absent/false ⇒ not a fork.
readonlykind:ForgeKind
Defined in: src/forge/types.ts:240
mergeMethod
Section titled “mergeMethod”
readonlymergeMethod:MergeMethod
Defined in: src/forge/types.ts:243
Default merge method for this host (from config; “squash” if unset).
readonlyslug:string|null
Defined in: src/forge/types.ts:241
webUrl?
Section titled “webUrl?”
readonlyoptionalwebUrl?:string|null
Defined in: src/forge/types.ts:247
Repo’s web home page (e.g. https://github.com/owner/repo); null when unbuildable; absent → null.
Methods
Section titled “Methods”addBlockedBy()?
Section titled “addBlockedBy()?”
optionaladdBlockedBy(issueNumber,blockerNumber):Promise<void>
Defined in: src/forge/types.ts:382
Parameters
Section titled “Parameters”issueNumber
Section titled “issueNumber”number
blockerNumber
Section titled “blockerNumber”number
Returns
Section titled “Returns”Promise<void>
addIssueLabel()?
Section titled “addIssueLabel()?”
optionaladdIssueLabel(issueNumber,label):Promise<void>
Defined in: src/forge/types.ts:361
Stamp a label on an issue, creating it on the host if absent (best-effort; the
drain claims a backlog issue with ACTIVE_LABEL when it spawns, so a second
shepherd instance skips it). Optional: hosts without a label API omit it and
claims degrade to single-instance local dedup.
Parameters
Section titled “Parameters”issueNumber
Section titled “issueNumber”number
string
Returns
Section titled “Returns”Promise<void>
addSubIssue()?
Section titled “addSubIssue()?”
optionaladdSubIssue(parentNumber,childNumber):Promise<void>
Defined in: src/forge/types.ts:381
Parameters
Section titled “Parameters”parentNumber
Section titled “parentNumber”number
childNumber
Section titled “childNumber”number
Returns
Section titled “Returns”Promise<void>
cancelWorkflowRun()?
Section titled “cancelWorkflowRun()?”
optionalcancelWorkflowRun(runId):Promise<void>
Defined in: src/forge/types.ts:265
Cancel an in-progress workflow run by id (gh run cancel). Optional, same
GitHub-only gating as rerunWorkflowRun.
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”Promise<void>
canPush()?
Section titled “canPush()?”
optionalcanPush():Promise<boolean>
Defined in: src/forge/types.ts:287
Whether the operator has push access to the repo on this host. Gates the gitignore-adopt flow (no push → it can’t open the adopt PR; the caller shows an info toast rather than an error). Optional: hosts without an access API omit it and the adopter treats absence as “no push access”.
Returns
Section titled “Returns”Promise<boolean>
closeIssue()?
Section titled “closeIssue()?”
optionalcloseIssue(issueNumber):Promise<void>
Defined in: src/forge/types.ts:346
Close an issue by number (best-effort; used by the drain to retire a backlog issue once its auto PR merges). Optional: hosts without an issues-close API omit it.
Parameters
Section titled “Parameters”issueNumber
Section titled “issueNumber”number
Returns
Section titled “Returns”Promise<void>
comment()?
Section titled “comment()?”
optionalcomment(prNumber,body):Promise<void>
Defined in: src/forge/types.ts:316
Post a plain issue comment on a PR (gh pr comment). Optional: only hosts
with a comment API (GitHub) implement it; others omit it and the
dependabot-rebase endpoint 400s.
Parameters
Section titled “Parameters”prNumber
Section titled “prNumber”number
string
Returns
Section titled “Returns”Promise<void>
commentIssue()?
Section titled “commentIssue()?”
optionalcommentIssue(issueNumber,body):Promise<void>
Defined in: src/forge/types.ts:351
Post a plain comment on an issue (the issue-log’s workflow protocol: one note when the session’s PR enters the waiting-on-handoff state, one when it merges). Best-effort; optional (hosts without an issue-comment API omit it and the issue-log stays silent).
Parameters
Section titled “Parameters”issueNumber
Section titled “issueNumber”number
string
Returns
Section titled “Returns”Promise<void>
convertToDraft()?
Section titled “convertToDraft()?”
optionalconvertToDraft(prNumber):Promise<void>
Defined in: src/forge/types.ts:323
Convert an open ready PR back to draft (gh pr ready <n> --undo). Optional,
same host gating as markReady.
Parameters
Section titled “Parameters”prNumber
Section titled “prNumber”number
Returns
Section titled “Returns”Promise<void>
createIssue()?
Section titled “createIssue()?”
optionalcreateIssue(o):Promise<{number:number;url:string; }>
Defined in: src/forge/types.ts:376
Open a new issue (capture-extension delivery path). Returns the created issue’s number + URL. Optional: hosts without an issue-create API omit it and POST /api/issues 400s.
Parameters
Section titled “Parameters”string
string
Returns
Section titled “Returns”Promise<{ number: number; url: string; }>
currentUser()?
Section titled “currentUser()?”
optionalcurrentUser():Promise<string|null>
Defined in: src/forge/types.ts:277
The operator’s own login on this host (gh api user), cached. Drives the
“is the configured reviewer/merger someone other than me” decision. Null
when it can’t be resolved. Optional: hosts without an identity API omit it.
Returns
Section titled “Returns”Promise<string | null>
defaultBranch()
Section titled “defaultBranch()”defaultBranch():
Promise<string>
Defined in: src/forge/types.ts:297
The repo’s default branch name (the promote PR’s base).
Returns
Section titled “Returns”Promise<string>
ensureBranch()?
Section titled “ensureBranch()?”
optionalensureBranch(branch,fromRef):Promise<void>
Defined in: src/forge/types.ts:307
Ensure a branch exists on the host, creating it at fromRef’s tip when absent
(idempotent; a present branch is left untouched — its tip is NOT reset). Used to
cut an epic integration branch off the default branch. Optional: hosts without a
refs API omit it and the caller skips epic-branch orchestration.
Parameters
Section titled “Parameters”branch
Section titled “branch”string
fromRef
Section titled “fromRef”string
Returns
Section titled “Returns”Promise<void>
ensureIssueLink()?
Section titled “ensureIssueLink()?”
optionalensureIssueLink(prNumber,issueNumber):Promise<void>
Defined in: src/forge/types.ts:356
Ensure the PR body links the issue so the forge auto-closes it on merge.
Idempotent: appends a Closes #<issueNumber> line only when no closing
keyword for that issue is already present. Best-effort; optional (hosts
without a PR-body edit API omit it).
Parameters
Section titled “Parameters”prNumber
Section titled “prNumber”number
issueNumber
Section titled “issueNumber”number
Returns
Section titled “Returns”Promise<void>
getIssue()?
Section titled “getIssue()?”
optionalgetIssue(issueNumber):Promise<Issue|null>
Defined in: src/forge/types.ts:372
Fetch ONE issue fresh (UNCACHED) by number, for the drain’s pre-spawn claim
re-check. The cached listIssues view a candidate is selected from can be up to
issuesTtlMs stale, so a second instance may still see an issue another instance
stamped ACTIVE_LABEL on seconds ago. A fresh single-issue read closes that
stale-cache window: if it already carries the claim, the spawn is yielded. Returns
null when the issue is gone/unreadable. Best-effort and optional — hosts without it
(or a transient failure → null) fall back to the cached candidate set + local dedup.
Parameters
Section titled “Parameters”issueNumber
Section titled “issueNumber”number
Returns
Section titled “Returns”Promise<Issue | null>
issueId()?
Section titled “issueId()?”
optionalissueId(issueNumber):Promise<number|null>
Defined in: src/forge/types.ts:380
Parameters
Section titled “Parameters”issueNumber
Section titled “issueNumber”number
Returns
Section titled “Returns”Promise<number | null>
listBlockedBy()?
Section titled “listBlockedBy()?”
optionallistBlockedBy(issueNumber):Promise<number[]>
Defined in: src/forge/types.ts:379
Parameters
Section titled “Parameters”issueNumber
Section titled “issueNumber”number
Returns
Section titled “Returns”Promise<number[]>
listBranches()?
Section titled “listBranches()?”
optionallistBranches(prefix):Promise<string[]>
Defined in: src/forge/types.ts:302
Short-names of all host branches under prefix (e.g. "epic/"), refs/heads/
stripped. Used by epic-branch divergence detection (#645) to spot stray epic/*
branches that diverge from the pinned integration branch. Optional: only hosts with a
matching-refs API (GitHub) implement it; absent → divergence signal (c) degrades to off.
Parameters
Section titled “Parameters”prefix
Section titled “prefix”string
Returns
Section titled “Returns”Promise<string[]>
listCollaborators()?
Section titled “listCollaborators()?”
optionallistCollaborators():Promise<{logins:string[];unavailable:boolean; }>
Defined in: src/forge/types.ts:281
Logins with access to the repo, for the roles dialog’s people picker.
unavailable is true when the host refused the list (e.g. GitHub 403 with no
push access) so the dialog falls back to free-text. Optional.
Returns
Section titled “Returns”Promise<{ logins: string[]; unavailable: boolean; }>
listIssues()
Section titled “listIssues()”listIssues():
Promise<Issue[]>
Defined in: src/forge/types.ts:252
Returns
Section titled “Returns”Promise<Issue[]>
listPrComments()?
Section titled “listPrComments()?”
optionallistPrComments(prNumber):Promise<PrComment[]>
Defined in: src/forge/types.ts:331
Issue comments on a PR (oldest first), used to read back the author’s responses to earlier review rounds. Optional: only hosts with a comments API implement it (GitHub); others omit it and no author notes are surfaced.
Parameters
Section titled “Parameters”prNumber
Section titled “prNumber”number
Returns
Section titled “Returns”Promise<PrComment[]>
listPullRequests()
Section titled “listPullRequests()”listPullRequests():
Promise<PullRequest[]>
Defined in: src/forge/types.ts:254
Open PRs for the backlog PRs tab (newest first), capped server-side.
Returns
Section titled “Returns”Promise<PullRequest[]>
listRunJobs()?
Section titled “listRunJobs()?”
optionallistRunJobs(runId):Promise<WorkflowJob[]>
Defined in: src/forge/types.ts:272
Per-job breakdown for a single run, lazy-loaded when a history row expands. Optional, same GitHub-only gating as listWorkflowRunHistory.
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”Promise<WorkflowJob[]>
listSubIssues()?
Section titled “listSubIssues()?”
optionallistSubIssues(parentNumber):Promise<SubIssueRef[]>
Defined in: src/forge/types.ts:378
Parameters
Section titled “Parameters”parentNumber
Section titled “parentNumber”number
Returns
Section titled “Returns”Promise<SubIssueRef[]>
listSubIssueSummaries()?
Section titled “listSubIssueSummaries()?”
optionallistSubIssueSummaries():Promise<{subIssueNumbers:number[];summaries:Map<number, {completed:number;total:number; }>; }>
Defined in: src/forge/types.ts:387
Cheap per-parent native sub-issue counts for the backlog epic-badge discovery (GitHub only; absent → no native-epic discovery, markdown fallback only). Map keyed by parent issue number; only entries with total > 0 are included. Also returns the numbers of all open issues that are native sub-issues (i.e. have a non-null parent).
Returns
Section titled “Returns”Promise<{ subIssueNumbers: number[]; summaries: Map<number, { completed: number; total: number; }>; }>
listWorkflowRunHistory()?
Section titled “listWorkflowRunHistory()?”
optionallistWorkflowRunHistory(workflowId,o):Promise<WorkflowRun[]>
Defined in: src/forge/types.ts:269
Prior runs of one workflow on the default branch (summary rows; jobs
empty), newest-first, capped by limit. Optional, GitHub-only like
listWorkflowRuns; other forges omit it and the history UI degrades.
Parameters
Section titled “Parameters”workflowId
Section titled “workflowId”number
number
Returns
Section titled “Returns”Promise<WorkflowRun[]>
listWorkflowRuns()?
Section titled “listWorkflowRuns()?”
optionallistWorkflowRuns():Promise<WorkflowRun[]>
Defined in: src/forge/types.ts:258
Latest run per workflow on the default branch, with per-job breakdown, for the backlog Actions tab. Optional: only hosts with an Actions API implement it (GitHub); others omit it and the tab shows a “GitHub only” state.
Returns
Section titled “Returns”Promise<WorkflowRun[]>
markReady()?
Section titled “markReady()?”
optionalmarkReady(prNumber):Promise<void>
Defined in: src/forge/types.ts:320
Flip an open draft PR to ready-for-review (gh pr ready <n>). Optional: only
hosts with a draft API implement it; the draft-reconcile service treats absence
as “cannot promote on this host”.
Parameters
Section titled “Parameters”prNumber
Section titled “prNumber”number
Returns
Section titled “Returns”Promise<void>
merge()
Section titled “merge()”merge(
prNumber,o):Promise<void>
Defined in: src/forge/types.ts:312
Parameters
Section titled “Parameters”prNumber
Section titled “prNumber”number
Returns
Section titled “Returns”Promise<void>
openPr()
Section titled “openPr()”openPr(
o):Promise<PrStatus>
Defined in: src/forge/types.ts:282
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<PrStatus>
postReview()
Section titled “postReview()”postReview(
prNumber,o):Promise<{url?:string; }>
Defined in: src/forge/types.ts:327
Post a critic review (request-changes / comment) on a PR. Returns the review’s URL when the host provides one.
Parameters
Section titled “Parameters”prNumber
Section titled “prNumber”number
Returns
Section titled “Returns”Promise<{ url?: string; }>
prChangedPaths()?
Section titled “prChangedPaths()?”
optionalprChangedPaths(prNumber):Promise<string[]>
Defined in: src/forge/types.ts:337
The changed file paths of a PR (gh pr view <n> --json files). Used by the epic-landing
migration-awareness check (#645) to detect migration files carried by the landing PR.
Optional: only hosts with a PR-files API (GitHub) implement it; others omit it and the
migration check degrades to off (no chip). Best-effort; the caller wraps the call so a
failure never breaks the landing.
Parameters
Section titled “Parameters”prNumber
Section titled “prNumber”number
Returns
Section titled “Returns”Promise<string[]>
prReviewMeta()?
Section titled “prReviewMeta()?”
optionalprReviewMeta(prNumber):Promise<PrReviewMeta|null>
Defined in: src/forge/types.ts:343
Number-keyed PR metadata for the standalone critic: body + base branch + fork flag +
live state, via gh pr view <number>. Number-keyed so a recurring/fork head branch
name can’t resolve a different PR (unlike branch-keyed prStatus). Optional: only hosts
with a PR-view API (GitHub) implement it; others omit it and the standalone critic skips
that PR. Returns null when the PR is gone/unreadable.
Parameters
Section titled “Parameters”prNumber
Section titled “prNumber”number
Returns
Section titled “Returns”Promise<PrReviewMeta | null>
prStatus()
Section titled “prStatus()”prStatus(
headBranch):Promise<PrStatus>
Defined in: src/forge/types.ts:273
Parameters
Section titled “Parameters”headBranch
Section titled “headBranch”string
Returns
Section titled “Returns”Promise<PrStatus>
redeploy()
Section titled “redeploy()”redeploy(
o):Promise<void>
Defined in: src/forge/types.ts:324
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<void>
removeIssueLabel()?
Section titled “removeIssueLabel()?”
optionalremoveIssueLabel(issueNumber,label):Promise<void>
Defined in: src/forge/types.ts:364
Remove a label from an issue (best-effort; releases the drain’s claim when an auto session is abandoned, returning the issue to the pool). Optional.
Parameters
Section titled “Parameters”issueNumber
Section titled “issueNumber”number
string
Returns
Section titled “Returns”Promise<void>
renameBranch()?
Section titled “renameBranch()?”
optionalrenameBranch(oldBranch,newBranch):Promise<void>
Defined in: src/forge/types.ts:311
Rename a branch on the host, retargeting any open PR to the new name. Optional: hosts that can’t do this safely (Gitea) omit it, and the caller falls back to a display-only rename so an open PR is never orphaned.
Parameters
Section titled “Parameters”oldBranch
Section titled “oldBranch”string
newBranch
Section titled “newBranch”string
Returns
Section titled “Returns”Promise<void>
rerunWorkflowRun()?
Section titled “rerunWorkflowRun()?”
optionalrerunWorkflowRun(runId,o):Promise<void>
Defined in: src/forge/types.ts:262
Re-run a workflow run by id. failedOnly re-runs just the failed jobs
(gh run rerun --failed); otherwise the whole run. Optional: only Actions
hosts (GitHub) implement it; others omit it and the tab hides the button.
Parameters
Section titled “Parameters”number
failedOnly
Section titled “failedOnly”boolean
Returns
Section titled “Returns”Promise<void>
syncFork()?
Section titled “syncFork()?”
optionalsyncFork():Promise<void>
Defined in: src/forge/types.ts:295
Sync the fork’s default branch from the upstream on the host (gh repo sync),
keeping the fork current so fresh PR branches cut off it aren’t already behind.
Only meaningful in fork mode (isFork); throws on a non-fork forge and
propagates the host error (auth / a diverged fork default) for the caller to
classify. The local clone is fast-forwarded separately by the caller. Optional:
only hosts with a fork-sync API (GitHub) implement it; others omit it and the
sync-fork endpoint 400s.
Returns
Section titled “Returns”Promise<void>