Gherkit documentation

Get started

1. Install Gherkit from the Atlassian Marketplace (Jira admin). Every site gets Atlassian's 30-day free trial. After that it is $10 a month for 1 to 10 users, then billed per user.
2. Open any issue. The Scenarios panel shows the scenarios linked to that issue and their latest test result. If there are none yet, it shows No scenarios yet.
3. Open a project and choose Scenarios in the project sidebar. This page has six tabs: Scenarios, Feature files, Step library, Test runs, CI and Activity.
4. Write your first scenario: on an issue, click Add scenario, or on the project page open Feature files and click New feature file.
5. Optional: connect your CI on the CI tab so your pipeline can pull feature files and post results back.

Scenarios live in feature files, stored as plain Gherkin text. Gherkit adds two kinds of ordinary tags to that text: @sc-12 (a stable scenario ID) and @PAY-142 (a link to issue PAY-142). Because they are standard tags, your feature files still run in Cucumber and round-trip through Git unchanged.

The Scenarios panel on an issue

The panel lists every scenario tagged with the issue's key:

• A summary line with the number of scenarios and lozenges for passing, failing and not run.
• One card per scenario with its status (Passed, Failed, Skipped or Not run), name, ID (for example sc-12), feature name, when it last ran, and the scenario's Gherkin with syntax highlighting.
• Last failure: for a failed scenario, the failure message from the latest test run.
• If some linked scenarios are in projects you can't browse, the panel says how many and doesn't show them.

Buttons (shown if you have the Edit issues permission and the license is active):

• Add scenario: opens Add a scenario. Pick the Feature it belongs in (an existing feature file, or New feature file) and click Write scenario. The editor opens with a new scenario block tagged with the issue key, ready for you to fill in. With New feature file, the Feature and the Scenario are titled with the issue's summary (read with your own Jira permissions); rename them as you like.
• Link existing: opens Link an existing scenario. Search scenarios in this project, pick one and click Link. Gherkit adds the issue key tag to that scenario. A scenario can cover any number of issues.
• Edit feature (on each card): opens the whole feature file in the editor.
• Unlink from the issue (on each card): removes that issue's tag from the scenario and leaves its other tags alone.

The feature file editor

The editor opens in a window from the issue panel or the project page.

• Path in exports and Git: where this file goes in exports, for example features/checkout/discounts.feature. Leave it empty on a new file and Gherkit uses features/<feature name>.feature, adding a number if that path is taken. Paths must be relative, end in .feature and use letters, digits, spaces, -, _, . and /.
• Keyword and Add a step from the library: choose Given, When, Then, And or But, then type to search steps your team already uses. Each suggestion shows how often it is used. Choosing one adds the step as a new line at the end of the file, with parameters turned into placeholder text you can edit.
• Three tabs:
  • Edit: the Gherkin text.
  • Preview: the file with Gherkin highlighting and line numbers. Lines with errors or warnings are highlighted.
  • Checks: every problem with its line number and severity (error, warning or info). The tab title shows the number of errors and warnings.
• Below the tabs, a line shows how many scenarios, errors and warnings the file has.

Buttons:

• Check: runs the checks now. They also run when you click out of the text box.
• Format: re-indents the file and lines up every table (numbers right-aligned). Comments and doc strings are kept, and the meaning of the file doesn't change.
• Save: disabled while the file has errors. Warnings don't block saving. On save, every scenario without an ID gets an @sc- tag.
• Cancel

What the checks catch

Errors (block saving):

• Gherkin syntax errors, such as steps or tables outside a scenario, table rows with uneven columns, unclosed doc strings, tags with nothing after them, or a second Feature in one file.
• A Scenario Outline with no Examples, or Examples with no table.
• A <placeholder> used in the steps but missing from the Examples columns.
• An Examples column that appears twice.
• Examples under a plain Scenario (they only work with Scenario Outline:).
• Keywords in a language other than English.

Warnings:

• A feature or scenario with no name, a feature with no scenarios, a scenario or Background with no steps.
• Two scenarios with the same name (reports match scenarios by name, so names should be unique).
• Steps out of order (a Given or When after a Then, for example), a scenario that starts with And or But, and a scenario with no Then step.
• When or Then steps in a Background.
• Examples columns not used in any step, Examples with a header but no rows, and placeholders in a scenario that is not an outline.
• A step that matches wording marked as deprecated in the step library, with the library note if there is one.

Information:

• New step: a step that matches nothing in the step library yet. If similar steps exist, the message lists them and the Checks tab shows a Use button for each one that replaces the line with the library wording.
• A step that matches more than one library step.

Two people editing the same file

Saving is conflict-safe. If someone else saved the feature after you opened it, you see Someone else saved this feature first and nothing is overwritten. Copy your changes, close the editor, open the feature again and merge them.

If you can read the project but don't have the Edit issues permission, the editor opens read-only.

Scenario IDs and issue tags

