Jira

The Jira integration connects runZero to a Jira Cloud project for issue-tracking and service-desk operations. Once it is configured, you can push a runZero issue to Jira as a ticket and keep the runZero issue timeline in sync with changes made in Jira.

To import runZero asset data into Jira Service Management’s CMDB, see Atlassian Insight & Jira Service Management instead. That asset-enrichment integration is independent of the issue-tracking sync described here.

How the integration works

• runZero authenticates to Jira Cloud as a regular Atlassian user with HTTP basic auth (email + API token).
• When you create a Jira ticket from a runZero issue, runZero calls the Jira REST API (v3) to create the issue in the project configured on the credential, copies the relevant fields across, and stores the resulting Jira key and link on the runZero issue.
• A configurable Jira webhook posts changelog events back to runZero, and each change becomes a timeline entry on the matching runZero issue. If you configure state mapping, status and due-date changes also update the runZero issue directly.
• When you change a runZero issue state and a state mapping is configured, runZero calls the Jira Transitions API to move the linked ticket to the corresponding Jira status.
• When a linked runZero issue has an owner that runZero can match to an external Jira user, runZero syncs that owner with the Jira assignee. Changes to the Jira assignee sync back to the runZero issue.
• runZero initiates all traffic to Jira, and all traffic from Jira is signed and verified with HMAC-SHA256. runZero reads and writes no other Jira data in your environment.

Prerequisites

Before you start, you need:

• An Atlassian Cloud account that can create issues in the target Jira project.
• A Jira project to write tickets to, and that project’s Project key (for example SCRUM, SEC, or OPS).
• A Jira API token. Create one at https://id.atlassian.com/manage-profile/security/api-tokens and copy it somewhere safe. You cannot view it again after you close the dialog.
• A randomly generated webhook secret if you plan to enable two-way sync. Any reasonably long random string will do; runZero uses it to verify inbound webhook requests.
• The Jira integration entitlement on your runZero account.

Creating the Jira credential

The Jira integration uses a runZero credential of type Jira API Token. You can create one ahead of time from the Credentials page, or directly from the Create Jira ticket dialog the first time you push an issue.

To create the credential ahead of time:

1. Go to Credentials in the runZero Console.
2. Click New credential and choose Jira API Token.
3. Fill in the form:
   • URL: the base URL of your Jira Cloud site, for example https://yourcompany.atlassian.net. Do not include a trailing path.
   • Email: the email address of the Atlassian user the API token belongs to. This account must be able to create and transition issues in the target project.
   • API token: the API token you created on the Atlassian side.
   • Webhook secret: a random string that authenticates inbound Jira webhooks. Save the value somewhere you can paste it into Jira later.
   • Jira Project Key: the key of the Jira project where runZero creates tickets (for example SEC or OPS). This field is required; ticket creation fails if you leave it empty.
   • Map Issue States to Jira Values: optional. A table mapping each runZero issue state to the corresponding Jira status name. See State mapping and bidirectional sync for details.
4. Save the credential. runZero validates the URL, email, and token with an authenticated call to Jira and rejects the credential if the call fails. The validation result appears next to the credential.

After you save the credential, open it for editing and copy the read-only Jira webhook URL field. You need that URL when configuring the Jira webhook.

You can reuse one credential for as many Jira tickets as you like. If you change the API token in Atlassian, update the credential in runZero or future calls will fail.

Creating a Jira ticket from an issue

1. Open an issue from the Issues page.
2. In the sidebar:

• Credential: select the Jira credential to use.
• Attach snapshot to ticket: optional. When enabled, runZero uploads a CSV of the issue’s instance snapshot as an attachment on the new Jira ticket.
• Click Create ticket.

runZero then:

• Creates the Jira issue with the project key from the credential, the summary, the description, and the runZero issue’s due date if one is set.
• Uploads the snapshot CSV as a Jira attachment, if you enabled it. A failed CSV upload does not abort ticket creation; the ticket is still linked.
• Saves the Jira issue key (for example SEC-42), a browse link ({your-jira-url}/browse/SEC-42), the credential, and the Jira base URL on the runZero issue.
• Appends a Created Jira ticket SEC-42 for issue "..." entry to the runZero issue timeline.

Once linked, the issue sidebar shows the Jira key and a button that opens the ticket in Jira.

A runZero issue links to at most one Jira ticket at a time. To relink, unlink the existing ticket first.

Unlinking a ticket

From a runZero issue with a linked ticket, use the unlink action in the sidebar to clear the link. Unlinking changes only the runZero side: the Jira ticket is neither deleted nor modified. After unlinking, you can create a new ticket from the same issue.

State mapping and bidirectional sync

The Map Issue States to Jira Values table on the Jira credential turns on two-way sync of state and due date between runZero issues and Jira tickets.

To configure state mapping, open the credential and add one row per runZero state you want to sync:

• Issue State (key): one of the four runZero issue states, open, in progress, closed, or resolved.
• Jira Value (value): the exact name of the corresponding Jira status in your project workflow, for example To Do, In Progress, or Done. Matching is case-insensitive for inbound webhook events.

You can map all four states or only some of them. runZero ignores unmapped states in both directions.

Outbound sync (runZero → Jira)

