External Tool Integration

Connect BetaHub with your project management and development tools for streamlined workflows.

Overview

BetaHub integrates with popular project and task management tools to bridge the gap between bug reporting and development workflows. Send entries from BetaHub directly to your preferred project management system.

Supported Platforms

Project Management Tools

• Jira Cloud - Atlassian’s cloud-hosted issue tracking and project management
• Jira Server - Self-hosted Atlassian Jira (on-premise deployments)
• Asana - Team collaboration and task management
• Monday.com - Work operating system and project tracking
• Notion - All-in-one workspace with databases
• ClickUp - Project management and productivity platform
• Fibery - Work management platform with custom databases
• Linear - Issue tracking and project management for software teams

Development Platforms

• GitHub - Code repository with integrated issue tracking
• GitLab - Code repository with integrated issue tracking (gitlab.com and self-hosted)
• Redmine - Open-source project management

Custom Integrations

• API-based - Any system with REST API support
• Webhooks - Real-time notifications to external services (Comprehensive Webhooks Guide)

Setting Up Integrations

Initial Setup Process

1. Access Integration Settings
   • Navigate to your project page in BetaHub
   • Select Settings from the left sidebar
   • Click on Integrations
2. Choose Platform
   • Select your desired integration (e.g., “Connect with Jira”)
   • Follow the connection wizard’s authentication steps
3. Configure Authentication
   • Provide API credentials or complete OAuth flow
   • Test connection to verify access
4. Map Fields
   • Configure how BetaHub fields translate to external fields
   • Set default values and dynamic expressions
   • Test with sample data

Platform-Specific Setup

Jira Cloud Integration

Prerequisites:

• Jira Cloud instance (*.atlassian.net)
• Admin access to create API tokens
• Project permissions for issue creation

Authentication Options:

• OAuth2 (recommended) — Click “Connect with Jira OAuth2” for a seamless setup. OAuth2 also enables one-click webhook auto-registration for incoming sync.
• Basic Auth — Provide your email and an API token. Generate one at Account Settings → Security → API tokens.

Setup Steps:

1. Choose authentication method (OAuth2 or Basic Auth)
2. Provide Jira Cloud URL, email, and API token (for Basic Auth) or complete OAuth flow
3. Select target project and issue type
4. Map BetaHub fields to Jira fields
5. Optionally enable incoming sync to receive status and priority updates back from Jira

Common Field Mappings:

• Summary ← Bug title
• Description ← Bug description + steps to reproduce
• Priority ← BetaHub priority level
• Labels ← BetaHub tags

Jira Server Integration

Prerequisites:

• Self-hosted Jira Server or Data Center instance
• OAuth2 application configured in Jira
• Project permissions for issue creation

Setup Steps:

1. Configure OAuth2 application in Jira Server administration
2. Complete OAuth2 authentication flow in BetaHub
3. Select target project and issue type
4. Map BetaHub fields to Jira fields

Common Field Mappings:

• Summary ← Bug title
• Description ← Bug description + steps to reproduce
• Priority ← BetaHub priority level
• Labels ← BetaHub tags

GitHub Integration

Prerequisites:

• GitHub repository access
• Personal access token with repository permissions

Setup Steps:

1. Generate personal access token on GitHub
2. Provide repository owner and name
3. Configure issue templates and labels
4. Map fields to GitHub issue format

Common Field Mappings:

• Title ← Bug title
• Body ← Formatted description with links
• Labels ← BetaHub tags and priority
• Assignees ← Project developers

GitLab Integration

Prerequisites:

• GitLab account (gitlab.com or self-hosted instance)
• For gitlab.com: Use OAuth2 authentication (recommended)
• For self-hosted: Personal Access Token with api scope

Setup Steps (gitlab.com - OAuth2):

1. Click “Connect with GitLab” button
2. Authorize BetaHub in GitLab OAuth flow
3. Select target GitLab project
4. Configure field mappings

