Jira — Integration Setup

Jira is CMDash's first bi-directional integration: it both reads existing issues into CMDash as incidents, and lets CMDash push risks/remediations out to Jira as new issues, then poll them for status changes.

Prerequisites

• Jira Cloud site (*.atlassian.net)
• An Atlassian account with permission to browse the relevant project(s) and, for write-back, create/edit issues in the target project
• CMDash Essentials tier or above

Step 1: Create an API Token

1. Log in to id.atlassian.com/manage-profile/security/api-tokens.
2. Click Create API token, name it CMDash Integration, and copy the token — it is shown only once.
3. Note the email address of the Atlassian account the token belongs to; CMDash needs it to build the Basic auth header.

Step 2: Connect in CMDash

1. Navigate to Integrations in your CMDash dashboard.
2. Find Jira and click Connect.
3. Enter:
   • Domain — your site's subdomain only (e.g., acme for acme.atlassian.net)
   • Email — the Atlassian account tied to the API token
   • API Token (stored as this connection's access token)
   • Project Key (e.g., SEC) — used to build the default read query, or supply your own JQL override
4. Click Save & Test Connection.

What Syncs (Read Direction)

By default CMDash searches:

project = "<Project Key>" AND (type = Bug OR type = Task OR type = "Security") AND updated >= -7d ORDER BY updated DESC

You can override this entirely with a custom JQL string in the connection config if your security-relevant issues live in a different project, issue type, or label scheme. Results are paginated 100 at a time and capped at 1,000 issues per sync. Jira priority (Highest/Blocker → critical, High → high, Medium → medium, everything else → low) and status category (new/undefined → open, indeterminate → investigating, done → resolved) are mapped onto CMDash's incident severity/status fields.

Write-Back Direction

CMDash can push a risk or remediation item to Jira as a new issue, then track it:

Write-back requires the same API token/email used for reads to also have Create Issues and Edit Issues permission on the target project. This direction is invoked from CMDash's risk/remediation workflow (e.g., "Push to Jira" action), not on the scheduled sync cadence — it happens on demand.

Troubleshooting

• 401 Unauthorized: The API token was regenerated/revoked, or the email doesn't match the token's owner.
• 403 Forbidden on search: The account can't browse the configured project; grant it Browse Projects permission.
• Push fails with 400: The target project key doesn't exist, or the specified issue type isn't enabled for that project — check Project settings → Issue types.
• Status never updates after push: fetchIssueStatus must be triggered per issue (e.g., from the remediation detail view); it isn't part of the scheduled bulk sync.

Rate Limits & Sync Behavior

Credential Rotation

Atlassian API tokens do not expire unless you set an expiration when creating them (Atlassian now supports up to 1 year). CMDash recommends rotating annually or whenever the token owner leaves the org.

To rotate:

1. Create a new API token at id.atlassian.com.
2. In CMDash: Settings → Integrations → Jira → Edit.
3. Enter the new API Token and Save.
4. Revoke the old token once confirmed working.

Multiple Instances / Multi-Site

If your organization runs more than one Jira Cloud site, or wants separate connections per project/business unit, add a connection per site or per JQL scope.

To add another connection:

1. In CMDash: Settings → Integrations → Add Integration → Jira.
2. Enter the domain, email, API token, and project key/JQL for the additional scope.
3. Give the connection a descriptive name (e.g., Jira - Security Team, Jira - Platform).
4. Click Save & Test Connection.

Compliance Framework Coverage

The Jira integration provides evidence for the following controls. Coverage is automatically mapped when data is synced.