User Manual 0.5.x

What is the Confluence for Bitbucket add-on?

The add-on "Confluence for Bitbucket" has the target to map the workflow between Conluence and Bitbucket. Especially from the point of view of development process or also from the point of view of certification bodies, many documents are necessary regarding software development and the quality assurance. It must be ensured that documents are not only available, but also be lived and integrated into the workflow. For example, "software design documents" are necessary or the "change control board" must be documented before the development of a new feature can begin. What about test or review reports? Equally important are test reports or review reports, which must be documented before a new feature or bugfix will be integrated into a target branch.

These are just a few examples where it may make sense for Bitbucket to interact with Confluence. In your company, respectively in your "Development Guidelines" you will certainly find further meaningful rules in which it makes sense to compare the software development with corresponding documents.

With each push and with each merge the add-on compares whether your documentation guidelines are fulfilled. But in most cases, it is not sufficient that these documents only exist. The Documents must have certain properties. For example, documents may have to be released by a certain person and have a certain status. This means that if the corresponding documents are not exist or are not in the correct state, a push or a merge should be prevented.

How it can be configured?

The configuration of the hook is identical for the merge hook and for the push hook. The general settings can be used to configure the behavior for issue keys. A regular expression field "Issue-key resular expression" can be used to define how issue keys are detected. You can also set the behavior, if no issue key based on the regular expression was detected. If wanted, a push can be allowed even if no issue key was found. If this is not the case, all configured rules will be checked for each detected issue key.

Confluence rules can be added using the "Add new rule" button. Any number of rules can be defined. For a valid hook configuration at least one rule has to be added.

Rules

A Confluence rule represents a check of a Confluence page for an issue key or/and a branch. This means that each configured rule is checked for each issue key/branch found. For example, if 10 issue keys were found, the rule will be evaluated 10 times. An issue key is usually represented by the keyword %key% and a branch by the keyword %branch%. The keyword can be used in any option, even in error or hint fields. Before a rule is evaluated, the keywords are automatically replaced with the appropriate issue key or branch name. In this section you will find the exact description of the fields. In later sections you will find examples with a more practically description.

Title: The title of the rule. If an evaluation of the rule results in an error, this text is printed to the developer. This text is the core message in error situations. For a valid configuration, the field must not be empty.
CQL rule: The CQL rule identifies the Confluence Pages that should be checked. The possibilities how to formulate a CQL can be found in the official Atlassian Documentation Advanced Searching using CQL. Additionally it can be specified what will happen, if no Confluence Page has been detected with this CQL. If it makes sense, the rule can be skipped, if no Confluence page has been detected. In this case this rule will not be evaluated. For a valid configuration the field must not be empty, the keyword %key% and/or %branch% must be present and of course the CQL query must be valid.
Like count: With the "Like count" you can define how many Likes Page must have at least. If this option is used, a push or a merge will be rejected if the "Like count" is smaller than the specified value. However, it can be defined whether each page found must meet this "like count" or only one page.
Page properties: With the option "Page Properties" the properties of a Confluence page can be evaluated, based on the Page Properties Macro. It can be checked if a page property value is exactly correct or if a value contains a string or if a value is not empty. The syntax is quite simple and consists of key-value pairs, which are connected with a comparator. The evaluation is not case-sensitive. Of course, several page properties can also be evaluated. This can be done by specifying multiple key-value pairs. In this case the key-value pairs are separated with a new line. In the case of multiple key-value pairs, it can also be defined whether only one entry has to fit for a page or all entries have to fit.
There are the comparison operators available:
'=' - The specified value must correspond exactly to the value of the page. (status=approved)
'~' - The specified value must be included in the value of the page. (issue-keys~DEM-1)
'+' - The value of the page must not be empty (tester+) (value is not needed in this case)
Error Message: The exact error message of the rule. This error message will be reported to a developer, if the evaluation of the rule leads to an error. The field must not be empty for a valid configuration.
Hint: This message will be printed to the developer also. The message should be a hint. The message should contain instructions about how to correct the issue. The field must not be empty for a valid configuration.