GitHub Integration

BugPin's GitHub integration automatically creates GitHub Issues from bug reports submitted through the widget. Each issue includes the report description, screenshot, browser and device metadata, page URL, and captured console errors. The integration supports both on-demand manual forwarding and automatic two-way sync via webhooks, so closing a GitHub issue also updates the report status in 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	List repositories, load labels, and assignees
   Issues	Read and write	Create and update issues
   Contents	Read and write	Upload files to GitHub (only needed if enabled)

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

Configure the GitHub token per project in the Admin Console:

1. Go to Projects in the admin panel
2. Select your project
3. Navigate to Integrations → GitHub
4. Enter a integration name and your GitHub token
5. Select the repository to forward issues to

3. Configure Repository

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

1. After entering your token, click the "Load" icon
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
Upload files to repo	repo	Contents: Read and write
Load labels	repo	Metadata: Read
Load assignees	repo	Metadata: Read

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

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

Sync Modes

BugPin supports two sync modes for GitHub integrations:

Manual Sync

• Reports are synced to GitHub only when you explicitly trigger it
• Use the "Sync Existing Reports" button to sync pending reports
• No webhooks required
• Works with any deployment (including localhost)

Automatic Sync (Two-way)

• New reports are automatically synced to GitHub when created
• Issue status changes in GitHub sync back to BugPin:
  • When an issue is closed in GitHub → report status updates to "Resolved" in BugPin
  • When an issue is reopened → report status updates to "Open" in BugPin
• Requires a publicly accessible URL
• BugPin automatically creates a GitHub webhook when you enable automatic sync

Webhook Requirements

Public URL Required

Automatic sync (two-way) requires your BugPin instance to be accessible from the internet. localhost URLs will NOT work because GitHub needs to send webhook events to your server.

Why Webhooks Need Public URLs

When you enable automatic sync, BugPin registers a webhook with GitHub. GitHub then sends HTTP POST requests to your BugPin server when issue events occur (closed, reopened, etc.). For this to work:

• Your BugPin instance must have a public domain or IP address
• http://localhost:7300 will NOT work (GitHub can't reach your local machine)
• Private network IPs (192.168.x.x, 10.x.x.x) will NOT work

Deployment Options

Production Deployment (Recommended)

Deploy BugPin to a server with a public domain and set the Application URL in Settings → System.

Enabling Automatic Sync

1. Navigate to Projects → Select your project → Integrations
2. Click on your GitHub integration
3. Toggle Automatic sync to ON
4. BugPin will automatically:
   • Create a webhook on GitHub with the configured Application URL
   • Generate a webhook secret for secure communication
   • Store the webhook ID in the integration config

Verifying Webhook Creation

To verify the webhook was created successfully:

1. Go to your GitHub repository
2. Navigate to Settings → Webhooks
3. You should see a webhook with URL: https://your-domain.com/api/webhooks/github/int_...
4. Click on the webhook to view recent deliveries and check for errors

If No Webhook Appears

If you don't see the webhook:

1. Check the BugPin server logs for errors
2. Verify your Application URL is publicly accessible
3. Ensure your GitHub token has the correct permissions (repo scope or Issues: Read and write)
4. Try disabling and re-enabling automatic sync

Webhook Security

BugPin automatically:

• Generates a unique secret for each webhook
• Validates GitHub's signature on incoming webhook requests
• Rejects requests with invalid signatures

You don't need to manually configure webhook secrets.

Manual vs Automatic Sync Comparison

Feature	Manual Sync	Automatic Sync
Reports → GitHub	On-demand (button click)	Automatic (on report creation)
GitHub → Reports	Not supported	Automatic status updates
Webhook Required	No	Yes
Public URL Required	No	Yes
Works on localhost	Yes	No
Best for	Local development, testing	Production deployments

Frequently Asked Questions

Why am I getting "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).

Why can't I 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.

Why aren't all my repositories showing?

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

How do I 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

What should I do when my token expires?

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

Why are file uploads to GitHub failing?

If "Upload files to GitHub" is enabled but files show as "GitHub upload failed" in the issue body, your token is missing the Contents: Read and write permission. Classic tokens with repo scope include this automatically. For fine-grained tokens, add the Contents: Read and write permission.

Why can't I load labels or assignees?

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

Why aren't issues syncing back from GitHub?

If closing issues in GitHub doesn't update BugPin report status:

1. Check webhook exists: Go to GitHub repository → Settings → Webhooks
2. Verify webhook deliveries: Click on the webhook and check "Recent Deliveries" for errors
3. Common causes:
   • Application URL is set to localhost or private IP
   • BugPin server is not publicly accessible
   • Firewall blocking incoming webhook requests
   • Webhook was never created (check integration config)
4. Solution: Deploy BugPin to a public server or use ngrok for testing

Why is the webhook showing delivery failures in GitHub?

1. Check Application URL: Ensure it's publicly accessible (not localhost)
2. Test accessibility: Try accessing https://your-domain.com/api/webhooks/github/test from an external network
3. Check server logs: Look for webhook-related errors
4. Verify SSL: If using HTTPS, ensure your SSL certificate is valid