Jira Cloud Integration

This page covers the Jira Cloud integration (regscale jira) only. For on-prem Jira Server / Data Center, see the separate Jira Data Center page.

The regscale jira command group performs bulk processing and ticket assignment between RegScale and Jira Cloud (*.atlassian.net). It cross-links RegScale and Jira IDs, syncs attachments both ways, and is designed for automated, scheduled assignment of RegScale issues/tasks to Jira and vice versa. Authentication uses an Atlassian account email + API token.

Commands

regscale jira issues options

regscale jira tasks options

Same as issues, except there is no --jira_issue_type (it is hardcoded to Task) and no --poams.

A task closed or cancelled in Jira gets its dateClosed from the first Jira timestamp that has a UTC offset, and keeps that offset: statuscategorychangedate, then resolutiondate, then created. None of these moves after the close, so a task created closed and a task closed on a later run get the same value. If statuscategorychangedate is missing or unreadable and there is no resolutiondate, the date is when the Jira issue was created, which can be earlier than the real close. A task that stays closed keeps its stored dateClosed when other fields change, unless Jira's statuscategorychangedate or resolutiondate is readable. If Jira sends none of these timestamps, the task gets the current UTC time and the run logs a warning, because RegScale refuses a closed task with no dateClosed.

Jira issue types

--jira_issue_type takes the name of an issue type as it exists in your Jira Cloud project. Issue types are defined per-project in Jira, not by RegScale — the CLI passes your string through and validates it against the project's available types before syncing, aborting with a clear message if it is not found.

Two rules govern what you can pass:

1. Case sensitive — the value must match Jira exactly. Bug works; bug does not.
2. It must exist in the target project — the authoritative list is in Jira → Project settings → Issue types for that specific project (or via the Jira createmeta REST endpoint).

Default Jira Cloud issue types by project type

The defaults depend on how the Jira project was created:

Notes on specific types

Your instance may rename these defaults or define custom issue types. Always confirm the exact names in your project's settings and pass them verbatim. If RegScale reports the type is invalid, it is not present in the target project.

Priority → RegScale severity mapping

When a Jira issue is imported, its priority is mapped to a RegScale IssueSeverity:

Outbound (RegScale → Jira) severity is sent as the simple labels Critical / High / Medium / Low.

Status mapping

jira issues and jira tasks map a Jira status by one rule. The match ignores case.

issues.jira.status is Open by default. With Open, every Jira status lands the same way in both commands. An open task can be only Backlog or Open. If issues.jira.status is another value, such as Draft or Closed, issues take that value, tasks land Open, and the CLI logs a warning on each jira tasks run. A Jira record that moves back to a non-terminal status reopens the RegScale record by the same rule.

jira tasks syncs both ways. A task created in RegScale as Backlog goes to Jira as To Do, and the next run sets it to issues.jira.status. Only status: Backlog keeps such a task at Backlog, but then jira issues sends Backlog, which is not a RegScale issue status.

The completion date comes from Jira's status-change date (the statuscategorychangedate field), with its UTC offset kept. If that date cannot be read, the resolution date (resolutiondate) is used, and then the date the Jira issue was created (created). The created date can be earlier than the real close. This applies to the dateCompleted of an issue and the dateClosed of a task, so both commands date the same Jira issue the same way. The regscale jira tasks options give the task re-run rules. For an issue, a readable status-change or resolution date replaces the stored completion date on every run. A created date is set only when the run creates or closes the issue. An issue that is already closed or cancelled keeps its stored completion date. If Jira sends none of the three dates for an issue, RegScale sets the completion date when it first closes or cancels the issue.

Issue processing workflow

