Gherkit user guide

Gherkit lets you write BDD scenarios in Gherkin on Jira issues, see them all as living documentation, and connect them to your Cucumber test runs.

Write scenarios on an issue

1. Open an issue, click Apps (under the summary) and choose Scenarios.
2. Click Write scenarios. Gherkit starts a feature named after the issue and tags it with the issue key (for example @SHOP-12). That tag links test results back to the issue.
3. Write your scenarios. As you type:
   • Problems appear under the editor and in the margin: broken tables, Examples columns that don't match the <placeholders>, scenarios with no steps, steps written outside a scenario.
   • After Given, When, Then, And or But, suggestions show steps your project already uses, so wording stays consistent.
   • Format fixes indentation and lines up tables.
4. Save (or Ctrl+S / Cmd+S).

If someone else saves the same issue while you're editing, Gherkit tells you and lets you load their version or keep yours. History shows earlier versions, and you can restore any of them.

Living documentation

In a project, open Apps > Living documentation in the sidebar. You'll see every issue with scenarios, how many are failing, passing or not run, and each feature's tags. Click a row to read the feature with its latest results.

• Export .feature files downloads a zip laid out the way your admin chose (flat, by project, or by project and epic).

• Import reads .feature files or a .zip of your features folder (up to 500 files at a time). Each file goes to an issue chosen in this order:

  1. the issue named in a @KEY-123 tag above Feature:;
  2. the key its file name starts with;
  3. a single @KEY-123 tag shared by its scenarios.

  You see exactly what will be created or replaced before anything is written.

Run the scenarios in CI

1. Download gherkit-ci.mjs from Living documentation > Set up CI (or the settings page) and commit it to your repository. It's one file with no dependencies, and needs Node.js 18 or newer.
2. Create a Jira API token for a CI user who can browse the project (to pull) and edit issues (to store results). Save the user's email and the token as CI secrets.
3. Add these steps to your pipeline:

export JIRA_SITE=https://your-site.atlassian.net JIRA_EMAIL=... JIRA_API_TOKEN=...
node gherkit-ci.mjs pull --jql "project = SHOP" --out features
<run Cucumber with a JSON report, e.g. --format json:reports/cucumber.json>
node gherkit-ci.mjs push --report reports/cucumber.json --projects SHOP --run-name "Build 42" --run-url "$BUILD_URL"

--projects tells the helper which tags are Jira issue keys. Tags like @TC-5 or @REQ-9 are then ignored, and a missing issue is reported as a warning rather than failing the build.

Which test runners work: tested with cucumber-js. Cucumber-JVM writes the same JSON report. Behave, SpecFlow/Reqnroll and Behat need a plugin or converter that writes Cucumber JSON.

Results then appear on each issue:

• a ✓ or ✕ next to every scenario and every Examples row,
• the error message for each failure,
• a link back to the build.

Use JQL to build dashboards, for example gherkitStatus = failed AND sprint in openSprints().

pull keeps a list of the files it wrote in features/.gherkit-pull.json. With --clean, it deletes files from earlier pulls that are no longer in Jira, and never touches any other file. Add --dry-run to see what would happen first.

Moving from Behave Pro

As of October 2026, Behave Pro's Jira Cloud app appears to still run on Atlassian Connect (version 2.0.66-AC), which loses support on 31 January 2027. Check with Hindsight Software for their plans.

1. Get your feature files. If you used Behave Pro's Git sync, they're in your repository. If not, export them from Behave Pro first.
2. Check how each file links to its issue. Gherkit accepts a @KEY-123 tag above Feature:, a file name starting with the key, or the same @KEY-123 tag on all its scenarios. The import preview shows any file it can't place, and why.
3. Zip the folder and use Living documentation > Import. Check the preview, then import.
4. Replace Behave Pro's sync with the two CI steps above (pull before your tests, push after them).

Moving from Cucumber for Jira (SmartBear)

Follow the same steps: import the .feature files from your repository, then add the pull and push steps to CI. That app keeps its issue links inside the app, so your files may have no issue tags. Start each file name with the issue key (for example SHOP-12-login.feature) before importing, or add @SHOP-12 above Feature:.

Questions

Email support@gherkit.com.