• @sc-12: added to each scenario the first time it is saved. IDs are unique within a Jira project and never change. If someone deletes the tag, the scenario gets its old ID back when it is saved with the same name. A copy-pasted scenario whose ID is already used gets a new one.
• @PAY-142: links the scenario to issue PAY-142. Add these with Add scenario and Link existing, or type them yourself. A scenario can have any number of issue tags. Tags on the Feature line apply to every scenario in the file, and tags on a Rule apply to every scenario in that Rule.

Keep both kinds of tags when you store feature files in Git. Test results are matched by the @sc- tag first.

The project page

Open Scenarios in the project sidebar. The top line shows the number of feature files, scenarios and linked issues, with passing, failing and not run counts.

Scenarios tab

Every scenario in the project in one table: ID, Scenario, Feature, Issues, Last result and Last run. Use Search (name, ID, tag or issue key) and the Status filter (All statuses, Failed, Passed, Not run). Open opens the scenario's feature file in the editor.

Feature files tab

Every feature file with its Path, Feature name, number of Scenarios, Results (passing, failing and not run counts) and Updated (version and time).

• New feature file opens the editor with an empty feature.
• Edit opens a file (View if you can only read it).
• Download saves that file as a .feature file, with its @sc- and issue tags. Anyone who can browse the project can download, with or without an active license. Each click makes a link that works for 10 minutes and only for that one file; Jira may ask you to confirm before opening it. To get every file at once, use the zip command on the CI tab.
• Delete asks for confirmation (the window has a Download .feature file button so you can keep a copy first), then removes the file, its scenarios, their latest results and their issue links. Past test runs keep their counts, and their results for removed scenarios show as "(deleted scenario)".

Step library tab

Every step your team writes is collected here automatically when a feature file is saved, with quoted text and numbers turned into parameters. The table shows the Step, what it is Used as (Given, When or Then), Uses and Notes.

• Add step: add a step before anyone uses it. The window has Step (Cucumber Expression), Usually used as, Notes for writers and Deprecated: warn when someone uses this wording. Parameters: {int}, {float}, {word}, {string} and {}; optional text in brackets, such as item(s); alternatives with a slash, such as button/link.
• Describe: add a note or deprecation to a step that was collected automatically.
• Edit and Remove: change or remove steps you added or described. Steps that are still used in feature files stay in the list.

Steps you added or described show a library lozenge; deprecated steps show deprecated. The editor warns whenever someone writes a deprecated step.

Test runs tab

The 20 most recent runs posted by CI: When, Build (the label your CI sent), Report format, Results (passed, failed, other) and Unmatched. Details shows each scenario's result with its failure text, and a Report entries that matched no scenario list.

CI tab

The endpoint URL, the project's token and ready-to-copy commands. See the next section.

Activity tab

