Publishes Gauge specifications to Confluence. This is a plugin for gauge.
This plugin is aimed at teams who use Confluence for documentation.
It enables living documentation by publishing your Gauge specs to Confluence and therefore allowing everyone to see them, seamlessly.
One of many use cases is if you are using Specification by Example, for instance.
Writing your specifications in Gauge allows the documentation to be close to the code and also to be executable. Being able to publish the specifications to the other tools you use makes this even more powerful.
See also the Gauge Jira plugin which enables Gauge specs to be published to Jira issues. Using both of these plugins to publish your specs to Confluence and Jira is a powerful combo!
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
- use this plugin in a Continuous Integration (CI) pipeline to publish (or republish) the specifications to Confluence (and to Jira, if you use the Jira plugin too)
- 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 Confluence
The plugin supports Confluence Server, Confluence Data Center and Confluence Cloud.
If you find a problem with a particular version of Confluence, please raise an issue
There are three mandatory variables and three optional variables to configure, as either:
-
environment variables
-
properties in a properties file, e.g.
<project_root>/env/default/anythingyoulike.properties
The three mandatory variables to configure are:
CONFLUENCE_BASE_URL e.g. https://example.com/path-to-your-confluence-wiki for Confluence Server, or https://example.atlassian.net for Confluence Cloud
CONFLUENCE_USERNAME
CONFLUENCE_TOKEN (This can either be a token or the password for the given Confluence username)
The three optional variables to configure are:
GAUGE_LOG_LEVEL
DRY_RUN
CONFLUENCE_SPACE_KEY
The GAUGE_LOG_LEVEL variable can be set to debug or info (default is info).
It controls the logging level both for the log files which are generated, and what is logged to the console.
NB the command line flag --log-level does not have any effect on the logging for this plugin.
Setting the DRY_RUN variable to true means that running the plugin does not publish specs to Confluence.
Instead the plugin just checks that the specs are in a valid publishable state (e.g. that there are no duplicate spec headings). This is very useful e.g. in a CI/CD pipeline the plugin can run in dry run mode on feature branches and pull requests. This ensures that the Gauge specs are always in good shape to be automatically published by the CI/CD pipeline upon any push to the trunk branch (e.g. upon a successful pull request merge).
The three config variables which are mandatory for actual publishing (CONFLUENCE_BASE_URL, CONFLUENCE_USERNAME and
CONFLUENCE_TOKEN) do not need to be provided when doing a dry run.
If the CONFLUENCE_SPACE_KEY is not provided, the plugin will derive the Space key to be used based on the remote Git repository URL. This convention ensures that each Git repository has its own unique Confluence space key derived from it, i.e. a one to one mapping between each Git repository and its associated one to one space.
The recommended way to run the plugin is not to provide the CONFLUENCE_SPACE_KEY variable, and instead to rely on the plugin to set it. This is particularly useful in CI/CD for instance, as it removes the need to set the Space key manually before being able to run the plugin.
One use case for setting the CONFLUENCE_SPACE_KEY is if for whatever reason you are unable to specify a Confluence user who has permission to create Confluence Spaces. By setting the CONFLUENCE_SPACE_KEY to be an existing Space which someone (e.g. a Confluence admin) has created for you, you will still be able to run the plugin even without Confluence create space permissions. In this case use a dedicated, empty Confluence Space that will contain just the Gauge specifications and nothing else.
NB You can use Confluence's include macro to include the page tree of Gauge Specs (that gets created by this plugin) in as many of your existing spaces as you like.
gauge docs confluence
or, if you want to specify a different directory to the default specs directory
gauge docs confluence <path to specs dir>
-
Can the specifications be edited in Confluence and synced back into the Gauge specs?
No. We include a message in Confluence warning not to make edits to the specifications in Confluence.
-
Is it safe to publish the specs to Confluence multiple times?
Yes. The plugin replaces any previously published specs with the latest version.
gauge install confluence
To install a specific version of the plugin use the --version flag.
gauge install confluence --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 confluence --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-Confluence is released under the Apache License, Version 2.0. See LICENSE for the full license text.