GitHub Integration

Automatically create GitHub issues from bug reports submitted through BugPin.

Overview

When enabled, BugPin can forward bug reports to GitHub as issues. This allows your development team to track and manage bugs directly in their existing workflow.

Features:

• Automatically create GitHub issues from bug reports
• Include screenshots and metadata in issue body
• Sync issue status back to BugPin
• Support for labels and assignees
• Works with personal and organization repositories

Setup

1. Create a GitHub Token

You need a GitHub personal access token to authorize BugPin to create issues on your behalf.

Token Location

Tokens are created from your personal GitHub account under: Settings → Developer settings → Personal access tokens

Option 1: Classic Token (Recommended)

Classic tokens are simpler to set up and work well for most use cases.

1. Go to GitHub Tokens (classic) and click "Generate new token (classic)"

2. Note: Enter a descriptive name (e.g., "BugPin Integration")

3. Expiration: Choose an expiration period or "No expiration" for permanent access

4. Select scopes: Check the repo checkbox. This grants:

   • Full control of private repositories
   • Access to commit status, deployments, and invitations
   • Read and write security events
   tip

   If you only need access to public repositories, you can select just public_repo instead.

5. Click "Generate token" at the bottom

6. Copy the token immediately - you won't be able to see it again!

Classic tokens start with ghp_

Option 2: Fine-grained Token

Fine-grained tokens offer more precise control over permissions but require more setup.

1. Go to Fine-grained tokens and click "Generate new token"

2. Enter a token name (e.g., "BugPin Integration")

3. Set an expiration date

4. Under "Repository access", select "All repositories" to allow BugPin to list and access your repos

5. Under "Permissions" → "Repository permissions", set:

   Permission	Access Level	Purpose
   Metadata	Read	Required to list repositories, load labels, and assignees
   Issues	Read and write	Required to create and update issues

   warning

   Read-only is NOT sufficient for Issues - BugPin needs write access to create and sync issues.

6. Click "Generate token"

7. Copy the token immediately - you won't be able to see it again!

Fine-grained tokens start with github_pat_

2. Add Token to BugPin

There are two ways to configure the GitHub token:

Server-wide (Environment Variable)

Add the token to your .env file:

GITHUB_TOKEN=ghp_your_token_here
APP_URL=https://bugs.yourdomain.com

This token will be available for all projects.

Per-project (Admin Panel)

1. Go to Projects in the admin panel
2. Select your project
3. Navigate to Integrations → GitHub
4. Enter your GitHub token
5. Select the repository to forward issues to
6. Configure labels and default assignee (optional)

3. Configure Repository

In the project settings, select which repository should receive the issues:

1. After entering your token, click "Load Repositories"
2. Select the target repository from the dropdown
3. Optionally configure:
   • Default labels to apply to all issues
   • Default assignee for new issues

Required Permissions

Quick Reference

Feature	Classic Token	Fine-grained Token
List repositories	repo	Metadata: Read
Create issues	repo	Issues: Read and write
Update issues (sync)	repo	Issues: Read and write
Load labels	repo	Metadata: Read
Load assignees	repo	Metadata: Read

note

For fine-grained tokens, read-only permissions are not sufficient. BugPin requires write access to create and update issues.

Organization Repositories

To access organization repositories:

For Classic Tokens

1. Go to your token settings on GitHub
2. Click "Configure SSO" if available
3. Authorize the token for your organization

For Fine-grained Tokens

1. When creating the token, set "Resource owner" to the organization
2. Your organization admin may need to enable fine-grained token access under: Organization Settings → Personal access tokens

Troubleshooting

"Resource not accessible by personal access token"

Classic token: Ensure the repo scope is checked.

Fine-grained token: Enable Issues: Read and write permission (read-only is not sufficient).

Cannot create or update issues

BugPin requires Issues: Read and write permission to create and sync issues. Read-only permissions are not sufficient. Classic tokens with repo scope include write access automatically.

Not all repositories showing

Fine-grained tokens require Metadata: Read permission to list repos. Classic tokens with repo scope include this automatically.

Cannot access organization repositories

1. Go to your token settings and click "Configure SSO" if available
2. Authorize the token for your organization
3. For fine-grained tokens, ensure "Resource owner" is set to the organization

Token expired

Generate a new token. Consider using "No expiration" for classic tokens if you don't want to rotate tokens regularly.

Unable to load labels/assignees

Fine-grained tokens need Metadata: Read permission. Classic tokens with repo scope work automatically.

Issue Format

When BugPin creates a GitHub issue, it includes:

• Title: The bug report title
• Body:
  • Description from the reporter
  • Screenshot (embedded as image)
  • Browser and device information
  • Page URL where the bug was reported
  • Console errors (if captured)
• Labels: Any configured default labels
• Assignee: Default assignee if configured

Two-way Sync

BugPin can sync issue status changes from GitHub back to BugPin:

• When an issue is closed in GitHub, the report status updates in BugPin
• When an issue is reopened, the report status reflects this change

This requires setting up a GitHub webhook (configured automatically when you enable the integration).