---
name: bijection-convex-github
description: "Evaluate and integrate the Convex GitHub component with Bijection."
---

# Convex GitHub

Sync GitHub issues and pull requests into Convex reactively. Open, comment on, and merge them directly from Convex functions.

This is an upstream package. It has not been adapted or qualified for Bijection.

- Package: convex-github
- Source: https://github.com/sholajegede/convex-github
- npm: https://www.npmjs.com/package/convex-github
- Directory: https://bijection.com/components/convex-github

Read the upstream README for setup, license, and compatibility before using it.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes convex-github. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Convex GitHub. Follow the installation and configuration steps exactly.

# Convex GitHub

## Instructions

convex-github maintains a live, queryable mirror of GitHub issues and pull requests inside an isolated Convex component schema, kept current via verified GitHub webhooks. It exposes actions for creating issues, posting comments, closing issues, and merging pull requests through the GitHub REST API, with changes written to Convex immediately rather than waiting for webhook round-trips. Webhook deliveries are deduplicated by X-GitHub-Delivery ID and verified via HMAC-SHA256, making retries safe.

### Installation

```bash
npm install convex-github
```

Current npm version: `convex-github@0.0.6`

## Use cases

- Building an internal developer dashboard that surfaces open issues and PRs reactively in a React UI without polling GitHub's API
- Automating issue triage or PR merges from Convex mutations triggered by your own application logic, such as closing a bug report when a user marks a problem resolved
- Auditing webhook delivery history for a repo by querying the stored webhookEvents table from within Convex functions
- Syncing GitHub project state into a Convex-backed app so useQuery re-renders immediately when issues are labeled, assigned, or closed on GitHub
- Bootstrapping a lightweight GitHub integration without standing up a separate webhook server or managing your own database schema for issues and PRs

## How it works

After installing the package, you register the component in convex/convex.config.ts with app.use(convexGithub), then instantiate a GitHub client with your token and webhook secret. The client exposes a webhookHandler httpAction that you mount on any HTTP route in convex/http.ts. GitHub delivers issues and pull_request events to that endpoint, which verifies the X-Hub-Signature-256 header, deduplicates by X-GitHub-Delivery, and upserts the current issue or PR state into the component's isolated tables.

The component schema includes three tables: issues, pullRequests, and webhookEvents. These live entirely within the component's own namespace and never appear in your app's convex/schema.ts. Issues are keyed by GitHub's globally unique numeric id (as a string) rather than by number, which remains stable across repo renames and transfers.

For write operations, the GitHub class provides actions: createIssue, createIssueComment, closeIssue, and mergePullRequest. These call the GitHub REST API and immediately patch the corresponding Convex record without waiting for the next webhook delivery. mergePullRequest accepts an optional mergeMethod parameter supporting merge, squash, or rebase strategies.

Read operations include listIssuesByRepo, listPullRequestsByRepo, getIssue, getPullRequest, and cross-repo helpers like listRecentIssues. These work from Convex queries, mutations, or actions and can be called directly from useQuery in a React component to get reactive updates whenever GitHub sends a webhook event.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Convex GitHub is not needed

## Resources

- [npm package](https://www.npmjs.com/package/convex-github)
- [GitHub repository](https://github.com/sholajegede/convex-github)
- [Live demo](https://convex-github.vercel.app)
- [Convex Components Directory](https://www.convex.dev/components/convex-github)
- [Convex documentation](https://docs.convex.dev)