Publishes Gauge specifications to Jira. This is a plugin for gauge.
This plugin is aimed at teams who use Jira as an important part of their development lifecycle (having their User Stories in Jira, for example).
It enables living documentation by publishing your Gauge specs right into the descriptions of the Jira stories that they relate to and therefore allowing everyone to see them, seamlessly.
This is particularly useful if you are using Specification by Example.
As Gojko Adzic, the father of Specification by Example, says:
The big challenge related to tooling over the next 10 years will be in integrating better with Jira and its siblings. Somehow closing the loop so that teams that prefer to see information in task tracking tools get the benefits of living documentation will be critical.
A typical workflow could be something like this:
- collaborative story refinement sessions to come up with specification examples, using example mapping for instance
- write up the specification examples in Gauge
- link specifications to individual Jira issues as required (see below)
- use this plugin in a Continuous Integration (CI) pipeline to publish (or republish) the specifications to Jira
- automate the specifications using Gauge whenever possible (not essential, there's still value even when not automated)
- continue the cycle throughout the lifespan of the story: more conversations, more spec updates, more automated publishing to Jira
The plugin supports both Jira Server and Jira Cloud.
If you find a problem with a particular version of Jira Server or Jira Cloud, please raise an issue
There are three variables to configure, as either:
-
environment variables
-
properties in a properties file, e.g.
<project_root>/env/default/anythingyoulike.properties
The four variables to configure are:
JIRA_BASE_URL e.g. https://example.com for Jira Server, or https://example.atlassian.net for Jira Cloud
JIRA_USERNAME e.g. joe.bloggs for Jira Server, or [email protected] for Jira Cloud.
This user must have permissions to edit issues in the Jira projects that the specs will be linked to.
JIRA_TOKEN The Jira token is the password for the given JIRA_USERNAME if using Jira Server, or an
api token if using Jira Cloud.
gauge docs jira
or, if you want to specify a different directory to the default specs directory
gauge docs jira <path to specs dir>
Simply add one or more Jira issue keys, anywhere in the Gauge specification.
-
You can link more than one Jira issue to a Gauge specification. Just add the Jira issue keys anywhere in the Gauge spec (they don't all need to be together, although it may make sense from a readability point of view to keep them together)
-
You can also link more than one Gauge specification to the same Jira issue(s).
-
If you link to a Jira issue multiple times from the same Gauge specification, the specification will only be published to Jira once (rather than appearing in duplicate in Jira).
-
Linked Jira issues always pertain to the entire Gauge specification - there is no current ability to publish at the individual scenario level of granularity.
-
Jira issue keys are of the following format:
<projectkey>-<issuenumber>
e.g.
MYPROJECT-1
-
You can specify the Jira issue keys in a normal Gauge comment, (i.e. in normal plain text anywhere in the specification), e.g.
Linked Jira issue: MYPROJECT-1orLinked Jira issues: MYPROJECT-1, MYPROJECT-2 -
Or you could specify them as url links, e.g.
https://example.com/browse/MYPROJECT-1, https://example.com/browse/MYPROJECT-2or
[MYPROJECT-1](https://example.com/browse/MYPROJECT-1), [MYPROJECT-2](https://example.com/browse/MYPROJECT-2) -
Or you can specify the Jira issue keys as Gauge tags if you wish, e.g.
Tags: MYPROJECT-1, MYPROJECT-2
The specifications are appended to the existing contents of the Jira description field.
You can (and should) republish at will, as the plugin replaces any previously published specs with the latest version. Recommended approach is to republish them to Jira automatically on every change to the specs, as part of a Continuous Integration pipeline.
We chose to publish to the description field because it is a core field in Jira, always present and clearly visible in all issue pages in Jira.
-
Can the specifications be edited in Jira and synced back into the Gauge specs?
No. Only make edits in the Gauge specifications themselves. We include a message in Jira warning not to make edits to the specifications in Jira.
-
Is it safe to publish the specs to Jira multiple times?
Yes. The plugin replaces any previously published specs with the latest version.
-
What happens if the Gauge specs are longer than the Jira description field maximum length?
The default maximum length of Jira fields is 32,767 characters. This is long enough for most cases. If the specs for a given issue exceed the maximum length, the plugin will skip publishing that issue and report this in the console output. The recommended solution if that happens is to get an administrator of your Jira instance (or the Jira support team, if you are using Jira Cloud) to increase the maximum field length.
gauge install jira
To install a specific version of jira plugin use the --version flag.
gauge install jira --version $VERSION
Download the plugin zip from the Github Releases,
or alternatively (if you want to experiment with an unreleased version, which is not recommended) from the
artifacts in the
Store distros GitHub Action (NB you must be logged
in to GitHub to be able to retrive the artifacts from there).
use the --file or -f flag to install the plugin from zip file.
gauge install jira --file ZIP_FILE_PATH
go run build/make.go
For cross-platform compilation
go run build/make.go --all-platforms
After compilation
go run build/make.go --install
Note: Run after compiling
go run build/make.go --distro
For distributable across platforms: Windows and Linux for both x86 and x86_64
go run build/make.go --distro --all-platforms
See the CONTRIBUTING.md
Gauge-Jira is released under the Apache License, Version 2.0. See LICENSE for the full license text.