Requirements From Trackers: Import Tickets and Trace Them to Tests

Overview

Your requirements often live in a tracker, not in a document. This feature reads tickets straight from the tracker and breaks them into requirements the same way a document is broken down. Then it traces each ticket to its tests and results.

You can read these trackers:

• Jira Cloud and Jira Data Center (Data Center has not yet been tried against a live server)
• Azure DevOps
• GitHub issues
• GitLab issues
• Confluence pages, through a Jira connection

A read-only token is enough. Shift-Left API never changes a ticket's status, assignee or text.

Before you begin

• An administrator has connected the tracker (Step 1).
• The project has an API specification or endpoints, so tickets can be matched to the APIs they likely touch.
• An AI provider is configured. Importing uses about one AI call per ticket, billed by your own AI provider. The ticket text goes to the AI provider your installation uses.

Step 1 — Connect a tracker (administrator)

1. Open Settings, then Requirement Trackers.
2. Select Add a tracker.
3. Fill in the details for your tracker:
   • Jira Cloud: the site address, the email the API token belongs to, and the token.
   • Jira Data Center: the address and a personal access token.
   • Azure DevOps: the organisation address and a personal access token.
   • GitHub or GitLab: the repository or project, and a token.
4. Set Projects that may be read. A token often sees more than a Studio project should, so list the tracker projects or Confluence spaces that people may import from. Empty means only the project the connection was set up with. Every read is checked against this list, including a typed query.

Tokens are write-only and encrypted. Self-hosted servers must be listed by an administrator. Tracker connections need no security add-on.

Step 2 — Import tickets

1. Go to Requirements, then Requirement Documents.
2. Select Add without a file, then Import from a tracker.
3. Connect: choose the connection and the project.
4. Choose what to read: this sprint, a release, an epic or feature, an area path (Azure DevOps), pasted ticket keys, words, a label, or a query (JQL, WIQL or CQL) for experts. A saved choice stays live, so "this sprint" means the current sprint at every check.
5. Preview. Nothing is spent yet. The preview shows:
   • the tree of epics, features and stories
   • a readiness reason for each ticket, from fixed rules with no AI: Ready, No acceptance criteria, No API behaviour named, Vague wording or Almost empty
   • the endpoints each ticket likely touches. A ticket nothing matches is left unticked, with the reason, so it does not cost an AI call
   • where acceptance criteria were found, for example "found on 17 of 20 tickets"
6. Import. Large imports over 200 tickets ask you to confirm.

Select Copy the not-ready list for the authors to send weak tickets back at planning.

What becomes a requirement

• One tracker ticket becomes one document. A story becomes a story plus one requirement per acceptance criterion plus any field rules.
• Epics and features are shown as headings. They become requirements only if they have acceptance criteria or you tick them.
• Tasks and bugs start unticked. Test cases are never imported.
• Acceptance criteria come from a custom field where your process has one, otherwise from a heading in the description. GitHub and GitLab have no such field, so use a heading in the issue body.
• Comments, attachments, work logs and people are not read.

Imported tickets appear under From trackers on the Requirement Documents tab. Review them like any document, with Review, Review all under <epic> or Review every ticket here.

Plan for a first big import

Extraction runs one document at a time per project, so a large first import takes a while. Start with one sprint or one epic. Jira reads 50 tickets a page. Azure DevOps reads 200 work items a call and refuses a scope over 20,000 work items.

Step 3 — Keep in step with the tracker

Select Check for changes to read the tracker again. It never uses AI.

• A changed status, sprint, label or parent is applied at once.
• Changed text waits in an inbox, ordered by risk. Tickets whose rules have passing tests come first.
• Each row shows the ticket's words before and after.

Select Apply on the ones you accept. A changed ticket becomes a new version of its document. Unchanged rules keep their review. Changed rules go back to review and their tests are flagged. Rules the ticket no longer states are listed for you to retire or keep. Then select Run only these to run just the affected tests on a non-production environment.

A finished ticket is never retired, because regression tests protect it. If part of the tracker cannot be read, such as a 403 or a timeout, nothing is treated as removed.

A source can check on a schedule, which still only reports. It can also apply changes automatically up to a monthly ticket limit that you set. Checking is by polling, so it is not instant.

Step 4 — Trace tickets to tests

1. Open Requirements, then Traceability.
2. Set Group by to Ticket.

You see epic, story, requirement, tests and result, with the ticket's own status beside it. The states are Passing, Failing, Partly tested, Not run, Not tested, Nothing to test yet and Not API-related. The word "verified" is deliberately not used, because passing tests are not proof that a ticket is right.

• Disagreements. When a story says one thing and another document or the API specification says another, the ticket shows it. A person decides which is right.
• Gaps both ways. Tickets with no tests, tests that belong to no ticket, endpoints an epic touches with no tests, and API changes with no ticket.

Choose a Jira fix version or an Azure DevOps iteration to judge a release, for example "1 of the 40 stories in release 4.2 has no passing test". Stories with no passing test block the release by default, which follows the project's release policy. See Release verdict.

You can export the matrix. See Requirements traceability matrix.

Step 5 — Use it in a pipeline

The pipeline runner can run only the tests behind the tickets in a change:

--project <id> --tickets PROJ-21,PROJ-22 --environment staging

A ticket with no tests fails the build by default, because no evidence is not a pass. Add --tickets-allow-untested to turn that off. See CI with the REST API.

Optional: put the result on the ticket

This is off by default. It needs a tick by an administrator on the connection and a tick on each source. Shift-Left API then writes one link back to Studio and a short result, such as "Passing. 3 rules, 5 tests, 5 passed, 0 failed". A comment is posted only when the state changes. It needs a Public Address that other people can reach. See Public address and desktop sharing.

What is not included

• Two-way text sync, or editing tickets from Shift-Left API.
• Real-time sync from tracker webhooks.
• Sign-in to trackers with OAuth. API tokens only.
• Linear, Asana, ServiceNow, Trello, Rally, ClickUp or Bitbucket Issues.
• Import on the Citizen Developer plan. Upload a CSV or Excel export instead.

Good to know

These readers are new. If an import behaves unexpectedly on your tracker, note the ticket type and the tracker's process template and contact support.

Troubleshooting

• No acceptance criteria were found. Choose another field, or "a heading in the description" in the preview.
• A ticket is unticked. No endpoint matched it. Tick it if you still want it.
• Check for changes found nothing, but the ticket changed. A partial read is never treated as a change. Try again.
• The import is slow. Start with a sprint or an epic.

Related articles

• Import and review requirements
• Requirements traceability matrix
• Release verdict
• AI Settings