Get started

A step-by-step setup runbook for a Jira administrator installing Nexus, and for the first tester who creates and runs a test. Follow it top to bottom on a new project — the same checklist Nexus Setup itself walks you through.

Before you start

You'll need:

• A Jira admin for steps 1–2 and the project-provisioning parts of step 3 — Nexus Setup asks Jira to create issue types, workflows and a project role, which needs admin-level permission the first time.
• A pilot project to provision first. Any company-managed or team-managed software space works. When you create a space, Jira asks how it is managed and recommends company-managed; either choice is fine, but the setup steps differ (step 3). Nexus can also create a sample project for you if you don't have one yet.
• At least one requirement (a Story or Epic) in the pilot project, so your first test case has something to link to.
• (Optional) an API key from Anthropic, OpenAI, Google Gemini, Moonshot Kimi or xAI Grok if you plan to turn on AI requirement analysis and test generation. Every other feature works without one.

Nexus is available now on the Atlassian Marketplace. All features are included, with pricing based on your Jira user tier. Marketplace manages licensing and billing. View current pricing or talk to the Nexus team for help planning a rollout.

1. Install Nexus

Open Nexus: Test Management for Jira on the Atlassian Marketplace. Choose the installation option shown for your Jira Cloud site and follow Atlassian's prompts. A Jira administrator completes the installation.

During install, Jira shows you the permissions Nexus asks for — read/write access to Jira work items; a configuration scope it uses only to provision its own issue types, workflows and project roles; a project scope used only to create a Fix Version from the Releases page; read-only sprint and board access for report filters; Confluence page and folder access for Publish to Confluence; and Atlassian's personal data reporting API. Optional AI providers, CI dispatch and direct migration connections can send selected data to configured services when used. Review the trust and security overview for those boundaries.

Installation finishes in seconds. Nothing is provisioned on any project yet — that's step 2.

2. Run Nexus Setup

Open the Apps menu → Nexus, then press Nexus Setup at the top right (it is also under Jira settings → Marketplace apps → Nexus Setup). Only Jira admins can open it. The Nexus page also lists Projects not set up yet, each with an Open Nexus Setup button that opens setup on that project.

The fast way: Quick setup (company-managed spaces). On the Setup Checklist, below the Health and Recompute coverage panels, choose your pilot project (it is already chosen if you came from Open Nexus Setup) and press Set up KEY. Nexus creates anything site-wide that's missing (issue types, link types, statuses, workflows, roles). It then adds Test Case, Test Set and Test Execution to that project and switches them to the Nexus workflows. If the project shares a scheme with other projects, Nexus shows you what else would change and waits for you to confirm. When it reads KEY is ready for Nexus, add the Nexus tab to the space (step 3, Add the Nexus tab to the space; the message has an Open KEY in a new tab button), then press Open Test Hub for KEY. If you pick a team-managed project here, Quick setup sends you to the Team-managed Projects page instead (step 3).

To look around before you touch a real project, press Create sample project instead. You get a new company-managed project with test cases, a cycle and results already in it, every issue labelled nexus-sample. Add the Nexus tab to it the same way before opening its Test Hub.

The full checklist. The Setup Checklist page is the one-time, site-wide half of provisioning — issue types, workflows, schemes and roles for company-managed projects, plus optional sample data. Press Create now and work down its rows; each has a live check and, where Jira allows it, a one-click fix. Re-running it later is always safe — it's idempotent, and adopts whatever already exists rather than duplicating it.

Team-managed (next-gen) projects are different — they keep their own work types, statuses and workflows, so Nexus sets each one up individually rather than once for the whole site. If your pilot project is team-managed, skip to step 3; the Setup Checklist page doesn't touch it.

3. Add Nexus to a project

For a team-managed project, open Nexus Setup → Team-managed Projects and choose your project (the Open Nexus Setup button on the Apps → Nexus page opens this page with the project already chosen). The page walks you through four actions:

1. Create the three work types yourself, in Jira. This is the one step Jira gives no API for. In the space: ••• → Space settings → Work types → + Add work type (the page links straight there, in a new browser tab). In the Create work type dialog, create all three with these exact names: Test Case, Test Set, Test Execution. Create them as standard work types, not sub-tasks. Then go back to the Nexus Setup tab and press Re-check work types. Each one shows created.

2. Set up this project. One button. Nexus creates the project's own statuses (Draft, Ready, Not Run, Pass, Fail and the rest) and its three workflows, attaches its validator and post-function guard rules, and switches the three work types onto them. If it says Jira is finishing the workflow change, press Check progress until it reads set up for Nexus. Safe to press again at any time.

3. Check this project's health. Confirms every work type, status and workflow Nexus needs is present and correctly wired, and calls out the exact fix if a status or workflow was later renamed. Green means This project looks healthy.
4. Add the Nexus tab to the space and turn on modules (you do this in Jira and in the Nexus tab; see the two paragraphs after the company-managed section below).

For a company-managed project, the same outcome comes from the Setup Checklist rows in step 2 (workflow scheme mapping, then issue type scheme) — pick your project in each row's picker, confirm the "what will this change" summary, and apply.

Either way, a project administrator who isn't a Jira admin can do the same thing from inside the project itself: Test Hub → Project Settings → General Preferences → Add Nexus work types, no site-admin access needed.

