Install and configure the Jira integration
- Public preview
Install XBOW Integration for Jira from Atlassian Marketplace, then configure it from Jira admin settings.
Jira lists the app in admin settings as “XBOW Jira Integration”.
Install the app
You install XBOW Integration for Jira in the same way as other free Atlassian Marketplace apps. Open the XBOW Integration for Jira listing, then follow the steps in Atlassian’s Install and manage app access.
The XBOW integration app requests the minimal scopes needed to work. Jira scopes are broad, so you grant permission for some actions beyond those the app uses, for example deleting an issue. For details of the permissions actually used by the app, see Jira integration security, permissions, and data handling.
Installation may take a while. Jira notifies you when the app is ready to use.
Open the app settings
- In Jira, open Settings, then Marketplace apps.
- If Jira shows a redirection page, ignore it and expand the left sidebar.
- Under “Apps”, expand XBOW Jira Integration.
- Click the view you want to open: Configuration, Mapping, or Events.
Configure the connection
The Configuration view lists five setup steps and tracks each one. A step reads “Missing” or “Needs setup” until you complete it.
Four of the five need action from you. Nothing is needed in “Load webhook signing keys” unless XBOW Support asks you to refresh the keys.
The view displays a series of sections that you can edit and save independently.
- Save buttons are disabled until you make a valid change.
- While saving, each button shows a loading state followed by a confirmation or error beside it.
- Saving one section does not save or discard changes in another.
1. Choose integration mode
If the default integration mode meets your needs, you can ignore this step.
- Select Create Jira work items only for unidirectional mode, or Create Jira work items and keep XBOW updated for bidirectional mode. Bidirectional mode writes Jira workflow state back to XBOW and supports automatic closure when you enable it in Mapping.
- Click Save Mode.
You can change the integration mode later. Switching to unidirectional mode stops writebacks and turns off automatic closure. Existing workflow information stays in XBOW.
2. Connect to XBOW
- Select your XBOW region. To identify your region, see Identify your region.
- Paste your XBOW organization ID. Copy it from your organization’s URL:
https://console.xbow.com/v2/organizations/ORGANIZATION-ID(the base URL varies by region). - Click Save Configuration.
3. Store the XBOW API token
- Paste your XBOW API token. To learn how to generate a token, see Generate an API key in the API reference.
- Click Save Token.
The integration validates the token by connecting to your XBOW organization. If the connection is successful, the “Current token status” shows “Validated” with the date and time.
The token field is write-only. After you save the token, the app shows only the token status. It does not show the token value again.
Save Token is enabled when you enter a token. The input clears after a confirmed save.
4. Connect webhook
- Click Connect Webhook.
- Confirm that the webhook status shows “Signal received” and a recent signed ping. The step list in the sidebar calls this “Webhook signal”.
If the webhook signal does not update, open Events and click Show Debug Info. Email that information to support@xbow.com.
If Connect Webhook fails and Events shows a webhook signature problem, click Refresh Signing Keys, then click Connect Webhook again.
Upgrade an existing installation
Version 0.3.0 uses XBOW’s rolling next API version. The integration stays on next when a dated API version is released.
Your saved mappings and credentials stay unchanged. You do not need to uninstall and reinstall the app.
Existing webhook subscriptions keep their previous payload version until you update them. If Configuration shows “Webhook update required”:
- Click Connect Webhook.
- Confirm that the status shows “Signal received” and a recent signed ping.
Automatic closure is off by default and requires bidirectional mode. Enable it in Mapping. It does not close work items for findings that are already “Fixed”.
Replace the XBOW API token
When you need to rotate the token:
- Create a new XBOW API token for the same XBOW organization.
- Open Configuration.
- Paste the new token.
- Click Save Token.
- Confirm that validation succeeds.
- Revoke the old token in XBOW.
The app stores the new token only after validation succeeds. If validation fails, the existing token remains in use.