Setup Steps (Self-hosted or PAT):

1. Enter your GitLab instance URL (leave blank for gitlab.com)
2. Generate Personal Access Token with api scope in GitLab (User Settings → Access Tokens)
3. Enter the token and click “Connect with Token”
4. Select target GitLab project
5. Configure field mappings

Common Field Mappings:

• Title ← Bug title
• Description ← Formatted description with links
• Labels ← BetaHub tags (labels must exist in GitLab project first)

Features:

• Attachments (screenshots, videos, logs) are automatically uploaded to GitLab
• Supports both gitlab.com and self-hosted GitLab instances

Asana Integration

Prerequisites:

• Asana workspace access
• API token or OAuth application

Setup Steps:

1. Authenticate with Asana account
2. Select workspace and project
3. Configure task fields and custom fields
4. Set up automatic assignee rules

Common Field Mappings:

• Name ← Bug title
• Notes ← Detailed description
• Priority ← Asana priority levels
• Tags ← BetaHub categories

ClickUp Integration

Prerequisites:

• ClickUp workspace access
• API token from ClickUp settings

Setup Steps:

1. Generate API token in ClickUp (Settings → Apps → API)
2. Provide API token to BetaHub
3. Select workspace, space, and list
4. Map BetaHub fields to ClickUp task fields

Common Field Mappings:

• Name ← Bug title
• Description ← Detailed description
• Priority ← ClickUp priority levels
• Tags ← BetaHub tags

Fibery Integration

Prerequisites:

• Fibery workspace access
• API key from Fibery settings

Setup Steps:

1. Generate API key in Fibery (Settings → API Keys)
2. Provide API key to BetaHub
3. Select space and database type
4. Map BetaHub fields to Fibery entity fields

Common Field Mappings:

• Name ← Bug title
• Description ← Detailed description
• State ← BetaHub status
• Custom fields ← BetaHub custom fields

Linear Integration

Prerequisites:

• Linear account with access to the target team
• API key with write permissions (Settings → API → Personal API Keys in Linear)

Setup Steps:

1. Generate a personal API key in Linear (Settings → API → Personal API Keys)
2. Enter the API key in BetaHub and save — BetaHub verifies the connection automatically
3. Select the target Linear team from the dropdown
4. Map BetaHub fields to Linear issue fields
5. Optionally enable auto-push to send new bug reports to Linear automatically

Common Field Mappings:

Features:

• Attachments (screenshots, videos, log files, and other binary files) are automatically uploaded to Linear alongside the issue
• Supports both manual push and automatic push via background jobs
• Subsequent pushes update the existing Linear issue instead of creating duplicates

Field Mapping Configuration

Mapping Modes

BetaHub supports four field mapping modes:

Dynamic Expression Examples

Dynamic expressions use triple braces {{{ field_name }}} to insert values from BetaHub entries. The expression engine automatically resolves field names without requiring a namespace prefix.

Rich Description Template:

# {{{ title }}}

**Reported:** {{{ created_at }}}
**Version:** {{{ version }}}

## Description
{{{ description }}}

## Steps to Reproduce
{{{ steps_to_reproduce }}}

## Device Information
{{{ device }}}

## BetaHub Link
[View in BetaHub]({{{ issue_url }}})

Formatted Title:

[{{{ priority }}}] {{{ title }}}

Tag Combination:

{{{ tag_names }}} beta-testing {{{ priority }}}-priority

Including Custom Fields:

Custom fields use identifiers in the format custom_field_{identifier}. See Custom Field Identifiers for more details.

Bug Report: {{{ title }}}

Platform: {{{ custom_field_platform }}}
Game Mode: {{{ custom_field_game_mode }}}
Affected System: {{{ custom_field_affected_system }}}
Version: {{{ version }}}

Description:
{{{ description }}}

Steps to Reproduce:
{{{ steps_to_reproduce }}}

[View in BetaHub]({{{ issue_url }}})

