Jira integration

Use the Jira integration to bring existing Jira work into Sharkly and keep selected Jira projects connected to Sharkly Spaces. Jira Cloud and Jira Server or Data Center are supported.

Choose import or sync

Import copies existing Jira data into Sharkly. Use it for historical work or a controlled migration.

Sync links a Jira project to a Sharkly Space and keeps recent changes connected. Sync does not import historical data by itself.

Import and then sync imports the selected history and, when a matching Jira connection exists, creates a bidirectional link before the import runs.

Connect Jira for ongoing sync

Open Integrations, select Jira, and choose Connect Jira.

For Jira Cloud, enter:

The bare host name, such as acme.atlassian.net

The Jira account email address

An Atlassian API token

For Jira Server or Data Center, enter:

The full Jira base URL

The Jira username

A personal access token

Sharkly validates the credentials, stores an organization-level connection, and attempts to load the projects visible to that account. Project loading is best effort, so a valid connection can be saved even when the account cannot browse projects. Use Refresh Jira projects after correcting access.

The Jira account needs access to every project you intend to link. Automatic webhook installation also requires Jira administration permission. A missing webhook permission does not block creation of the connection or link, but Jira changes will not arrive until webhook access is available.

Create and manage sync links

A sync link pairs one Jira project with one Sharkly Space.

Open the Jira integration page.

Select Add new link.

Choose a Jira project and a Sharkly Space.

Choose a direction.

Review the issue and project status mappings.

Save the link.

One Jira project can have only one active Space link. Multiple Jira projects can link to the same Space. The Jira project and Space cannot be changed after creation; delete the link and create a new one to select different targets.

Available directions are:

Bidirectional: Jira issues and epics sync with Sharkly Tasks and Projects in both directions. New Tasks and Projects in the linked Space can create Jira issues and epics.

Jira to Sharkly: Jira issues and epics create or update their linked Sharkly records, but new Sharkly records are not created in Jira. Supported updates to records that are already linked can still be written back to Jira.

Deleting a link stops future sync without deleting Jira issues, Jira epics, Sharkly Tasks, or Sharkly Projects. Disconnecting the Jira connection disables all of its links and also leaves existing records intact.

Import Jira data

Open Settings, then Import & export, and start a Jira import. The current API flow includes these steps:

Enter the Jira host, account, token, project key, optional JQL, and target Space.

Validate the connection and review counts for issues, epics, statuses, labels, users, task types, custom fields, and existing Tasks.

Choose open issues, closed issues, or both, and exclude individual issues if needed.

Map Jira statuses.

Map Jira users or choose not to import users.

Choose import options and confirm the result.

Import options include:

Sync issues and epics after import

Add the Migrated label, enabled by default

Overwrite mutable Jira-sourced data on records imported earlier

Import Jira Sprint data

Switch the target Space to the Jira Sprint mode when Sprint import is enabled

Only one Jira import can run in a Space at a time. You can cancel an active import; records already created remain. A completed or failed import can be rolled back within seven days, which removes the Tasks and Projects created by that import but does not change Jira data. A canceled import cannot currently be rolled back automatically.

Data and mappings

The import and sync flows use these core mappings:

Jira	Sharkly
Issue	Task
Epic	Project
Issue type	Task type
Status	Task or Project status
Label	Label
Assignee and supported user fields	Member identity
Comment	Comment
Attachment	Attachment
Issue link	Task relationship
Parent and sub-task relationship	Parent and subtask relationship

For import status mapping, each Jira status can use an existing Sharkly status or create a new status with a selected category and order. If no explicit mapping is supplied, import uses category-based defaults.

For sync links, saved mappings take priority. Sharkly then tries an exact Jira status name and finally the Jira status category. A missing or invalid mapping can prevent a status update from being written to Jira.

User import is conservative by default. You can leave users unassigned, map Jira users to existing members, or invite a new member by email. If user import is disabled, assignees remain unassigned and imported comments use the importing member as author.

Members can connect a personal Jira account after an organization connection exists. Personal credentials are used for comment identity and identity-field mapping. If a personal credential is unavailable, comment publishing falls back to the organization integration account.

Permissions and security

Organization owners and admins can connect or disconnect Jira, update credentials, refresh projects, create or remove links, and start, cancel, or roll back imports.

Organization members can view connection and link status. A member can connect or disconnect their own personal Jira account.

Organization and personal Jira tokens are encrypted at rest. Connection responses expose token metadata rather than the full token.

Import credentials may be retained in encrypted job state so an interrupted import can resume and a prior import can be prefilled for re-import. Restrict administrative access and rotate Jira tokens when needed.

Jira webhooks use a connection secret, and inbound events are accepted only for active links.

Use a Jira account with only the permissions required for the selected projects, plus Jira administration permission if Sharkly must install webhooks. Rotate API tokens and personal access tokens according to your security policy.

Troubleshooting

Credentials are rejected

For Jira Cloud, use the bare *.atlassian.net host, the account email, and an Atlassian API token. For Jira Server or Data Center, use the correct base URL, username, and personal access token. Update the stored credentials after a token expires or is revoked.

No Jira projects appear

Confirm that the integration account can browse the project, then select Refresh Jira projects. Refreshing metadata does not create links or repair failed items.

Jira changes do not reach Sharkly

Confirm that the project has an active link and that the Jira account has permission to install and manage webhooks. Check that the webhook project filter covers the linked project. JQL used during import limits only the import and does not limit ongoing sync.

A status or field update fails

Review the saved status mapping, allowed Jira transitions, required fields, field contexts, and Jira screens. Give unsupported required fields a Jira default or remove the requirement before retrying.

Comments use the integration account

Connect or update the member's personal Jira account. If the personal credential is missing or invalid, Sharkly uses the organization integration account.

An attachment fails to sync

Check the attachment size, Jira attachment settings, and the integration account's file permissions, then retry the affected record.

Choose import or sync#

Connect Jira for ongoing sync#

Create and manage sync links#

Import Jira data#

Data and mappings#

Permissions and security#

Troubleshooting#

Credentials are rejected#

No Jira projects appear#

Jira changes do not reach Sharkly#

A status or field update fails#

Comments use the integration account#

An attachment fails to sync#