Add the Nexus tab to the space. Jira never adds an app's tab to a space's navigation by itself. In the space, press + (Add to navigation) at the end of its tabs, scroll the menu down to Apps, choose Nexus, and press Add to navigation. Do this once per space. The first time the Nexus tab opens it can take up to 30 seconds while Jira loads the app; after that it opens quickly.

Turn on the modules you need. In the Nexus tab, open the settings menu → Project Settings → Modules, or use Modules beside the settings gear. Optional modules start off in a new project, including Reports. Switch on the ones your team will use and press Save in the settings page. The top-bar shortcut saves each switch immediately. Nothing is deleted when a module is off.

Optional: roles. You don't need to assign anyone to start. Nexus's workflow conditions are open to everyone until you configure them. To limit who may mark a test Ready or record a result, add people to the Test Designer, Test Executor and Approver roles (Space settings → People in a company-managed space, Space settings → Access in a team-managed one), then pick those roles on the condition in Jira's workflow editor. On the Jira Free plan roles can't be assigned, so the conditions stay open.

4. (Optional) Connect your AI account

Skip this step if you don't want AI — every other feature already works.

Open Nexus Setup → AI setup and connect an API key from Anthropic, OpenAI, Google Gemini, Moonshot Kimi or xAI Grok. Nexus uses your account and your terms; it never bills you for model usage and sets no usage cap of its own beyond what your own account allows. To keep an eye on spend, set token usage alerts on Nexus Setup → AI usage, and switch AI off for a project in its Project Settings → AI if you need to.

Every AI output — a requirement-quality finding or a drafted test case — is staged for review and never written to a live Jira issue until a person approves, edits and approves, or rejects it. Turning this on changes nothing about how your existing tests or requirements look; it only adds a review queue.

5. Understand the test design your team will use

Before creating your first test, decide which design fits: a step table (action, data, expected result per step), Gherkin/BDD (Feature and Scenario text, exportable as .feature files for Cucumber), a checklist, or free text for a quick narrative case. You can mix designs freely across a project — this is a per-test-case choice, not a project setting.

6. Create your first test

The Test Hub's Overview opens with a Quick start list: switch Nexus on, write a test case with steps, plan a cycle, record a result, see it in a report (and, once an AI account is connected, draft test cases with AI). Each step ticks itself off from your project's real data, and the next step always has its own button. A project admin with an empty project can press Add sample data to see the whole flow straight away (company-managed spaces only). Remove sample data deletes exactly those issues. By hand, the steps are:

1. Open the Nexus tab → Cases → Write the first test case. Give it a name and steps (or Gherkin, or a checklist — see step 5), and pick the requirement it tests under Jira Requirements. Nexus links them with the Tests link type. The list shows the space's Stories and Epics, so create one first if the space is new.
2. Mark it Ready from its status menu. The guard rule confirms every step has an expected result before it lets you.

3. Open Sets, press + to create a set, open it and use + Add Cases. Then use the set's ⋯ menu → Create Cycle.

4. Open the cycle from Cycles and expand the test to run it: record an actual result and a result for each step, and attach evidence as you go. On a failed step, press its bug icon to link an existing Bug or create one. The new Bug is pre-filled with the steps to reproduce and linked to the execution and the requirement. Press Complete run when every step has a result.

That's a complete requirement → test → run → evidence loop, the same one Nexus uses for every test in a project from here on.

7. Connect CI results (optional)

If your team already runs automated tests in GitHub Actions, GitLab CI, Jenkins or Azure Pipelines, you don't need to record those results by hand. Generate an API key under the project's Project Settings → CI, and send your results file to the ingestion URL shown there — one API key, one URL, no other configuration.

Automated tests run in your own CI or on a customer-hosted runner. Results return to Nexus, matched by Automation Key or issue key. Use the CI guide for pipeline snippets and the automation guide for framework setup.

To start a pipeline from a cycle, a project administrator connects GitHub Actions, GitLab.com, Azure DevOps Pipelines or Bitbucket Pipelines once. Run in CI then starts the pipeline with the selected project, cycle, environment and build context, and results come back to the same cycle. For Jenkins or self-hosted GitLab, use the customer-hosted Nexus runner.

For reporting integrations, an administrator can separately enable Read test data on a project API key. Read test cases, cycles, runs, step results and coverage as paged JSON through the read-only API. This permission is off by default and is never added to existing keys.

8. Add reporting and dashboards

Once you have a handful of executions recorded, add a Nexus gadget (Coverage Status, Test Execution Status, Requirement Quality, or Burndown) to a Jira dashboard, or open the Reports tab in the Nexus tab (turn on the Reports module first, step 3) for the fuller set — traceability, defect trend, workload by tester, test-case ageing and coverage by version.

Possible issues and how to fix them

What's next

You've installed Nexus, provisioned a project, and run one test end to end. From here:

• Read the product guide for the full detail on test design, reuse, model-based testing, planning and reporting.
• Read the CI guide to wire up automated results from your existing pipeline.
• Repeat step 3 (add Nexus to a project) for every other project your team tests in — everything else in Nexus Setup is a one-time, site-wide checklist.
• Set up regular backups in Nexus Setup → Backup & Restore. Your Jira backup does not include Nexus's own data. The backup and recovery guide (docs/backup-and-recovery.md) covers backups, what an uninstall keeps, and recovery after a reinstall.