Jira Integration

Table of contents

1. Overview
2. Prerequisites
3. Setup Instructions
   1. Step 1: Create Jira API Token
   2. Step 2: Configure ButterStack Integration
   3. Step 3: Field Mapping
   4. Step 4: Webhook Configuration
      1. Option A: Auto-create (one click)
      2. Option B: Manual registration
   5. Step 5: Custom Fields Setup
4. Advanced Configuration
   1. JQL Filters
   2. Workflow Automation
   3. Status Mapping
5. Integration Features
   1. Asset Linking
   2. Bulk Operations
   3. Reporting
6. Troubleshooting
   1. Common Issues
7. Best Practices
8. API Examples
   1. Create Issue with Asset
9. Next Steps

Overview

ButterStack integrates with Jira to synchronize tasks, track asset assignments, and provide visibility into your development pipeline. This integration enables automatic task updates and two-way synchronization.

Prerequisites

• Jira Cloud or Server instance
• API token or OAuth credentials for an account that can browse and read the project
• ButterStack project with admin rights

Setup Instructions

Step 1: Create Jira API Token

1. Log in to your Jira account
2. Navigate to Account Settings → Security → API tokens
3. Click Create API token
4. Name it “ButterStack Integration”
5. Copy the generated token

Step 2: Configure ButterStack Integration

1. In ButterStack, go to Settings → Integrations
2. Click Add Integration → Jira
3. Enter your Jira details:

Jira URL: https://your-domain.atlassian.net
Email: your-email@company.com
API Token: [paste your token]
Default Project: PROJ

Copy URL Template

Step 3: Field Mapping

Configure how ButterStack fields map to Jira:

Step 4: Webhook Configuration

Real-time updates require a webhook in Jira that POSTs to ButterStack. There are two ways to set it up.

Option A: Auto-create (one click)

If the API token’s account has the Administer Jira permission, open the integration in ButterStack and click Configure Webhook under Real-Time Updates. ButterStack registers the webhook, scopes it to your project, and (when a webhook secret is set) signs the deliveries automatically.

Option B: Manual registration

If you can’t grant the token that permission, register the webhook by hand. The ButterStack integration page shows the exact Webhook URL, recommended events, and JQL under Real-Time Updates → Manual Setup - copy them from there so the URL points at your own instance. Then in Jira:

1. Go to Settings → System → WebHooks
2. Click Create a WebHook
3. Configure:
   • Name: ButterStack Integration
   • URL: the URL shown on the integration page, of the form https://YOUR_BUTTERSTACK_HOST/webhooks/jira?token=YOUR_WEBHOOK_TOKEN (Jira Cloud must be able to reach it over public HTTPS: a localhost URL will not deliver)
   • Issue related events (JQL): project = YOUR_PROJECT_KEY (keeps other projects out)
   • Events: select
     • ✅ Issue created
     • ✅ Issue updated
     • ✅ Issue deleted
     • ✅ Comment created / updated

Step 5: Custom Fields Setup

Create custom fields in Jira for ButterStack data:

1. Go to Settings → Issues → Custom fields
2. Create these fields:
   • ButterStack Asset ID (Text field)
   • Asset Status (Select list)
   • Build Version (Text field)
   • Asset Type (Select list)

Advanced Configuration

JQL Filters

Configure which Jira issues sync with ButterStack:

project = "GAME" AND type in (Task, Bug) AND status != Done

Copy JQL

Workflow Automation

Set up Jira automation rules:

Trigger: Issue transitioned to "In Progress"
Action: Create ButterStack task
Condition: Issue has component "Assets"

Status Mapping

Map Jira statuses to ButterStack asset states:

Jira Status → ButterStack Status
To Do       → Pending
In Progress → Active
In Review   → Under Review
Done        → Completed

Integration Features

Asset Linking

Link assets directly to Jira issues:

1. In ButterStack asset view, click Link to Jira
2. Search for issue by key or summary
3. Select issue to create link
4. Asset status syncs automatically

Bulk Operations

Perform bulk actions on linked issues:

• Update multiple asset statuses
• Bulk assign to Jira users
• Mass comment on issues
• Batch transition workflows

Reporting

Access integrated reports:

• Asset completion by sprint
• Time tracking across assets
• Issue-to-asset mapping
• Team velocity metrics

Troubleshooting

Common Issues

curl -u email@example.com:api_token \
  https://your-domain.atlassian.net/rest/api/2/myself

Best Practices

API Examples

Create Issue with Asset

const createIssueWithAsset = async (assetId, assetName) => {
  const issue = {
    fields: {
      project: { key: 'PROJ' },
      summary: `Asset Review: ${assetName}`,
      description: 'Please review the attached asset',
      issuetype: { name: 'Task' },
      customfield_10100: assetId // ButterStack Asset ID
    }
  };
  
  const response = await fetch('https://your-domain.atlassian.net/rest/api/2/issue', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${btoa('email@example.com:api_token')}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(issue)
  });
  
  return response.json();
};

Copy Code

Next Steps

• Set up Linear integration for alternative task tracking
• Configure Slack notifications for updates
• Enable Jenkins CI/CD for automated builds