---
title: "GitHub"
description: "Use github.com and GitHub Enterprise Server: issues, pull requests, discussions, notifications, Actions, checks, releases and webhooks."
canonical_url: "https://docs-oquac2tli-poetry.vercel.app/providers/github"
---
# GitHub

> Use github.com and GitHub Enterprise Server: issues, pull requests, discussions, notifications, Actions, checks, releases and webhooks.

The GitHub provider covers github.com and GitHub Enterprise Server. It reads and writes issues, pull requests, discussions and commit comments. It also covers notifications, Actions runs and jobs, checks, releases, security alerts, webhooks and GitHub App installations.

<table>
<thead>
  <tr>
    <th>
      Detail
    </th>
    
    <th>
      Value
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Import
    </td>
    
    <td>
      <code>
        forges/github
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Factories
    </td>
    
    <td>
      <code>
        github()
      </code>
      
      , <code>
        githubLite()
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Auth
    </td>
    
    <td>
      <code>
        token
      </code>
      
      , <code>
        app
      </code>
      
      , <code>
        anonymous
      </code>
    </td>
  </tr>
</tbody>
</table>

## Authentication

The provider accepts a personal access token (classic or fine-grained), an OAuth token or GitHub App credentials:

```ts
import { github } from 'forges/github'

const forge = github({
  auth: { type: 'token', token: process.env.GITHUB_TOKEN! },
}).create()

const app = github({
  auth: {
    type: 'app',
    appId: 123456,
    privateKey: process.env.GITHUB_APP_PRIVATE_KEY!,
    installationId: 7890,
  },
}).create()
```

For app auth, `privateKey` is the app's PEM key, in PKCS#1 or PKCS#8 format. With `installationId`, the provider mints and caches installation tokens as it needs them. Without `installationId`, the provider authenticates as the app itself. In that case, `installations.list()` lists the app's installations, and `installations.provider(installation)` returns a provider for one installation.

Without `auth`, the provider makes anonymous public reads.

## GitHub Enterprise Server

Set `baseUrl` to the API root of the server. The `instance` in every ref is the server's host:

```ts
github({
  baseUrl: 'https://ghe.example.com/api/v3',
  auth,
  instanceVersion: '3.14.0',
})
```

Two capabilities depend on the server version:

- Marking notifications done requires 3.13 or later.
- Dependabot alerts require 3.8 or later.

Pass `instanceVersion` if you know the version. Otherwise, `refreshCapabilities()` reads it from `/meta`.

## Merging

If you don't pass `method`, `merge()` reads the repository's allowed merge methods. When exactly one method is allowed, it uses that method. When several are allowed, it throws `MergeMethodRequiredError`.

`merge()` and `approveAndMerge()` request a direct merge through GitHub's asynchronous merge API, so neither adds the pull request to a merge queue. Both wait for the result, within the provider's `timeout` (30 seconds by default), and resolve once GitHub reports the pull request merged, including when it was already merged. Otherwise, they reject with one of these errors:

- `MergeBlockedError` when GitHub refuses or fails the merge, for example for a draft, a failing required check or a pull request already in a merge queue. When GitHub reports a failed merge, the error message is GitHub's description of the failure.
- `MergeConflictError` when GitHub responds with a conflict status that names no pending merge request.
- `ForgeTimeoutError` when the merge is still pending after `timeout`. The message includes the merge request's UUID. GitHub can still complete the merge after this error, so read the pull request's state before you retry.

If a direct merge with the same method is already pending, and it expects the same head sha when you pass `sha`, the operation waits for that request instead. A pending request with different options rejects with `MergeBlockedError`. Supplying `message` also prevents adopting a pending request because GitHub doesn't return its commit message.

When the pull request is part of a stack, GitHub also merges every open pull request below it in the stack. `approveAndMerge()` approves only the pull request you pass.

