> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bounty.new/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub integration

> Create bounties from issues and pull requests

## Overview

The GitHub integration connects your repositories to bounty.new, allowing you to turn issues into bounties and automatically reward contributors when PRs are merged.

## Prerequisites

* A bounty.new account
* Admin access to your GitHub repository

## Installation

<Steps>
  <Step title="Install the GitHub app">
    Navigate to your organization's integrations page at `bounty.new/[slug]/integrations/github/[integration-id]` and click **Install GitHub App**.
  </Step>

  <Step title="Select repositories">
    Choose which repositories you want to connect to bounty.new.
  </Step>

  <Step title="Configure settings">
    Set default bounty amounts and approval rules in your dashboard.
  </Step>
</Steps>

## Creating bounties from issues

### Via bot command

Comment on any issue with:

```
@bountydotnew 100
```

Or specify currency explicitly:

```
@bountydotnew 500 USD
```

**Requirements:**

* Only repo collaborators with write access can create bounties
* Creates an unfunded bounty linked to the issue
* Bot replies with a link to complete payment on bounty.new
* Bounty activates once payment is completed

### Via dashboard

Create a bounty in your dashboard:

1. Select a repository from your GitHub App installation
2. Fill out the form with title, description, amount, deadline, and tags
3. Complete payment via Stripe Checkout
4. Bot posts a comment on the linked GitHub issue announcing the bounty

## Automatic payouts

When a PR that closes a bounty issue is merged:

1. The bounty.new bot detects the merge
2. Verifies the PR author
3. Processes the payout automatically
4. Comments on the issue with confirmation

<Tip>Use "Closes #123" or "Fixes #123" in your PR description to link it to the bounty issue.</Tip>

## Bot commands reference

| Command                    | Description                                | Who can use                       |
| -------------------------- | ------------------------------------------ | --------------------------------- |
| `@bountydotnew 100`        | Create \$100 bounty on issue               | Repo collaborators (write access) |
| `@bountydotnew 500 USD`    | Create \$500 bounty with explicit currency | Repo collaborators (write access) |
| `/submit 123`              | Submit PR #123 as solution                 | PR author or maintainers          |
| `@bountydotnew submit 123` | Submit PR #123 as solution                 | PR author or maintainers          |
| `/unsubmit 123`            | Remove submission for PR #123              | Submitter or bounty creator       |
| `/approve 123`             | Approve submission PR #123, trigger payout | Bounty creator only               |
| `/unapprove 123`           | Revoke approval for PR #123                | Bounty creator only               |
| `/reapprove 123`           | Switch winner to different PR              | Bounty creator only               |
| `/merge 123`               | Confirm merge and trigger payout           | Bounty creator only               |
| `@bountydotnew move 456`   | Move bounty to different issue             | Bounty creator only               |

<Note>
  All `/slash` commands also work with `@bountydotnew` prefix. PR numbers can optionally include `#` (e.g., `/submit #123` or `/submit 123`).
</Note>

## Bounty status tracking

The bot updates issue comments with bounty status:

* **Open**: Bounty is funded and accepting submissions
* **Completed**: Submission approved and payout processed
* **Cancelled**: Bounty cancelled and refunded

## Connecting GitHub

### Installation flow

1. Navigate to **Settings > Integrations** on bounty.new
2. Click **Connect GitHub**
3. Select which repositories to grant access
4. GitHub redirects back to bounty.new
5. Your installation is now active

### Managing installations

* **Sync repos**: Fetch latest repository list from GitHub
* **Modify access**: Redirects to GitHub's installation settings page
* **Remove**: Remove via GitHub settings (we receive a webhook notification)

## Submission workflow

### For contributors (submitting PRs)

<Steps>
  <Step title="Open a PR">
    Create a pull request that references the bounty issue (e.g., `Fixes #123` in PR description).
  </Step>

  <Step title="Submit your PR">
    Submit using one of these methods:

    **Option 1**: Add `@bountydotnew submit` to your PR description

    **Option 2**: Comment on the bounty issue:

    ```
    /submit 123
    ```

    Where `123` is your PR number.
  </Step>

  <Step title="Confirmation">
    The bot posts "Submission Received" comments on both the issue and the PR.
  </Step>

  <Step title="Wait for approval">
    The bounty creator will review your submission.
  </Step>
</Steps>

**Requirements:**

* PR must exist and be open
* Bounty must be funded
* Bounty must be accepting submissions (no approved submission yet)
* PR authors can submit their own PRs; maintainers can submit on behalf of others

### Removing a submission

```
/unsubmit 123
```

Only the submitter or bounty creator can remove submissions.

### For bounty creators (approving & paying)

<Steps>
  <Step title="Review the PR">
    Test the submitted pull request thoroughly.
  </Step>

  <Step title="Approve the submission">
    Comment on the bounty issue:

    ```
    /approve 123
    ```

    Where `123` is the PR number. The bot posts "Submission Approved" on both the issue and PR.
  </Step>

  <Step title="Merge the PR">
    Merge the pull request in GitHub.
  </Step>

  <Step title="Confirm merge">
    Comment on the bounty issue:

    ```
    /merge 123
    ```

    This triggers the Stripe payout to the solver.
  </Step>
</Steps>

**Requirements:**

* Only the bounty creator can approve
* Solver must have connected their Stripe account for payout

**What happens:**

* Submission status changes to approved
* All other pending submissions are rejected
* After `/merge`, payout is initiated to solver's Stripe Connected Account
* Bot posts confirmation comments with payout details on both issue and PR

<Warning>
  If the solver hasn't connected Stripe, the bot will reply with instructions to visit [https://bounty.new/settings/payments](https://bounty.new/settings/payments).
</Warning>

### Managing approvals

Revoke an approval:

```
/unapprove 123
```

Switch winner to a different PR:

```
/reapprove 123
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Bounty not created from issue">
    Ensure you have write access to the repository and the GitHub app is installed with proper permissions.
  </Accordion>

  <Accordion title="Cannot approve submission">
    Verify the solver has connected their Stripe account at [https://bounty.new/settings/payments](https://bounty.new/settings/payments).
  </Accordion>

  <Accordion title="Bot not responding to commands">
    Check that the bounty.new GitHub app has read/write access to issues and pull requests.
  </Accordion>
</AccordionGroup>