The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
/**
* The Harness GitHub App (docs/swarm-github-app.md): how the backend proves it is the app, finds the app's installation
* on a repository and creates installation access tokens for that one repository.
*
* A token comes from an installation, never from a person: GitHub user tokens cannot be narrowed to one repository, an
* installation token can, and it lasts an hour (docs/plans/2026-10-24-swarm-team-account.md, Findings). Only node's
* crypto signs the app's JWT. Nothing here logs a token or the private key.
*/
import { createPrivateKey, hkdfSync, sign, type KeyObject } from 'node:crypto'
import { readPushOrigin, type GitHubRead, type PushOrigin } from './pushOrigin.js'
import { githubRepository, type GitHubRepository } from './repository.js'
import type { PullRequestWatch } from '../superTabs/pullRequestEvents.js'
import type { PullRequestFile } from '../superTabs/pullRequestPatch.js'
import type { MergeSides } from '../superTabs/mergeCarry.js'
/** What a Swarm agent's token may do, and nothing more: push to and read the repository, open and update pull requests,
* and read checks and workflow runs to see whether its pull request passes. */
export const TOKEN_PERMISSIONS = { contents: 'write', pull_requests: 'write', checks: 'read', actions: 'read', metadata: 'read' } as const
/**
* What an agent's token also asks for where the repository's installation has granted it, at no more than the granted level
* (Scholes, task #2755, Ken approved): push changes to `.github/workflows`, which GitHub refuses without `workflows`, and
* read and write issues. Never asked for where not granted: GitHub refuses a token that asks for a permission its
* installation has not accepted, and every agent on it would lose its token. Ken accepted the risk: a workflow change runs
* in CI with the repository's secrets, and Team-written branches are among the pushers.
*/
export const GRANTED_TOKEN_PERMISSIONS = { workflows: 'write', issues: 'write' } as const
/** What no installation token may ever ask for (task #1788): a new repository is created with the person's own sign-in
* token only (github/repositoryCreate.ts), so a token minted from the app's key can never create, delete or transfer a
* repository, nor widen which repositories the installation covers. */
export const NEVER_ON_INSTALLATION_TOKENS = ['administration', 'repository_creation', 'installation_repositories'] as const
/** What preparing an agent's folder may do before the agent has a task: clone and fetch the repository, nothing more. */
export const PREPARE_PERMISSIONS = { contents: 'read', metadata: 'read' } as const
/** What the Swarm's tidying reads before it archives a finished group: whether its pull requests are merged or closed. */
export const PULL_READ_PERMISSIONS = { pull_requests: 'read', metadata: 'read' } as const
/** What the route's read of running CI jobs may do: read workflow runs and their jobs, nothing more. */
export const ACTIONS_READ_PERMISSIONS = { actions: 'read', metadata: 'read' } as const
/** What reading who pushed a pull request's commits may do (pushOrigin.ts): read the pull request and the repository's activity log. */
export const PUSH_ORIGIN_PERMISSIONS = { contents: 'read', pull_requests: 'read', metadata: 'read' } as const
/** What watching a task's pull request for its Engineer reads (superTabs/pullRequestEvents.ts): the pull request, its reviews
* and comments, and its head's checks. All already among the app's permissions ([TOKEN_PERMISSIONS]). */
/** The release watch (superTabs/releaseWatch.ts): release workflow runs, where their tags sit on the default branch, and a
* pull request's files. */
export const RELEASE_READ_PERMISSIONS = { contents: 'read', pull_requests: 'read', actions: 'read', metadata: 'read' } as const
export const PULL_WATCH_PERMISSIONS = { pull_requests: 'read', checks: 'read', metadata: 'read' } as const
/** What reading a pull request head's patch may do (superTabs/pullRequestPatch.ts, #3394): read the pull request, and the
* comparison of its base and head commits, which is repository contents. Read only, revoked when the watch's pass ends. */
export const PULL_PATCH_PERMISSIONS = { contents: 'read', pull_requests: 'read', metadata: 'read' } as const
/** The watch's answers kept for conditional reads: an unchanged one comes back 304, which GitHub's rate limit does not count. */
const WATCH_KEPT = 2000
/** The most files GitHub gives for a comparison of two commits (GET /compare/{base}...{head}). */
export const COMPARE_FILES_MAX = 300
/** Pages of 100 a pull request's file list reads: GitHub lists at most 3,000 files. */
const PULL_FILES_PAGES = 30
const PUSH_ORIGINS_KEPT = 1000
/** GitHub's files of a comparison as [PullRequestFile]s, or null when one lacks its name, status or blob. */
function filesOf(body: unknown[]): PullRequestFile[] | null {
const text = (value: unknown) => typeof value === 'string' ? value : undefined
const files: PullRequestFile[] = []
for (const file of body as Array<Record<string, unknown>>) {
const filename = text(file?.filename), status = text(file?.status), sha = text(file?.sha), patch = text(file?.patch), previousFilename = text(file?.previous_filename)
if (!filename || !status || sha === undefined) return null
files.push({ filename, status, sha, ...patch === undefined ? {} : { patch }, ...previousFilename === undefined ? {} : { previousFilename } })
}
return files
}
const PUSH_UNKNOWN_MS = 60_000
export type TokenPermissions = Readonly<Record<string, 'read' | 'write'>>
/** Jobs running and waiting on a repository's GitHub Actions, in all and on macOS runners: counts only. */
export interface CiLoad { running: number; queued: number; macosRunning: number; macosQueued: number }
/** A refusal with the code clients act on; `details` adds fields beside it, such as the install link. */
export class GitHubAppError extends Error {
constructor(readonly code: string, message: string, readonly status: number, readonly details?: Record<string, unknown>) {
super(message)
this.name = 'GitHubAppError'
}
}
/** Whether an organization lets Harness create a repository there (task #1788): the app is installed on it and its owner
* accepted Repository creation; [canAdd] when it also accepted installation repository access, so a new repository the
* installation does not cover yet can be added to it. */
export type OwnerReadiness = { state: 'ready'; installation: number; canAdd: boolean } | { state: 'not-installed'; installUrl: string | null } | { state: 'not-accepted' }
export interface GitHubAppConfig { appId: string; privateKey: KeyObject; slug: string | null }
/** The app's private key as GitHub hands it out (a PEM file), with its line breaks written as `\n`, or base64 of it. The
* error never repeats the value. */
export function readPrivateKey(value: string): KeyObject {
let pem = value.trim().replace(/\\n/g, '\n')
if (!pem.includes('-----BEGIN')) {
const decoded = /^[A-Za-z0-9+/=\s]+$/.test(pem) ? Buffer.from(pem, 'base64').toString('utf8') : ''
if (!decoded.includes('-----BEGIN')) throw new Error('GITHUB_APP_PRIVATE_KEY is not a PEM private key or base64 of one.')
pem = decoded.trim()
}
let key: KeyObject
try { key = createPrivateKey(pem) } catch { throw new Error('GITHUB_APP_PRIVATE_KEY could not be read as a private key.') }
if (key.asymmetricKeyType !== 'rsa') throw new Error('GITHUB_APP_PRIVATE_KEY must be the RSA key GitHub generated for the app.')
return key
}
/** Both empty: the feature is off. One without the other, or a value that cannot be right, stops the backend at startup
* rather than failing the first agent that asks. */
/** The name a Harness GitHub App's commits carry, whatever the app is called on GitHub (cli/src/lib/swarmGitHub.ts accepts it). */
export const COMMIT_IDENTITY: CommitIdentity = { name: 'Harness by Autonomous', email: '[email protected]' }
/** The line a commit, or the merge helper's squash message, names Harness by (attribution.ts; scripts/merge-validated-pr.py). */
export const HARNESS_CO_AUTHOR = `Co-authored-by: ${COMMIT_IDENTITY.name} <${COMMIT_IDENTITY.email}>`
export function githubAppConfig(env: { GITHUB_APP_ID: string; GITHUB_APP_PRIVATE_KEY: string; GITHUB_APP_SLUG: string }): GitHubAppConfig | null {
const appId = env.GITHUB_APP_ID.trim(), key = env.GITHUB_APP_PRIVATE_KEY.trim(), slug = env.GITHUB_APP_SLUG.trim()
if (!appId && !key) return null
if (!appId || !key) throw new Error('Set both GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY for the Harness GitHub App, or neither.')
// The numeric App ID, or the app's Client ID, which GitHub also takes as the JWT issuer.
if (!/^(?:[0-9]{1,12}|Iv[0-9A-Za-z.]{4,40})$/.test(appId)) throw new Error('GITHUB_APP_ID must be the app\'s numeric App ID or its Client ID.')
if (slug && !/^[a-z0-9](?:[a-z0-9-]{0,98}[a-z0-9])?$/.test(slug)) throw new Error('GITHUB_APP_SLUG must be the app\'s name as in github.com/apps/NAME.')
return { appId, privateKey: readPrivateKey(key), slug: slug || null }
}
/** The key that seals cached tokens (github/tokens.ts), derived from the app's own private key: whoever can read the cache
* without it learns nothing, and no further secret has to be configured. */
export function cacheSecret(config: GitHubAppConfig): Buffer {
const der = config.privateKey.export({ type: 'pkcs8', format: 'der' })
return Buffer.from(hkdfSync('sha256', der, 'harness-github-token-cache', config.appId, 32))
}
/** Where the default branch stands: a ruleset requires a pull request; classic branch protection is on, which an app
* without administration access cannot read further; nothing protects it; or it could not be read. */
export type BranchProtection = 'pull_request' | 'classic' | 'none' | 'unknown'
export interface DefaultBranch { branch: string | null; protection: BranchProtection }
const base64url = (value: string | Buffer) => Buffer.from(value).toString('base64url')
const samePermissions = (a: TokenPermissions, b: TokenPermissions) =>
Object.keys(a).length === Object.keys(b).length && Object.entries(a).every(([name, level]) => b[name] === level)
const INSTALLATION_TTL_MS = 10 * 60_000
const NOT_INSTALLED_TTL_MS = 60_000
/** How often a person's "check again" may make the server ask GitHub again about one repository. */
const REFRESH_MS = 15_000
const BRANCH_TTL_MS = 10 * 60_000
const REQUEST_TIMEOUT_MS = 10_000
/** How long a CI load is kept: routes come minutes apart, and a job takes minutes. */
export const CI_LOAD_TTL_MS = 30_000
/** The most GitHub calls one CI load makes: the token, the two run lists, the jobs of at most [CI_MAX_RUNS] runs, and the
* revoke (Lead, 10-31: a read's calls are counted and capped). The installation lookup is kept ten minutes apart. */
export const CI_MAX_CALLS = 10
/** The most runs whose jobs are read in one CI load; a run beyond it counts as one waiting job, on no particular runner. */
export const CI_MAX_RUNS = CI_MAX_CALLS - 4
/** The most CI loads one server process reads for one repository in an hour: past it, the last load is answered while it is
* at most [CI_STALE_MS] old, and after that none, which the route says as "not checked". The count, like the 30 s cache, is
* per server process, and production runs 2 to 8 pods (security review 2 of #2428): the worst case is 8 × 3 = 24 reads and,
* with [CI_MAX_CALLS], 240 calls an hour per repository, about 5% of an installation's 5,000. */
export const CI_READS_PER_HOUR = 3
/** The most server processes production runs (its autoscaler's maximum), for the worst case above. */
export const SERVER_PROCESSES_MAX = 8
export const CI_STALE_MS = 5 * 60_000
const CI_WAITING = new Set(['queued', 'waiting', 'requested', 'pending'])
/** A git author and committer. */
export interface CommitIdentity { name: string; email: string }
export interface GitHubAppOptions {
fetch?: typeof fetch
now?: () => number
/** api.github.com unless a test serves a fake. */
apiUrl?: string
}
export class GitHubApp {
private readonly fetch: typeof fetch
private readonly now: () => number
private readonly apiUrl: string
private signed: { jwt: string; until: number } | null = null
/** The app's name, as GitHub answers it (botLogin). */
private slug: string | null = null
private readonly installations = new Map<string, { id: number | null; until: number }>()
/** What each installation has granted, by its id, for [GRANTED_TOKEN_PERMISSIONS]: null when GitHub did not say. */
private readonly grants = new Map<number, { permissions: TokenPermissions | null; until: number }>()
private readonly branches = new Map<string, { value: DefaultBranch; until: number }>()
/** A repository's name now, by the name asked for (lower case): null when it was not renamed. */
private readonly renames = new Map<string, { repository: GitHubRepository | null; until: number }>()
private readonly shownNames = new Map<string, { name: string; until: number }>()
/** Each repository's CI load while fresh, or being read ([ciLoad]), by its name in lower case; per server process. */
private readonly ciLoads = new Map<string, { value: Promise<CiLoad | null>; until: number }>()
private readonly pushOrigins = new Map<string, { origin: PushOrigin; until: number }>()
/** Each repository's CI reads in the last hour, and its last load read, for [CI_READS_PER_HOUR]. */
private readonly ciReads = new Map<string, { at: number[]; last: { load: CiLoad | null; at: number } | null }>()
/** The app's installation on each organization, by its login in lower case, for [ownerReadiness]; null when not installed. */
private readonly orgInstallations = new Map<string, { id: number | null; until: number }>()
/** When each repository's "not installed" was last forgotten on request ([forget]). */
private readonly forgotten = new Map<string, number>()
/** The watch's last answer and its ETag, by path ([watchPullRequest]). */
private readonly watched = new Map<string, { etag: string; body: Record<string, unknown> | unknown[]; link: string | null }>()
constructor(readonly config: GitHubAppConfig, options: GitHubAppOptions = {}) {
this.fetch = options.fetch ?? fetch
this.now = options.now ?? Date.now
this.apiUrl = (options.apiUrl ?? 'https://api.github.com').replace(/\/$/, '')
}
/** Where an owner installs the app, when its URL name is configured. */
installUrl(): string | null {
return this.config.slug ? `https://github.com/apps/${this.config.slug}/installations/new` : null
}
/**
* Who the app's commits are by, as Claude's are by its own line (Dee, task #2136). A Harness Team account has no git identity
* of its own, so its commits would read "Harness Team <harnessteam@<host>.local>" (PR #1934). No GitHub account owns this
* address, so GitHub links these commits to nobody: telling a Team agent's commits apart rests on who pushed (pushOrigin.ts).
*/
commitIdentity(): CommitIdentity { return COMMIT_IDENTITY }
/** The app's bot account's login, which GitHub's activity log names as the actor of every push with the app's token: GitHub's
* own answer, remembered. Never a configured name, as a wrong one asks the log for a bot that never pushed, and its empty
* answer reads as clean. Null while GitHub cannot say, which reads as unknown. Never read from a commit. */
async botLogin(): Promise<string | null> {
if (this.slug) return `${this.slug}[bot]`
try {
const app = await this.call('GET', '/app', `Bearer ${this.jwt()}`)
const named = (app.body as { slug?: unknown }).slug
if (app.status === 200 && typeof named === 'string' && /^[a-z0-9-]{1,100}$/.test(named)) this.slug = named
} catch (error) {
if (!(error instanceof GitHubAppError)) throw error
}
return this.slug ? `${this.slug}[bot]` : null
}
/** The app's own JWT (RS256, ten minutes at most): issued a minute back against clock drift, valid nine minutes, and
* reused until a minute before it ends. */
jwt(): string {
const now = this.now()
if (this.signed && this.signed.until > now) return this.signed.jwt
const iat = Math.floor(now / 1000) - 60
const exp = iat + 60 + 9 * 60
const input = `${base64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }))}.${base64url(JSON.stringify({ iat, exp, iss: this.config.appId }))}`
const jwt = `${input}.${base64url(sign('sha256', Buffer.from(input), this.config.privateKey))}`
this.signed = { jwt, until: (exp - 60) * 1000 }
return jwt
}
private async call(method: string, path: string, auth: string | null, body?: unknown, headers: Record<string, string> = {}):
Promise<{ link?: string | null; etag?: string | null; status: number; body: Record<string, unknown> | unknown[] }> {
let response: Response
try {
response = await this.fetch(`${this.apiUrl}${path}`, {
method, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
headers: { Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', 'User-Agent': 'harness-backend',
...(auth ? { Authorization: auth } : {}), ...(body ? { 'Content-Type': 'application/json' } : {}), ...headers },
...(body ? { body: JSON.stringify(body) } : {}),
})
} catch {
throw new GitHubAppError('GITHUB_UNAVAILABLE', 'GitHub did not answer. Try again in a minute.', 503)
}
const text = await response.text().catch(() => '')
let parsed: unknown = {}
try { parsed = text ? JSON.parse(text) : {} } catch { parsed = {} }
return { status: response.status, body: parsed && typeof parsed === 'object' ? parsed as Record<string, unknown> : {},
link: response.headers.get('link'), etag: response.headers.get('etag') }
}
private misconfigured(): GitHubAppError {
return new GitHubAppError('GITHUB_APP_MISCONFIGURED', 'GitHub refused the Harness GitHub App\'s credentials. Check GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY on the server.', 503)
}
notInstalled(repository: GitHubRepository): GitHubAppError {
const installUrl = this.installUrl()
return new GitHubAppError('GITHUB_APP_NOT_INSTALLED',
`The Harness GitHub App is not installed on ${repository.fullName}. Ask an owner of ${repository.owner} to install it${installUrl ? `: ${installUrl}` : ''}.`,
409, installUrl ? { installUrl } : undefined)
}
/** The installation that covers [repository], or null when the app is not installed there. Remembered ten minutes,
* and a missing installation one minute, so a busy Swarm does not ask GitHub for every token. */
async installation(repository: GitHubRepository): Promise<number | null> {
const key = repository.fullName.toLowerCase()
const known = this.installations.get(key)
if (known && known.until > this.now()) return known.id
const answer = await this.call('GET', `/repos/${repository.owner}/${repository.name}/installation`, `Bearer ${this.jwt()}`)
if (answer.status === 401) throw this.misconfigured()
if (answer.status === 404) {
this.installations.set(key, { id: null, until: this.now() + NOT_INSTALLED_TTL_MS })
return null
}
const id = (answer.body as Record<string, unknown>).id
if (answer.status !== 200 || typeof id !== 'number') throw new GitHubAppError('GITHUB_UNAVAILABLE', `GitHub could not look up the app on ${repository.fullName}.`, 502)
this.installations.set(key, { id, until: this.now() + INSTALLATION_TTL_MS })
return id
}
/**
* The installation that covers [repository], with the repository under the name GitHub knows it by now; null when the
* app is not installed there. A repository renamed on GitHub still answers to its old name for git, but not for the
* app's installation lookup, and a Swarm project's repository address is set once: a project made from a checkout
* whose remote still had the old name could never get a token (2026-10-27, autonomous-harness renamed openharness).
*/
async resolve(repository: GitHubRepository): Promise<{ installation: number; repository: GitHubRepository } | null> {
const direct = await this.installation(repository)
if (direct !== null) return { installation: direct, repository }
const current = await this.currentName(repository)
if (!current) return null
const renamed = await this.installation(current)
return renamed === null ? null : { installation: renamed, repository: current }
}
/**
* [repository]'s name as GitHub shows it now, for people to read: a project keeps the address it was given, and GitHub
* answers an old name by redirect, so a renamed repository was shown by the name it no longer has (autonomous-harness
* for autonomous-ai/openharness, 2026-10-28). Its own name when GitHub cannot say. Kept ten minutes either way, so a
* status read costs at most one lookup per repository in that time.
*/
async currentFullName(repository: GitHubRepository): Promise<string> {
const key = repository.fullName.toLowerCase()
const known = this.shownNames.get(key)
if (known && known.until > this.now()) return known.name
const name = (await this.currentName(repository))?.fullName ?? repository.fullName
this.shownNames.set(key, { name, until: this.now() + INSTALLATION_TTL_MS })
return name
}
/** [repository]'s name now when it was renamed, else null: read with a read-only token of its owner's installation of
* the app, which GitHub answers by the repository's id once it moved. The token is revoked at once. */
private async currentName(repository: GitHubRepository): Promise<GitHubRepository | null> {
const key = repository.fullName.toLowerCase()
const known = this.renames.get(key)
if (known && known.until > this.now()) return known.repository
let current: GitHubRepository | null = null
try {
const owner = await this.ownerInstallation(repository.owner)
if (owner !== null) {
const minted = await this.call('POST', `/app/installations/${owner}/access_tokens`, `Bearer ${this.jwt()}`, { permissions: { metadata: 'read' } })
const token = (minted.body as Record<string, unknown>).token
if (minted.status === 201 && typeof token === 'string') {
try {
const read = await this.call('GET', `/repos/${repository.owner}/${repository.name}`, `Bearer ${token}`)
const fullName = (read.body as Record<string, unknown>).full_name
const found = read.status === 200 && typeof fullName === 'string' ? githubRepository(`https://github.com/${fullName}`) : null
if (found && found.fullName.toLowerCase() !== key) current = found
} finally {
await this.revoke(token).catch(() => {})
}
}
}
} catch (error) {
if (error instanceof GitHubAppError && error.code === 'GITHUB_APP_MISCONFIGURED') throw error
// GitHub did not say: the repository reads as not installed, as it did before.
}
this.renames.set(key, { repository: current, until: this.now() + (current ? INSTALLATION_TTL_MS : NOT_INSTALLED_TTL_MS) })
return current
}
/** The app's installation on [owner], an organization or a user, or null. */
private async ownerInstallation(owner: string): Promise<number | null> {
for (const path of [`/orgs/${owner}/installation`, `/users/${owner}/installation`]) {
const answer = await this.call('GET', path, `Bearer ${this.jwt()}`)
if (answer.status === 401) throw this.misconfigured()
const id = (answer.body as Record<string, unknown>).id
if (answer.status === 200 && typeof id === 'number') return id
}
return null
}
/** Whether [owner], an organization, lets Harness create a repository there (task #1788). Its installation is remembered
* ten minutes (a missing one a minute), and what it granted as for agents' tokens ([granted]). A personal account reads
* as not installed: v1 creates in organizations only. */
async ownerReadiness(owner: string): Promise<OwnerReadiness> {
const key = owner.toLowerCase()
let known = this.orgInstallations.get(key)
if (!known || known.until <= this.now()) {
const answer = await this.call('GET', `/orgs/${encodeURIComponent(owner)}/installation`, `Bearer ${this.jwt()}`)
if (answer.status === 401) throw this.misconfigured()
const id = (answer.body as Record<string, unknown>).id
if (answer.status === 200 && typeof id === 'number') known = { id, until: this.now() + INSTALLATION_TTL_MS }
else if (answer.status === 404) known = { id: null, until: this.now() + NOT_INSTALLED_TTL_MS }
else throw new GitHubAppError('GITHUB_UNAVAILABLE', `GitHub could not look up the app on ${owner}.`, 502)
if (this.orgInstallations.size >= 1000) this.orgInstallations.delete(this.orgInstallations.keys().next().value!)
this.orgInstallations.set(key, known)
}
if (known.id === null) return { state: 'not-installed', installUrl: this.installUrl() }
const granted = await this.granted(known.id)
if (granted?.repository_creation !== 'write') return { state: 'not-accepted' }
return { state: 'ready', installation: known.id, canAdd: granted.installation_repositories === 'write' }
}
/** Forgets that the app was not on [repository] (and its rename), so the next lookup asks GitHub: a person just
* installed it. At most once every REFRESH_MS per repository, so a refresh cannot become a stream of lookups. */
forget(repository: GitHubRepository): void {
const key = repository.fullName.toLowerCase()
const last = this.forgotten.get(key)
if (last !== undefined && this.now() - last < REFRESH_MS) return
this.forgotten.set(key, this.now())
if (this.installations.get(key)?.id === null) this.installations.delete(key)
if (this.renames.get(key)?.repository === null) this.renames.delete(key)
}
/** What [installationId] has granted (GET /app/installations/{id}, with the app's JWT), remembered ten minutes; [fresh]
* asks GitHub again. Null when GitHub does not say, remembered a minute: the token then asks for TOKEN_PERMISSIONS alone. */
private async granted(installationId: number, fresh = false): Promise<TokenPermissions | null> {
const known = this.grants.get(installationId)
if (!fresh && known && known.until > this.now()) return known.permissions
let permissions: TokenPermissions | null = null
try {
const answer = await this.call('GET', `/app/installations/${installationId}`, `Bearer ${this.jwt()}`)
if (answer.status === 401) throw this.misconfigured()
const listed = (answer.body as Record<string, unknown>).permissions
if (answer.status === 200 && listed && typeof listed === 'object' && !Array.isArray(listed)) {
permissions = Object.fromEntries(Object.entries(listed as Record<string, unknown>)
.filter((entry): entry is [string, 'read' | 'write'] => entry[1] === 'read' || entry[1] === 'write'))
} else {
// Said every time, as agents then lose workflow pushes and issue writes with nothing else to show why (review 2 of #2956).
console.warn(`[github] installation ${installationId}'s permissions unreadable (HTTP ${answer.status}); agent tokens ask for today's set alone`)
}
} catch (error) {
if (!(error instanceof GitHubAppError) || error.code === 'GITHUB_APP_MISCONFIGURED') throw error
console.warn(`[github] installation ${installationId}'s permissions unreadable (${error.code}); agent tokens ask for today's set alone`)
// GitHub did not answer: today's set, asked again next time.
return null
}
if (this.grants.size >= 1000) this.grants.delete(this.grants.keys().next().value!)
this.grants.set(installationId, { permissions, until: this.now() + (permissions ? INSTALLATION_TTL_MS : NOT_INSTALLED_TTL_MS) })
return permissions
}
/** An agent's token's permissions on [installationId]: TOKEN_PERMISSIONS, and each of GRANTED_TOKEN_PERMISSIONS the
* installation granted, at the lower of the two levels. */
private async agentPermissions(installationId: number, fresh = false): Promise<TokenPermissions> {
const granted = await this.granted(installationId, fresh)
const permissions: Record<string, 'read' | 'write'> = { ...TOKEN_PERMISSIONS }
for (const [name, wanted] of Object.entries(GRANTED_TOKEN_PERMISSIONS)) {
const level = granted?.[name]
if (level) permissions[name] = level === 'write' && wanted === 'write' ? 'write' : 'read'
}
return permissions
}
/**
* A token for [repository] alone. With [permissions] given, those alone; without, an agent's token: TOKEN_PERMISSIONS and
* what of GRANTED_TOKEN_PERMISSIONS its installation granted. A permission refusal of an agent's token reads the grant
* again and asks once more when that changes what to ask for: an owner took a permission away within the ten minutes.
*/
async createToken(installationId: number, repository: GitHubRepository, permissions?: TokenPermissions): Promise<{ token: string; expiresAt: string }> {
if (permissions) return this.mint(installationId, repository, permissions)
const asked = await this.agentPermissions(installationId)
try {
return await this.mint(installationId, repository, asked)
} catch (error) {
if (!(error instanceof GitHubAppError) || error.code !== 'GITHUB_APP_PERMISSIONS') throw error
const now = await this.agentPermissions(installationId, true)
if (samePermissions(asked, now)) throw error
return this.mint(installationId, repository, now)
}
}
private async mint(installationId: number, repository: GitHubRepository, permissions: TokenPermissions): Promise<{ token: string; expiresAt: string }> {
const forbidden = Object.keys(permissions).filter(name => (NEVER_ON_INSTALLATION_TOKENS as readonly string[]).includes(name))
if (forbidden.length) throw new GitHubAppError('GITHUB_APP_PERMISSIONS_FORBIDDEN', `An installation token never asks for ${forbidden.join(', ')}.`, 500)
const answer = await this.call('POST', `/app/installations/${installationId}/access_tokens`, `Bearer ${this.jwt()}`,
{ repositories: [repository.name], permissions })
const body = answer.body as Record<string, unknown>
if (answer.status === 201 && typeof body.token === 'string' && typeof body.expires_at === 'string' && Number.isFinite(Date.parse(body.expires_at))) {
return { token: body.token, expiresAt: body.expires_at }
}
if (answer.status === 401) throw this.misconfigured()
if (answer.status === 404 || answer.status === 422 || answer.status === 403) {
this.installations.delete(repository.fullName.toLowerCase())
// GitHub says which: the installation lacks the repository, or has not accepted a permission asked for.
if (/permission/i.test(String(body.message ?? ''))) {
throw new GitHubAppError('GITHUB_APP_PERMISSIONS',
`The Harness GitHub App on ${repository.owner} has not been granted all the permissions it needs. An owner of ${repository.owner} should accept its requested permissions in the app's installation settings.`, 409)
}
throw this.notInstalled(repository)
}
throw new GitHubAppError('GITHUB_UNAVAILABLE', `GitHub could not create a token for ${repository.fullName}.`, 502)
}
/** One call with an installation [token] this server minted (the merge train's, github/train.ts): its status and JSON body.
* Throws [GitHubAppError] GITHUB_UNAVAILABLE when GitHub does not answer. */
async installationCall(token: string, method: string, path: string, body?: unknown): Promise<{ status: number; body: Record<string, unknown> | unknown[] }> {
const answer = await this.call(method, path, `Bearer ${token}`, body)
return { status: answer.status, body: answer.body }
}
/** Ends [token] at once (DELETE /installation/token, authorised by the token itself). One GitHub already ended reads as
* done. */
/** One GET of [path] with an installation [token], for readers that page and judge answers themselves (superTabs/releaseWatch.ts):
* its status, body, and the next page's path from the Link header. Throws [GitHubAppError] when GitHub does not answer. */
async get(path: string, token: string): Promise<{ status: number; body: unknown; next?: string }> {
const answer = await this.call('GET', path, `Bearer ${token}`)
const next = /<https:\/\/[^/>]+(\/[^>]+)>;\s*rel="next"/.exec(answer.link ?? '')?.[1]
return { status: answer.status, body: answer.body, ...(next ? { next } : {}) }
}
async revoke(token: string): Promise<void> {
const answer = await this.call('DELETE', '/installation/token', `Bearer ${token}`)
if (answer.status === 204 || answer.status === 401) return
throw new GitHubAppError('GITHUB_UNAVAILABLE', `GitHub did not revoke the token (HTTP ${answer.status}).`, 502)
}
/** The jobs running and waiting on [repository]'s GitHub Actions (Scholes's goals, piece 5: work that starts heavy CI waits
* for the account's limit), or null when the app is not installed there. Read with a token that can only read workflow
* runs, revoked as soon as the counts are in; the token, run names and branches never leave this method. Kept
* [CI_LOAD_TTL_MS], and routes asking at once share one read; a failed read is not kept. Throws [GitHubAppError] when
* GitHub cannot say. */
async ciLoad(repository: GitHubRepository): Promise<CiLoad | null> {
const key = repository.fullName.toLowerCase(), now = this.now()
const known = this.ciLoads.get(key)
if (known && known.until > now) return known.value
// Kept per repository a Swarm routes for; the expired ones go once there are many.
if (this.ciLoads.size >= 200) for (const [k, v] of this.ciLoads) if (v.until <= now) this.ciLoads.delete(k)
if (this.ciReads.size >= 200) for (const [k, v] of this.ciReads) if (!v.at.some(t => now - t < 3_600_000)) this.ciReads.delete(k)
const reads = this.ciReads.get(key) ?? { at: [], last: null }
reads.at = reads.at.filter(t => now - t < 3_600_000)
this.ciReads.set(key, reads)
if (reads.at.length >= CI_READS_PER_HOUR) {
if (reads.last && now - reads.last.at <= CI_STALE_MS) return reads.last.load
throw new GitHubAppError('GITHUB_CI_BUDGET', `This hour's CI reads for ${repository.fullName} are spent.`, 429)
}
reads.at.push(now)
const value = this.readCiLoad(repository)
this.ciLoads.set(key, { value, until: now + CI_LOAD_TTL_MS })
// A failed read leaves the cache only if it is still this read's: one that fails late never drops a newer read's entry.
value.then(load => { reads.last = { load, at: now } }, () => { if (this.ciLoads.get(key)?.value === value) this.ciLoads.delete(key) })
return value
}
/**
* Who pushed the pull request [number]'s commits (pushOrigin.ts), remembered by its head alone. A failure never reads as clean.
*/
async pushOrigin(repository: GitHubRepository, number: number): Promise<PushOrigin> {
try {
const resolved = await this.resolve(repository)
if (!resolved) return 'unknown'
const { token } = await this.createToken(resolved.installation, resolved.repository, PUSH_ORIGIN_PERMISSIONS)
const auth = `Bearer ${token}`, name = `${resolved.repository.owner}/${resolved.repository.name}`
const call: GitHubRead = async path => {
const answer = await this.call('GET', path, auth)
const next = /<https:\/\/[^/>]+(\/[^>]+)>;\s*rel="next"/.exec(answer.link ?? '')?.[1]
return { status: answer.status, body: answer.body, ...(next ? { next } : {}) }
}
const pullPath = `/repos/${name}/pulls/${number}`
const pull = await call(pullPath)
const sha = (pull.body as { head?: { sha?: unknown } }).head?.sha
const key = typeof sha === 'string' ? `${name.toLowerCase()}@${sha}` : null
const known = key ? this.pushOrigins.get(key) : undefined
if (known && known.until > this.now()) return known.origin
// The same read of the pull request decides the head and the answer, so a push in between cannot file it under another commit.
const read: GitHubRead = path => path === pullPath ? Promise.resolve(pull) : call(path)
const origin = await readPushOrigin(read, name, number, await this.botLogin())
if (key) {
if (this.pushOrigins.size >= PUSH_ORIGINS_KEPT) this.pushOrigins.delete(this.pushOrigins.keys().next().value!)
// An answer for a head holds for good. An `unknown` is asked again a minute later, so retries cost no more than that.
this.pushOrigins.set(key, { origin, until: origin === 'unknown' ? this.now() + PUSH_UNKNOWN_MS : Infinity })
}
return origin
} catch {
return 'unknown'
}
}
/** Who pushed [branch]: the default branch is clean, as it passed review; any other reads its one open pull request, and with none is unknown. */
async branchOrigin(repository: GitHubRepository, branch: string): Promise<PushOrigin> {
try {
const resolved = await this.resolve(repository)
if (!resolved) return 'unknown'
const { token } = await this.createToken(resolved.installation, resolved.repository, PUSH_ORIGIN_PERMISSIONS)
const auth = `Bearer ${token}`, { owner, name } = resolved.repository
const about = await this.call('GET', `/repos/${owner}/${name}`, auth)
if (about.status === 200 && (about.body as { default_branch?: unknown }).default_branch === branch) return 'clean'
const listed = await this.call('GET', `/repos/${owner}/${name}/pulls?state=open&head=${encodeURIComponent(`${owner}:${branch}`)}&per_page=2`, auth)
const number = Array.isArray(listed.body) && listed.body.length === 1 ? (listed.body[0] as { number?: unknown }).number : null
return listed.status === 200 && typeof number === 'number' ? await this.pushOrigin(repository, number) : 'unknown'
} catch {
return 'unknown'
}
}
private async readCiLoad(repository: GitHubRepository): Promise<CiLoad | null> {
const resolved = await this.resolve(repository)
if (!resolved) return null
const { token } = await this.createToken(resolved.installation, resolved.repository, ACTIONS_READ_PERMISSIONS)
const auth = `Bearer ${token}`, runs = `/repos/${resolved.repository.owner}/${resolved.repository.name}/actions/runs`
const read = (path: string) => this.call('GET', path, auth)
const unavailable = () => new GitHubAppError('GITHUB_UNAVAILABLE', `GitHub did not say what runs on ${resolved.repository.fullName}.`, 502)
const listOf = (body: unknown, field: string) => {
const items = (body as Record<string, unknown>)[field]
return Array.isArray(items) ? items.filter((i): i is Record<string, unknown> => !!i && typeof i === 'object') : []
}
try {
const pages = await Promise.all(['in_progress', 'queued'].map(async status => {
const answer = await read(`${runs}?status=${status}&per_page=${CI_MAX_RUNS}`)
if (answer.status !== 200) throw unavailable()
const listed = listOf(answer.body, 'workflow_runs'), total = (answer.body as Record<string, unknown>).total_count
return { ids: listed.map(r => r.id).filter((id): id is number => Number.isSafeInteger(id)),
more: Math.max(0, (Number.isSafeInteger(total) ? total as number : 0) - listed.length) }
}))
const ids = [...new Set(pages.flatMap(p => p.ids))]
const counted = ids.slice(0, CI_MAX_RUNS)
const load: CiLoad = { running: 0, queued: ids.length - counted.length + pages.reduce((n, p) => n + p.more, 0), macosRunning: 0, macosQueued: 0 }
for (const jobs of await Promise.all(counted.map(async id => {
const answer = await read(`${runs}/${id}/jobs?filter=latest&per_page=100`)
if (answer.status !== 200) throw unavailable()
return listOf(answer.body, 'jobs')
}))) {
for (const job of jobs) {
const mac = Array.isArray(job.labels) && job.labels.some(l => typeof l === 'string' && /macos/i.test(l))
if (job.status === 'in_progress') { load.running++; if (mac) load.macosRunning++ }
else if (CI_WAITING.has(String(job.status))) { load.queued++; if (mac) load.macosQueued++ }
}
}
return load
} finally {
await this.revoke(token).catch(() => { console.warn(`[github] a CI read's token for ${resolved.repository.fullName} was not revoked; it expires within the hour`) })
}
}
/** Whether pull request [number] is open, merged or closed (GET /repos/{owner}/{repo}/pulls/{number}); missing when GitHub
* answers 404, as for another repository's number read in this one (#2602); null when GitHub cannot say, which a caller
* must read as possibly open. */
async pullRequestState(repository: GitHubRepository, number: number, token: string): Promise<'open' | 'merged' | 'closed' | 'missing' | null> {
try {
const answer = await this.call('GET', `/repos/${repository.owner}/${repository.name}/pulls/${number}`, `Bearer ${token}`)
if (answer.status === 404) return 'missing'
const body = answer.body as Record<string, unknown>
if (answer.status !== 200 || !['open', 'closed'].includes(String(body.state))) return null
return body.state === 'open' ? 'open' : typeof body.merged_at === 'string' ? 'merged' : 'closed'
} catch (error) {
if (error instanceof GitHubAppError) return null
throw error
}
}
/**
* What a task's Engineer is told of its pull request [number] (superTabs/pullRequestEvents.ts): the pull request, its head's
* latest check runs and its check suites, its reviews and its conversation comments, read with a [PULL_WATCH_PERMISSIONS]
* token. Each read names the last answer's ETag, and a 304 reuses that answer. Reviews and comments come oldest first, so
* their last page is read too when there is more than one (review of #2750). Null when GitHub cannot say.
*/
async watchPullRequest(repository: GitHubRepository, number: number, token: string): Promise<PullRequestWatch | null> {
const base = `/repos/${repository.owner}/${repository.name}`
const answerOf = async (path: string, fresh = false): Promise<{ body: Record<string, unknown> | unknown[]; link: string | null } | null> => {
const kept = this.watched.get(path)
const answer = await this.call('GET', path, `Bearer ${token}`, undefined, kept && !fresh ? { 'If-None-Match': kept.etag } : {})
if (answer.status === 304 && kept) return kept
if (answer.status !== 200) return null
this.watched.delete(path)
if (answer.etag) {
if (this.watched.size >= WATCH_KEPT) this.watched.delete(this.watched.keys().next().value!)
this.watched.set(path, { etag: answer.etag, body: answer.body, link: answer.link ?? null })
}
return { body: answer.body, link: answer.link ?? null }
}
const read = async (path: string) => (await answerOf(path))?.body ?? null
// A full first page is read afresh: a new last page changes its Link, not its body.
const pages = async (path: string): Promise<unknown[] | null> => {
const first = await answerOf(path, (this.watched.get(path)?.body as unknown[] | undefined)?.length === 100)
if (!first || !Array.isArray(first.body)) return null
const last = /<([^>]+)>;\s*rel="last"/.exec(first.link ?? '')?.[1]
const lastPath = last?.startsWith(this.apiUrl) ? last.slice(this.apiUrl.length) : null
if (!lastPath) return first.body
const tail = await read(lastPath)
return Array.isArray(tail) ? [...first.body, ...tail] : null
}
const text = (value: unknown) => typeof value === 'string' ? value : ''
const login = (value: unknown) => text((value as { login?: unknown } | null)?.login)
const at = (value: unknown) => typeof value === 'string' && Number.isFinite(Date.parse(value)) ? Date.parse(value) : null
try {
const pull = await read(`${base}/pulls/${number}`) as Record<string, unknown> | null
const head = text((pull?.head as { sha?: unknown } | undefined)?.sha)
if (!pull || (pull.state !== 'open' && pull.state !== 'closed') || !/^[0-9a-f]{7,64}$/.test(head)) return null
const [runs, suites, reviews, comments] = await Promise.all([read(`${base}/commits/${head}/check-runs?per_page=100`),
read(`${base}/commits/${head}/check-suites?per_page=100`), pages(`${base}/pulls/${number}/reviews?per_page=100`),
pages(`${base}/issues/${number}/comments?per_page=100`)])
if (!runs || !suites || !Array.isArray(reviews) || !Array.isArray(comments)) return null
const list = (value: unknown) => Array.isArray(value) ? value as Array<Record<string, unknown>> : []
return {
url: text(pull.html_url) || `https://github.com/${repository.owner}/${repository.name}/pull/${number}`, number,
state: pull.state, ...typeof pull.merged_at === 'string' ? { merged: true as const } : {}, draft: pull.draft === true, head, base: text((pull.base as { ref?: unknown } | undefined)?.ref) || 'main',
mergeable: typeof pull.mergeable === 'boolean' ? pull.mergeable : null,
checkRuns: list((runs as Record<string, unknown>).check_runs).map(run => ({ name: text(run.name), status: text(run.status),
conclusion: typeof run.conclusion === 'string' ? run.conclusion : null, completedAt: at(run.completed_at) })),
checkSuites: list((suites as Record<string, unknown>).check_suites).map(suite => ({ status: text(suite.status),
runs: typeof suite.latest_check_runs_count === 'number' ? suite.latest_check_runs_count : 0 })),
reviews: list(reviews).filter(review => typeof review.id === 'number').map(review => ({ id: review.id as number, login: login(review.user),
association: text(review.author_association) || 'NONE', state: text(review.state), body: text(review.body), url: text(review.html_url) })),
comments: list(comments).filter(comment => typeof comment.id === 'number').map(comment => ({ id: comment.id as number,
login: login(comment.user), association: text(comment.author_association) || 'NONE', body: text(comment.body), url: text(comment.html_url) })),
}
} catch (error) {
if (error instanceof GitHubAppError) return null
throw error
}
}
/** The files of a pull request at [head], for its patch id (superTabs/pullRequestPatch.ts, #3394), read with a token of
* [PULL_PATCH_PERMISSIONS]: the comparison of the base and head commits the pull request names in one answer
* (GET /pulls/{number}, then GET /compare/{base}...{head}), two fixed commits no push changes (review of #3218, round 3:
* a listing of the pull request's files ties removed ones to no head, and pages to no single head). Null unless the pull request still names [head], and when GitHub cannot
* say or gives as many files as it ever gives ([COMPARE_FILES_MAX]), as it may then have left some out. With the branch it
* merges into from the same answer, which the patch id names (security review of #3218, round 3). */
async pullRequestPatchFiles(repository: GitHubRepository, number: number, token: string, head: string): Promise<{ base: string; files: PullRequestFile[] } | null> {
const base = `/repos/${repository.owner}/${repository.name}`
const sha = (value: unknown) => typeof value === 'string' && /^[0-9a-f]{40}$/i.test(value) ? value.toLowerCase() : undefined
try {
const pull = await this.call('GET', `${base}/pulls/${number}`, `Bearer ${token}`)
if (pull.status !== 200) return null
const named = pull.body as { head?: { sha?: unknown }; base?: { sha?: unknown; ref?: unknown } }
const at = sha(named.head?.sha), from = sha(named.base?.sha), branch = typeof named.base?.ref === 'string' ? named.base.ref : ''
if (!at || !from || !branch || at !== head.toLowerCase()) return null
const compared = await this.call('GET', `${base}/compare/${from}...${at}?per_page=1`, `Bearer ${token}`)
const listed = compared.status === 200 ? (compared.body as { files?: unknown }).files : undefined
if (!Array.isArray(listed) || listed.length >= COMPARE_FILES_MAX) return null
const files = filesOf(listed)
return files && { base: branch, files }
} catch (error) {
if (error instanceof GitHubAppError) return null
throw error
}
}
/** What the head [head] of pull request [number] is, to judge whether it is git's own merge of its reviewed head and main
* (superTabs/mergeCarry.ts, task #3553), read with a token of [PULL_PATCH_PERMISSIONS]: its parents (GET /git/commits); for
* a two-parent head, whether its second parent is on the branch the pull request merges into (GET /compare/{it}...{tip},
* the base commit the same answer names: identical or ahead), and the files of the three comparisons of fixed commits, each GET /compare/{a}...{b} from their merge
* base: main's side (first parent to second), the pull request's (second to first) and the merge (first parent to head). Null
* unless the pull request still names [head], when GitHub cannot say, or when a side gives as many files as GitHub ever
* gives ([COMPARE_FILES_MAX]), as it may have left some out. With the branch from the same answer as the pull request. */
async mainMergeSides(repository: GitHubRepository, number: number, token: string, head: string): Promise<{ base: string; sides: MergeSides } | null> {
const base = `/repos/${repository.owner}/${repository.name}`
const sha = (value: unknown) => typeof value === 'string' && /^[0-9a-f]{40}$/i.test(value) ? value.toLowerCase() : undefined
const files = async (from: string, to: string) => {
const compared = await this.call('GET', `${base}/compare/${from}...${to}?per_page=1`, `Bearer ${token}`)
const listed = compared.status === 200 ? (compared.body as { files?: unknown }).files : undefined
return Array.isArray(listed) && listed.length < COMPARE_FILES_MAX ? filesOf(listed) : null
}
try {
const pull = await this.call('GET', `${base}/pulls/${number}`, `Bearer ${token}`)
if (pull.status !== 200) return null
const named = pull.body as { head?: { sha?: unknown }; base?: { sha?: unknown; ref?: unknown } }
// The base as a commit, from the same answer (security review of #3284, Important 1): a branch name a tag of the same
// name could shadow is never compared against.
const at = sha(named.head?.sha), tip = sha(named.base?.sha), branch = typeof named.base?.ref === 'string' ? named.base.ref : ''
if (!at || !tip || !branch || at !== head.toLowerCase()) return null
const commit = await this.call('GET', `${base}/git/commits/${at}`, `Bearer ${token}`)
const listed = commit.status === 200 ? (commit.body as { parents?: unknown }).parents : undefined
if (!Array.isArray(listed)) return null
const parents = listed.map(p => sha((p as { sha?: unknown })?.sha))
if (parents.some(p => p === undefined)) return null
const none: MergeSides = { parents: parents as string[], onBase: false, prSide: [], mainSide: [], mergeSide: [] }
if (parents.length !== 2) return { base: branch, sides: none }
const [parent, merged] = parents as [string, string]
const onBranch = await this.call('GET', `${base}/compare/${merged}...${tip}?per_page=1`, `Bearer ${token}`)
const status = onBranch.status === 200 ? (onBranch.body as { status?: unknown }).status : undefined
if (status !== 'identical' && status !== 'ahead') return { base: branch, sides: none }
const [mainSide, prSide, mergeSide] = [await files(parent, merged), await files(merged, parent), await files(parent, at)]
if (!mainSide || !prSide || !mergeSide) return null
return { base: branch, sides: { parents: [parent, merged], onBase: true, prSide, mainSide, mergeSide } }
} catch (error) {
if (error instanceof GitHubAppError) return null
throw error
}
}
/**
* The files pull request [number] changes, read with the watch's read-only token (task #3401: its review steps are planned
* from them): GET /pulls/{n}/files, 100 a page. A renamed file is listed under its old name too, so moving a file out of a
* sensitive path still counts as changing it. Null when GitHub cannot say, or when the list may be cut at GitHub's 3,000.
*/
async pullRequestFiles(repository: GitHubRepository, number: number, token: string): Promise<Array<{ filename: string }> | null> {
const names = new Set<string>()
const text = (value: unknown) => typeof value === 'string' && value ? value : undefined
try {
for (let page = 1; page <= PULL_FILES_PAGES; page++) {
const answer = await this.call('GET', `/repos/${repository.owner}/${repository.name}/pulls/${number}/files?per_page=100&page=${page}`, `Bearer ${token}`)
if (answer.status !== 200 || !Array.isArray(answer.body)) return null
for (const file of answer.body as Array<Record<string, unknown>>) {
const filename = text(file.filename)
if (!filename) return null
names.add(filename)
const previous = text(file.previous_filename)
if (previous) names.add(previous)
}
if (answer.body.length < 100) return [...names].map(filename => ({ filename }))
}
// A full last page: GitHub lists at most 3,000 files, so more may exist.
return null
} catch (error) {
if (error instanceof GitHubAppError) return null
throw error
}
}
/** The default branch and whether pushing to it straight needs a pull request, read with the agent's own token
* (metadata and contents read): rulesets first (GET /repos/{owner}/{repo}/rules/branches/{branch}), then classic
* protection's flag on the branch. Remembered ten minutes; a failed read is `unknown`, never a refusal. */
async defaultBranch(repository: GitHubRepository, token: string): Promise<DefaultBranch> {
const key = repository.fullName.toLowerCase()
const known = this.branches.get(key)
if (known && known.until > this.now()) return known.value
const auth = `Bearer ${token}`, path = `/repos/${repository.owner}/${repository.name}`
let value: DefaultBranch = { branch: null, protection: 'unknown' }
try {
const repo = await this.call('GET', path, auth)
const branch = (repo.body as Record<string, unknown>).default_branch
if (repo.status === 200 && typeof branch === 'string' && branch) {
value = { branch, protection: 'unknown' }
const rules = await this.call('GET', `${path}/rules/branches/${encodeURIComponent(branch)}`, auth)
if (rules.status === 200 && Array.isArray(rules.body) && rules.body.some(rule => (rule as Record<string, unknown>)?.type === 'pull_request')) {
value = { branch, protection: 'pull_request' }
} else {
const classic = await this.call('GET', `${path}/branches/${encodeURIComponent(branch)}`, auth)
const flag = (classic.body as Record<string, unknown>).protected
if (classic.status === 200 && typeof flag === 'boolean') value = { branch, protection: flag ? 'classic' : 'none' }
}
}
} catch (error) {
if (!(error instanceof GitHubAppError)) throw error
}
if (value.protection !== 'unknown') this.branches.set(key, { value, until: this.now() + BRANCH_TTL_MS })
return value
}
}