🧩 Jira
Chipper can automatically create Jira issues whenever a threshold-triggered alert occurs.
✅ Current Strategy (PAT Based)
We use Jira Cloud's REST API with a Personal Access Token (API token) for your Atlassian account. This is more reliable than Jira Automation webhooks (which required additional rule setup and strict payload shapes).
🔐 Required Fields
Add a Jira integration in Settings > Integrations > Jira and provide:
| Field | Description | Example |
|---|---|---|
| Domain | Your Atlassian Cloud domain (without protocol) | chipperbot.atlassian.net |
| The Atlassian account email associated with the API token | you@company.com | |
| API Token | A Jira Cloud API token (create at id.atlassian.com/manage-api-tokens) | ******** |
| Project Key | The key of the project where issues should be created | SCRUM |
| Issue Type (optional) | Type for created issues (defaults to Task) | Bug / Incident |
Once saved, select this integration in any threshold configuration to enable Jira issue creation for that alert.
📝 Issue Content
Each issue includes:
- Summary:
[SEVERITY] Alert CHIPPER-<id>: <reason> - Description: A structured Atlassian Document (ADF) with alert metadata
- Severity: Included in the description text
- Direct Link: URL back to the alert in Chipper
We now send the description in Atlassian Document Format (ADF). If you previously saw
Operation value must be an Atlassian Document, this is resolved.
🧪 Testing Your Integration
Trigger a threshold manually using the Preview Alerts feature in the UI, or force an alert by lowering a threshold temporarily. Then:
- Open the alert details.
- View the timeline. A Jira entry will show status code (201 on success) and the created issue key.
- Click the key in Jira to verify content.
🔍 Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| 400 with description error | Description not in ADF | Ensure integration is updated (we've already patched backend) |
| 401 Unauthorized | Invalid email/token pair | Regenerate token; confirm email matches Atlassian account |
| 404 Project does not exist | Wrong project key | Verify the key in Jira project settings |
| Issue type error | Unsupported type | Use a valid type name (Task, Bug, Story, Incident, etc.) |
| No Jira timeline row | Integration incomplete | Ensure all required fields are set in integration form |
🔄 Updating / Rotating Tokens
You can revoke API tokens anytime from Atlassian. After rotation, edit the integration and replace only the token—domain, email, and project key remain unchanged.
📌 Future Enhancements (Planned)
- Custom field mapping
- Support for attaching event excerpts
- Optional dual mode (Webhook + PAT)
- Configurable summary templates
If you need one of these sooner, reach out via Support > Contact Us.
⚠️ Deprecated: Webhook / Automation Path
We previously experimented with Jira Automation webhooks requiring a X-Automation-Webhook-Token and an issues array. That approach is deprecated in favor of direct issue creation via PAT. If you still want webhook mode, contact support.
✅ Security Notes
- API token stored encrypted server-side
- Only used at alert notification time
- Not shared with other accounts or users
Need help or missing a feature? Open a ticket via the support page or create a feedback issue.