GitHub Enterprise Server releases without the asynchronous merge API use the synchronous merge endpoint instead. That endpoint doesn't support stacked pull requests.

These options reject with `UnsupportedOperationError`:

- `whenChecksPass`, because the REST API doesn't enable auto-merge.
- The `rebase_merge` and `fast_forward_only` methods, which GitHub doesn't have.

## Checks

With an app installation credential, `checks.report()` writes a check run. With any other credential, it writes a commit status. `checks.rerun()` re-requests a check run. Commit statuses can't be re-run.

## Large files and trees

`contents.file()` reads files over 1 MB through the Git blobs API, so these files have `encoding: 'none'`. When GitHub truncates a large tree, `contents.tree()` adds a `tree_truncated` warning.

## Search

GitHub gives search a lower rate limit than the rest of the API. Commit search has its own limit, separate from issue and repository search. After a search, `page.rateLimit` reports the limit that the search used.

Repository search can't sort by creation time. A request for that sort order returns results by relevance, with a `sort_unsupported` warning.

## Webhook management

GitHub responds with `404` on its webhook endpoints when the credential lacks `admin:repo_hook` or `admin:org_hook`. The provider raises this response as `ForbiddenError` with `reason: 'resource_protected'`.

`webhooks.deliveries()` reads a hook's delivery log, and `webhooks.redeliver()` sends a delivery again.

## Webhooks

Set `webhookSecret` to the secret configured on the hook:

```ts
const forge = github({
  webhookSecret: process.env.GITHUB_WEBHOOK_SECRET,
}).create()

const events = await forge.webhooks.ingest({
  headers: request.headers,
  body: await request.text(),
})
```

GitHub sends these headers with each delivery:

<table>
<thead>
  <tr>
    <th>
      Header
    </th>
    
    <th>
      Content
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        X-Hub-Signature-256
      </code>
    </td>
    
    <td>
      <code>
        sha256=
      </code>
      
       followed by the hex HMAC-SHA256 of the body
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        X-GitHub-Event
      </code>
    </td>
    
    <td>
      The event name
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        X-GitHub-Delivery
      </code>
    </td>
    
    <td>
      The delivery ID
    </td>
  </tr>
</tbody>
</table>

`installation` and `installation_repositories` deliveries become `installation` events.

## Recording fixtures

```sh
GITHUB_TOKEN=ghp_... pnpm record-fixtures github
```

To record different targets, set `FIXTURE_GITHUB_REPO`, `FIXTURE_GITHUB_PULL`, `FIXTURE_GITHUB_ISSUE`, `FIXTURE_GITHUB_DISCUSSION_REPO` or `FIXTURE_GITHUB_DISCUSSION`. To record a GitHub Enterprise Server instance, set `GITHUB_BASE_URL`.

## Capabilities

Generated by `pnpm capability-matrix`; do not edit by hand.