Available Template Variables

The following variables are available for use in dynamic expressions:

Entry Fields:

Device & Environment:

Discord Integration:

Duplicate Tracking:

Custom Fields:

Custom fields use the format custom_field_{identifier}:

See Custom Field Identifiers for how to find your custom field identifiers.

Best Practices for Mapping

Include Context:

• Add links back to BetaHub entries
• Include reporter information
• Reference game version and platform

Maintain Traceability:

• Use consistent formatting across tools
• Include unique identifiers
• Cross-reference related items

Optimize for Workflow:

• Map to appropriate priority levels
• Use relevant categories and labels
• Set up automatic assignments

Using Integrations

Sending Individual Items

From List View:

1. Navigate to Bugs, Suggestions, or Tickets list
2. Click the three-dots menu (…) next to the entry
3. Select Send to…
4. Choose your configured integration

From Detail View:

1. Open the entry details page
2. Click the three-dots menu (…) in the top-right corner
3. Select Send to…
4. Choose your configured integration

Bulk Operations

Multi-Select Sending:

1. Use checkboxes to select multiple entries
2. Click bulk actions menu
3. Choose Send to… for selected items
4. Select target integration

Entry Linking and Updates

Automatic Linking:

• BetaHub creates bidirectional links between entries
• External item IDs are stored for reference
• Status sync (where supported by external tool)

Update Behavior:

• Subsequent “Send to…” actions update existing items
• No duplicate creation in external systems
• Manual trigger required (no automatic sync)

Incoming Sync (Two-Way)

Jira Cloud supports two-way sync — when someone changes a ticket’s status or priority in Jira, the linked BetaHub bug updates automatically. This is useful when developers work in Jira and want status changes to flow back to BetaHub without manual updates.

What Gets Synced

Incoming sync covers two fields:

Other changes (title, description, comments, assignee) are not synced back.

Enabling Incoming Sync

1. Open your Jira integration’s edit page (Settings → Integrations → click your Jira integration)
2. Scroll to the Incoming Sync (Two-Way) section
3. Check Enable incoming sync from Jira
4. Click Save Incoming Sync Settings — this generates your webhook URL and secret

Setting Up the Webhook

After saving, BetaHub displays a Webhook URL and Webhook Secret. You need to tell Jira to send events to this URL.

Option A: Auto-Register (OAuth2 only)

If you connected with OAuth2, click the Auto-register webhook in Jira button. BetaHub registers the webhook in your Jira project automatically — no manual configuration needed.

Option B: Manual Setup

1. Copy the Webhook URL from BetaHub
2. In Jira, go to Settings → System → Webhooks (requires Jira admin access)
3. Click Create Webhook
4. Paste the BetaHub webhook URL
5. Under events, select Issue: updated
6. Optionally paste the Webhook Secret for HMAC signature verification
7. Save the webhook

Configuring Status Mapping

The status mapping table shows all statuses from your Jira project on the left and BetaHub statuses on the right. For each Jira status, choose the corresponding BetaHub status:

Select – Do not sync – for Jira statuses that should be ignored.

Configuring Priority Mapping

Similar to status mapping, the priority table maps Jira priorities to BetaHub priorities:

How It Works

When a Jira ticket linked to a BetaHub bug is updated:

1. Jira sends a webhook event to BetaHub
2. BetaHub identifies the linked bug via the external reference
3. The status and/or priority change is mapped using your configured mappings
4. The BetaHub bug is updated — this update does not push back to Jira (loop prevention)
5. Team members receive the usual notifications (Discord, email) about the status change

Loop Prevention

BetaHub has built-in safeguards to prevent infinite update loops between Jira and BetaHub. When a change originates from Jira, BetaHub updates the bug locally without pushing the change back to Jira.

Advanced Configuration

Custom Field Mapping

Jira Custom Fields:

{
  "customfield_10001": "{{{ device }}}",
  "customfield_10002": "{{{ version }}}",
  "customfield_10003": "BetaHub Import"
}

