Module: integrations/githubChecks

GitHub App Check Run client with cached installation tokens (INT-002).

Source:

Methods

(static) buildRunUrl(runId) → {string|undefined}

Build an absolute Run Detail URL for GitHub's details link.

Parameters:
Name Type Description
runId string
Source:
Returns:
Type
string | undefined

(static) claimInstallState(nonce) → {Promise.<boolean>}

Claim (consume) a previously-verified install-state nonce. Used by callers that passed { claim: false } to verifyInstallState and have now completed their fallible work.

Parameters:
Name Type Description
nonce string
Source:
Returns:

True if the nonce was successfully claimed.

Type
Promise.<boolean>

(static) clearInstallStateCache() → {void}

Clear cached one-shot GitHub install state nonces. Intended for tests.

Source:
Returns:
Type
void

(static) clearInstallationTokenCache() → {void}

Clear cached installation tokens. Intended for tests.

Source:
Returns:
Type
void

(static) conclude(checkRunId, args, optionsopt) → {Promise.<Object>}

Conclude an existing GitHub Check Run.

Parameters:
Name Type Attributes Description
checkRunId string | number
args Object
Properties
Name Type Description
repo string
installationId string | number
conclusion "success" | "failure" | "neutral"
summaryMd string
options Object <optional>
Source:
Returns:
Type
Promise.<Object>

(static) createPending(runId, args, optionsopt) → {Promise.<Object>}

Create a queued GitHub Check Run.

Parameters:
Name Type Attributes Description
runId string
args Object
Properties
Name Type Description
repo string
sha string
installationId string | number
options Object <optional>
Source:
Returns:

GitHub check-run payload.

Type
Promise.<Object>

(static) getChangedFilesForPr(args, optionsopt) → {Promise.<Array.<string>>}

List file paths changed by a pull request using the GitHub PR Files API.

Parameters:
Name Type Attributes Description
args Object
Properties
Name Type Description
repo string
prNumber number | string
installationId string | number
options Object <optional>
Properties
Name Type Attributes Description
fetchImpl function <optional>
Source:
Returns:
Type
Promise.<Array.<string>>

(static) getInstallationRepos(installationId, optionsopt) → {Promise.<Array.<string>>}

List repositories selected for a GitHub App installation.

Parameters:
Name Type Attributes Description
installationId string | number
options Object <optional>
Properties
Name Type Attributes Description
fetchImpl function <optional>
Source:
Returns:

Repository names in owner/name format.

Type
Promise.<Array.<string>>

(static) getInstallationToken(installationId, optionsopt) → {Promise.<string>}

Return a cached GitHub App installation token, refreshing before expiry.

Parameters:
Name Type Attributes Description
installationId string | number
options Object <optional>
Properties
Name Type Attributes Description
fetchImpl function <optional>
Source:
Returns:
Type
Promise.<string>

(static) markInProgress(checkRunId, args, optionsopt) → {Promise.<Object>}

Mark an existing GitHub Check Run in progress.

Parameters:
Name Type Attributes Description
checkRunId string | number
args Object
Properties
Name Type Description
repo string
installationId string | number
options Object <optional>
Source:
Returns:
Type
Promise.<Object>

(static) signInstallState(projectId, optionsopt) → {Promise.<string>}

Sign a short-lived, one-shot state token for the GitHub App install flow.

The state JWT is the only auth on the callback route because GitHub redirects the user back from github.com — a cross-site navigation that browsers refuse to attach SameSite=Strict cookies to (the default for same-origin Sentri deployments). The signed nonce-tracked state proves an authenticated admin initiated the flow; the embedded actor fields let the callback log who completed the install without req.authUser.

Parameters:
Name Type Attributes Description
projectId string
options Object <optional>
Properties
Name Type Attributes Default Description
ttlSec number <optional>
 600
actor Object <optional>

Optional authenticated user metadata captured at sign-time so the callback can attribute the activity log entry.

Properties
Name Type Attributes Description
userId string <optional>
userName string <optional>
Source:
Returns:

Signed state JWT.

Type
Promise.<string>

(static) verifyInstallState(token, optionsopt) → {Promise.<({projectId: string, nonce: string, actorId: (string|null), actorName: (string|null)}|null)>}

Verify a GitHub App install state token.

By default the nonce is claimed (consumed) on verification — the token is one-shot. Callers that need to perform fallible work (e.g. GitHub API calls) between verification and final acceptance can pass { claim: false } to defer consumption and then call claimInstallState(nonce) after the fallible work succeeds; this prevents a transient upstream failure from permanently spending the state JWT and forcing the user to restart the entire install flow.

Parameters:
Name Type Attributes Description
token string
options Object <optional>
Properties
Name Type Attributes Default Description
claim boolean <optional>
 true

When false, the nonce is left in place; the caller is responsible for calling claimInstallState(nonce).
Source:
Returns:
Type
Promise.<({projectId: string, nonce: string, actorId: (string|null), actorName: (string|null)}|null)>