1. Log into RegScale via the CLI (regscale login) to set the 24-hour access token, or use a service account. See the CLI Login docs.
2. Run the command with the flags above.
3. The CLI retrieves all existing RegScale issues for the given regscale_id / regscale_module.
4. The CLI retrieves all matching Jira issues (paging 100 at a time until all are retrieved, via /rest/api/3/search/jql with nextPageToken pagination).
5. For each Jira issue:
   • If it has no matching RegScale issue → a RegScale issue is created and linked.
   • If RegScale has issues not yet in Jira → a Jira ticket is created and the RegScale issue is updated with the new Jira ID.
     The push sends every issue under the record that has no Jira ID — whichever integration created it. On a security
     plan that also holds Wiz, AWS or GCP issues, each of those becomes a Jira ticket too; scope the run to a record
     that holds only the issues you mean to send. jira tasks behaves the same for tasks without an otherIdentifier.
   • If the issue exists in both → the records are compared and updated.
   • When --sync_attachments is true → attachments are compared and synced both ways (see the attachment rules below).

Detailed logging is emitted throughout for progress and troubleshooting.

Init.yaml configuration

Creating an API token: In Jira, click the Settings icon → Atlassian Account Settings → Security tab → Create or Manage API Token → Create API Token. Copy it into init.yaml.

Attachment rules (--sync_attachments)

• A file brought into RegScale is saved as Jira_attachment_<name>.
• A file sent to Jira is named RegScale_<Module>_<record id>_<name>: RegScale_Issues_123_report.pdf
  from jira issues, RegScale_Tasks_123_report.pdf from jira tasks.
• A Jira file without an extension is skipped and the run logs a WARNING — RegScale requires an extension.
• Jira allows several attachments with the same name; each is kept — a taken name gets a
  counter suffix (notes.txt → notes (2).txt) — and the hash-based dedupe still lands
  identical same-name content once (REG-30826).
• The sync compares files by content, not by name: a file whose content is already on the other
  side is not copied again, even after a rename. Before it adds a prefix, the sync strips the
  Jira_attachment_ and RegScale_Issue(s)_<id>_ prefixes, but not yet RegScale_Tasks_<id>_, so
  a task file that makes a round trip can carry that prefix twice (REG-35058).

The issues.jira block in init.yaml controls remediation SLAs (days until due) and status, the RegScale status for a Jira record in a non-terminal status (see Status mapping):

issues:
  jira:
    highest: 7
    high: 30
    medium: 90
    low: 180
    lowest: 365
    status: Open

Example init.yaml

domain: https://mycompany.regscale.com
token: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVC...
maxThreads: 1000
userId: c9f579e2-a8c9-4c02-8e91-ce122a1aa518
jiraUrl: https://team-99999999.atlassian.net
jiraUserName: [email protected]
jiraApiToken: 99rtYi34trydt345ynb

Examples

Log in (token good for 24 hours; skip if using a service account):

regscale login

Sync issues for a System Security Plan:

regscale jira issues --regscale_id=5 --regscale_module="securityplans" --jira_project="AT" --jira_issue_type="[System] Incident"

Sync tasks:

regscale jira tasks --regscale_id=5 --regscale_module="securityplans" --jira_project="AT" --sync_attachments True

Create incoming Jira issues as POA&Ms in RegScale:

regscale jira issues --regscale_id=5 --regscale_module="securityplans" --jira_project="AT" --jira_issue_type="Bug" --poams

Bash script example

#!/bin/sh
regscale login
regscale jira issues --regscale_id=5 --regscale_module="securityplans" --jira_project="AT" --jira_issue_type="Bug"

Run with . regscaleScheduler.sh. Chain any sequence of CLI commands to run them in order.

Custom filtering with JQL

issues and tasks accept a --jql option using full Jira Query Language:

regscale jira issues --regscale_id=1 --regscale_module=securityplans --jira_issue_type=Bug --jira_project=project1 --jql="project=project1 AND priority=High AND status=Backlog"

Important: When --jql is supplied, the integration does not implicitly scope to --jira_project. If you do not name a project in the JQL, it searches all projects. Include project=<key> in your JQL to scope it.