Two-way Git synchronisation

Owned by Maryna Pristrom
Last updated: Sept 16, 2019

Starting from plugin version 3.0.0 it is possible to use Git for saving stories into a remote Git repository. The plugin supports pulling down as well as pushing up the changes, hence achieving a two-way synchronisation with the remote Git repository. This is useful as some of your more technical team members may wish to commit further changes to stories directly from their IDEs as they work on implementing the functionality.

By default the plugin is configured to use Jira’s database for storage, to use Git instead go to the plugin configuration page, then Storage tab and choose Git like shown in the screenshot below.

Additional information on some of the input fields

Subdirectory - if you specify a path to a folder into this field then new story files will be added to this directory; if you leave this field blank then new story files will be added to the root folder of the repository. Note that this field supports the use of the following placeholder ‘${component}', e.g. ‘src/test/resources/${component}/stories', in this example if the issue to which the story is attached happens to have the issue component field populated e.g. ‘componentA’ then the added story will be placed into the directory “src/test/resources/componentA/stories“ and if the issue’s component field is blank then the directory path used will be 'src/test/resources/stories'. If the issue happens to have several values for the component field, then only the first one specified will be used and others ignored.

Committer name - value to use for the committer name attribute of the git commit. If left blank then the name of the Jira user making the changes will be used. Note that Jira user name will always be used for the author name attribute of the git commit irrespective of this field.

Committer email - value to use for the committer email attribute of the git commit. If left blank then the email configured in Jira belonging to the Jira user making the changes will be used. Note that Jira email address will always be used for the author email attribute of the git commit irrespective of this field.

Stories base branch - the base branch of the git repository. If git branch workflow is enabled then new feature branches will be created from this branch. If git feature branch workflow is disabled then all story file changes will be committed directly to this branch.

Branch per issue - enables/disables git feature branch workflow support. See further information on this page.

Reports branch - while using git storage option story execution reports as well as story files are stored in the git repository. Value in this field controls which branch to use for the execution reports. Note that the branch prefix/type must be “notes“, e.g. refs/notes/reports.

Sync frequency - controls how frequently to pull down changes from the remote repository. Note that changes to story files made via the plugin interface are pushed instantly to remote repository upon the user clicking the Save button; so this setting impacts only pulling down of changes.

Git feature branch workflow support

Often while using Git teams would be following a Git feature branch workflow where changes are made on branches other than the base branch (e.g. feature, bugfix, etc.) and then merged into the base branch (e.g. master) after code reviews and other checks that teams may have established. To turn on support for Git feature branch workflow enable the option shown in the screenshot below.

With this option enabled any change that you make to a story file via the plugin interface will be committed and pushed to a dedicated feature branch for that particular issue, i.e. a feature branch that starts with the issue key.

If the Jira issue doesn’t have a story file attached yet and you add it via the plugin interface the git branch will be created automatically and the name used will be “refs/feature/<issue_key>“. You can of cause create the git branch manually yourself also e.g. by using a link under the Development panel on the view issue screen, but you must specify the issue key at the beginning of your branch name, e.g. if your issue key & title are something like “DEMO-123“ and “Implement feature A“ you may specify a branch name like 'refs/feature/DEMO-123_implement_feature_A'. The plugin will search for a feature branch starting with the issue key of the issue that you are viewing in order to check if the issue has a story attached or not.

Assumptions & Limitations

  1. Story file names must always start with the Jira issue key
    When you add a story to an issue using the plugin interface the file that will be added to the repository will be called “<issue_key>.story“ e.g. DEMO-123.story. If you want to add a story file by other means (e.g. by a git command line client) then ensure that the name of the file also starts with the issue key, e.g. “DEMO-123_feature_A.story”. The file can be placed into any directory of the git repository, just so long as there is just one story file per Jira issue. If you add more than one, then the first file found will be shown by the Jira plugin and others ignored.

  2. Issue branches must always start with the Jira issue key
    Applies only while using GIt branch workflow support. See explanation above under Git branch workflow support section.

  3. There must be only one branch per Jira issue
    Applies only while using Git branch workflow support. If you happen to create more than one git branch for a Jira issue, then the first branch starting with the issue key found will be used by the plugin.

  4. History does not follow renamed files
    If you happen to rename the story file (e.g. via git command line client) for example from say ‘DEMO-123_implement_feature_A' to 'DEMO-123_implement_feature_B’ then although the issue key remained the same the renamed file would be treated as a new file from the story history perspective.