GitHub Issue Templates:

---
title: {{{ title }}}
labels: {{{ tag_names }}}, bug
---

**Bug Report from BetaHub**

{{{ description }}}

**Steps to Reproduce:**
{{{ steps_to_reproduce }}}

**Environment:**
- Version: {{{ version }}}
- Device: {{{ device }}}

[View in BetaHub]({{{ issue_url }}})

Template Engine

BetaHub uses the Mustache template engine for dynamic expressions. This provides simple, logic-less templating focused on variable substitution.

Supported Syntax:

• Variable substitution: {{{ variable_name }}}
• All variables are converted to strings automatically
• Empty variables render as blank strings

Unsupported Features:

• Conditional logic (if/else statements)
• Loops and iterations
• Filters or transformations
• Liquid-style syntax

Webhook Configuration

For comprehensive webhook setup, configuration, and examples, see the dedicated Webhooks Documentation.

Key Features:

• Real-time notifications to external services
• Custom payload formatting with variable substitution
• Multiple event types (issues, feature requests, tickets)
• Built-in testing and debugging tools
• Retry logic for failed deliveries
• Security headers and authentication support

Integration Monitoring

Success Tracking

Integration Dashboard:

• Success/failure rates for each integration
• Recent sync activity logs
• Error message analysis
• Performance metrics

Audit Trail:

• Track which items were sent where
• Monitor user actions and timestamps
• Maintain compliance records

Error Handling

Common Error Types:

• Authentication failures
• Network connectivity issues
• Field validation errors
• Rate limiting responses

Resolution Strategies:

• Automatic retry with exponential backoff
• User notification for manual intervention
• Fallback to alternative integrations
• Error log aggregation for analysis

Troubleshooting

Authentication Issues

Token Expiration:

• Check token validity in external system
• Regenerate tokens as needed
• Update BetaHub configuration

Permission Problems:

• Verify account permissions in target system
• Check project-specific access rights
• Confirm API scope and capabilities

Field Mapping Errors

Validation Failures:

• Review required fields in target system
• Check data format requirements
• Test with minimal field mappings

Template Syntax Errors:

• Validate dynamic expression syntax
• Test templates with sample data
• Check for missing or invalid variables

Performance Issues

Slow Sync Times:

• Review network connectivity
• Check external system status
• Optimize field mapping complexity

Rate Limiting:

• Implement request throttling
• Spread sync operations over time
• Contact external service for rate increases

Security Considerations

Credential Management

Best Practices:

• Use dedicated service accounts
• Rotate credentials regularly
• Apply principle of least privilege
• Monitor access logs

Token Security:

• Store tokens securely
• Never expose in logs or UI
• Use encrypted storage
• Implement token rotation

Data Privacy

Information Transfer:

• Review what data is sent to external systems
• Ensure compliance with privacy regulations
• Implement data retention policies
• Document data flows

Getting Help

Support Resources

Documentation:

• Platform-specific integration guides
• API reference documentation
• Field mapping examples

Community Support:

• Join our Discord server
• Community knowledge base
• User-contributed examples

Direct Support:

• Technical support for complex integrations
• Custom integration development
• Enterprise integration consulting

Common Questions

Q: Can I sync data back from external tools to BetaHub? A: Yes — Jira Cloud supports two-way sync for status and priority changes. Enable it in your Jira integration’s edit page under “Incoming Sync (Two-Way).” Other integrations currently support one-way sync only.

Q: How often does synchronization occur? A: Sync is manual and triggered by user action. Automatic sync is not currently supported.

Q: Can I integrate with multiple tools simultaneously? A: Yes, you can configure multiple integrations and choose which tool to send each item to.

See Also

• Webhooks – Real-time event notifications
• API Access – REST API and authentication
• AI Assistants – AI-powered workflow automation
• Advanced Features – Webhooks, API, and automation