The 200 most recent changes in the project: When, Who (the person's name and avatar as Jira shows them to you, or CI) and What. It records feature files created, updated and deleted, links and unlinks, step library changes, token changes, CI result posts and imports.

Connecting your CI

Your CI calls Gherkit; Gherkit never calls out. On the CI tab:

1. Copy the Endpoint URL.
2. Click Create token (project admins and Jira admins). Copy it right away: it is shown only once. Store it as a CI secret named GHERKIT_TOKEN.
3. Copy the ready-made commands under CI variables (store the token as a secret), Pull feature files before the test run (zip), Post results after the run (Cucumber JSON or JUnit XML) and Optional: push .feature files from Git into Jira (mirror=true also removes deleted ones).

Replace token issues a new token and the old one stops working immediately. Revoke removes it. The tab shows when the token was created and last used.

Send the token as Authorization: Bearer <token> on every call. Operations:

Posting results

Gherkit detects the report format automatically:

• Cucumber JSON (cucumber-js, Cucumber-JVM, Behave, SpecFlow and Reqnroll Cucumber JSON output): matched by the @sc- tag, then by feature and scenario name.
• JUnit XML (any runner): matched by feature and scenario name, then by a scenario name that is unique in the project, then by an sc-12 ID anywhere in the test name.
• Simple JSON for scripts: {"results":[{"id":"sc-12","status":"passed"}]}.

A Scenario Outline counts as one scenario; if any Examples row fails, the scenario is failed. Each run updates the scenario's latest result, the issue panel and the JQL fields of every linked issue. Report entries that match no scenario are listed in the run's Details. The usual cause is feature files in Git without the @sc- tags: pull the feature files before the test run, or import them so the tags match.

Importing existing feature files

Use the import command to bring a Git folder of .feature files into Jira. Files that haven't changed are skipped. Each new scenario gets an @sc- ID, and issue key tags already in the text become links. Files with errors are not imported; the response lists each file with its result and any errors. To keep the IDs in Git, pull the files back after the first import and commit them.

Finding issues with JQL

Gherkit keeps three searchable fields on every issue it has linked scenarios for:

• bddScenarios: number of linked scenarios, for example bddScenarios > 0.
• bddFailing: number of linked scenarios whose latest result failed, for example bddFailing > 0.
• bddStatus: failing, passing, not-run or none, for example bddStatus = failing.

Saves, links and result posts update up to 25 issues straight away. Any more are updated by an hourly background job, so after a large change some issues can take up to an hour or more to show in JQL.

Who can do what

Gherkit uses your Jira project permissions, checked on every action:

• Browse projects: read scenarios, feature files, results, the step library and activity.
• Edit issues: add, edit, format, save, delete, link and unlink scenarios, and edit the step library.
• Administer projects (or Jira admin): create, replace and revoke the project's CI token.
• Your CI: whoever holds a project's token can pull that project's feature files and post results and feature files to it.

Licensing and trials

Gherkit is paid through Atlassian, with Atlassian's 30-day free trial. There is no free tier.

Each band's rate applies to the users inside that band. For example, 25 users cost $93.75 a month. Annual billing is 10 times the monthly price. Atlassian handles billing, invoices and refunds.

If the license is not active, Gherkit becomes read-only:

• A Gherkit is read-only on this site banner appears on the issue panel and the project page.
• Add scenario, Link existing, Edit feature, Unlink, New feature file, Delete and Add step are hidden, and saving is refused with a message to renew in Apps > Manage apps.
• CI result posts and imports are refused with status 402.
• Everything stays readable, Download still works, and CI can still pull your feature files, so you never lose access to your own scenarios.

Permissions and data

• Gherkit runs entirely on Atlassian's Forge platform (Runs on Atlassian). It has no external network permissions and sends nothing to any outside server, including Great Work. Your CI sends data in through an endpoint hosted by Atlassian.
• The app asks for three Jira scopes: app storage, reading Jira work (to check your project permissions and that an issue exists before linking it), and writing Jira work (to set the searchable gherkit issue property used by JQL).
• Stored in Forge storage for your site: feature files and their versions, the scenario index (names, tags, linked issue keys), the step library and its notes, test results (status, duration, failure message, run label, names of unmatched entries), the activity log (account IDs, not names), a random key that signs download links, and for the CI token only a SHA-256 hash, a short hint and who created it. The token itself is never stored.
• On linked issues, Gherkit stores the scenario count, failing count and status as an issue property for JQL.
• Retention: feature files stay until you delete them in the app or a mirror import removes them. Only the newest 200 test runs per project are kept; older runs are deleted automatically.
• Great Work can't see your Jira data or anything Gherkit stores.

Limits and known gaps

• English Gherkin keywords only. Files with a # language: header for another language show an error.
• Feature files up to 256 KB each, and up to 2,000 feature files per project.
• Test reports up to 5 MB per post (413 above that). Send one report per feature folder, or JUnit XML, which is smaller.
• Up to 500 files per import request.
• Matching by name can't tell apart two scenarios with the same name; those results are listed as unmatched. Keep the @sc- tags in your test runs to avoid this.
• The Test runs tab shows the 20 most recent runs, and the Activity tab shows the 200 most recent changes.
• The Download button saves one feature file at a time. Bulk export (zip or JSON) goes through the CI endpoint.
• Step suggestions from the library are added as a new line at the end of the file. Move the line where you need it.
• The JQL fields exist only on issues that have had linked scenarios; issues that never had any don't match bddStatus = none.
• Gherkit has no Data Center or Server version.

FAQ

Do scenarios have to map one to one onto Jira tickets? No. Scenarios live in feature files, and a scenario can be linked to any number of issues by tag. Each issue's panel shows every scenario that covers it.

What happens when a Git sync or webhook breaks? There is nothing to break. Gherkit has no webhooks and no Git integration: your CI pulls feature files with a token before the test run and posts results after it. If a post fails, the next run updates everything.

Can my team reuse the steps it already wrote? Yes. The step library collects every step automatically, shows usage counts, and the editor suggests library wording as you type and when a step is new. You can add notes and mark old wording as deprecated.

Can I count scenarios or report on which ones pass? Yes. The project page lists every scenario with its latest result, and JQL (bddScenarios, bddFailing, bddStatus) finds issues by scenario coverage and status.

Will I be asked to pay during the trial? No. Billing goes only through Atlassian: the 30-day trial, then your Atlassian subscription. Great Work never asks you for payment details.

Can I bring scenarios from another BDD app or from Git? Yes. Export them as .feature files and run the import command from the CI tab. Issue key tags in the text become links.

Is it still maintained, and can I get help? Yes. Support requests get a first response within 1 business day.

Does my data leave Atlassian? No. Gherkit runs on Atlassian's Forge platform and has no external network permissions.

Uninstalling and your data

Before uninstalling, pull your feature files with the CI endpoint (GET ?op=features) if you want to keep them. When the app is uninstalled, Atlassian deletes Gherkit's stored data for your site under its Forge data deletion process. The gherkit issue property stays on issues as inert data unless you remove it.

Support

Open a request in the Great Work support portal (linked from the Marketplace listing) or email hello@greatwork.company. First response within 1 business day.