Skip to main content
The GitHub integration allows you to sync repositories, automatically create bounties from issues, and manage submissions via pull requests.

​
Overview

Bounty integrates with GitHub through both a GitHub App (for repository access and issue management) and GitHub OAuth (for user authentication).

​
Features

  • Sync GitHub repositories to your organization
  • Create bounties directly from GitHub issues
  • Automatic bot comments on issues when bounties are created or funded
  • Track pull request submissions
  • Multi-installation support for different organizations

​
GitHub App Setup

The GitHub App provides repository-level access for issue integration and bot functionality.
1

Create a GitHub App

Navigate to GitHub Developer Settings and click New GitHub App.Configure the following settings:
  • App name: Choose a unique name (e.g., bounty-your-org)
  • Homepage URL: Your Bounty instance URL
  • Webhook URL: https://your-domain.com/api/webhooks/github
  • Webhook secret: Generate with openssl rand -base64 32
2

Configure Permissions

Set the following repository permissions:
  • Issues: Read & Write (create comments, read issues)
  • Pull requests: Read & Write (track submissions)
  • Metadata: Read-only (access repository info)
3

Subscribe to Webhook Events

Enable the following webhook events:
  • Issues
  • Pull requests
  • Installation
4

Generate Private Key

After creating the app:
  1. Scroll to Private keys section
  2. Click Generate a private key
  3. Download the .pem file
  4. Encode it to base64:
cat private-key.pem | base64
5

Set Environment Variables

Add the following to your .env file:
# GitHub App Configuration
GITHUB_APP_NAME="your_github_app_name"  # App slug from URL
GITHUB_APP_ID="123456"                  # Numeric App ID
GITHUB_APP_CLIENT_ID="Iv1.abc123"       # OAuth Client ID
GITHUB_APP_PRIVATE_KEY="base64_encoded_key"  # Base64-encoded .pem
GITHUB_WEBHOOK_SECRET="your_webhook_secret"
The GITHUB_APP_NAME is the app slug visible in the GitHub App URL: github.com/apps/your-app-name

​
GitHub OAuth Setup

GitHub OAuth enables users to sign in and connect their GitHub accounts.
1

Create OAuth App

Go to GitHub OAuth Apps and click New OAuth App.Configure:
  • Application name: Your app name
  • Homepage URL: https://your-domain.com
  • Authorization callback URL: https://your-domain.com/api/auth/callback/github
2

Get Credentials

After creating the app, note your Client ID and generate a Client Secret.
3

Add to Environment

# GitHub OAuth
GITHUB_CLIENT_ID="your_oauth_client_id"
GITHUB_CLIENT_SECRET="your_oauth_client_secret"
GITHUB_TOKEN="ghp_optional_pat"  # Optional: Personal access token

​
Installing the GitHub App

Once configured, users can install the GitHub App to their repositories:
1

Navigate to Integrations

In your Bounty organization settings, go to the GitHub integration page.
2

Click Install GitHub App

The system will redirect you to GitHub’s installation flow.
3

Select Repositories

Choose which repositories to grant access to:
  • All repositories (current and future)
  • Specific repositories only
4

Sync Installation

After installation, Bounty automatically syncs:
  • Repository metadata
  • Available issues
  • Installation status

​
Repository Management

​
Viewing Installations

API endpoint: githubInstallation.getInstallations Returns all GitHub App installations for your organization: 
const { installations } = await trpc.githubInstallation.getInstallations.query();

// Each installation includes:
// - id: Installation ID
// - accountLogin: GitHub org/user name
// - accountType: 'Organization' or 'User'
// - repositoryIds: Array of repo IDs
// - isDefault: Whether this is the default installation

​
Fetching Repositories

API endpoint: githubInstallation.getRepositories Get all repositories for a specific installation: 
const { repositories } = await trpc.githubInstallation.getRepositories.query({
  installationId: 12345678,
});

// Returns: name, fullName, private, htmlUrl, description

​
Setting Default Installation

For organizations with multiple installations, set a default: 
await trpc.githubInstallation.setDefaultInstallation.mutate({
  installationId: 12345678,
});
Only organization owners can set the default installation or remove installations.

​
Issue Integration

When you create a bounty linked to a GitHub issue, Bounty automatically:
  1. Posts a bot comment on the issue with bounty details
  2. Updates the comment when the bounty is funded
  3. Tracks PR submissions when contributors open pull requests
  4. Updates submission comments when payment status changes

​
Bot Comment Example

When a bounty is created: 
🎯 Bounty Posted: $500 USD

This issue has a bounty! Submit your solution to earn the reward.

View bounty: https://bounty.new/bounty/abc123
After funding: 
✅ Bounty Funded: $500 USD

This bounty is now funded and ready for submissions!

💰 Submit your solution: https://bounty.new/bounty/abc123

​
Webhook Handling

Bounty listens for GitHub webhook events to sync installations and issues.

​
Supported Events

  • installation.created - New app installation
  • installation.deleted - App uninstalled
  • installation_repositories.added - Repos added to installation
  • installation_repositories.removed - Repos removed
  • issues.opened - New issue created
  • pull_request.opened - New PR submission

​
Webhook Security

Webhooks are verified using the GITHUB_WEBHOOK_SECRET: 
import { verify } from '@octokit/webhooks-methods';

const signature = request.headers['x-hub-signature-256'];
const isValid = await verify(
  process.env.GITHUB_WEBHOOK_SECRET,
  payload,
  signature
);
Always verify webhook signatures to prevent unauthorized requests.

​
Removing an Installation

To disconnect a GitHub installation: 
await trpc.githubInstallation.removeInstallation.mutate({
  installationId: 12345678,
});
This will:
  1. Revoke the app’s access on GitHub
  2. Delete the installation record from the database
  3. Remove associated bounty links (bounties remain, but lose GitHub integration)
Only organization owners can remove installations.

​
Troubleshooting

​
Installation Not Showing

  • Verify the GitHub App is installed on the correct organization
  • Check that GITHUB_APP_ID matches your GitHub App
  • Ensure the user has connected their GitHub OAuth account

​
Bot Comments Not Appearing

  • Confirm the app has Issues: Read & Write permission
  • Check webhook delivery in GitHub App settings
  • Verify GITHUB_WEBHOOK_SECRET matches GitHub configuration

​
Private Key Errors

Failed to parse private key: Invalid PEM format
Solution: Ensure your private key is base64-encoded: 
cat downloaded-private-key.pem | base64 | tr -d '\n'
Then set the entire base64 string as GITHUB_APP_PRIVATE_KEY.

​
API Reference

​
getInstallations

Get all installations for the active organization. Returns: Array of installations with metadata

​
getRepositories

Input: { installationId: number } Returns: Array of repositories with name, URL, and description

​
syncInstallation

Input: { installationId: number } Manually sync an installation after adding new repositories.

​
removeInstallation

Input: { installationId: number } Uninstalls the GitHub App and removes the installation record. Requires: Organization owner role

​
setDefaultInstallation

Input: { installationId: number } Sets the default installation for creating new bounties. Requires: Organization owner role

Build docs developers (and LLMs) love

Get started for freeTalk to us