<table>
<thead>
  <tr>
    <th>
      Capability
    </th>
    
    <th>
      Support
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        experimental
      </code>
    </td>
    
    <td>
      ❌
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sources.poll
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sources.webhook
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sources.subscribe
      </code>
    </td>
    
    <td>
      ❌
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        repos.get
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        users.get
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        repos.list
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        repos.labels
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        repos.createLabel
      </code>
    </td>
    
    <td>
      experimental
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        repos.milestones
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        repos.collaborators
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        repos.permissionFor
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        repos.addCollaborator
      </code>
    </td>
    
    <td>
      experimental
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        repos.assignableUsers
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        repos.reviewerCandidates
      </code>
    </td>
    
    <td>
      emulated
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        threads.get
      </code>
    </td>
    
    <td>
      issue, PR, discussion, commit (experimental)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        threads.list
      </code>
    </td>
    
    <td>
      issue, PR, discussion
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        threads.getMany
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        comments.list
      </code>
    </td>
    
    <td>
      issue, PR, discussion, commit (experimental)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        comments.edit
      </code>
    </td>
    
    <td>
      issue (experimental), PR, discussion (experimental), commit (experimental)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        comments.delete
      </code>
    </td>
    
    <td>
      issue (experimental), PR, discussion (experimental), commit (experimental)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reactions.list
      </code>
    </td>
    
    <td>
      issue, PR, discussion
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        notifications.list
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        notifications.markRead
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        notifications.markDone
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        notifications.unsubscribe
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        notifications.markAllRead
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        notifications.markAllDone
      </code>
    </td>
    
    <td>
      ❌
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        notifications.unreadCount
      </code>
    </td>
    
    <td>
      ❌
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        writes.comment
      </code>
    </td>
    
    <td>
      issue (experimental), PR, discussion, commit (experimental)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        writes.upsertComment
      </code>
    </td>
    
    <td>
      issue (emulated), PR (emulated), discussion (emulated), commit (emulated)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        writes.close
      </code>
    </td>
    
    <td>
      issue, PR, discussion
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        writes.reopen
      </code>
    </td>
    
    <td>
      issue (experimental), PR, discussion
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        writes.create
      </code>
    </td>
    
    <td>
      issue, PR (experimental)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        writes.update
      </code>
    </td>
    
    <td>
      issue (experimental), PR, discussion (experimental)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        writes.setLabels
      </code>
    </td>
    
    <td>
      issue (experimental), PR
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        writes.addLabels
      </code>
    </td>
    
    <td>
      issue (experimental), PR
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        writes.removeLabels
      </code>
    </td>
    
    <td>
      issue (experimental), PR
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        writes.setMilestone
      </code>
    </td>
    
    <td>
      issue (experimental), PR (experimental)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        writes.react
      </code>
    </td>
    
    <td>
      issue (experimental), PR, discussion (experimental)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        writes.setAssignees
      </code>
    </td>
    
    <td>
      issue (experimental), PR
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        writes.requestReview
      </code>
    </td>
    
    <td>
      PR
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        writes.merge
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        writes.approveAndMerge
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        writes.transfer
      </code>
    </td>
    
    <td>
      experimental
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        writes.markDuplicate
      </code>
    </td>
    
    <td>
      experimental
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        subscriptions.get
      </code>
    </td>
    
    <td>
      issue, PR, discussion
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        subscriptions.set
      </code>
    </td>
    
    <td>
      issue, PR, discussion
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        installations
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        checks.thread
      </code>
    </td>
    
    <td>
      PR
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        checks.list
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        checks.report
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        checks.rerun
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ci.runs
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ci.run
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ci.jobs
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ci.log
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contents.file
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contents.tree
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contents.branches
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contents.tags
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contents.resolveRef
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contents.commits
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contents.commit
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contents.compare
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contents.threadFiles
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contents.threadCommits
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reviews.list
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reviews.create
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reviews.submit
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reviews.approve
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reviews.resolveThread
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        releases.list
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        releases.get
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        releases.latest
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        releases.getByTag
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        releases.downloadAsset
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webhooks.list
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webhooks.create
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webhooks.update
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webhooks.delete
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webhooks.rotateSecret
      </code>
    </td>
    
    <td>
      experimental
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webhooks.deliveries
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webhooks.redeliver
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        search.threads
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        search.repos
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        search.commits
      </code>
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        securityAlerts
      </code>
    </td>
    
    <td>
      dependency (experimental), code scanning (experimental), secret (experimental)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        eventKinds
      </code>
    </td>
    
    <td>
      native
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        auth
      </code>
    </td>
    
    <td>
      <code>
        token
      </code>
      
      , <code>
        app
      </code>
      
      , <code>
        anonymous
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        limits
      </code>
    </td>
    
    <td>
      body 65536, comment 65536, label 50
    </td>
  </tr>
</tbody>
</table>


## Sitemap

See the full [sitemap](https://docs-oquac2tli-poetry.vercel.app/sitemap.md) for all pages.