GithubForge
Defined in: src/forge/github.ts:160
GitHub forge driven through the gh CLI (operator’s existing auth).
Implements
Section titled “Implements”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new GithubForge(
slug,cfg,run?,forkSlug?):GithubForge
Defined in: src/forge/github.ts:168
Parameters
Section titled “Parameters”string
GhRunner = defaultRunner
forkSlug?
Section titled “forkSlug?”string
Fork (origin) slug when the repo is a fork (slug = upstream). Drives the
fork-aware PR head qualifier and the canPush probe target.
Returns
Section titled “Returns”GithubForge
Properties
Section titled “Properties”deployWorkflow
Section titled “deployWorkflow”
readonlydeployWorkflow:string|null
Defined in: src/forge/github.ts:163
Configured deploy workflow filename, or null if redeploy is unavailable.
Implementation of
Section titled “Implementation of”
readonlykind:"github"
Defined in: src/forge/github.ts:161
Implementation of
Section titled “Implementation of”mergeMethod
Section titled “mergeMethod”
readonlymergeMethod:MergeMethod
Defined in: src/forge/github.ts:162
Default merge method for this host (from config; “squash” if unset).
Implementation of
Section titled “Implementation of”
readonlyslug:string
Defined in: src/forge/github.ts:169
Implementation of
Section titled “Implementation of”Accessors
Section titled “Accessors”isFork
Section titled “isFork”Get Signature
Section titled “Get Signature”get isFork():
boolean
Defined in: src/forge/github.ts:186
Fork mode = a fork slug was supplied (slug is the upstream it forked from).
Returns
Section titled “Returns”boolean
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.
Implementation of
Section titled “Implementation of”webUrl
Section titled “webUrl”Get Signature
Section titled “Get Signature”get webUrl():
string
Defined in: src/forge/github.ts:181
Repo’s web home page (e.g. https://github.com/owner/repo); null when unbuildable; absent → null.
Returns
Section titled “Returns”string
Repo’s web home page (e.g. https://github.com/owner/repo); null when unbuildable; absent → null.
Implementation of
Section titled “Implementation of”Methods
Section titled “Methods”addBlockedBy()
Section titled “addBlockedBy()”addBlockedBy(
issueNumber,blockerNumber):Promise<void>
Defined in: src/forge/github.ts:1006
Parameters
Section titled “Parameters”issueNumber
Section titled “issueNumber”number
blockerNumber
Section titled “blockerNumber”number
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”addIssueLabel()
Section titled “addIssueLabel()”addIssueLabel(
issueNumber,label):Promise<void>
Defined in: src/forge/github.ts:755
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>
Implementation of
Section titled “Implementation of”addSubIssue()
Section titled “addSubIssue()”addSubIssue(
parentNumber,childNumber):Promise<void>
Defined in: src/forge/github.ts:992
Parameters
Section titled “Parameters”parentNumber
Section titled “parentNumber”number
childNumber
Section titled “childNumber”number
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”cancelWorkflowRun()
Section titled “cancelWorkflowRun()”cancelWorkflowRun(
runId):Promise<void>
Defined in: src/forge/github.ts:467
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>
Implementation of
Section titled “Implementation of”canPush()
Section titled “canPush()”canPush():
Promise<boolean>
Defined in: src/forge/github.ts:588
Whether the authenticated user can push. Returns a DEFINITIVE boolean only; THROWS on a probe failure (network/auth/unrecognised output) so the caller can treat that as retryable rather than silently as “no access”.
Returns
Section titled “Returns”Promise<boolean>
Implementation of
Section titled “Implementation of”closeIssue()
Section titled “closeIssue()”closeIssue(
issueNumber):Promise<void>
Defined in: src/forge/github.ts:720
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>
Implementation of
Section titled “Implementation of”comment()
Section titled “comment()”comment(
prNumber,body):Promise<void>
Defined in: src/forge/github.ts:728
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>
Implementation of
Section titled “Implementation of”commentIssue()
Section titled “commentIssue()”commentIssue(
issueNumber,body):Promise<void>
Defined in: src/forge/github.ts:724
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>
Implementation of
Section titled “Implementation of”convertToDraft()
Section titled “convertToDraft()”convertToDraft(
prNumber):Promise<void>
Defined in: src/forge/github.ts:685
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>
Implementation of
Section titled “Implementation of”createIssue()
Section titled “createIssue()”createIssue(
o):Promise<{number:number;url:string; }>
Defined in: src/forge/github.ts:689
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; }>
Implementation of
Section titled “Implementation of”currentUser()
Section titled “currentUser()”currentUser():
Promise<string|null>
Defined in: src/forge/github.ts:575
The authenticated gh login (gh api user), cached for the forge’s lifetime —
it never changes mid-session, so one call serves every handoff computation.
Returns
Section titled “Returns”Promise<string | null>
Implementation of
Section titled “Implementation of”defaultBranch()
Section titled “defaultBranch()”defaultBranch():
Promise<string>
Defined in: src/forge/github.ts:530
The repo’s default branch (gh repo view ... defaultBranchRef), cached for
the forge’s lifetime — it never changes mid-session. Cached ONLY on success:
a transient failure rethrows so the next call retries rather than sticking.
Returns
Section titled “Returns”Promise<string>
Implementation of
Section titled “Implementation of”ensureBranch()
Section titled “ensureBranch()”ensureBranch(
branch,fromRef):Promise<void>
Defined in: src/forge/github.ts:540
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>
Implementation of
Section titled “Implementation of”ensureIssueLink()
Section titled “ensureIssueLink()”ensureIssueLink(
prNumber,issueNumber):Promise<void>
Defined in: src/forge/github.ts:732
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>
Implementation of
Section titled “Implementation of”getIssue()
Section titled “getIssue()”getIssue(
issueNumber):Promise<Issue|null>
Defined in: src/forge/github.ts:229
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>
Implementation of
Section titled “Implementation of”issueId()
Section titled “issueId()”issueId(
issueNumber):Promise<number|null>
Defined in: src/forge/github.ts:977
Parameters
Section titled “Parameters”issueNumber
Section titled “issueNumber”number
Returns
Section titled “Returns”Promise<number | null>
Implementation of
Section titled “Implementation of”listBlockedBy()
Section titled “listBlockedBy()”listBlockedBy(
issueNumber):Promise<number[]>
Defined in: src/forge/github.ts:963
Parameters
Section titled “Parameters”issueNumber
Section titled “issueNumber”number
Returns
Section titled “Returns”Promise<number[]>
Implementation of
Section titled “Implementation of”listBranches()
Section titled “listBranches()”listBranches(
prefix):Promise<string[]>
Defined in: src/forge/github.ts:563
Short-names of all branches matching prefix via the matching-refs API. Strips the
leading refs/heads/. Returns [] when none match (the endpoint 200s with an empty list).
Parameters
Section titled “Parameters”prefix
Section titled “prefix”string
Returns
Section titled “Returns”Promise<string[]>
Implementation of
Section titled “Implementation of”listCollaborators()
Section titled “listCollaborators()”listCollaborators():
Promise<{logins:string[];unavailable:boolean; }>
Defined in: src/forge/github.ts:625
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; }>
Implementation of
Section titled “Implementation of”listIssues()
Section titled “listIssues()”listIssues():
Promise<Issue[]>
Defined in: src/forge/github.ts:190
Returns
Section titled “Returns”Promise<Issue[]>
Implementation of
Section titled “Implementation of”listPrComments()
Section titled “listPrComments()”listPrComments(
prNumber):Promise<PrComment[]>
Defined in: src/forge/github.ts:846
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[]>
Implementation of
Section titled “Implementation of”listPullRequests()
Section titled “listPullRequests()”listPullRequests():
Promise<PullRequest[]>
Defined in: src/forge/github.ts:271
Open PRs for the backlog PRs tab (newest first), capped server-side.
Returns
Section titled “Returns”Promise<PullRequest[]>
Implementation of
Section titled “Implementation of”listRunJobs()
Section titled “listRunJobs()”listRunJobs(
runId):Promise<WorkflowJob[]>
Defined in: src/forge/github.ts:387
Per-job breakdown for a single run (gh run view --json jobs), mapped to
the four-light CI vocab. Shared by the latest-run listing and history-row
expansion.
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”Promise<WorkflowJob[]>
Implementation of
Section titled “Implementation of”listSubIssues()
Section titled “listSubIssues()”listSubIssues(
parentNumber):Promise<SubIssueRef[]>
Defined in: src/forge/github.ts:933
Parameters
Section titled “Parameters”parentNumber
Section titled “parentNumber”number
Returns
Section titled “Returns”Promise<SubIssueRef[]>
Implementation of
Section titled “Implementation of”listSubIssueSummaries()
Section titled “listSubIssueSummaries()”listSubIssueSummaries():
Promise<{subIssueNumbers:number[];summaries:Map<number, {completed:number;total:number; }>; }>
Defined in: src/forge/github.ts:1020
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; }>; }>
Implementation of
Section titled “Implementation of”GitForge.listSubIssueSummaries
listWorkflowRunHistory()
Section titled “listWorkflowRunHistory()”listWorkflowRunHistory(
workflowId,o):Promise<WorkflowRun[]>
Defined in: src/forge/github.ts:415
Prior runs of one workflow on the default branch, newest-first, capped by
limit. Summary rows only — jobs is empty; callers lazy-load per-run
jobs via listRunJobs.
Parameters
Section titled “Parameters”workflowId
Section titled “workflowId”number
number
Returns
Section titled “Returns”Promise<WorkflowRun[]>
Implementation of
Section titled “Implementation of”GitForge.listWorkflowRunHistory
listWorkflowRuns()
Section titled “listWorkflowRuns()”listWorkflowRuns():
Promise<WorkflowRun[]>
Defined in: src/forge/github.ts:322
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[]>
Implementation of
Section titled “Implementation of”markReady()
Section titled “markReady()”markReady(
prNumber):Promise<void>
Defined in: src/forge/github.ts:681
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>
Implementation of
Section titled “Implementation of”merge()
Section titled “merge()”merge(
prNumber,o):Promise<void>
Defined in: src/forge/github.ts:712
Parameters
Section titled “Parameters”prNumber
Section titled “prNumber”number
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”openPr()
Section titled “openPr()”openPr(
o):Promise<PrStatus>
Defined in: src/forge/github.ts:647
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<PrStatus>
Implementation of
Section titled “Implementation of”postReview()
Section titled “postReview()”postReview(
prNumber,o):Promise<{url?:string; }>
Defined in: src/forge/github.ts:808
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; }>
Implementation of
Section titled “Implementation of”prChangedPaths()
Section titled “prChangedPaths()”prChangedPaths(
prNumber):Promise<string[]>
Defined in: src/forge/github.ts:875
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[]>
Implementation of
Section titled “Implementation of”prReviewMeta()
Section titled “prReviewMeta()”prReviewMeta(
prNumber):Promise<PrReviewMeta|null>
Defined in: src/forge/github.ts:893
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>
Implementation of
Section titled “Implementation of”prStatus()
Section titled “prStatus()”prStatus(
headBranch):Promise<PrStatus>
Defined in: src/forge/github.ts:471
Parameters
Section titled “Parameters”headBranch
Section titled “headBranch”string
Returns
Section titled “Returns”Promise<PrStatus>
Implementation of
Section titled “Implementation of”redeploy()
Section titled “redeploy()”redeploy(
o):Promise<void>
Defined in: src/forge/github.ts:804
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”removeIssueLabel()
Section titled “removeIssueLabel()”removeIssueLabel(
issueNumber,label):Promise<void>
Defined in: src/forge/github.ts:771
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>
Implementation of
Section titled “Implementation of”renameBranch()
Section titled “renameBranch()”renameBranch(
oldBranch,newBranch):Promise<void>
Defined in: src/forge/github.ts:699
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>
Implementation of
Section titled “Implementation of”rerunWorkflowRun()
Section titled “rerunWorkflowRun()”rerunWorkflowRun(
runId,o):Promise<void>
Defined in: src/forge/github.ts:459
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>
Implementation of
Section titled “Implementation of”syncFork()
Section titled “syncFork()”syncFork():
Promise<void>
Defined in: src/forge/github.ts:619
Sync the fork’s default branch from upstream on GitHub
(gh repo sync <fork> --source <upstream>). Idempotent — a fork already level
with upstream is a no-op. THROWS (with gh’s stderr) when called on a non-fork,
on an auth failure, or when the fork’s default branch has diverged from upstream
(gh refuses a non-fast-forward rather than discarding the fork’s commits); the
caller classifies the stderr into a syncfork_failed_* code.
Returns
Section titled “Returns”Promise<void>