When you change a runZero issue state, or when runZero automatically transitions an issue to resolved, runZero looks up the new state in the credential’s state mapping. If that state maps to a Jira status name, runZero calls the Jira Transitions API to move the linked ticket to the target status.

If the Jira workflow has no available transition from the ticket’s current status to the target status, the transition silently fails. runZero applies the state change on its side whether or not the Jira transition succeeds.

Inbound sync (Jira → runZero)

When Jira sends a webhook with a status change, runZero reverses the state mapping to find the matching runZero state and updates the issue. Due date changes on the Jira ticket also flow back to the runZero issue.

Issue owner synchronization

runZero syncs issue owners with Jira assignees for linked tickets. When you push an issue to Jira, runZero looks for an external Jira user that matches the runZero owner. For the runZero issue owner, you can enter either the email address or the username of the Jira user. If runZero finds a matching Jira user, it assigns that user to the Jira ticket.

When the Jira assignee changes, the Jira webhook updates the owner of the linked runZero issue. For Jira sync, runZero accepts an owner only if it matches an external Jira user.

Issue ownership uses the built-in Issue owner type and supports one owner per issue. runZero does not sync custom ownership types. See Managing Issue ownership and Issue ownership.

Note: The casing of the Jira status needs to match the casing set in the Jira workflow

Example mapping:

Configuring the Jira webhook

To turn on inbound sync from Jira to runZero, configure a Jira webhook for the project (or the whole site):

1. In Jira, go to System → WebHooks and click Create a WebHook (administrator access required).
2. Name: anything descriptive, for example runZero issue sync.
3. URL: open your runZero Jira credential and copy the read-only Jira webhook URL field. It follows the pattern https://<your-runzero-console>/api/webhooks/jira/${issue.key}. The literal text ${issue.key} is a Jira URL variable; Jira substitutes the actual issue key for each event.
4. Secret: paste the same webhook secret you saved on the runZero credential. Jira signs each request with HMAC-SHA256 and sends the signature in the X-Hub-Signature header.
5. Events: enable at least the issue updated event. You can add more events; runZero records every changelog item it receives.
6. (Optional) JQL filter: restrict the webhook to the project used with this credential, for example project = SEC. This keeps out unneeded events from other projects.
7. Save the webhook.

When an event fires, runZero:

1. Looks up the matching runZero issue by Jira issue key + Jira base URL (so multiple Jira sites do not collide).
2. Validates the HMAC-SHA256 signature against the credential’s webhook secret using a constant-time comparison.
3. If state mapping is configured, applies any status or due-date changes to the runZero issue.
4. Appends one timeline line per changelog item, in this form:

Jira update (SEC-42): status changed from "In Progress" to "Done"; assignee set to "alice@example.com"

If a webhook arrives without a valid signature, for an unknown Jira key, or for a deleted runZero issue, runZero silently returns 200 OK without writing anything, so the endpoint does not leak which keys are linked.

What gets sent to Jira

When runZero creates a ticket, it sends:

• The runZero issue name as the Jira summary.
• The runZero issue description as the Jira description.
• The runZero due date, if one is set, as the Jira due date.
• The project key from the credential, which routes the ticket to the right project.
• Optionally, a CSV file with one row per (vulnerability, asset) instance from the issue snapshot, uploaded as a Jira attachment.

After ticket creation, ongoing sync depends on your state mapping configuration:

• runZero → Jira: when a runZero issue state changes and a mapping is configured, runZero pushes the transition to Jira through the Transitions API.
• Jira → runZero: status and due date changes arrive through the Jira webhook and update the runZero issue (status changes require state mapping).

After the initial ticket creation, runZero does not push comments, description edits, or other field changes to Jira.

Troubleshooting

• Credential verification fails when saving. Check that the URL has no trailing path, the email matches the Atlassian account that owns the API token, and the token has not been revoked. The credential page shows the specific HTTP status returned by Jira.
• Create Jira ticket returns an error. The runZero issue must have a non-empty name and description. The selected credential must have a Jira Project Key configured; if the field is empty, the request fails with a project_key is required error. The project key must exist in Jira, and the API user must be allowed to create issues in it. The error message echoes the HTTP status returned by Jira.
• Snapshot CSV is missing from the Jira ticket. Check that the API user has permission to add attachments to the project. Snapshot upload is best-effort; the ticket is still created if the upload fails.
• Jira changes do not appear in the runZero timeline.
  • Confirm the webhook URL contains the literal ${issue.key} variable.
  • Confirm the webhook secret in Jira matches the value stored on the runZero credential.
  • Confirm Jira is sending the X-Hub-Signature header (some proxies strip it).
  • Confirm the runZero issue’s stored Jira base URL matches the Jira site sending the webhook. If you migrate Jira sites, unlink and recreate the ticket.
• State changes are not being pushed to Jira. Confirm the credential has a state mapping entry for the runZero state that changed, and that the Jira status name matches the exact name in your Jira workflow. The API user must also have permission to transition issues in the project. If no available Jira workflow transition leads from the ticket’s current status to the target status, the push silently fails.
• Jira status changes are not updating the runZero issue state. Confirm the Jira status name in the webhook event matches the value in the credential’s state mapping (matching is case-insensitive). Confirm the webhook secret is correct and that the X-Hub-Signature header is reaching runZero.