Jira
What is it?
Sharely reads the Jira projects where your product work is planned, and treats an issue as what was meant to ship.
That gives the product connectors the other half of the story. A merged pull request says what the code did; the issue it references says what somebody intended. Sharely reads both, and says when they disagree.
What problems does it solve?
- "Done" in Jira is not done in the docs. An issue that ships is checked against your content the same way a merged pull request is, and gets its own report.
- Code alone does not say why. A diff shows what changed; the issue says what it was for. Reports read better, and the agent can answer "what shipped this week" in product terms rather than commit titles.
- The plan and the code drift quietly. When a change references an issue, Sharely compares what was planned with what the code actually did, and says so when they differ.
Requirements
- A Sharely.ai workspace, with a GitHub connection for the code side.
- Owner or admin of that workspace.
- A Jira Cloud account that can see the projects you want read, and permission to grant an app access to them.
Note: Pick the workspace in the sidebar before you start. A Jira connection belongs to one workspace.
How to connect it
- Go to Product → Connect and press Connect on the Jira card.
- Approve the request on Atlassian's consent screen. Sharely asks for read-only access to issues, projects and users, permission to manage its own webhook, and a refresh token so the connection keeps working after you leave.
- Atlassian sends you back to the connection's settings.
- Choose the Jira site, if the account that granted access reaches more than one. One connection reads one site; press Add account on the same card to add a second.
- Pick the Projects to read, and press Save. The first read runs in the background.
How to set it up
Open the connection from Product → Connect.
Projects
Issues in the projects you pick become work items — visible in Product → Work, and beside any code change that references them. Sub-tasks are listed under their parent rather than as rows of their own.
A project you remove stops syncing. The work items already read from it stay.
When an issue counts as shipped
There is nothing to configure: Sharely reads the status and the fix version Jira already has.
| The issue | Recorded as |
|---|---|
| Status in Jira's done category | completed |
| Done, and in a released fix version | released, which says more than completed |
| In a released fix version, but not done | not shipped. Jira lets a version be released with unresolved issues in it, and those did not ship with it |
| Done with a resolution such as Won't Do, Won't Fix, Duplicate, Cannot Reproduce, Declined, Incomplete or Obsolete | not shipped. It was closed, but nothing went out |
| A sub-task, in any state | not shipped on its own. It is progress on its parent |
| Reopened | no longer shipped |
An issue that is finished and later released in a version is one shipment, not two: the release updates the existing record and does not produce a second report.
The first read of a project is a baseline. Issues that were already finished appear in Work, but they do not count as newly shipped, so connecting a project does not produce a report for its whole history.
Visibility
The roles that may see this connection's issues, in Work and beside the changes that reference them. The same rule as GitHub: a person holding none of these roles sees none of it, and visitors to your public sites never hold them.
How work items stay current
| When a project is first picked | every issue in it is read once |
| While you work | a webhook sends each change as it happens, and each version as it is released |
| Every night | a backstop re-reads anything updated since the last sync, and every issue in a recently released version, in case a webhook was missed |
Jira expires a webhook 30 days after it was registered, so the nightly pass also extends it. The Webhook row on the connection's settings says Live while it is healthy and Nightly only when it is not; press it to register the webhook again. Meanwhile the nightly pass keeps your issues current, so changes arrive late rather than never.
What it produces
Work
Every work item, grouped by status, with the code changes matched to it and whether each shipped change was checked against your content.
An issue is matched to code by its key: SHAR-412 in a branch name, pull request title, body or commit message. Keys are case-sensitive, as Jira writes them, so feat/SHAR-412-add-export matches and feat/shar-412-add-export does not.
A report when an issue ships
An issue that ships produces a report of its own, in product terms — what it changed for users, read from the issue and from any code already matched to it.
This matters for work whose code is spread across several pull requests, lives in a repository nobody connected, or is internal: the issue is the trigger, and its own words are enough when there is no diff to read. Reports resting on the issue alone carry lower confidence, and say so.
A capability in the vocabulary
A report from an issue names capabilities the same way a report from code does, so work that never produced a diff Sharely could read still reaches Capabilities and Coverage. See GitHub.
Intent on a code change
When a change references an issue, the agent is given the issue as the plan behind it — up to three per change. If the code visibly does something other than the issue described, or leaves part of it out, the report says what was planned and what was observed.
Data and privacy
- Read-only. Sharely never writes an issue, a comment or a field back to Jira. The only thing it creates is its own webhook, which it removes when you disconnect.
- Only the fields it needs. Summary, description, type, status, fix versions, resolution, labels, parent and assignee. Comments and attachments are not read.
- Issue text is treated like code. Summaries and descriptions pass through the same secret scanner as a diff, so a token pasted into an issue is redacted before it is stored.
- Descriptions are capped at 4,000 characters.
- Tokens are encrypted before they are stored and are never sent to a browser.
When something does not appear
| What you see | Usually |
|---|---|
| The Jira card says it is not set up | Sharely's Jira app is not configured on this environment yet |
| "No Jira site Sharely can read" | the Atlassian account that granted access does not belong to a Jira site. Connect with one that does |
| No work items | no project is picked yet, the first read is still running, or the account that granted access cannot see the project |
| An issue is there, no code beside it | nothing references it. Put the key, in capitals, in a branch, title, body or commit |
| A done issue shows no report | it was done before the project's first read, it was closed without shipping, it is a sub-task, or it was judged not user-facing: internal work, a refactor, tooling or research |
| An issue in a released version shows no report | it is not done. Only a finished issue ships with its version |
| An issue disappeared from Work | it was deleted, or moved to a project this connection does not read |
| Nightly only beside Webhook | Jira dropped the webhook, or it could not be registered. Press it to try again; the reason is shown beside it |
| "Reconnect" on the connection | the app was removed or the grant was revoked in Atlassian. Connect it again |
Disconnect
Settings → Disconnect removes the webhook and the stored access. Work items already read stay in the workspace, as do the reports written from them.
Learn more
- Product — how connections, changes, reports and gaps fit together.
- GitHub — the code side, which Jira work items are matched against.
- Asana — the same thing, if your team plans there instead.
- Slack — where what the connectors find gets posted.
- Integrations overview — the other ways to connect Sharely.ai.