Scenario Book for Jira

Sync with Git

Your own pipeline keeps the feature files in your repository and the scenarios in Jira in step. Scenario Book never reaches out of Atlassian; your pipeline calls in, with a key you give it, and reads Jira's changes back with its own Jira credentials.

DirectionHowAuthenticated with
Git → JiraYour pipeline sends changed files to Scenario BookA sync key from Project settings
Git → Jira, test resultsYour pipeline sends its test reportThe same sync key
Jira → GitYour pipeline reads the files Scenario Book published to the projectYour own Jira API token

Turn it on

  1. Project settings → Apps → Scenario Book → Pipeline sync → tick Turn on pipeline sync.

    Turning sync on publishes this project's feature files into Jira project properties so your pipeline can read them. Anyone who can browse the project can read them. Turning sync off takes them back.

  2. Create a sync key on the same page and give it a name, such as main pipeline. It is shown once: copy it then. Scenario Book stores only a hash of it. A key works for this one project and can be revoked any time.
  3. Copy the two addresses under Pipeline URLs on the same page: one for files, one for test results.
  4. Create a Jira API token for the account your pipeline reads as (id.atlassian.com → Security → API tokens). That account needs Browse projects on this project and nothing more.
  5. Put these in your CI's secret store, then add the step for your CI below.
JIRA_BASE_URL=https://your-site.atlassian.net
JIRA_EMAIL=pipeline@yourcompany.com
JIRA_API_TOKEN=<the API token>   # secret
JIRA_PROJECT=PAY
SB_SYNC_KEY=<the sync key>      # secret
SB_PUSH_URL=<the files trigger address>
SB_RESULTS_URL=<the results trigger address>
SB_DIR=features          # optional: where your .feature files live
SB_LABEL=nightly         # optional: names this pipeline in the results

The scripts

Download the one for your CI. Each calls scenario-book-sync.mjs (Node 18 or later, no dependencies), or the shell script for push and results.

The CI templates are starting points: check them against your own pipeline before you rely on them. The Node script is tested against a simulated Jira; the shell script and the five CI templates have not yet been run in real CI services. The terms of service cover these files, including the disclaimer.

How a sync runs

  1. Pull first, then push. sync does both in that order. Pushing first sends Jira a repository that has not caught up, which can turn changes made in Jira into conflicts someone has to resolve by hand.
  2. Jira's changes land on a branch, scenario-book/from-jira, for review: the GitHub template opens a pull request, the GitLab one a merge request, and the Bitbucket and Azure ones push the branch for you to open one. Nothing is committed straight to your main branch.
  3. A push sends the repository's feature files and the list of every one it holds. A file missing from that list is treated as deleted in Jira, where it can be restored for 30 days. The scripts refuse to push at all if they find no feature files, so a wrong folder can't empty your project.

When both sides changed

If both Jira and the repository changed the same scenario, Scenario Book records a conflict and writes neither version over the other. The story shows both versions side by side, and someone chooses Jira's, the repository's, or an edit of their own. The next pull carries the choice back.

What a push tells you

The project page's Sync tab shows whether sync is on, each key and when it was last used, the last push and results upload, and any open conflicts. It also has every script below, with Copy and Download.

Your pipeline prints, by name, any file that was a conflict, could not be read, was refused (not a .feature file, or a path outside the project), was saved in Jira while the push ran, or differs from Jira and needs a pull.

Limits