Guide
Keep .feature files in Jira and Git in sync
By Miftode Vasilica, maker of Gherkin Studio ·
A two-way sync between Jira and Git has one hard case: the same scenario was changed in both places since the last sync. Everything else is a copy. A sync you can trust copies when only one side changed, and stops and shows you both versions when both did. This page explains the cases, and how Gherkin Studio handles each one.
The scenario that changed twice
Monday morning the product owner opens a story in Jira and changes "one hour" to "30 minutes". She saves and goes to a meeting.
Monday afternoon a developer opens the same .feature file in the repository. He adds a scenario for an already-used link, commits, pushes.
Both of them are right. Both changes should survive. A sync that simply takes the newest version throws one of them away, and nobody notices until the test fails, or worse, passes.
The three cases
Every sync compares three texts: what Jira has now, what Git has now, and what both had after the last successful sync.
| What changed since the last sync | What a safe sync does |
|---|---|
| Only Jira | Writes the Jira text to the file in Git |
| Only Git | Brings the file's text into Jira |
| Both | Stops. Shows both versions. A person chooses |
The third row is the one to ask any vendor about.
How Gherkin Studio does it
One file per story. Each story syncs to <folder>/KEY-123.feature in the repository, branch and folder the project admin picked. The file name carries the issue key, so nothing has to guess which story a file belongs to.
You press the button. Sync with Git is in the Gherkin Studio panel on the story. Nothing moves in the background while you are typing.
When both sides changed, you get a line-by-line comparison and three choices: Keep Jira version, Keep Git version, or Use the editor text if you merged the two by hand.
If Git changes again while you are deciding, you are shown the new version. Your choice is never applied to a file you have not seen.
The first sync never overwrites. When a story and a file both already have text and they were never synced, that counts as "both changed", and you choose. The same happens after an admin changes the repository, branch or folder.
Broken scenarios stay in Jira. A scenario with a syntax error can be saved, so a half-written idea is not lost. It is never pushed to Git, where it would break the build.
Line endings do not count as a change. Windows and Unix line endings, and spaces at the end of a line, are ignored when the two sides are compared. A colleague's editor settings will not produce a conflict.
Connecting the repository
A project admin opens Project settings → Gherkin Studio, picks the provider, repository, branch and folder, and pastes a token. The connection is tested before it is saved.
Give the token access to this one repository and nothing else:
- GitHub: a fine-grained personal access token with "Contents: Read and write" on this repository only.
- GitLab.com: a personal access token with the
apiscope. On GitLab Premium, a project access token withapiand the Developer role. - Bitbucket Cloud: a repository access token (Repository settings → Access tokens) with Repositories: Read and Write. Not your Atlassian account API token.
The token is kept in Forge secret storage.
Which side should be the source of truth?
Teams ask this first, and the honest answer is that it depends on who writes.
- If product owners and testers write most scenarios, they write in Jira and the repository receives.
- If developers write most of them next to the code, Git leads and Jira shows.
- Most teams are both, on different days. That is why the conflict case matters more than the rule.
Whichever you pick, tag every scenario with its issue key. See how to link scenarios to Jira issues.
Short answers
Does the sync run on every push?
No. In Gherkin Studio a person presses Sync with Git on the story.
What if the file was deleted in Git?
You are asked: keep the Jira version and re-create the file, or clear the scenarios in Jira. Deleting a file never silently deletes scenarios in Jira.
Does it work with self-hosted Git?
Not today. Gherkin Studio works with GitHub, GitLab.com and Bitbucket Cloud.
Where Gherkin Studio fits
Gherkin Studio is a BDD app for Jira Cloud, built on Atlassian Forge. It is on the Atlassian Marketplace, with a 30-day free trial. Read the Git sync section of the docs.