# jg-github

> GitHub App authentication for Node.js: app tokens, scoped installation tokens, webhook signatures, and rate-limit retry times.

- **Version:** `0.2.1`
- **Runtimes:** Node.js
- **Install:** `npm install jg-github`
- **On npm:** [jg-github](https://www.npmjs.com/package/jg-github)
- **Source:** [packages/jg-github](https://github.com/jesusgraterol/jg-packages/tree/main/packages/jg-github)
- **Recipes:** [jg-github recipes](https://jg-packages.jesusgraterol.dev/packages/jg-github/recipes/index.md)

## Usage

Create an installation token for exactly the repositories and the permissions a job needs, and revoke it when the job is done:

```ts
import { createInstallationToken, revokeInstallationToken } from 'jg-github';

declare const privateKey: string;

const { token, expiresAt } = await createInstallationToken({
  appId: 123456,
  privateKey,
  installationId: 12345678,
  repositories: ['app', 'docs'], // or repositoryIds: [101, 102]
  permissions: { contents: 'read', pull_requests: 'write' },
  userAgent: 'acme-release-bot',
});
try {
  // call the API with createGithubHeaders(token, { userAgent: 'acme-release-bot' })
} finally {
  await revokeInstallationToken(token, { userAgent: 'acme-release-bot' });
}
```

`permissions` is required and can't be empty, because GitHub grants every permission of the installation to a request without it. The repositories are named by name or by ID, never both, with no repeats. Anything else throws `GITHUB_INVALID_ARGUMENT` before a request is sent. GitHub's answer must match the request exactly: only the selected repositories, the same ones, compared by name ignoring case or by ID as you named them, and the same permissions, plus the `metadata: 'read'` GitHub adds. A token that doesn't match, or that had already expired, is revoked before the error is thrown, and the error's `isRevoked` says whether that worked.

Verify a webhook delivery before parsing its body:

```ts
import { verifyGithubWebhookSignature } from 'jg-github';

declare const rawBody: Buffer;
declare const headers: Record<string, string | string[] | undefined>;
declare const webhookSecret: string;

const isAuthentic = verifyGithubWebhookSignature(
  rawBody,
  headers['x-hub-signature-256'],
  webhookSecret,
);
```

It's false for a header that's missing, repeated, longer than 71 characters, or not `sha256=` and 64 lowercase hexadecimal characters, and compares the signature in constant time.

Find when to retry a rate limited request:

```ts
import { getGithubRateLimitDeadline } from 'jg-github';

declare const response: Response;

const retryAt = getGithubRateLimitDeadline({
  status: response.status,
  headers: response.headers,
  retryCount: 0,
}); // a Date, or null when the response isn't rate limited
```

A 429 is rate limited, and so is a 403 with `Retry-After`, with no requests remaining, or with `hasRateLimitMessage`, and a success that used the last request. The deadline is the latest future one of `Retry-After`, as whole seconds or a strict IMF-fixdate, and `x-ratelimit-reset` when no requests remain; without one, it's a minute from now, doubled for each retry already made.

The rest of the API:

- `createGithubAppJwt({ appId, privateKey })`, the App's own JWT, signed with RS256, issued 60 seconds back and expiring 540 seconds ahead, inside GitHub's ten-minute limit even with a clock a minute ahead. `assertGithubAppPrivateKey(pem)` checks the key at startup: an unencrypted RSA key, PKCS#1 or PKCS#8.
- `createGithubHeaders(token, { userAgent, apiVersion })`, the headers every request sends, with `X-GitHub-Api-Version` set to `GITHUB_API_VERSION` unless you pass another.
- `buildGithubApiUrl(segments, query, { apiOrigin })` and `buildGithubRawContentUrl(location, { rawContentOrigin })`, which encode each value, so a branch's `/` or a `..` can't change the path. `apiOrigin`, such as GitHub Enterprise Server's `https://ghe.example.com/api/v3`, must be https, or http on a loopback host for a test server.

Requests go through jg-fetch with `redirect: 'error'`, a 10-second timeout, a 128 KiB response limit, and no retries, because creating or revoking a token twice isn't safe.

### Errors

| Code                          | When                                                                                                                     |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `GITHUB_PRIVATE_KEY_INVALID`  | The App's private key isn't an unencrypted RSA key, PEM-encoded as PKCS#1 or PKCS#8                                      |
| `GITHUB_INVALID_ARGUMENT`     | An argument isn't valid, such as missing or empty `permissions`, a repeated repository, or an installation ID not digits |
| `GITHUB_REQUEST_FAILED`       | A request fails: an error status, a redirect, a timeout, an abort, or no answer                                          |
| `GITHUB_RESPONSE_INVALID`     | GitHub's answer isn't in the expected format, or is larger than `maxResponseBytes`                                       |
| `GITHUB_TOKEN_SCOPE_MISMATCH` | The granted token reaches other repositories, or has other permissions, than requested                                   |
| `GITHUB_TOKEN_EXPIRED`        | The granted token had already expired                                                                                    |
| `GITHUB_TOKEN_REVOKE_FAILED`  | GitHub answers a revocation with anything but 204, or not at all                                                         |

`GITHUB_REQUEST_FAILED`'s data holds jg-fetch's `kind` of failure, the `status`, and the `rateLimitDeadline` as an ISO string, or null. `GITHUB_TOKEN_SCOPE_MISMATCH`'s data says what differs, `repository_selection`, `repositories`, or `permissions`, and, like `GITHUB_TOKEN_EXPIRED`'s and `GITHUB_RESPONSE_INVALID`'s when GitHub granted a token, whether it was revoked. No error has a cause or holds a token, the App's JWT, the private key, or a response body. `verifyGithubWebhookSignature` throws jg-crypto's `INVALID_HMAC_SECRET` for an empty secret.

## <a id="api-reference"></a>jg-github API reference

Every export of `jg-github@0.2.1`, 30 in all, with its signature, its errors, and an example. It's generated from the package's TSDoc.

- Functions: [`assertGithubAppPrivateKey`](#api-assertGithubAppPrivateKey), [`buildGithubApiUrl`](#api-buildGithubApiUrl), [`buildGithubRawContentUrl`](#api-buildGithubRawContentUrl), [`createGithubAppJwt`](#api-createGithubAppJwt), [`createGithubHeaders`](#api-createGithubHeaders), [`createInstallationToken`](#api-createInstallationToken), [`getGithubRateLimitDeadline`](#api-getGithubRateLimitDeadline), [`revokeInstallationToken`](#api-revokeInstallationToken), [`verifyGithubWebhookSignature`](#api-verifyGithubWebhookSignature)
- Constants: [`DEFAULT_GITHUB_MAX_RESPONSE_BYTES`](#api-DEFAULT_GITHUB_MAX_RESPONSE_BYTES), [`DEFAULT_GITHUB_TIMEOUT_SECONDS`](#api-DEFAULT_GITHUB_TIMEOUT_SECONDS), [`ERRORS`](#api-ERRORS), [`GITHUB_API_ORIGIN`](#api-GITHUB_API_ORIGIN), [`GITHUB_API_VERSION`](#api-GITHUB_API_VERSION), [`GITHUB_RAW_CONTENT_ORIGIN`](#api-GITHUB_RAW_CONTENT_ORIGIN)
- Types: [`ICreateGithubAppJwtOptions`](#api-ICreateGithubAppJwtOptions), [`ICreateInstallationTokenOptions`](#api-ICreateInstallationTokenOptions), [`IGithubApiUrlOptions`](#api-IGithubApiUrlOptions), [`IGithubHeadersOptions`](#api-IGithubHeadersOptions), [`IGithubPermissionLevel`](#api-IGithubPermissionLevel), [`IGithubPermissions`](#api-IGithubPermissions), [`IGithubQuery`](#api-IGithubQuery), [`IGithubRateLimitDeadlineOptions`](#api-IGithubRateLimitDeadlineOptions), [`IGithubRawContentLocation`](#api-IGithubRawContentLocation), [`IGithubRawContentUrlOptions`](#api-IGithubRawContentUrlOptions), [`IGithubRepository`](#api-IGithubRepository), [`IGithubRequestOptions`](#api-IGithubRequestOptions), [`IGithubResponseHeaders`](#api-IGithubResponseHeaders), [`IInstallationToken`](#api-IInstallationToken), [`IInstallationTokenRepositories`](#api-IInstallationTokenRepositories)

### <a id="api-functions"></a>Functions

#### <a id="api-assertGithubAppPrivateKey"></a>`assertGithubAppPrivateKey`

*Function*

Checks that a GitHub App's private key can sign its JWTs: an unencrypted RSA key, PEM-encoded as PKCS#1, the `RSA PRIVATE KEY` GitHub downloads, or PKCS#8, the `PRIVATE KEY` it converts to. Run it at startup, so a bad key fails before the first request. The error never holds the key.

```ts
assertGithubAppPrivateKey(pem: string): void
```

**Parameters**

- `pem` `string`: The key.

**Throws**

- `GITHUB_PRIVATE_KEY_INVALID`: The GitHub App's private key isn't an unencrypted RSA private key.

**Example**

```ts
import { assertGithubAppPrivateKey } from 'jg-github';

declare const privateKey: string;

assertGithubAppPrivateKey(privateKey);
```

#### <a id="api-buildGithubApiUrl"></a>`buildGithubApiUrl`

*Function*

Builds a REST API URL from its path segments, each encoded on its own, so a branch's `/` becomes `%2F` and no value can climb out of the path, plus the query parameters.

```ts
buildGithubApiUrl(
  segments: readonly (string | number)[],
  query?: IGithubQuery,
  options?: IGithubApiUrlOptions,
): string
```

**Parameters**

- `segments` `readonly (string | number)[]`: The path's segments, such as `['repos', owner, repository, 'branches', branch]`.
- `query?` `IGithubQuery`: The query parameters; undefined ones are left out. Defaults to `{}`.
- `options?` `IGithubApiUrlOptions`: The API's base URL, for GitHub Enterprise Server or a test server. Defaults to `{}`.

**Returns** `string`: The URL.

**Throws**

- `GITHUB_INVALID_ARGUMENT`: An argument isn't valid.

**Example**

```ts
import { buildGithubApiUrl } from 'jg-github';

buildGithubApiUrl(['repos', 'acme', 'app', 'branches', 'feature/login'], { per_page: 100 });
// 'https://api.github.com/repos/acme/app/branches/feature%2Flogin?per_page=100'
```

#### <a id="api-buildGithubRawContentUrl"></a>`buildGithubRawContentUrl`

*Function*

Builds the URL of a file's raw content at a ref, with the owner and the repository encoded as one segment each, and the ref's and the path's `/`s kept.

```ts
buildGithubRawContentUrl(
  location: IGithubRawContentLocation,
  options?: IGithubRawContentUrlOptions,
): string
```

**Parameters**

- `location` `IGithubRawContentLocation`: The repository, the ref, and the file's path.
- `options?` `IGithubRawContentUrlOptions`: The raw content's base URL, for a test server. Defaults to `{}`.

**Returns** `string`: The URL.

**Throws**

- `GITHUB_INVALID_ARGUMENT`: An argument isn't valid.

**Example**

```ts
import { buildGithubRawContentUrl } from 'jg-github';

buildGithubRawContentUrl({ owner: 'acme', repository: 'app', ref: 'main', path: 'docs/setup.md' });
// 'https://raw.githubusercontent.com/acme/app/main/docs/setup.md'
```

#### <a id="api-createGithubAppJwt"></a>`createGithubAppJwt`

*Function*

Creates the JWT a GitHub App authenticates as itself with, signed with RS256: issued 60 seconds back, for a GitHub clock behind this one, and expiring 540 seconds ahead, inside GitHub's ten-minute limit even with this clock a minute ahead.

```ts
createGithubAppJwt(options: ICreateGithubAppJwtOptions): string
```

**Parameters**

- `options` `ICreateGithubAppJwtOptions`: The App's ID, its private key, and the time.

**Returns** `string`: The JWT.

**Throws**

- `GITHUB_INVALID_ARGUMENT`: An argument isn't valid.
- `GITHUB_PRIVATE_KEY_INVALID`: The GitHub App's private key isn't an unencrypted RSA private key.

**Example**

```ts
import { createGithubAppJwt } from 'jg-github';

declare const privateKey: string;

const jwt = createGithubAppJwt({ appId: 123456, privateKey });
```

#### <a id="api-createGithubHeaders"></a>`createGithubHeaders`

*Function*

Builds the headers a request to GitHub's REST API sends: the media type, the token as a bearer credential, the User-Agent GitHub requires, and the API version.

```ts
createGithubHeaders(
  token: string,
  options: IGithubHeadersOptions,
): Record<string, string>
```

**Parameters**

- `token` `string`: The token, such as an installation token or an App JWT.
- `options` `IGithubHeadersOptions`: The User-Agent and the API version.

**Returns** `Record<string, string>`: The headers, with lowercase names.

**Throws**

- `GITHUB_INVALID_ARGUMENT`: An argument isn't valid.

**Example**

```ts
import { createGithubHeaders } from 'jg-github';

declare const token: string;

const response = await fetch('https://api.github.com/installation/repositories', {
  headers: createGithubHeaders(token, { userAgent: 'acme-deploy-bot' }),
});
```

#### <a id="api-createInstallationToken"></a>`createInstallationToken`

*Function*

Creates an installation token for exactly the repositories and the permissions asked for, with `POST /app/installations/{id}/access_tokens`, authenticated as the App. `permissions` is required, because GitHub grants every permission of the installation without it, and the repositories are named by name or by ID, never both. The granted token must reach exactly those repositories, only the selected ones, with exactly those permissions, plus `metadata: 'read'`, and must not have expired; otherwise it's revoked before the error is thrown, and the error's data says whether that worked. Nothing is retried, and no error holds the token or the App's JWT.

```ts
createInstallationToken(
  options: ICreateInstallationTokenOptions,
): Promise<IInstallationToken>
```

**Parameters**

- `options` `ICreateInstallationTokenOptions`: The App, the installation, the scope, and the request's limits.

**Returns** `Promise<IInstallationToken>`: A promise that resolves to the token, when it expires, and what it reaches.

**Throws**

- `GITHUB_INVALID_ARGUMENT`: An argument isn't valid.
- `GITHUB_PRIVATE_KEY_INVALID`: The GitHub App's private key isn't an unencrypted RSA private key.
- `GITHUB_REQUEST_FAILED`: The GitHub request failed.
- `GITHUB_RESPONSE_INVALID`: GitHub's response isn't in the expected format.
- `GITHUB_TOKEN_SCOPE_MISMATCH`: The installation token's scope isn't the one requested.
- `GITHUB_TOKEN_EXPIRED`: The installation token had already expired.

**Example**

```ts
import { createInstallationToken, revokeInstallationToken } from 'jg-github';

declare const privateKey: string;

const { token } = await createInstallationToken({
  appId: 123456,
  privateKey,
  installationId: 12345678,
  repositories: ['app'],
  permissions: { contents: 'read' },
  userAgent: 'acme-deploy-bot',
});
try {
  // read the repository's contents with the token
} finally {
  await revokeInstallationToken(token, { userAgent: 'acme-deploy-bot' });
}
```

#### <a id="api-getGithubRateLimitDeadline"></a>`getGithubRateLimitDeadline`

*Function*

Gives the time to retry a GitHub request at after a rate limit, or null when the response isn't rate limited. A 429 is, and so is a 403 with Retry-After, with no requests remaining, or with a rate-limit message, and a success that used the last remaining request. The deadline is the latest of Retry-After, as whole seconds or a strict IMF-fixdate, and `x-ratelimit-reset` when no requests remain, counting only future times; without one, it's a minute from now, doubled for each retry already made.

```ts
getGithubRateLimitDeadline(
  options: IGithubRateLimitDeadlineOptions,
): Date | null
```

**Parameters**

- `options` `IGithubRateLimitDeadlineOptions`: The response's status and headers, the retries made, and the time.

**Returns** `Date | null`: The time to retry at, or null.

**Throws**

- `GITHUB_INVALID_ARGUMENT`: An argument isn't valid.

**Example**

```ts
import { getGithubRateLimitDeadline } from 'jg-github';

declare const response: Response;

const deadline = getGithubRateLimitDeadline({
  status: response.status,
  headers: response.headers,
  retryCount: 0,
});
```

#### <a id="api-revokeInstallationToken"></a>`revokeInstallationToken`

*Function*

Revokes an installation token before it expires, such as when the work it was for is done, with `DELETE /installation/token`, which GitHub answers with 204. It never retries. The error never holds the token.

```ts
revokeInstallationToken(
  token: string,
  options: IGithubRequestOptions,
): Promise<void>
```

**Parameters**

- `token` `string`: The installation token.
- `options` `IGithubRequestOptions`: The User-Agent, the API's base URL and version, and the limits.

**Returns** `Promise<void>`: A promise that resolves once GitHub has revoked it.

**Throws**

- `GITHUB_INVALID_ARGUMENT`: An argument isn't valid.
- `GITHUB_TOKEN_REVOKE_FAILED`: The installation token couldn't be revoked.

**Example**

```ts
import { revokeInstallationToken } from 'jg-github';

declare const token: string;

await revokeInstallationToken(token, { userAgent: 'acme-deploy-bot' });
```

#### <a id="api-verifyGithubWebhookSignature"></a>`verifyGithubWebhookSignature`

*Function*

Verifies a GitHub webhook delivery's X-Hub-Signature-256 header against the body's exact bytes, in constant time. A header that's missing, repeated, longer than 71 characters, or not `sha256=` and 64 lowercase hexadecimal characters is false, like a wrong signature. Verify the raw body before parsing it, because parsing and serializing can change its bytes.

```ts
verifyGithubWebhookSignature(
  rawBody: string | Uint8Array<ArrayBufferLike>,
  header: unknown,
  secret: string | Uint8Array<ArrayBufferLike>,
): boolean
```

**Parameters**

- `rawBody` `string | Uint8Array<ArrayBufferLike>`: The request's body, as received.
- `header` `unknown`: The X-Hub-Signature-256 header, as the framework gives it.
- `secret` `string | Uint8Array<ArrayBufferLike>`: The webhook's secret.

**Returns** `boolean`: Whether the signature is the body's.

**Throws**

- `INVALID_HMAC_SECRET`: The HMAC secret must be a non-empty string or byte array.

**Example**

```ts
import { verifyGithubWebhookSignature } from 'jg-github';

declare const rawBody: Buffer;
declare const headers: Record<string, string | string[] | undefined>;
declare const webhookSecret: string;

if (!verifyGithubWebhookSignature(rawBody, headers['x-hub-signature-256'], webhookSecret)) {
  // answer 401
}
```

### <a id="api-constants"></a>Constants

#### <a id="api-DEFAULT_GITHUB_MAX_RESPONSE_BYTES"></a>`DEFAULT_GITHUB_MAX_RESPONSE_BYTES`

*Constant*

the bytes a response from GitHub may take when the options don't say (128 KiB)

```ts
const DEFAULT_GITHUB_MAX_RESPONSE_BYTES: 131072
```

#### <a id="api-DEFAULT_GITHUB_TIMEOUT_SECONDS"></a>`DEFAULT_GITHUB_TIMEOUT_SECONDS`

*Constant*

the seconds a request to GitHub may take when the options don't say

```ts
const DEFAULT_GITHUB_TIMEOUT_SECONDS: 10
```

#### <a id="api-ERRORS"></a>`ERRORS`

*Constant*

the codes for every error thrown by the package

```ts
const ERRORS: { GITHUB_PRIVATE_KEY_INVALID: "GITHUB_PRIVATE_KEY_INVALID"; GITHUB_INVALID_ARGUMENT: "GITHUB_INVALID_ARGUMENT"; GITHUB_REQUEST_FAILED: "GITHUB_REQUEST_FAILED"; GITHUB_RESPONSE_INVALID: "GITHUB_RESPONSE_INVALID"; GITHUB_TOKEN_SCOPE_MISMATCH: "GITHUB_TOKEN_SCOPE_MISMATCH"; GITHUB_TOKEN_EXPIRED: "GITHUB_TOKEN_EXPIRED"; GITHUB_TOKEN_REVOKE_FAILED: "GITHUB_TOKEN_REVOKE_FAILED" }
```

#### <a id="api-GITHUB_API_ORIGIN"></a>`GITHUB_API_ORIGIN`

*Constant*

the origin of GitHub's REST API on github.com

```ts
const GITHUB_API_ORIGIN: "https://api.github.com"
```

#### <a id="api-GITHUB_API_VERSION"></a>`GITHUB_API_VERSION`

*Constant*

the REST API version every request asks for, in the X-GitHub-Api-Version header

```ts
const GITHUB_API_VERSION: "2026-03-10"
```

#### <a id="api-GITHUB_RAW_CONTENT_ORIGIN"></a>`GITHUB_RAW_CONTENT_ORIGIN`

*Constant*

the origin GitHub serves a repository's raw files from

```ts
const GITHUB_RAW_CONTENT_ORIGIN: "https://raw.githubusercontent.com"
```

### <a id="api-types"></a>Types

#### <a id="api-ICreateGithubAppJwtOptions"></a>`ICreateGithubAppJwtOptions`

*Type*

what createGithubAppJwt takes

```ts
type ICreateGithubAppJwtOptions = {
    appId: string | number;
    privateKey: string;
    now?: Date | undefined;
};
```

**Members**

- `appId: string | number` (property): the App's ID, such as 123456, or its client ID
- `privateKey: string` (property): the App's private key, PEM-encoded, as GitHub downloads it
- `now: Date` (property): the time the JWT is issued at. Defaults to now

#### <a id="api-ICreateInstallationTokenOptions"></a>`ICreateInstallationTokenOptions`

*Type*

what createInstallationToken takes

```ts
type ICreateInstallationTokenOptions = IGithubRequestOptions & IInstallationTokenRepositories & {
    appId: string | number;
    privateKey: string;
    installationId: string | number;
    permissions: IGithubPermissions;
    maxResponseBytes?: number | undefined;
};
```

#### <a id="api-IGithubApiUrlOptions"></a>`IGithubApiUrlOptions`

*Type*

what buildGithubApiUrl takes

```ts
type IGithubApiUrlOptions = {
    apiOrigin?: string | undefined;
};
```

**Members**

- `apiOrigin: string` (property): the API's base URL, such as `https://ghe.example.com/api/v3` for GitHub Enterprise Server. Defaults to GITHUB_API_ORIGIN

#### <a id="api-IGithubHeadersOptions"></a>`IGithubHeadersOptions`

*Type*

what createGithubHeaders takes

```ts
type IGithubHeadersOptions = {
    userAgent: string;
    apiVersion?: string | undefined;
};
```

**Members**

- `userAgent: string` (property): the User-Agent GitHub requires on every request, such as the app's name
- `apiVersion: string` (property): the REST API version. Defaults to GITHUB_API_VERSION

#### <a id="api-IGithubPermissionLevel"></a>`IGithubPermissionLevel`

*Type*

the access a GitHub App permission grants

```ts
type IGithubPermissionLevel = 'read' | 'write' | 'admin';
```

#### <a id="api-IGithubPermissions"></a>`IGithubPermissions`

*Type*

the permissions of an installation token, by GitHub's names, such as { contents: 'read' }

```ts
type IGithubPermissions = Record<string, IGithubPermissionLevel>;
```

#### <a id="api-IGithubQuery"></a>`IGithubQuery`

*Type*

the query parameters a URL builder appends; undefined ones are left out

```ts
type IGithubQuery = Record<string, string | number | boolean | undefined>;
```

#### <a id="api-IGithubRateLimitDeadlineOptions"></a>`IGithubRateLimitDeadlineOptions`

*Type*

what getGithubRateLimitDeadline takes

```ts
type IGithubRateLimitDeadlineOptions = {
    status: number;
    headers: IGithubResponseHeaders;
    retryCount: number;
    hasRateLimitMessage?: boolean | undefined;
    now?: Date | undefined;
};
```

**Members**

- `status: number` (property): the response's HTTP status
- `headers: IGithubResponseHeaders` (property): the response's headers
- `retryCount: number` (property): the retries already made for this request, from 0, which doubles the fallback wait
- `hasRateLimitMessage: boolean` (property): whether the response's message says a rate limit was hit, which makes a bare 403 count. Defaults to false
- `now: Date` (property): the current time. Defaults to now

#### <a id="api-IGithubRawContentLocation"></a>`IGithubRawContentLocation`

*Type*

a file in a repository, at a ref

```ts
type IGithubRawContentLocation = {
    owner: string;
    repository: string;
    ref: string;
    path: string;
};
```

**Members**

- `owner: string` (property): the account that owns the repository
- `repository: string` (property): the repository's name
- `ref: string` (property): the branch, tag, or commit, such as `main` or `feature/login`
- `path: string` (property): the file's path from the repository's root, such as `docs/setup.md`

#### <a id="api-IGithubRawContentUrlOptions"></a>`IGithubRawContentUrlOptions`

*Type*

what buildGithubRawContentUrl takes

```ts
type IGithubRawContentUrlOptions = {
    rawContentOrigin?: string | undefined;
};
```

**Members**

- `rawContentOrigin: string` (property): the raw content's base URL. Defaults to GITHUB_RAW_CONTENT_ORIGIN

#### <a id="api-IGithubRepository"></a>`IGithubRepository`

*Type*

a repository an installation token can reach

```ts
type IGithubRepository = {
    id: number;
    fullName: string;
};
```

**Members**

- `id: number` (property): the repository's ID
- `fullName: string` (property): the repository's owner and name, such as 'acme/app'

#### <a id="api-IGithubRequestOptions"></a>`IGithubRequestOptions`

*Type*

what every request to GitHub's REST API takes

```ts
type IGithubRequestOptions = {
    userAgent: string;
    apiOrigin?: string | undefined;
    apiVersion?: string | undefined;
    timeoutSeconds?: number | undefined;
    signal?: AbortSignal | undefined;
};
```

**Members**

- `userAgent: string` (property): the User-Agent GitHub requires on every request, such as the app's name
- `apiOrigin: string` (property): the API's base URL, such as `https://ghe.example.com/api/v3` for GitHub Enterprise Server. Defaults to GITHUB_API_ORIGIN
- `apiVersion: string` (property): the REST API version. Defaults to GITHUB_API_VERSION
- `timeoutSeconds: number` (property): the seconds the request may take. Defaults to 10
- `signal: AbortSignal` (property): stops the request when it aborts

#### <a id="api-IGithubResponseHeaders"></a>`IGithubResponseHeaders`

*Type*

a response's headers: a Headers object, or a record with lowercase names, as Node.js's IncomingHttpHeaders has

```ts
type IGithubResponseHeaders = Headers | Readonly<Record<string, string | readonly string[] | undefined>>;
```

#### <a id="api-IInstallationToken"></a>`IInstallationToken`

*Type*

an installation token, scoped as requested

```ts
type IInstallationToken = {
    token: string;
    expiresAt: Date;
    permissions: Record<string, string>;
    repositories: IGithubRepository[];
};
```

**Members**

- `token: string` (property): the token, sent as a bearer credential
- `expiresAt: Date` (property): when it expires, an hour after it was created
- `permissions: Record<string, string>` (property): the permissions it grants: the ones requested, and `metadata: 'read'` when GitHub adds it
- `repositories: IGithubRepository[]` (property): the repositories it reaches, exactly the ones requested

#### <a id="api-IInstallationTokenRepositories"></a>`IInstallationTokenRepositories`

*Type*

the repositories an installation token is for: by name or by ID, never both

```ts
type IInstallationTokenRepositories = {
    repositories: readonly string[];
    repositoryIds?: undefined;
} | {
    repositoryIds: readonly number[];
    repositories?: undefined;
};
```
