--- language: "en" --- # Confluence Hooks for Bitbucket ## What is the Confluence for Bitbucket add-on? The add-on "Confluence for Bitbucket" aims to map and enforce a workflow between Confluence and Bitbucket. Documentation (e.g. release notes, concepts, etc.) must be created at a certain point in the development process. "Confluence for Bitbucket" ensures that code changes are made at the right time and do not bypass your process. 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. It is exactly this interaction that Confluence Hooks takes care of for you. If documents do not exist or simply have the wrong attributes, this add-on can prevent a code change. A push or a merge is rejected and reference is made to missing or incorrect documentation. With each push and with each merge the add-on compares whether your documentation guidelines are fulfilled. ## Add-on Setup Because the add-on will check if a valid Confluence page exists, an application link must exist between Bitbucket and Confluence. Please follow the steps below to create a application link. |---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 1 | In the Bitbucket "Administration" menu, select **Application links** | | | 2 | If no valid link exists, you have to create a new one using the **Create new link** button | ![create-link.png](https://help.devopssystems.de/__attachments/a_4fcc755c46f803c177ae19b16201abf6f5683d42473f5e3faa3461bb3cd0ea3c/create-link.png?cb=0255a322e81aec486c9a829d7c963536) | | 3 | * You should be adminstrator in Confluence. * Depending on your user management you can confirm that both instances have the same users or not * (If unsure leave it unchecked) * The **Continue** Button will start the creation of the application link and will redirect you to the Confluence instance you have entered. | ![ApplicationLinkCreation.png](https://help.devopssystems.de/__attachments/a_4f77fa7bdcc7a1def4540c9907ba3446de8c554d52bee54167044e90aba442ed/ApplicationLinkCreation.png?cb=e6991314c44d50aad5015c1484c06d8f) | | 4 | In Confluence you can now confirm the application link. Please press the **Continue** button and you will be redirected to Bitbucket. | ![ConfluenceRedirect.png](https://help.devopssystems.de/__attachments/a_89c1ac98320faffe559d35e28caec9ffbaa4800248e4c89d82ff6d4780c088b4/ConfluenceRedirect.png?cb=678e63b601dd97eaa59e61d3b6de273a) | | 5 | After the redirection to Bitbucket has been done, you will see a connected a Confluence instance in you application link list. | ![ValidConfluenceLink.png](https://help.devopssystems.de/__attachments/a_d11a6606d94eec7acb43baea65bf8bde0fdbf5e673690af418acb0134a147123/ValidConfluenceLink.png?cb=921bda2036cac7933b3a3d94df8b26ed) | | 6 | Finally you can check the authentication settings of the application link, via pressing the **pen button.**By default OAuth should be selected, which is correct | ![OAuthIsFine.png](https://help.devopssystems.de/__attachments/a_a1f8a86a49ee39cac2bdb24706e70ae812b732c30ac1a0d265e747794d07ef95/OAuthIsFine.png?cb=9fb956cbe7c2621427986a80a5620f90) | ## Hook Configuration \& Hands-on Example In the next sections we will explain the possibilities of the hook and illustrate the configuration in several steps with a hands-on example. Together we will configure the hook step by step and perform a code change with you to show the effects of the hook. ### Where you can find the hook configuration? * **Step 1**: The configuration of the hook you will find in the administration area of your project or repository * **Step 2:** You can now find the configuration under the standard place for hook * **Hooks** if you would like to configure push check * **Merge Checks** if you would like to configure to configure merge checks * **Step 3:**Open the Confluence Hooks configuration ![HookConfiguration.png](https://help.devopssystems.de/__attachments/a_ab5e9854232427f251ff8a0540bd112d22aa0d17a7dbac7882eba0c17d0c7fcb/HookConfiguration.png?cb=41f7217571ca3c60f99cdd40a832b5ac) ### How can I configure the hook? The hook evaluates whether a specific Confluence page exists for a code change or a branch. To better identify this Confluence page, an issue key can also be used, which is found in a commit message. Thus it is possible to capture the issue key from a commit message and use this information when searching for a specific page. More about this in the following sections. To capture this issue key a regular expression is used, which can be configured via the field***Issue-key regular expression (see screenshot).***Of course, you don't need an issue key to search for a Confluence Page. But usually it makes not much sense to do this, because an issue key is an important factor to identify a corresponding page for a code change, because an issue key is representative for a code change. And normally you are looking for pages which have a direct relation to a code change. But maybe there are commits in your workflow which do not contain issue keys. These issue keys can be excluded from further evaluation. For this you can select the following option. If this is the case, all further rules (which will be configured afterwards) will not be evaluated if no issue key was found. Normally, you do not need to change anything in these settings and can proceed directly to step 4. The validity of the issue is not checked. The issue key is used exclusively in the fields of a rule. If you want to check the validity of the issue key, please use the [Jira Hooks for Bitbucket](https://marketplace.atlassian.com/apps/1211959/jira-hooks-for-bitbucket?tab=overview&hosting=datacenter) add-on. **Step 4 - Add Rule:** 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.** ![HookConfigurationAddRule.png](https://help.devopssystems.de/__attachments/a_38f89665649f30c642de7c04595d458d3d450426426a55ddb11852117852f9d8/HookConfigurationAddRule.png?cb=75f666580272a5d590fa6beee712dbec) **Step 5 Possibilities to configure a rule** A rule aims to find one or more Confluence pages and evaluate this page against the configuration. As soon the configuration is violated, a push or merge is rejected. Since a check is always performed based on a code change, the properties of a code change should also be able to be used for a search. Therefore, different information is available as keywords to be able to use them in the further rule configuration. **Keywords:** * **%key%** - Represents an issue key which was found. * **%branch%** - Represents the branch name where the changes were made. * **%hash%** - Identifies a hash in which e.g. an issue key was found 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 values A rule is evaluated for each issue key found and for each branch found. So if 3 different issue keys are pushed in one or more commit messages, then each rule is checked for each issue key and each branch. So in this example the rules are checked 4 times (3 issue keys + 1 branch). |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ![HookConfigurationSettings.png](https://help.devopssystems.de/__attachments/a_1ef51a588adec6f6dddd1560c0acc27f5d86716fea5eb20c2b0a59e38aa6c47f/HookConfigurationSettings.png?cb=a076245b15fdb1f96c5d24c13e9e303b) | **Rule Options** To follow our hands-on example the following options are now occupied. You will find a short description of the options as well as snippets, which you can copy directly into the respective options. * ***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 Software design document is needed * ***CQL rule:*** The CQL rule identifies all 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](https://developer.atlassian.com/server/confluence/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. label = "%key%" and label = "chfb-demonstration" and label = "design-document" Based on this CQL now all sides are selected, which have the following labels **design-document** - e.g. the label which identifies your design documents **issue-key** - so that the correct design document is identified for your code change **chfb-demonstration** - a unique label to uniquely identify pages for the participation example * ***Like count:*** With the *"Like count"* you can define how many Likes a 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. 1 // select all pages must have the given like count * ***Page properties*** : With the option "Page Properties" the properties of a Confluence page can be evaluated, based on the [Page Properties Macro](https://confluence.atlassian.com/doc/page-properties-macro-184550024.html). 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) status=Approved reviewer+ // select all pages must match the properties // select all key pairs must match Based on these settings, the selected pages must have a page properties macro. This macro must contain a table with the "**Status** " field having the value "**Approved** " and the "**Reviewer** " field with **some** **user**. * ***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. No valid software design document has been found for the given code change (issue: %key%) * ***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. Please create a software design document for the issue %key% and please ask your team lead to approve the design document. | ``` ``` ``` ``` ``` ``` **Steps 7 - 11 Create a Confluence Page** Open the Confluence instance you configured as an application link and create a Confluence page in any space. Of course, the user you use in Bitbucket should have read permissions on this page via the application link. |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ![CFCreatePage.png](https://help.devopssystems.de/__attachments/a_84d63e0660d4895d561bf836fb7792f3755fc9153ce1d4546eccfd2e82797e92/CFCreatePage.png?cb=28095d53bd1e59d4dd83f28e6233403c) | **Step - 7:** Create a Confluence page as usual via the **Create Button** | | ![CFAddPageMacro.png](https://help.devopssystems.de/__attachments/a_961b9142afa0eaab26aa95767ab39dfd1a4b8ba0495142dcde6c590bbdde0606/CFAddPageMacro.png?cb=2bfe185a9bfe4eb3e5f6891e83166090) | **Step 8:** You can choose any page name, because the page selection in our example is done via labels only. **Step 9:** In order to evaluate the page properties, a Confluence page must also contain a page properties macro. Therefore the macro is added in this step | | ![CFInsertMacro.png](https://help.devopssystems.de/__attachments/a_819543635bcf6190c06f87834e151128a35602d6378b33f273599f3482ea9630/CFInsertMacro.png?cb=aacd2317f2915574d0cd8b948d4db75d) | **Step 10:** You do not necessarily have to enter further details with the macro - Just press insert | | ![CFInsertProperties.png](https://help.devopssystems.de/__attachments/a_e1bcd787122bb0943087889daf98bc85e866f2da2a8e7eff149f0e5b14ffae9d/CFInsertProperties.png?cb=dd6cda550b7163541f5ef417c96e20bd) | **Step 11:** Now you can add a table to the Page Property macro that represents the keys and values of the page. * **Step 11.1**: In our example we change the table header from hoizintal to vertical. * **Step 11.2**: We add the properties Designer, Status and Reviewer * **Step 11.3**: For the Status we use the macro Status | | ![CFAddLabels.png](https://help.devopssystems.de/__attachments/a_71372fd65b298fd3f07b57159654cc49f701b48cc45fcf7d0288b9acb8abf846/CFAddLabels.png?cb=bedad4ff10ec05c86bba3de181e77aa0) | **Step 12:** Because the page selection in our example is done via labels only, we have to add 3 labels to the page test-1 design-document chfb-demonstration | | ![CFPageResult.png](https://help.devopssystems.de/__attachments/a_38df6b348433baa48e83022e317b646d6da58dcb37b2a1a8dc8695ef4fb1a200/CFPageResult.png?cb=522a4385f165ea429a36e17ebd7367a2) | The final page should be like this It is intended that the page will not get any likes yet | **Steps 13-20 - Git clone - commit - push** Now that we have created the hook and created a Confluence page for the test, we are ready to execute the test using Git commands. We will now clone the Git repository where we have configured the hook, make a change, commit the change with the issue key "TEST-1" and push it afterwards. Since the page has not received any likes yet, we expect the push to fail. **Execute the following commands (e.g. in your /tmp directory)** * **Step-13:** Clone your git Repository **Clone repository** Bash git clone http://admin@bitbucket-server/scm/project_1/rep_1.git ![git-clone.png](https://help.devopssystems.de/__attachments/a_ea741b598f07831bd4180e2fb70b5064ea9c28086c8a74bf3e64bef25a4c876d/git-clone.png?cb=030c01fe508f6f287b37fe4c3f6c28d0) * **Step 14 -**Got into the repository **Change directory** Bash cd rep_1 ![git-cd.png](https://help.devopssystems.de/__attachments/a_181cfe8d035635dfc2369f2f74feb9b5633f26ef6ec8c5b07098c4ad1ad58e01/git-cd.png?cb=3d7597332455a1cb92ed1ba185a22d10) * **Step 15** - Create a file, add file, commit file with the issue key TEST-1 **Modify file and commit the file** Bash echo "test-string" >> test1.txt git add test1.txt git commit -m "TEST-1 anything" ![git-modify.png](https://help.devopssystems.de/__attachments/a_fa5372f9bcfcf0a7651ad733ed85ce422ebe908ca7045f861cfff487b806888c/git-modify.png?cb=378894ae3ce86e1fc28806915a71a698) * **Step 16** - Push the changes **Git push** Bash git push ![git-push.png](https://help.devopssystems.de/__attachments/a_0d0325c3e2f3f8324a8802352c7e6868bb847e9c7cb43bff1ed22569f72268ff/git-push.png?cb=548d0a30131278323ccbe94c53b10f03) As you can see, the change could not be pushed. The correct page was selected based on our CQL, the status and reviewer were successfully evaluated, but no like could be found. * **Step 17** - Edit the Confluence page - set the status of the page to **OPEN** ![CFWrongStatus.png](https://help.devopssystems.de/__attachments/a_148beca9f4b2766cb8d6e3024f39b100d5f42f81e96f9bc89f4b361c32d66c8b/CFWrongStatus.png?cb=55a88f8603d56e762a50f48a97a9a50e) Now the push should fail because the status of the document does not match APPROVED and the page still has no likes. * **Step 18** - Push again **Git push** Bash git push ![git-push-2.png](https://help.devopssystems.de/__attachments/a_85612bbe077b51ec919ed6e28a196b4dcaa9400074b5b433c99eaf01a1a08eb9/git-push-2.png?cb=de2c6a5834c20fade150b53a86b6e1e9) As you can see, the change could not be pushed. Because of the wrong status and the missing like ![ConfigRelation.png](https://help.devopssystems.de/__attachments/a_80849b22748f128408ff6818d217a32516ac95f4c84ece81744290ecb8728aaf/ConfigRelation.png?cb=c5d75cfb616417c7913a4a4b953b4b08) * **Step 18** - Lets change the Confluence page again (Add a like and set the correct status) * ![CFCorrect.png](https://help.devopssystems.de/__attachments/a_5d0d33d72da1e91cc187b0cc6f6bd3b16c4dc824afae266112983ea88560daa4/CFCorrect.png?cb=56a8f98456f8291353d24b38ca742d96) * **Step 19 - PUSH AGAIN** Now the push works... ![git-push-3.png](https://help.devopssystems.de/__attachments/a_47916ae4306442a7059891e551bed24362a3d1a57fccea1ee3892eb62aa7c7ea/git-push-3.png?cb=e18eb9baacbc4c4d10417bd3dfe4d1dd) * **Last Step** It would be super helpful if you could give us feedback. We are constantly trying to make our products even better and for that we need your feedback. Please leave us a message in our [service desk](http://It would be super helpful if you could give us feedback. We are constantly trying to make our products even better and for that we need your feedback among other things. Please leave us a message in our service desk) --- language: "en" --- # Authentication As you know, the add-on uses the Application Link to access Confluence. However, this mechanism requires an OAuth token for each user. If this is not present, the following error message appears and you are asked to create a token via authorisation link. **Examples:** | Hook configuration | ![ErrorMesssage.png?version=1&modificationDate=1636392157641&cacheVersion=1&api=v2&width=700](https://help.devopssystems.de/__attachments/a_3e0608af5154aefccc12b0747e1d955fb7c7e7b233743be8d2096043c967ba16/ErrorMesssage.png%3Fversion=1&modificationDate=1636392157641&cacheVersion=1&api=v2&width=700?cb=d7c1d14bf7bea94d017385017a758170) | | Git push | ![gitPushError.png?version=1&modificationDate=1636392490982&cacheVersion=1&api=v2&width=700](https://help.devopssystems.de/__attachments/a_56832a7593cabf2c7759c21e6efb6a614def2387138abc80a551649e8e43160b/gitPushError.png%3Fversion=1&modificationDate=1636392490982&cacheVersion=1&api=v2&width=700?cb=594f0f85a9f1650cacae8938ae2c9f53) | |--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| **How to create a Token** |---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 1 | Copy the link into a web browser and Bitbucket will redirect you to the appropriate Confluence instance. If you are not logged in yet, you have to log in | ![ConfluenceLogin.png?version=1&modificationDate=1636392156697&cacheVersion=1&api=v2&width=600](https://help.devopssystems.de/__attachments/a_691c4b8b2519c0b6421900721237977ef2e0cdb046d26128f6b9e7307c0a8b47/ConfluenceLogin.png%3Fversion=1&modificationDate=1636392156697&cacheVersion=1&api=v2&width=600?cb=68ca7d1a454106d563e34d0642c56d04) | | 2 | After you log in, you will be asked if you want to give Bitbucket read and write access to the data on the Confluence server. After you have checked the username and you want to grant access in this name, you can give Bitbucket access via **Allow**. Of course, this user also needs the normal access rights in Confluence. If the user is not allowed to access the pages, the add-on will not be able to access the pages either. | ![OAuthConfluence.png?version=1&modificationDate=1636392155903&cacheVersion=1&api=v2&height=250](https://help.devopssystems.de/__attachments/a_ba4e608a8a1ad40b102fa2b36fe45073a3666e358d0a550fea848be0e2b0571e/OAuthConfluence.png%3Fversion=1&modificationDate=1636392155903&cacheVersion=1&api=v2&height=250?cb=bdb54ba598ccddcb28e293bf60ecde24) | | 3 | You can view your existing tokens in Confluence at any time via the following link and also you can delete the token at this place http://\/plugins/servlet/oauth/users/access-tokens | ![ListOfTokens.png?version=1&modificationDate=1636392155084&cacheVersion=1&api=v2&width=600](https://help.devopssystems.de/__attachments/a_bba818e16501022aa26dc5b034fc513de07b45f63ac0110ed0a9a02f7a5bd15a/ListOfTokens.png%3Fversion=1&modificationDate=1636392155084&cacheVersion=1&api=v2&width=600?cb=5e988e53a6dc60e67109d87b25b26843) | | 4 | Done | | --- language: "en" --- # Change Control Board --- language: "en" --- # DEM-2 - Software Design Document - Fix of bug 4711 | Issue | DEM-2 | | Design | Test User 1 | | Status | CREATED | | Reviewed by | Software Team Lead | | Review-Status | APPROVED | | Date | 2019-04-24 | |---------------|--------------------| ## Design description Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. ## Design justification Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. ## Big Picture ![test.png](https://help.devopssystems.de/__attachments/a_676623fce8543d1f8ef067b44404968a0f499771fa6a8f7a4938422ece259ac1/test.png?cb=b619c9050f8305e4e9f971360f27517c) --- language: "en" --- # DEM-2 Test Report - Fix of bug 4711 | Issue | DEM-2 | | Tester | Test User 3 | | Test-Status | PROGRESS | | Approval by | | | Approval-Status | | | Hash | **5e23ad0f2** | |-----------------|---------------| ## Expected behavior Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. ## How the issue has been tested 1. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, 2. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. 3. Lorem ipsum dolor sit amet, consetetur sadipscing elitr 4. At vero eos et accusam et justo duo dolores et ea rebum. ## Test result Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. --- language: "en" --- # DEM-3 More Bitbucket hooks | Issue | DEM-3 | | Tester | Test User 3 | | Test-Status | TESTED | | Approval by | Test User 1 | | Approval-Status | NEEDs rework | | Hash | **5e23ad0f2** | |-----------------|---------------| ## Expected behavior Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. ## How the issue has been tested 1. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, 2. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. 3. Lorem ipsum dolor sit amet, consetetur sadipscing elitr 4. At vero eos et accusam et justo duo dolores et ea rebum. ## Test result Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. --- language: "en" --- # DEM-3 - More Bitbucket hooks | Issue | DEM-3 | | Design | Test User 3 | | Status | DRAFT | | Reviewed by | Software Team Lead | | Review-Status | neeed rework | | Date | 2019-04-24 | |---------------|--------------------| ## Design description Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. ## Design justification Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. ## Big Picture ![test.png](https://help.devopssystems.de/__attachments/a_fdb0aec21aadacd9ac0605618f675dad13b7783e2822649043010634f7b07d35/test.png?cb=b619c9050f8305e4e9f971360f27517c) --- language: "en" --- # Example Change Control Board for Release/1.0.x | Title | Change Control Board for version 1.0.0 | | Product | Demonstration Product | | Version | 1.0.0 | | Maintenance line | release/1.0.x | | Board Members | Test User 1 Test User 2 Test User 3 | | Issues accepted | DEM-2 DEM-3 | |------------------|----------------------------------------| ## Desicion matrix for version 1.0.0 | Issue | Status | Test User 1 | Test User 2 | Test User 3 | Comment | |-------|----------|-------------|-------------|-------------|------------------------------------------------------------------------------------------------------------------| | DEM-1 | Rejected | Accepted | Rejected | Rejected | Because of the time pressure, *Test User 2* and *Test User 3* would like to move the issue into the next release | | DEM-2 | Accepted | Accepted | Accepted | Accepted | This is critical bug, which needs to be fixed as soon as possible. | | DEM-3 | Accepted | Accepted | Accepted | Accepted | This issue we promised customers in this release, so we can not skip it. | --- language: "en" --- # Example Pages --- language: "en" --- # Example Release/2.0.x CCB | Title | Change Control Board for version 1.0.0 | | Product | Demonstration Product | | Version | 2.0.0 | | Maintenance line | | | Board Members | Test User 1 Test User 2 Test User 3 | | Issues accepted | DEM-2 DEM-3 | |------------------|----------------------------------------| ## Desicion matrix for version 1.0.0 | Issue | Status | Test User 1 | Test User 2 | Test User 3 | Comment | |-------|----------|-------------|-------------|-------------|------------------------------------------------------------------------------------------------------------------| | DEM-1 | Rejected | Accepted | Rejected | Rejected | Because of the time pressure, *Test User 2* and *Test User 3* would like to move the issue into the next release | | DEM-2 | Accepted | Accepted | Accepted | Accepted | This is critical bug, which needs to be fixed as soon as possible. | | DEM-3 | Accepted | Accepted | Accepted | Accepted | This issue we promised customers in this release, so we can not skip it. | --- language: "en" --- # Example-Scenarios --- language: "en" --- # Examples After the configuration possibilities have been described in general, these possibilities are additionally described with examples. I would like to point out that the following CQL queries are only examples and must of course be adapted to your use case or your Confluence page structure. ## Merge-Hook - Test reports are required The following scenario assumes that a test report must be created before a new code change can be integrated. A merge hook is configured accordingly, which checks whether a test report exists for the respective issue and is in the correct status. **Page selection based on CQL** In the Test-Reports folder you will find the following 3 Test-Report sample pages. Also you will find examples of how these can be identified by the CQL. However, it is clear that other CQLs may be necessary in your company to identify the corresponding pages. It depends on your structure. | Page | Issue key (e.g. commit message) | Identified by Query-Example | Description | | [New Example Feature - Just for Test Demonstration](https://help.devopssystems.de/chfb/new-example-feature-just-for-test-demonstration.md) | DEM-1 | label = "%key%" and label = "test-report" | Match the given page, because both labels match | | [DEM-2 Test Report - Fix of bug 4711](https://help.devopssystems.de/chfb/dem-2-test-report-fix-of-bug-4711.md) | DEM-2 | title \~ "%key%" and title \~ "Test Report" | Match the given page, because the page title contains both strings | | [DEM-3 More Bitbucket hooks](https://help.devopssystems.de/chfb/dem-3-more-bitbucket-hooks.md) | DEM-3 | title \~ "%key%" and label = "test-report" | Match the given page, because the page title contains the issue key ant the label "test-report" is given | |---------------------------------------------------------------------------------------------------------------|---------------------------------|---------------------------------------------|----------------------------------------------------------------------------------------------------------| **Page properties configuration** Now let's evaluate the page properties of the above detected pages. The page properties are for all three pages the same, but the page properties are different (please check the related pages and you will see). | Page | Merge will be | Issue key (e.g. commit message) | Properties-Example | Description | | [New Example Feature - Just for Test Demonstration](https://help.devopssystems.de/chfb/new-example-feature-just-for-test-demonstration.md) | Accept | DEM-1 | Java issue~%key% tester+ test-status=tested approval by=software team lead approval-status=approved | The merge is allowed, because: * the issue key is correct in the page * the property tester is not empty * the test status is "tested" * the approval has been done by the user "software team lead" * and the approval-status is "approved" | | [DEM-2 Test Report - Fix of bug 4711](https://help.devopssystems.de/chfb/dem-2-test-report-fix-of-bug-4711.md) | Reject | DEM-2 | Java issue~%key% tester+ test-status=tested approval by=software team lead approval-status=approved | The merge will be rejected, because: * the test status is in "progress" and not "tested" * Nobody has done the approval * approval-status is not set | | [DEM-3 More Bitbucket hooks](https://help.devopssystems.de/chfb/dem-3-more-bitbucket-hooks.md) | Reject | DEM-3 | Java issue~%key% tester+ test-status=tested approval by=software team lead approval-status=approved | The merge will be rejected, because the approval-status is "needs rework" | |---------------------------------------------------------------------------------------------------------------|---------------|---------------------------------|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| --- language: "en" --- # FAQ --- language: "en" --- # How to access debug logging information? ## Enable debug logging (since 1.0.0) You can enable the debug logging via the default mechanism of Bitbucket. As described in this document you can enable specific logger. The *Confluence Hooksfor Bitbucket* logger has the name *chfb-logger.*You can enable it via the Bitbucket properties file or you can enable it via the following curl command. Bash #enable curl -u -v -X PUT -d "" -H "Content-Type: application/json" http:///rest/api/latest/logs/logger/chfb-logger/debug Attention: Please disable this logging again after you have done your investigation Bash #disable curl -u -v -X PUT -d "" -H "Content-Type: application/json" http:///rest/api/latest/logs/logger/chfb-logger/info ## How to filter all Confluence Hooks for Bitbucket entries? Each log entry will start with the prefix "`chfb-logger`". To see only Bitbucket Hooks for Bitbucket log entries, just filter the entries regarding the keyword "`chfb-logger`". ## Support If you have technical issues, please add the "`chfb-logger`" logs to the ticket or email. Thank you in advance. Alternatively you can create a support zip via the Bitbucket mechanism. (see ) --- language: "en" --- # Merge Hook - Test reports are required The following scenario assumes that a test report must be created before a new code change can be integrated. The teste report must exists and it must have the correct status. **Common Settings** The common settings of a rule are needed to provide developers information about the configured rule in error situations. | Option | Value | Description | | Title | Test report is needed | Is needed to identify the rule in the error messages | | Error message | No valid test report has been found for the give code change (issue: %key) | Gives the user further information about the error situation | | Hint | Please create for the issue %key% and test report and please ask your team lead to approve the test report. | Gives the user the information about how they can solves the issue. | |---------------|-------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------| **Page selection based on CQL** Based on the CQL you can identify the test reports you would like to check. In the folder [Test-Reports](https://help.devopssystems.de/chfb/test-reports.md) you will find 3 test reports, with different characteristics. This 3 pages are listed in the table above and you will also find examples of how these can be identified by the CQL. However, it is clear that other CQLs may be necessary in your company to identify the corresponding pages. It depends on your page structure. | Page | Issue key (e.g. commit message) | Identified by Query-Example | Description | | [New Example Feature - Just for Test Demonstration](https://help.devopssystems.de/chfb/new-example-feature-just-for-test-demonstration.md) | DEM-1 | label = "%key%" and label = "test-report" | Match the given page, because both labels match | | [DEM-2 Test Report - Fix of bug 4711](https://help.devopssystems.de/chfb/dem-2-test-report-fix-of-bug-4711.md) | DEM-2 | title \~ "%key%" and title \~ "Test Report" | Match the given page, because the page title contains both strings | | [DEM-3 More Bitbucket hooks](https://help.devopssystems.de/chfb/dem-3-more-bitbucket-hooks.md) | DEM-3 | title \~ "%key%" and label = "test-report" | Match the given page, because the page title contains the issue key ant the label "test-report" is given | |---------------------------------------------------------------------------------------------------------------|---------------------------------|---------------------------------------------|----------------------------------------------------------------------------------------------------------| **Skip CQL** Also it should not be allowed to push, if no page has been found by a CQL. For that please ensure, that the option "*If no page matches the CQL, the rule will be skipped. The rule will be validated only, if a page has been found.*" is unset. **Page properties configuration** Now let's evaluate the page properties of the above detected pages. The requested page properties in the hook are for all three pages the same, but the real page properties are different (please check the related pages and you will see). | Page | Merge will be | Issue key (e.g. commit message) | Properties-Example | Description | | [New Example Feature - Just for Test Demonstration](https://help.devopssystems.de/chfb/new-example-feature-just-for-test-demonstration.md) | Accept | DEM-1 | Java issue~%key% tester+ test-status=tested approval by=software team lead approval-status=approved | The merge is allowed, because: * the issue key is correct in the page * the property tester is not empty * the test status is "tested" * the approval has been done by the user "software team lead" * and the approval-status is "approved" | | [DEM-2 Test Report - Fix of bug 4711](https://help.devopssystems.de/chfb/dem-2-test-report-fix-of-bug-4711.md) | Reject | DEM-2 | Java issue~%key% tester+ test-status=tested approval by=software team lead approval-status=approved | The merge will be rejected, because: * the test status is in "progress" and not "tested" * Nobody has done the approval * approval-status is not set | | [DEM-3 More Bitbucket hooks](https://help.devopssystems.de/chfb/dem-3-more-bitbucket-hooks.md) | Reject | DEM-3 | Java issue~%key% tester+ test-status=tested approval by=software team lead approval-status=approved | The merge will be rejected, because the approval-status is "needs rework" | |---------------------------------------------------------------------------------------------------------------|---------------|---------------------------------|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| **Page properties strategy** To have a valid test report all requested properties must match. So it is needed to set the option *"All key pairs must match"* **Example configuration** ![settings-test-report.png](https://help.devopssystems.de/__attachments/a_f7b0addd91e8a09b2c9520f93e65557035d56fd4856f30792780b9a777407d7e/settings-test-report.png?cb=ae33fb7359404d071164ff6aa8a6e9cb) --- language: "en" --- # New Example Feature - Just for Demonstration | Issue | DEM-1 | | Design | Test User 1 | | Status | Progress | | Reviewed by | | | Review-Status | | | Date | | |---------------|-------------| ## Design description Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. ## Design justification Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. ## Big Picture ![test.png](https://help.devopssystems.de/__attachments/a_1c07d78f1db65df2e745e2df0aeac70980ab9e7f28aaabdedbdf2a64eb8f3488/test.png?cb=b619c9050f8305e4e9f971360f27517c) --- language: "en" --- # New Example Feature - Just for Test Demonstration | Issue | DEM-1 | | Tester | Test User 3 | | Test-Status | TESTED | | Approval by | Test User 1 | | Approval-Status | Approved | | Hash | **5e23ad0f2** | |-----------------|---------------| ## Expected behavior Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. ## How the issue has been tested 1. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, 2. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. 3. Lorem ipsum dolor sit amet, consetetur sadipscing elitr 4. At vero eos et accusam et justo duo dolores et ea rebum. ## Test result Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. --- language: "en" --- # Push Hook - Change Control Board is documented The following scenario assumes that a change control board decision ist documented before a new code change can be pushed The change control board document must exists and the related issue must be accepted in this document. **Common Settings** The common settings of a rule are needed to provide developers information about the configured rule in error situations. | Option | Value | Description | | Title | Change control board decision is documented | Is needed to identify the rule in the error messages | | Error message | The change control board decision has not been documented for %key% in %branch% | Gives the user further information about the error situation | | Hint | Please ask the change control board to document the CCB decision for %key% in the release %branch% | Gives the user the information about how they can solves the issue. | |---------------|----------------------------------------------------------------------------------------------------|---------------------------------------------------------------------| **Page selection based on CQL** Based on the CQL you can identify the change control board document. In the folder [Example Pages](https://help.devopssystems.de/chfb/example-pages.md) you will find 1 change control board document. In the table below you will find examples how document can be identified by the CQL. However, it is clear that other CQLs may be necessary in your company to identify the corresponding pages. It depends on your page structure. | Page | Branch key | Identified by Query-Example | Description | | [Example Change Control Board for Release/1.0.x](https://help.devopssystems.de/chfb/example-change-control-board-for-release-1-0-x.md) | release/1.0.x | title \~ "%branch%" and title \~ "Change Control" | Match the given page, because the title contains the branch name and "Change Control" | | [Example Release/2.0.x CCB](https://help.devopssystems.de/chfb/example-release-2-0-x-ccb.md) | release/2.0.x | title \~ "%branch%" and label = "ccb" | Match the given page, because the title contains the branch name and the labeld contains "ccb" | |-----------------------------------------------------------------------------------------------------------|---------------|---------------------------------------------------|------------------------------------------------------------------------------------------------| **Skip CQL** Also it should not be allowed to push, if no page has been found by a CQL. For that please ensure, that the option "*If no page matches the CQL, the rule will be skipped. The rule will be validated only, if a page has been found.*" is unset. **Page properties configuration** Now let's evaluate the page properties of the above detected pages. The requested page properties in the hook are for all three pages the same, but the real page properties are different (please check the related pages and you will see). | Page | Merge will be | Branch key | Issue key (e.g. commit message) | Properties-Example | Description | | [Example Change Control Board for Release/1.0.x](https://help.devopssystems.de/chfb/example-change-control-board-for-release-1-0-x.md) | Reject | release/1.0.x | DEM-1 | Java issues accepted~%key% maintenance line~%branch% | The push will be rejected, because: * the issue DEM-1 is not accepted in this change control board | | [Example Change Control Board for Release/1.0.x](https://help.devopssystems.de/chfb/example-change-control-board-for-release-1-0-x.md) | Accept | release/1.0.x | DEM-2 | Java issues accepted~%key% maintenance line~%branch% | The push is allowed, because: * the issue key is in the accepted list * the maintenance list is matchinge | | [Example Release/2.0.x CCB](https://help.devopssystems.de/chfb/example-release-2-0-x-ccb.md) | Reject | release/2.0.x | DEM-3 | Java issues accepted~%key% maintenance line~%branch% | The push will be rejected, because: * the maintenance line property is empty | | [Example Release/2.0.x CCB](https://help.devopssystems.de/chfb/example-release-2-0-x-ccb.md) | Reject | release/2.0.x | DEM-4 | Java issues accepted~%key% maintenance line~%branch% | The push will be rejected, because: * the maintenance line property is empty * the issue is not in the accepted list | |-----------------------------------------------------------------------------------------------------------|---------------|---------------|---------------------------------|------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------| **Page properties strategy** To have a valid change control document all requested properties must match. So it is needed to set the option *"All key pairs must match"* **Example configuration** ![settings-change-control.png](https://help.devopssystems.de/__attachments/a_d711888e511443da9c3dd687ce34f838d8a9854ff660402f4f5322bd9958e951/settings-change-control.png?cb=0315d7ff44c6725a3408a84db832a050) --- language: "en" --- # Push Hook - Design documents are required The following scenario assumes that a software design document must be created before a new code change can be pushed The design document must exists and it must have the correct status (e.g. reviewed) **Common Settings** The common settings of a rule are needed to provide developers information about the configured rule in error situations. | Option | Value | Description | | Title | Software design document is needed | Is needed to identify the rule in the error messages | | Error message | No valid software design document has been found for the give code change (issue: %key) | Gives the user further information about the error situation | | Hint | Please create a software design document for the issue %key% and please ask your team lead to approve the design document. | Gives the user the information about how they can solves the issue. | |---------------|----------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------| **Page selection based on CQL** Based on the CQL you can identify the software design document you would like to check. In the folder [Software Design Documents](https://help.devopssystems.de/chfb/software-design-documents.md) you will find 3 software design documents with different characteristics. This 3 pages are listed in the table below and you will also find examples of how these can be identified by the CQL. However, it is clear that other CQLs may be necessary in your company to identify the corresponding pages. It depends on your page structure. | Page | Issue key (e.g. commit message) | Identified by Query-Example | Description | | [New Example Feature - Just for Demonstration](https://help.devopssystems.de/chfb/new-example-feature-just-for-demonstration.md) | DEM-1 | label = "%key%" and label = "software-design" | Match the given page, because both labels match | | [DEM-2 - Software Design Document - Fix of bug 4711](https://help.devopssystems.de/chfb/dem-2-software-design-document-fix-of-bug-4711.md) | DEM-2 | title \~ "%key%" and title \~ "Software Design" | Match the given page, because the page title contains both strings | | [DEM-3 - More Bitbucket hooks](https://help.devopssystems.de/chfb/dem-3-more-bitbucket-hooks-1.md) | DEM-3 | title \~ "%key%" and label = "software-design" | Match the given page, because the page title contains the issue key ant the label "software-design" is given | |---------------------------------------------------------------------------------------------------------------|---------------------------------|-------------------------------------------------|--------------------------------------------------------------------------------------------------------------| **Skip CQL** Also it should not be allowed to push, if no page has been found by a CQL. For that please ensure, that the option "*If no page matches the CQL, the rule will be skipped. The rule will be validated only, if a page has been found.*" is unset. **Page properties configuration** Now let's evaluate the page properties of the above detected pages. The requested page properties in the hook are for all three pages the same, but the real page properties are different (please check the related pages and you will see). | Page | Merge will be | Issue key (e.g. commit message) | Properties-Example | Description | | [New Example Feature - Just for Demonstration](https://help.devopssystems.de/chfb/new-example-feature-just-for-demonstration.md) | Reject | DEM-1 | Java issue~%key% design+ status=created reviewed by=software team lead review-status=approved | The push will be rejected, because: * the status is in "progress" and not "created" * Nobody has done the review * the review-status is not set | | [DEM-2 - Software Design Document - Fix of bug 4711](https://help.devopssystems.de/chfb/dem-2-software-design-document-fix-of-bug-4711.md) | Accept | DEM-2 | Java issue~%key% design+ status=created reviewed by=software team lead review-status=approved | The push is allowed, because: * the issue key is correct in the page * the property design is not empty * the status of the page is "created" * the approval has been done by the user "software team lead" * the review status is "approved" | | [DEM-3 - More Bitbucket hooks](https://help.devopssystems.de/chfb/dem-3-more-bitbucket-hooks-1.md) | Reject | DEM-3 | Java issue~%key% design+ status=created reviewed by=software team lead review-status=approved | The push will be rejected, because the review-status is "needs rework" | |---------------------------------------------------------------------------------------------------------------|---------------|---------------------------------|-----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| **Page properties strategy** To have a valid software design document all requested properties must match. So it is needed to set the option *"All key pairs must match"* **Example configuration** ![settings-software-design.png](https://help.devopssystems.de/__attachments/a_277ad3d47ae9506d8cf8ac6de683ded0836e55e9d6c2b0306efea1b6d1fdd8e1/settings-software-design.png?cb=1f137335d67870c22de35e0622b23cd1) --- language: "en" --- # Release Guide 0.5.x --- language: "en" --- # Release Guide 0.6.x --- language: "en" --- # Release Guide 1.0.x --- language: "en" --- # Release Guide 1.1.x --- language: "en" --- # Release Guide 2.0.x --- language: "en" --- # Release Guides --- language: "en" --- # Software Design Documents --- language: "en" --- # Test Reports --- language: "en" --- # User Manual 0.5.x ## What is the Confluence for Bitbucket add-on? ![logo-square.png](https://help.devopssystems.de/__attachments/a_6644b6d202d4fcdb0758bbe1d8fe0277cd0e39b6d4c5416e3297e4c62fe2aa1f/logo-square.png?cb=deed5bd2cb77b9b445a8bdd18db7f365) 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. ![settings-main.png](https://help.devopssystems.de/__attachments/a_e45ca204e8f04d487d583c8b2adc46d51689c42ccc152bb94e561ad0b37458d6/settings-main.png?cb=b5211720c26217963e4cf6b85cdec688) 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. ![settings-rule.png](https://help.devopssystems.de/__attachments/a_9584685ec9bb6fa131d5a4c09dee8534262b620f8b420d06c022e502c2be892d/settings-rule.png?cb=5eec305c15cb05c9b7a187086d74252f) * ***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](https://developer.atlassian.com/server/confluence/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](https://confluence.atlassian.com/doc/page-properties-macro-184550024.html) . 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. --- language: "en" --- # User Manual 0.6.x ## What is the Confluence for Bitbucket add-on? ![logo-square.png](https://help.devopssystems.de/__attachments/a_a49bda0f45cdc187371af7aa1a9ca08038068602d5b12d0f8bf60a4241695cfb/logo-square.png?cb=deed5bd2cb77b9b445a8bdd18db7f365) 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. ![settings-main.png](https://help.devopssystems.de/__attachments/a_5364444b9f287b1490fb94ecaa83f4060767b2dc29231ef875c1fea77039a8d3/settings-main.png?cb=b5211720c26217963e4cf6b85cdec688) 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. ![settings-rule.png](https://help.devopssystems.de/__attachments/a_3942212bdf0b8da5acbcdc1d6415ce803cc2112facc4e897b1df8f6c801712f5/settings-rule.png?cb=5eec305c15cb05c9b7a187086d74252f) * ***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](https://developer.atlassian.com/server/confluence/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](https://confluence.atlassian.com/doc/page-properties-macro-184550024.html) . 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. --- language: "en" --- # User Manual 1.0.x ![logo-square.png](https://help.devopssystems.de/__attachments/a_9e3668a057317cd6eb8ec61c15c2e566a87ca65b1dd70b684e06df9e29e0298d/logo-square.png?cb=deed5bd2cb77b9b445a8bdd18db7f365) **Table of contents** ## 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. It is exactly this interaction that Confluence Hooks takes care of for you. If documents do not exist or simply have the wrong attributes, this add-on can prevent a code change. A push or a merge is rejected and reference is made to missing or incorrect documentation. With each push and with each merge the add-on compares whether your documentation guidelines are fulfilled. ## Add-on Setup Because the add-on will check if a valid Confluence page exists, an application link must exist between Bitbucket and Confluence. Please follow the steps below to create a application link. |---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 1 | In the Bitbucket "Administration" menu, select **Application links** | | | 2 | If no valid link exists, you have to create a new one using the **Create new link** button | ![create-link.png](https://help.devopssystems.de/__attachments/a_eaa2612bcae314d47d860488190bd972f38b912a435aa0666a0195aa7626744a/create-link.png?cb=0255a322e81aec486c9a829d7c963536) | | 3 | * You should be adminstrator in Confluence. * Depending on your user management you can confirm that both instances have the same users or not * (If unsure leave it unchecked) * The **Continue** Button will start the creation of the application link and will redirect you to the Confluence instance you have entered. | ![ApplicationLinkCreation.png](https://help.devopssystems.de/__attachments/a_ca7e9860751ddeda7e6d445afb0ed55d85c1a332986dd8f54298f3c717898d7c/ApplicationLinkCreation.png?cb=e6991314c44d50aad5015c1484c06d8f) | | 4 | In Confluence you can now confirm the application link. Please press the **Continue** button and you will be redirected to Bitbucket. | ![ConfluenceRedirect.png](https://help.devopssystems.de/__attachments/a_dff7127dec567474f56747b18bbed39d395e93508a20238c8d4b4bf508da8cd7/ConfluenceRedirect.png?cb=678e63b601dd97eaa59e61d3b6de273a) | | 5 | After the redirection to Bitbucket has been done, you will see a connected a Confluence instance in you application link list. | ![ValidConfluenceLink.png](https://help.devopssystems.de/__attachments/a_9d04f87f921350e441aa33900492c5b3164f9f7c4f501bf17cb91e8a51a2656e/ValidConfluenceLink.png?cb=921bda2036cac7933b3a3d94df8b26ed) | | 6 | Finally you can check the authentication settings of the application link, via pressing the **pen button.**By default OAuth should be selected, which is correct | ![OAuthIsFine.png](https://help.devopssystems.de/__attachments/a_9562b7d69975cf96b883def6b6e7fbc9cbfc8be86018d88dada063d0d24373e0/OAuthIsFine.png?cb=9fb956cbe7c2621427986a80a5620f90) | ## Hook Configuration \& Hands-on Example In the next sections we will explain the possibilities of the hook and illustrate the configuration in several steps with a hands-on example. Together we will configure the hook step by step and perform a code change with you to show the effects of the hook. ### Where you can find the hook configuration? * **Step 1**: The configuration of the hook you will find in the administration area of your project or repository * **Step 2:** You can now find the configuration under the standard place for hook * **Hooks** if you would like to configure push check * **Merge Checks** if you would like to configure to configure merge checks * **Step 3:**Open the Confluence Hooks configuration ![HookConfiguration.png](https://help.devopssystems.de/__attachments/a_e4783a03d779b65251779bce960f640d0c8fbb3bc9f7d10dbda317971578c8aa/HookConfiguration.png?cb=41f7217571ca3c60f99cdd40a832b5ac) ### How can I configure the hook? The hook evaluates whether a specific Confluence page exists for a code change or a branch. To better identify this Confluence page, an issue key can also be used, which is found in a commit message. Thus it is possible to capture the issue key from a commit message and use this information when searching for a specific page. More about this in the following sections. To capture this issue key a regular expression is used, which can be configured via the field***Issue-key regular expression (see screenshot).***Of course, you don't need an issue key to search for a Confluence Page. But usually it makes not much sense to do this, because an issue key is an important factor to identify a corresponding page for a code change, because an issue key is representative for a code change. And normally you are looking for pages which have a direct relation to a code change. But maybe there are commits in your workflow which do not contain issue keys. These issue keys can be excluded from further evaluation. For this you can select the following option. If this is the case, all further rules (which will be configured afterwards) will not be evaluated if no issue key was found. Normally, you do not need to change anything in these settings and can proceed directly to step 4. The validity of the issue is not checked. The issue key is used exclusively in the fields of a rule. If you want to check the validity of the issue key, please use the [Jira Hooks for Bitbucket](https://marketplace.atlassian.com/apps/1211959/jira-hooks-for-bitbucket?tab=overview&hosting=datacenter) add-on. **Step 4 - Add Rule:** 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.** ![HookConfigurationAddRule.png](https://help.devopssystems.de/__attachments/a_8b49c29663f5625c3bd01399ed00a2abb0623bb746c44b343e2720a8b1f6c082/HookConfigurationAddRule.png?cb=75f666580272a5d590fa6beee712dbec) **Step 5 Possibilities to configure a rule** A rule aims to find one or more Confluence pages and evaluate this page against the configuration. As soon the configuration is violated, a push or merge is rejected. Since a check is always performed based on a code change, the properties of a code change should also be able to be used for a search. Therefore, different information is available as keywords to be able to use them in the further rule configuration. **Keywords:** * **%key%** - Represents an issue key which was found. * **%branch%** - Represents the branch name where the changes were made. * **%hash%** - Identifies a hash in which e.g. an issue key was found 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 values A rule is evaluated for each issue key found and for each branch found. So if 3 different issue keys are pushed in one or more commit messages, then each rule is checked for each issue key and each branch. So in this example the rules are checked 4 times (3 issue keys + 1 branch). |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ![HookConfigurationSettings.png](https://help.devopssystems.de/__attachments/a_bbd7c6f2f3c5da30c3c680617f38175661266b8df6169fccfbbbed40855a921b/HookConfigurationSettings.png?cb=a076245b15fdb1f96c5d24c13e9e303b) | **Rule Options** To follow our hands-on example the following options are now occupied. You will find a short description of the options as well as snippets, which you can copy directly into the respective options. * ***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 ``` Software design document is needed ``` * ***CQL rule:*** The CQL rule identifies all 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](https://developer.atlassian.com/server/confluence/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. ``` label = "%key%" and label = "chfb-demonstration" and label = "design-document" ``` Based on this CQL now all sides are selected, which have the following labels **design-document** - e.g. the label which identifies your design documents **issue-key** - so that the correct design document is identified for your code change **chfb-demonstration** - a unique label to uniquely identify pages for the participation example * ***Like count:*** With the *"Like count"* you can define how many Likes a 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. ``` 1 // select all pages must have the given like count ``` * ***Page properties***: With the option "Page Properties" the properties of a Confluence page can be evaluated, based on the [Page Properties Macro](https://confluence.atlassian.com/doc/page-properties-macro-184550024.html) . 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) ``` status=Approved reviewer+ // select all pages must match the properties // select all key pairs must match ``` Based on these settings, the selected pages must have a page properties macro. This macro must contain a table with the "**Status** " field having the value "**Approved** " and the "**Reviewer** " field with **some** **user**. * ***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. ``` No valid software design document has been found for the given code change (issue: %key%) ``` * ***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. ``` Please create a software design document for the issue %key% and please ask your team lead to approve the design document. ``` | ``` ``` ``` ``` ``` ``` **Steps 7 - 11 Create a Confluence Page** Open the Confluence instance you configured as an application link and create a Confluence page in any space. Of course, the user you use in Bitbucket should have read permissions on this page via the application link. |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ![CFCreatePage.png](https://help.devopssystems.de/__attachments/a_4a94236d5136f7690ddba6111a092c7cd2cd663085f87013b69c0d85a3d21543/CFCreatePage.png?cb=28095d53bd1e59d4dd83f28e6233403c) | **Step - 7:** Create a Confluence page as usual via the **Create Button** | | ![CFAddPageMacro.png](https://help.devopssystems.de/__attachments/a_688c08c3e9240070e11a0445bcd144c6c22996b0ea1d7e849292fb06e0d3439d/CFAddPageMacro.png?cb=2bfe185a9bfe4eb3e5f6891e83166090) | **Step 8:** You can choose any page name, because the page selection in our example is done via labels only. **Step 9:** In order to evaluate the page properties, a Confluence page must also contain a page properties macro. Therefore the macro is added in this step | | ![CFInsertMacro.png](https://help.devopssystems.de/__attachments/a_cdb3cecaf338fc3d21e40a4ba8334a127baac0d266ea95e7557b4d666f64e3d2/CFInsertMacro.png?cb=aacd2317f2915574d0cd8b948d4db75d) | **Step 10:** You do not necessarily have to enter further details with the macro - Just press insert | | ![CFInsertProperties.png](https://help.devopssystems.de/__attachments/a_122be0b260b04a9265c73616abe5a98b7477f7d649b445dfceb72e91f80b6e96/CFInsertProperties.png?cb=dd6cda550b7163541f5ef417c96e20bd) | **Step 11:** Now you can add a table to the Page Property macro that represents the keys and values of the page. * **Step 11.1**: In our example we change the table header from hoizintal to vertical. * **Step 11.2**: We add the properties Designer, Status and Reviewer * **Step 11.3**: For the Status we use the macro Status | | ![CFAddLabels.png](https://help.devopssystems.de/__attachments/a_1096b78c73f98a84fe6fa6e66360e9d5a9acd2b4441f7705403b9a79e21e28d8/CFAddLabels.png?cb=bedad4ff10ec05c86bba3de181e77aa0) | **Step 12:** Because the page selection in our example is done via labels only, we have to add 3 labels to the page ``` test-1 design-document chfb-demonstration ``` | | ![CFPageResult.png](https://help.devopssystems.de/__attachments/a_6b36f0e77b50d182f3061b8279b37da504906a6ee4f0cecac1e5b28284ff63fe/CFPageResult.png?cb=522a4385f165ea429a36e17ebd7367a2) | The final page should be like this It is intended that the page will not get any likes yet | **Steps 13-20 - Git clone - commit - push** Now that we have created the hook and created a Confluence page for the test, we are ready to execute the test using Git commands. We will now clone the Git repository where we have configured the hook, make a change, commit the change with the issue key "TEST-1" and push it afterwards. Since the page has not received any likes yet, we expect the push to fail. **Execute the following commands (e.g. in your /tmp directory)** * **Step-13:** Clone your git Repository Bash git clone http://admin@bitbucket-server/scm/project_1/rep_1.git ![git-clone.png](https://help.devopssystems.de/__attachments/a_e5328a3a7e0bba8a4983334edf0eb98eb449f37bb8432705e77fcf06cbb57664/git-clone.png?cb=030c01fe508f6f287b37fe4c3f6c28d0) * **Step 14 -**Got into the repository Bash cd rep_1 ![git-cd.png](https://help.devopssystems.de/__attachments/a_17092a6ed786c3c0400a82359037dba765b444367caf3cf4bfc87d393debe7a8/git-cd.png?cb=3d7597332455a1cb92ed1ba185a22d10) * **Step 15** - Create a file, add file, commit file with the issue key TEST-1 Bash echo "test-string" >> test1.txt git add test1.txt git commit -m "TEST-1 anything" ![git-modify.png](https://help.devopssystems.de/__attachments/a_f6c32b69b25b522b92def7c6af257309efd3b10ab3948aeca8422d100b433a78/git-modify.png?cb=378894ae3ce86e1fc28806915a71a698) * **Step 16** - Push the changes Bash git push ![git-push.png](https://help.devopssystems.de/__attachments/a_c9e24b7a3c3103a0af03f53a70d3f9e7316ca5302c34d6a5fdc833f48bc1f6ea/git-push.png?cb=548d0a30131278323ccbe94c53b10f03) As you can see, the change could not be pushed. The correct page was selected based on our CQL, the status and reviewer were successfully evaluated, but no like could be found. * **Step 17** - Edit the Confluence page - set the status of the page to **OPEN** ![CFWrongStatus.png](https://help.devopssystems.de/__attachments/a_e0409deab3cfe76a7d1a4361e093855d1afc442910334662373d7d19eb570863/CFWrongStatus.png?cb=55a88f8603d56e762a50f48a97a9a50e) Now the push should fail because the status of the document does not match APPROVED and the page still has no likes. * **Step 18** - Push again Bash git push ![git-push-2.png](https://help.devopssystems.de/__attachments/a_6e63184d60c1a8afd7b2d1093bc95fa654caebd2e77476b2512dd2e0f8af0400/git-push-2.png?cb=de2c6a5834c20fade150b53a86b6e1e9) As you can see, the change could not be pushed. Because of the wrong status and the missing like ![ConfigRelation.png](https://help.devopssystems.de/__attachments/a_99eb902eb6476c9bf186e024eeee5540e7d1e5ef105e1237b945de16066c6ae8/ConfigRelation.png?cb=c5d75cfb616417c7913a4a4b953b4b08) * **Step 18** - Lets change the Confluence page again (Add a like and set the correct status) * ![CFCorrect.png](https://help.devopssystems.de/__attachments/a_7c2ab12cdd80f058aa3be06e9a756c5483e2b07d8e8c989e90480549aae17532/CFCorrect.png?cb=56a8f98456f8291353d24b38ca742d96) * **Step 19 - PUSH AGAIN** Now the push works... ![git-push-3.png](https://help.devopssystems.de/__attachments/a_8abca03dbb24603a140c5faf53fa9fec30b158c6c53a916e0671c9589f13a696/git-push-3.png?cb=e18eb9baacbc4c4d10417bd3dfe4d1dd) * **Last Step** It would be super helpful if you could give us feedback. We are constantly trying to make our products even better and for that we need your feedback. Please leave us a message in our [service desk](http://It would be super helpful if you could give us feedback. We are constantly trying to make our products even better and for that we need your feedback among other things. Please leave us a message in our service desk) --- language: "en" --- # User Manual 1.1.x ![logo-square.png](https://help.devopssystems.de/__attachments/a_6c9500b89611eb300a27a814db6c9e862deac02aa4ebadfcae435d64ba970d82/logo-square.png?cb=deed5bd2cb77b9b445a8bdd18db7f365) **Table of contents** ## 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. It is exactly this interaction that Confluence Hooks takes care of for you. If documents do not exist or simply have the wrong attributes, this add-on can prevent a code change. A push or a merge is rejected and reference is made to missing or incorrect documentation. With each push and with each merge the add-on compares whether your documentation guidelines are fulfilled. ## Add-on Setup Because the add-on will check if a valid Confluence page exists, an application link must exist between Bitbucket and Confluence. Please follow the steps below to create a application link. |---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 1 | In the Bitbucket "Administration" menu, select **Application links** | | | 2 | If no valid link exists, you have to create a new one using the **Create new link** button | ![create-link.png](https://help.devopssystems.de/__attachments/a_07613b118a847b3ec2e56611eb64ae7a45c776ec9331c09083e49869dc347625/create-link.png?cb=0255a322e81aec486c9a829d7c963536) | | 3 | * You should be adminstrator in Confluence. * Depending on your user management you can confirm that both instances have the same users or not * (If unsure leave it unchecked) * The **Continue** Button will start the creation of the application link and will redirect you to the Confluence instance you have entered. | ![ApplicationLinkCreation.png](https://help.devopssystems.de/__attachments/a_1c1c34264527493c9c742a0677d473f4d8868e8859e511a537248d9b19a3b4e4/ApplicationLinkCreation.png?cb=e6991314c44d50aad5015c1484c06d8f) | | 4 | In Confluence you can now confirm the application link. Please press the **Continue** button and you will be redirected to Bitbucket. | ![ConfluenceRedirect.png](https://help.devopssystems.de/__attachments/a_fd76ec54eedaf20c3f5d123e6b52887e37aa8a807fbba749880f3cf0fdc5c061/ConfluenceRedirect.png?cb=678e63b601dd97eaa59e61d3b6de273a) | | 5 | After the redirection to Bitbucket has been done, you will see a connected a Confluence instance in you application link list. | ![ValidConfluenceLink.png](https://help.devopssystems.de/__attachments/a_72bee4546b329ecc3f03aa1b2d0192ebbec8a598079e8db6d6f1832287acfaf1/ValidConfluenceLink.png?cb=921bda2036cac7933b3a3d94df8b26ed) | | 6 | Finally you can check the authentication settings of the application link, via pressing the **pen button.**By default OAuth should be selected, which is correct | ![OAuthIsFine.png](https://help.devopssystems.de/__attachments/a_b3255b0b4fd05809d9bcd426606ab5ca6dfee558854e58984c17a7cbe2a343c7/OAuthIsFine.png?cb=9fb956cbe7c2621427986a80a5620f90) | ## Hook Configuration \& Hands-on Example In the next sections we will explain the possibilities of the hook and illustrate the configuration in several steps with a hands-on example. Together we will configure the hook step by step and perform a code change with you to show the effects of the hook. ### Where you can find the hook configuration? * **Step 1**: The configuration of the hook you will find in the administration area of your project or repository * **Step 2:** You can now find the configuration under the standard place for hook * **Hooks** if you would like to configure push check * **Merge Checks** if you would like to configure to configure merge checks * **Step 3:**Open the Confluence Hooks configuration ![HookConfiguration.png](https://help.devopssystems.de/__attachments/a_84854acc28ab8e2012e0444f1e68386d75a2fedad96b81d51483e3e433cb7e1f/HookConfiguration.png?cb=41f7217571ca3c60f99cdd40a832b5ac) ### How can I configure the hook? The hook evaluates whether a specific Confluence page exists for a code change or a branch. To better identify this Confluence page, an issue key can also be used, which is found in a commit message. Thus it is possible to capture the issue key from a commit message and use this information when searching for a specific page. More about this in the following sections. To capture this issue key a regular expression is used, which can be configured via the field***Issue-key regular expression (see screenshot).***Of course, you don't need an issue key to search for a Confluence Page. But usually it makes not much sense to do this, because an issue key is an important factor to identify a corresponding page for a code change, because an issue key is representative for a code change. And normally you are looking for pages which have a direct relation to a code change. But maybe there are commits in your workflow which do not contain issue keys. These issue keys can be excluded from further evaluation. For this you can select the following option. If this is the case, all further rules (which will be configured afterwards) will not be evaluated if no issue key was found. Normally, you do not need to change anything in these settings and can proceed directly to step 4. The validity of the issue is not checked. The issue key is used exclusively in the fields of a rule. If you want to check the validity of the issue key, please use the [Jira Hooks for Bitbucket](https://marketplace.atlassian.com/apps/1211959/jira-hooks-for-bitbucket?tab=overview&hosting=datacenter) add-on. **Step 4 - Add Rule:** 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.** ![HookConfigurationAddRule.png](https://help.devopssystems.de/__attachments/a_08133e57bff60c4f26bdf91b7f7ee9b3e9e713b76f9ddd69ca84a0ba2656a625/HookConfigurationAddRule.png?cb=75f666580272a5d590fa6beee712dbec) **Step 5 Possibilities to configure a rule** A rule aims to find one or more Confluence pages and evaluate this page against the configuration. As soon the configuration is violated, a push or merge is rejected. Since a check is always performed based on a code change, the properties of a code change should also be able to be used for a search. Therefore, different information is available as keywords to be able to use them in the further rule configuration. **Keywords:** * **%key%** - Represents an issue key which was found. * **%branch%** - Represents the branch name where the changes were made. * **%hash%** - Identifies a hash in which e.g. an issue key was found 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 values A rule is evaluated for each issue key found and for each branch found. So if 3 different issue keys are pushed in one or more commit messages, then each rule is checked for each issue key and each branch. So in this example the rules are checked 4 times (3 issue keys + 1 branch). |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ![HookConfigurationSettings.png](https://help.devopssystems.de/__attachments/a_01fbf5f5b408539b72ed8332723a45d392606aaf1087b33eb527486803477645/HookConfigurationSettings.png?cb=a076245b15fdb1f96c5d24c13e9e303b) | **Rule Options** To follow our hands-on example the following options are now occupied. You will find a short description of the options as well as snippets, which you can copy directly into the respective options. * ***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 ``` Software design document is needed ``` * ***CQL rule:*** The CQL rule identifies all 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](https://developer.atlassian.com/server/confluence/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. ``` label = "%key%" and label = "chfb-demonstration" and label = "design-document" ``` Based on this CQL now all sides are selected, which have the following labels **design-document** - e.g. the label which identifies your design documents **issue-key** - so that the correct design document is identified for your code change **chfb-demonstration** - a unique label to uniquely identify pages for the participation example * ***Like count:*** With the *"Like count"* you can define how many Likes a 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. ``` 1 // select all pages must have the given like count ``` * ***Page properties***: With the option "Page Properties" the properties of a Confluence page can be evaluated, based on the [Page Properties Macro](https://confluence.atlassian.com/doc/page-properties-macro-184550024.html) . 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) ``` status=Approved reviewer+ // select all pages must match the properties // select all key pairs must match ``` Based on these settings, the selected pages must have a page properties macro. This macro must contain a table with the "**Status** " field having the value "**Approved** " and the "**Reviewer** " field with **some** **user**. * ***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. ``` No valid software design document has been found for the given code change (issue: %key%) ``` * ***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. ``` Please create a software design document for the issue %key% and please ask your team lead to approve the design document. ``` | ``` ``` ``` ``` ``` ``` **Steps 7 - 11 Create a Confluence Page** Open the Confluence instance you configured as an application link and create a Confluence page in any space. Of course, the user you use in Bitbucket should have read permissions on this page via the application link. |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ![CFCreatePage.png](https://help.devopssystems.de/__attachments/a_63f8ae13dae528cf92b3aef935584038722204f22a28bb72186037dc50b0221a/CFCreatePage.png?cb=28095d53bd1e59d4dd83f28e6233403c) | **Step - 7:** Create a Confluence page as usual via the **Create Button** | | ![CFAddPageMacro.png](https://help.devopssystems.de/__attachments/a_793f6fe2de0c412acaf203332aea5cf4b9e5fe7e6bf8417c6bf341b898e21c24/CFAddPageMacro.png?cb=2bfe185a9bfe4eb3e5f6891e83166090) | **Step 8:** You can choose any page name, because the page selection in our example is done via labels only. **Step 9:** In order to evaluate the page properties, a Confluence page must also contain a page properties macro. Therefore the macro is added in this step | | ![CFInsertMacro.png](https://help.devopssystems.de/__attachments/a_0d32d40079fdb50c9945c9f20bd3561d2df0071bb4b1f7c2f192b41ead5bd5a7/CFInsertMacro.png?cb=aacd2317f2915574d0cd8b948d4db75d) | **Step 10:** You do not necessarily have to enter further details with the macro - Just press insert | | ![CFInsertProperties.png](https://help.devopssystems.de/__attachments/a_b0e1756b6c121b240feddd34d6db2ae2dabf0eb07a3330cb0ca3576eeb44393d/CFInsertProperties.png?cb=dd6cda550b7163541f5ef417c96e20bd) | **Step 11:** Now you can add a table to the Page Property macro that represents the keys and values of the page. * **Step 11.1**: In our example we change the table header from hoizintal to vertical. * **Step 11.2**: We add the properties Designer, Status and Reviewer * **Step 11.3**: For the Status we use the macro Status | | ![CFAddLabels.png](https://help.devopssystems.de/__attachments/a_edb302a6d92525ccc2e2859b98148e9f6f8052f5b2afff1fe47f3ac9879b2e8f/CFAddLabels.png?cb=bedad4ff10ec05c86bba3de181e77aa0) | **Step 12:** Because the page selection in our example is done via labels only, we have to add 3 labels to the page ``` test-1 design-document chfb-demonstration ``` | | ![CFPageResult.png](https://help.devopssystems.de/__attachments/a_2839f0b33066c679d016d055020368532b27a0cae2d14807cf0a881f8f40f440/CFPageResult.png?cb=522a4385f165ea429a36e17ebd7367a2) | The final page should be like this It is intended that the page will not get any likes yet | **Steps 13-20 - Git clone - commit - push** Now that we have created the hook and created a Confluence page for the test, we are ready to execute the test using Git commands. We will now clone the Git repository where we have configured the hook, make a change, commit the change with the issue key "TEST-1" and push it afterwards. Since the page has not received any likes yet, we expect the push to fail. **Execute the following commands (e.g. in your /tmp directory)** * **Step-13:** Clone your git Repository Bash git clone http://admin@bitbucket-server/scm/project_1/rep_1.git ![git-clone.png](https://help.devopssystems.de/__attachments/a_a7623641e11f7b82f3a152b1ddc8b85ab5c9fc5f467f7fc86e5428fdc60040fb/git-clone.png?cb=030c01fe508f6f287b37fe4c3f6c28d0) * **Step 14 -**Got into the repository Bash cd rep_1 ![git-cd.png](https://help.devopssystems.de/__attachments/a_3aa0830406716871a2d18ff85ea3b7e4590a01e13a565419f63ef3290b51a730/git-cd.png?cb=3d7597332455a1cb92ed1ba185a22d10) * **Step 15** - Create a file, add file, commit file with the issue key TEST-1 Bash echo "test-string" >> test1.txt git add test1.txt git commit -m "TEST-1 anything" ![git-modify.png](https://help.devopssystems.de/__attachments/a_982b068ec616362755efb625be7494362b436e5c3ff90d793aa63eb599b9a4f2/git-modify.png?cb=378894ae3ce86e1fc28806915a71a698) * **Step 16** - Push the changes Bash git push ![git-push.png](https://help.devopssystems.de/__attachments/a_d891b215001c3b5ca401bf0f6b882ea3f847870ec1433be197341a3d1e8c9b97/git-push.png?cb=548d0a30131278323ccbe94c53b10f03) As you can see, the change could not be pushed. The correct page was selected based on our CQL, the status and reviewer were successfully evaluated, but no like could be found. * **Step 17** - Edit the Confluence page - set the status of the page to **OPEN** ![CFWrongStatus.png](https://help.devopssystems.de/__attachments/a_4ec80a064e507bfda884e71d5de69d0600cfc41087a788195253ec51c525e288/CFWrongStatus.png?cb=55a88f8603d56e762a50f48a97a9a50e) Now the push should fail because the status of the document does not match APPROVED and the page still has no likes. * **Step 18** - Push again Bash git push ![git-push-2.png](https://help.devopssystems.de/__attachments/a_d2e9eea7d21a76f09646a92e0e6c1ecab368855637ff0c3c64c29e597015a057/git-push-2.png?cb=de2c6a5834c20fade150b53a86b6e1e9) As you can see, the change could not be pushed. Because of the wrong status and the missing like ![ConfigRelation.png](https://help.devopssystems.de/__attachments/a_21e7d8b0040f552781b2df200d0a59bc48135f256e8510d97e4d2c6db3480b09/ConfigRelation.png?cb=c5d75cfb616417c7913a4a4b953b4b08) * **Step 18** - Lets change the Confluence page again (Add a like and set the correct status) * ![CFCorrect.png](https://help.devopssystems.de/__attachments/a_c44dddfc92c90890f374942bf89a1b086605dab5c0ab8ef0ec420fc4f2a467cf/CFCorrect.png?cb=56a8f98456f8291353d24b38ca742d96) * **Step 19 - PUSH AGAIN** Now the push works... ![git-push-3.png](https://help.devopssystems.de/__attachments/a_5847aa8311c72e88803cdf38d2ca66201e2e4b17b466ed7025bb109f7929c12e/git-push-3.png?cb=e18eb9baacbc4c4d10417bd3dfe4d1dd) * **Last Step** It would be super helpful if you could give us feedback. We are constantly trying to make our products even better and for that we need your feedback. Please leave us a message in our [service desk](http://It would be super helpful if you could give us feedback. We are constantly trying to make our products even better and for that we need your feedback among other things. Please leave us a message in our service desk) --- language: "en" --- # User Manual 2.0.x ![logo-square.png](https://help.devopssystems.de/__attachments/a_c75785e7fa03b3d8361cab6deb588b515fb06aefe0cfb5893ea1738261a40451/logo-square.png?cb=deed5bd2cb77b9b445a8bdd18db7f365) **Table of contents** ## 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. It is exactly this interaction that Confluence Hooks takes care of for you. If documents do not exist or simply have the wrong attributes, this add-on can prevent a code change. A push or a merge is rejected and reference is made to missing or incorrect documentation. With each push and with each merge the add-on compares whether your documentation guidelines are fulfilled. ## Add-on Setup Because the add-on will check if a valid Confluence page exists, an application link must exist between Bitbucket and Confluence. Please follow the steps below to create a application link. |---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 1 | In the Bitbucket "Administration" menu, select **Application links** | | | 2 | If no valid link exists, you have to create a new one using the **Create new link** button | ![create-link.png](https://help.devopssystems.de/__attachments/a_61b3f37204d5f473078e1e6a1a317230271faa0409f226011f9a3264d8cb5e33/create-link.png?cb=0255a322e81aec486c9a829d7c963536) | | 3 | * You should be adminstrator in Confluence. * Depending on your user management you can confirm that both instances have the same users or not * (If unsure leave it unchecked) * The **Continue** Button will start the creation of the application link and will redirect you to the Confluence instance you have entered. | ![ApplicationLinkCreation.png](https://help.devopssystems.de/__attachments/a_b2b0072df8dad7d7d7e536dad063de22397a7dc295c0784d92258fbeb6bca272/ApplicationLinkCreation.png?cb=e6991314c44d50aad5015c1484c06d8f) | | 4 | In Confluence you can now confirm the application link. Please press the **Continue** button and you will be redirected to Bitbucket. | ![ConfluenceRedirect.png](https://help.devopssystems.de/__attachments/a_e954f2a9ad1f3c9326f87e3095190cc354413d9fb027e0766215dc5f6a479993/ConfluenceRedirect.png?cb=678e63b601dd97eaa59e61d3b6de273a) | | 5 | After the redirection to Bitbucket has been done, you will see a connected a Confluence instance in you application link list. | ![ValidConfluenceLink.png](https://help.devopssystems.de/__attachments/a_526e6b7a4ba34b747a5e3a0fe629e3cfad9cbaf2296f6e25c8e1dc8995647e0b/ValidConfluenceLink.png?cb=921bda2036cac7933b3a3d94df8b26ed) | | 6 | Finally you can check the authentication settings of the application link, via pressing the **pen button.**By default OAuth should be selected, which is correct | ![OAuthIsFine.png](https://help.devopssystems.de/__attachments/a_89556cb9f3d88ba7476ae91504c434a1094fae027256d17eeb419488aa9c5b40/OAuthIsFine.png?cb=9fb956cbe7c2621427986a80a5620f90) | ## Hook Configuration \& Hands-on Example In the next sections we will explain the possibilities of the hook and illustrate the configuration in several steps with a hands-on example. Together we will configure the hook step by step and perform a code change with you to show the effects of the hook. ### Where you can find the hook configuration? * **Step 1**: The configuration of the hook you will find in the administration area of your project or repository * **Step 2:** You can now find the configuration under the standard place for hook * **Hooks** if you would like to configure push check * **Merge Checks** if you would like to configure to configure merge checks * **Step 3:**Open the Confluence Hooks configuration ![HookConfiguration.png](https://help.devopssystems.de/__attachments/a_791a0b4cf02fa9bac325c18ad7e9f29bbc779b692a5ae1c9dbe2f15b25d5531a/HookConfiguration.png?cb=41f7217571ca3c60f99cdd40a832b5ac) ### How can I configure the hook? The hook evaluates whether a specific Confluence page exists for a code change or a branch. To better identify this Confluence page, an issue key can also be used, which is found in a commit message. Thus it is possible to capture the issue key from a commit message and use this information when searching for a specific page. More about this in the following sections. To capture this issue key a regular expression is used, which can be configured via the field***Issue-key regular expression (see screenshot).***Of course, you don't need an issue key to search for a Confluence Page. But usually it makes not much sense to do this, because an issue key is an important factor to identify a corresponding page for a code change, because an issue key is representative for a code change. And normally you are looking for pages which have a direct relation to a code change. But maybe there are commits in your workflow which do not contain issue keys. These issue keys can be excluded from further evaluation. For this you can select the following option. If this is the case, all further rules (which will be configured afterwards) will not be evaluated if no issue key was found. Normally, you do not need to change anything in these settings and can proceed directly to step 4. The validity of the issue is not checked. The issue key is used exclusively in the fields of a rule. If you want to check the validity of the issue key, please use the [Jira Hooks for Bitbucket](https://marketplace.atlassian.com/apps/1211959/jira-hooks-for-bitbucket?tab=overview&hosting=datacenter) add-on. **Step 4 - Add Rule:** 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.** ![HookConfigurationAddRule.png](https://help.devopssystems.de/__attachments/a_6afd2fb96fea345c089fe3fa8c574e443c144ec2d01d2407413e0eb09fa04402/HookConfigurationAddRule.png?cb=75f666580272a5d590fa6beee712dbec) **Step 5 Possibilities to configure a rule** A rule aims to find one or more Confluence pages and evaluate this page against the configuration. As soon the configuration is violated, a push or merge is rejected. Since a check is always performed based on a code change, the properties of a code change should also be able to be used for a search. Therefore, different information is available as keywords to be able to use them in the further rule configuration. **Keywords:** * **%key%** - Represents an issue key which was found. * **%branch%** - Represents the branch name where the changes were made. * **%hash%** - Identifies a hash in which e.g. an issue key was found 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 values A rule is evaluated for each issue key found and for each branch found. So if 3 different issue keys are pushed in one or more commit messages, then each rule is checked for each issue key and each branch. So in this example the rules are checked 4 times (3 issue keys + 1 branch). |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ![HookConfigurationSettings.png](https://help.devopssystems.de/__attachments/a_8ff8b67a49c258067b9492772ac26c362071f212503c7922773100aa9ed088d8/HookConfigurationSettings.png?cb=a076245b15fdb1f96c5d24c13e9e303b) | **Rule Options** To follow our hands-on example the following options are now occupied. You will find a short description of the options as well as snippets, which you can copy directly into the respective options. * ***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 ``` Software design document is needed ``` * ***CQL rule:*** The CQL rule identifies all 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](https://developer.atlassian.com/server/confluence/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. ``` label = "%key%" and label = "chfb-demonstration" and label = "design-document" ``` Based on this CQL now all sides are selected, which have the following labels **design-document** - e.g. the label which identifies your design documents **issue-key** - so that the correct design document is identified for your code change **chfb-demonstration** - a unique label to uniquely identify pages for the participation example * ***Like count:*** With the *"Like count"* you can define how many Likes a 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. ``` 1 // select all pages must have the given like count ``` * ***Page properties***: With the option "Page Properties" the properties of a Confluence page can be evaluated, based on the [Page Properties Macro](https://confluence.atlassian.com/doc/page-properties-macro-184550024.html) . 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) ``` status=Approved reviewer+ // select all pages must match the properties // select all key pairs must match ``` Based on these settings, the selected pages must have a page properties macro. This macro must contain a table with the "**Status** " field having the value "**Approved** " and the "**Reviewer** " field with **some** **user**. * ***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. ``` No valid software design document has been found for the given code change (issue: %key%) ``` * ***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. ``` Please create a software design document for the issue %key% and please ask your team lead to approve the design document. ``` | ``` ``` ``` ``` ``` ``` **Steps 7 - 11 Create a Confluence Page** Open the Confluence instance you configured as an application link and create a Confluence page in any space. Of course, the user you use in Bitbucket should have read permissions on this page via the application link. |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ![CFCreatePage.png](https://help.devopssystems.de/__attachments/a_e59de2ead708e0804fe0919c4aa6fc0dd43b58787bb9b1d66069701350522817/CFCreatePage.png?cb=28095d53bd1e59d4dd83f28e6233403c) | **Step - 7:** Create a Confluence page as usual via the **Create Button** | | ![CFAddPageMacro.png](https://help.devopssystems.de/__attachments/a_6846727c092c9a42a3a1116292840175630eef0f5ac885e6bc937a7863605822/CFAddPageMacro.png?cb=2bfe185a9bfe4eb3e5f6891e83166090) | **Step 8:** You can choose any page name, because the page selection in our example is done via labels only. **Step 9:** In order to evaluate the page properties, a Confluence page must also contain a page properties macro. Therefore the macro is added in this step | | ![CFInsertMacro.png](https://help.devopssystems.de/__attachments/a_f860147e9342406a091bbd2ae6c745e8147520763259d441cba926def6033d34/CFInsertMacro.png?cb=aacd2317f2915574d0cd8b948d4db75d) | **Step 10:** You do not necessarily have to enter further details with the macro - Just press insert | | ![CFInsertProperties.png](https://help.devopssystems.de/__attachments/a_fcfd2c103bd9de05fcd1dd9ab66fc50addbc2ee35b71ab8be5fa7fe3487a17e3/CFInsertProperties.png?cb=dd6cda550b7163541f5ef417c96e20bd) | **Step 11:** Now you can add a table to the Page Property macro that represents the keys and values of the page. * **Step 11.1**: In our example we change the table header from hoizintal to vertical. * **Step 11.2**: We add the properties Designer, Status and Reviewer * **Step 11.3**: For the Status we use the macro Status | | ![CFAddLabels.png](https://help.devopssystems.de/__attachments/a_ddb0f60e5af1668e415b00448e6ac8b3c074da664bcdc70dc69b90fd846649b5/CFAddLabels.png?cb=bedad4ff10ec05c86bba3de181e77aa0) | **Step 12:** Because the page selection in our example is done via labels only, we have to add 3 labels to the page ``` test-1 design-document chfb-demonstration ``` | | ![CFPageResult.png](https://help.devopssystems.de/__attachments/a_709b7dca60261051c3c1db8688617a4a08047bf47fc8283207f345070ad33e94/CFPageResult.png?cb=522a4385f165ea429a36e17ebd7367a2) | The final page should be like this It is intended that the page will not get any likes yet | **Steps 13-20 - Git clone - commit - push** Now that we have created the hook and created a Confluence page for the test, we are ready to execute the test using Git commands. We will now clone the Git repository where we have configured the hook, make a change, commit the change with the issue key "TEST-1" and push it afterwards. Since the page has not received any likes yet, we expect the push to fail. **Execute the following commands (e.g. in your /tmp directory)** * **Step-13:** Clone your git Repository Bash git clone http://admin@bitbucket-server/scm/project_1/rep_1.git ![git-clone.png](https://help.devopssystems.de/__attachments/a_ddaf7987ae0d5c0fb3827e170952fb847088d20536a75cff5599dc066ddc29bd/git-clone.png?cb=030c01fe508f6f287b37fe4c3f6c28d0) * **Step 14 -**Got into the repository Bash cd rep_1 ![git-cd.png](https://help.devopssystems.de/__attachments/a_eaf01d930e06e1c7752cda2646e18e532ee64c8c01b3ee090c01eb2ebe11e895/git-cd.png?cb=3d7597332455a1cb92ed1ba185a22d10) * **Step 15** - Create a file, add file, commit file with the issue key TEST-1 Bash echo "test-string" >> test1.txt git add test1.txt git commit -m "TEST-1 anything" ![git-modify.png](https://help.devopssystems.de/__attachments/a_067880f371ee5d5d03fcf85452091edbd0b0f37ffcac7189eda68dbf1cd854d6/git-modify.png?cb=378894ae3ce86e1fc28806915a71a698) * **Step 16** - Push the changes Bash git push ![git-push.png](https://help.devopssystems.de/__attachments/a_3083aa3974fbb0a2ea88b78d451b0cbcc797dc869f9b2cfc9bea00392db96b39/git-push.png?cb=548d0a30131278323ccbe94c53b10f03) As you can see, the change could not be pushed. The correct page was selected based on our CQL, the status and reviewer were successfully evaluated, but no like could be found. * **Step 17** - Edit the Confluence page - set the status of the page to **OPEN** ![CFWrongStatus.png](https://help.devopssystems.de/__attachments/a_03866c33d65319319058658d604666b561c17d8c67546043c6b4ce6e66567d5d/CFWrongStatus.png?cb=55a88f8603d56e762a50f48a97a9a50e) Now the push should fail because the status of the document does not match APPROVED and the page still has no likes. * **Step 18** - Push again Bash git push ![git-push-2.png](https://help.devopssystems.de/__attachments/a_063446bbf1b16fd92cb22106d8fd67612b35c05c28c26c73e871aef00104713e/git-push-2.png?cb=de2c6a5834c20fade150b53a86b6e1e9) As you can see, the change could not be pushed. Because of the wrong status and the missing like ![ConfigRelation.png](https://help.devopssystems.de/__attachments/a_280339f75297bd462ccd491c751d8364c2a1a00dad4934e32983fee875f8faa2/ConfigRelation.png?cb=c5d75cfb616417c7913a4a4b953b4b08) * **Step 18** - Lets change the Confluence page again (Add a like and set the correct status) * ![CFCorrect.png](https://help.devopssystems.de/__attachments/a_deb801e7efe37c70be675785efd25206b05cfcd41eb7f7a7d41545bdfa3ed28d/CFCorrect.png?cb=56a8f98456f8291353d24b38ca742d96) * **Step 19 - PUSH AGAIN** Now the push works... ![git-push-3.png](https://help.devopssystems.de/__attachments/a_af7264135936d224edcd2f21dd832d2f11cab2583bd978cd0e6cda1ab2866319/git-push-3.png?cb=e18eb9baacbc4c4d10417bd3dfe4d1dd) * **Last Step** It would be super helpful if you could give us feedback. We are constantly trying to make our products even better and for that we need your feedback. Please leave us a message in our [service desk](http://It would be super helpful if you could give us feedback. We are constantly trying to make our products even better and for that we need your feedback among other things. Please leave us a message in our service desk) --- language: "en" --- # Version 0.6.0 ## Release Notes KeyStatusSummaryDescriptionCHFB-2ResolvedData Center compatibilityThe new addon has successfully passed the Data Center approval process. Now the addon is listed as fully compatible with Bitbucket Datacenter instances. ## Known Bugs KeyStatusSummaryDescriptionAffects versionsCHFB-7ClosedLikes check result in "Communication breakdown"With enabled Page voting check, a push will fail with the error message "Communication Breakdown", if there are no details attached to an Confluence page.0.6.0, 0.6.1, 1.0.0 --- language: "en" --- # Version 0.6.1 ## Release Notes KeyStatusSummaryDescriptionCHFB-3ResolvedRefactoring and TyposCorrect some internals and remove typos. The behaviour has not been changed ## Known Bugs KeyStatusSummaryDescriptionAffects versionsCHFB-7ClosedLikes check result in "Communication breakdown"With enabled Page voting check, a push will fail with the error message "Communication Breakdown", if there are no details attached to an Confluence page.0.6.0, 0.6.1, 1.0.0 --- language: "en" --- # Version 1.0.0 ## Release Notes KeyStatusSummaryDescriptionCHFB-4ClosedCommercial SupportRegarding the commercial support, the plugin will get a license protection. Versions smaller than 1.0.0 are no longer officially maintained and supported. ## Known Bugs KeyStatusSummaryDescriptionAffects versionsCHFB-7ClosedLikes check result in "Communication breakdown"With enabled Page voting check, a push will fail with the error message "Communication Breakdown", if there are no details attached to an Confluence page.0.6.0, 0.6.1, 1.0.0 --- language: "en" --- # Version 1.0.1 ## Release Notes KeyStatusSummaryDescriptionCHFB-7ClosedLikes check result in "Communication breakdown"With enabled Page voting check, a push will fail with the error message "Communication Breakdown", if there are no details attached to an Confluence page.CHFB-6ClosedOne or all page selection for property checkAs for the like check it is now possible to define a one or all page selection for the property option. CHFB-5ClosedUsage of Radio Buttons instead of checkboxesRadio buttons have been used instead of checkboxes, since their meaning fits better to the options. This is a breaking change because the options are new and the existing options or settings have not been applied. CHFB-4ClosedCommercial SupportRegarding the commercial support, the plugin will get a license protection. Versions smaller than 1.0.0 are no longer officially maintained and supported. ## Known Bugs KeyTypeStatusSummaryDescriptionVersionsFixversions --- language: "en" --- # Version 1.1.0 ## Release Notes KeyTypeStatusSummaryDescriptionKeyClosedImproved Dark Theme compatibilityWith this change, the dark theme is fully supported as of Bitbucket 8.16.CHFB-9 ## Known Bugs IssuekeyTypeStatusSummaryDescriptionKey --- language: "en" --- # Version 2.0.0 ## Release Notes ## Known Bugs --- language: "en" --- # Smart Commits for Bitbucket **Dual Licensing** We take part in Atlassian's dual licensing model. Please note that this is currently not yet possible, but we already follow this model and will offer it as soon as it becomes available. **SOC 2 Type 2** Security and reliability are a priority for us. We follow the SOC 2 Type 2 framework and are currently going through the audit process. We expect to have a SOC 2 Type 2 report available by the end of this year. 🏅 **One Solution. One Goal. Two Versions. Two Platforms. Choose What Fits You Best.** Connect Jira and Bitbucket. Quality, traceability, and control in your development process. Whether you're on Cloud or Data Center, Jira Hooks adapts to your workflow. ## What is the Smart Commits for Bitbucket Cloud Plugin? Smart Commits allows users over commits to execute special actions during the development. Each commit can define one or more special actions. This actions will be executed if the change sets will be pushed to the remote repository, which is located in Bitbucket. After the change sets has been received in Bitbucket, Bitbucket will parse the change-sets regarding some special keywords and related parameters. If the parser will find a valid key and parameters, the corresponding action will be executed. Actions can relate to all Atlasssian products like JIRA or Bitbucket. ### **Cloud (Forge)** Lightweight, fully integrated with Atlassian Cloud. Perfect for teams looking for a quick and low-maintenance setup. #### **Data Center** Full control for enterprise environments. Ideal for organizations with strict compliance and self-hosting needs. --- language: "en" --- # Changelog This changelog is the source of truth for all changes to the Smart Commits for Bitbucket Cloud that affect people using the Addon. ## 2026-09-25 ### New Feature **Initial Forge Release** Smart Commits for Bitbucket Cloud is now available on Atlassian Forge! This initial release brings automated actions directly into your Git workflow, helping your team connect code changes with everyday tasks in Jira and Bitbucket. Add supported keywords and parameters to your commit messages to trigger one or more actions when you push to your repository. Reduce manual steps, spend less time switching between tools, and keep your development workflow moving. View the detailed list of code changesFor a detailed overview of code changes, improvements, and fixes across all releases, visit our [changelog](https://devopssystems.atlassian.net/jira/software/c/projects/SCFBC/list?jql=project%20%3D%20SCFBC%0AAND%20status%20IN%20%28Closed%2C%20Deployed%2C%20Resolved%29%0AAND%20type%20IN%20%28Epic%2C%20%22New%20Feature%22%2C%20Bug%2C%20Vulnerability%29%0AORDER%20BY%20cf%5B10009%5D%20ASC). --- language: "en" --- # Cloud (Forge App) --- language: "en" --- # Datacenter --- language: "en" --- # Differences to Data Center ## Differences to Data Center This page lists everything that works differently in **Smart Commits for Bitbucket Cloud** compared to **Smart Commits for Bitbucket Data Center**, and which features are not supported yet. Commits that contain an unsupported command are still processed. The unsupported command is ignored, and all other commands (e.g. transitions, comments) run normally. ### Not yet supported | Feature | Data Center | Cloud | Comment | |-------------------------------------------------------------------------------------|----------------------------------|-------|-----------------------------------------------------------------------------------------| | **Time tracking** (`#time`) | ✅ | ❌ | See the warning below. | | **Time tracking info in push response** | ✅ (original / spent / remaining) | ❌ | Depends on `#time`. | | **Comment visibility** (`#comment @jira[Developer]`) | ✅ | ❌ | Comments are always visible to everyone who can see the issue. | | **Review approval handling** (`#keep` / `#unapprove`, Keep- and Unapprove-Strategy) | ✅ | ❌ | Approvals are not changed by the app. | | **Push response** (results printed in the `git push` output, severity setting) | ✅ | ❌ | Bitbucket Cloud does not offer a synchronous hook response. Actions run after the push. | **Time tracking (** `#time`**) is currently not supported in Bitbucket Cloud.** Because all Jira actions run under the account of the Jira connection (see "Author of Jira changes" below), work logs would not be recorded under the developer who made the commit. Since that would make your time tracking inaccurate, we have disabled this feature for now. We are looking into ways to bring it back in a reliable way. If time tracking via Smart Commits is important to you, please let us know. Your feedback helps us set priorities. #### Behaves differently | Topic | Data Center | Cloud | |-------------------------------------------------------------------|----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Jira connection** | All Jira actions use the primary application link. | Jira actions use the **Jira connections** configured in the app settings. Multiple connections are possible, and the workspace, project and repository levels control which ones are used. | | **Author of Jira changes** (comments, transitions, assignee, ...) | The commit author | The account of the Jira connection This applies to all actions in Jira, not the developer who made the commit. | | **Author of Bitbucket changes** (comments, tasks) | The commit author | The Smart Commits app | | **Pull requests created with** `#pull` | Created as the commit author | Created by the Smart Commits app | | **Date of a comment** | Date of the push | Date of the push | | `#assignee` | `#assignee=` | `#assignee=` | | `#fixVersion` | `#fixVersion` | `#fixVersion` and `#fixedVersion` are both accepted | | **Jira comment header** | `$url`, `$repo`, `$hash` | Additionally `$short-hash` | | **Configuration** | Project and repository hooks | App settings on **workspace, project and repository** level | | `#reviewer @user` | Bitbucket username | Bitbucket Cloud user (see the syntax section) | #### Things to keep in mind when migrating * **Double execution:** If your workspace also uses Jira's built-in Smart Commits, commands like `#comment` or transitions may be executed twice. * **Time bookings:** Existing commit messages with `#time` keep working, but the time entry is ignored. Use Jira's own worklog until time tracking is supported. * **Connection setup:** Before the first push, a Jira connection must be created at workspace level and enabled for the project or repository. --- language: "en" --- # FAQ --- language: "en" --- # Forge FAQ --- language: "en" --- # How to access details logging information? ## Enable debug logging You can enable the debug logging via the default mechanism of Bitbucket. As described in this document you can enable specific logger. The *Smart Commits for Bitbucket* logger has the name *scfb-logger-hook.*You can enable it via the Bitbucket properties file or you can enable it via the following curl command. Bash #enable curl -u -v -X PUT -d "" -H "Content-Type: application/json" http:///rest/api/latest/logs/logger/scfb-logger-hook/debug Attention: Please disable this logging again after you have done your investigation Bash #disable curl -u -v -X PUT -d "" -H "Content-Type: application/json" http:///rest/api/latest/logs/logger/scfb-logger-hook/info ## How to filter all Smart Commits for Bitbucket entries? Each log entry will start with the prefix "scfb-logger-hook". To see only Smart Commits for Bitbucket log entries, just filter the entries regarding the keyword "scfb-logger-hook". ## Support If you have technical issues, please add the "scfb-logger-hook" logs to the ticket or email. Thank you in advance. --- language: "en" --- # How to install Smart Commits for Bitbucket is a Forge app that can be installed directly into your Bitbucket Cloud workspace. to a Bitbucket repository. This guide walks you through installing the app in Bitbucket Cloud using a secure installation link provided by Atlassian. ## **Installation Steps** 1. **Sign in to Bitbucket** Log in with your [Bitbucket Workspace](http://bitbucket.org/) 2. **Open the Installation Link** Click or copy-paste the following link into your browser (it can take some seconds to load the page): 👉 [Install Smart Commits for Bitbucket](https://developer.atlassian.com/console/install/024f6b7e-5467-4c1b-9577-e7bd74878ffd?signature=AYABeNiN5OT0YMjkZd8ZVfE8cn0AAAADAAdhd3Mta21zAEthcm46YXdzOmttczp1cy13ZXN0LTI6NzA5NTg3ODM1MjQzOmtleS83MDVlZDY3MC1mNTdjLTQxYjUtOWY5Yi1lM2YyZGNjMTQ2ZTcAuAECAQB4CxqLTo9l4lqXuFjNim1xJM%2Bp%2F3TVP9xHS2BrU5DRRucB2fMP5WSZhB%2Fah%2BsnVPWCCwAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDB747ZR7GPTpNxRwzgIBEIA7ViL%2FjuJJqFYS9LpvFSKYI3NvPbbXgWhD5XW55URrbEGPu9oRALY9l3UqWZhMQnPvIxEl%2Bx3FkNtN94MAB2F3cy1rbXMAS2Fybjphd3M6a21zOmV1LXdlc3QtMTo3MDk1ODc4MzUyNDM6a2V5LzQ2MzBjZTZiLTAwYzMtNGRlMi04NzdiLTYyN2UyMDYwZTVjYwC4AQICAHi9bVMAkme4qVQX1fQHo6ePw3H40A7cGfz7yrmSfBWMXgG7WqSAJ%2BEfzXKylNNzIKmcAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMJrHkc1UfMhZEUIBQAgEQgDvHc2PGeknHloT77u0REGY78B7bBrzSSR8Kh4wolZyYzb1RzRZEwhFXS%2FbtMslT0x%2FtMnUk3A1b1BxfDwAHYXdzLWttcwBLYXJuOmF3czprbXM6dXMtZWFzdC0xOjcwOTU4NzgzNTI0MzprZXkvNmMxMjBiYTAtNGNkNS00OTg1LWI4MmUtNDBhMDQ5NTJjYzU3ALgBAgIAeDYASx0XCjkny4iLV6vz%2BKtEGSGT6kdt0QRpkn6D%2FlVEAVgG%2BTOq6z0q1%2FxCzVSAj5gAAAB%2BMHwGCSqGSIb3DQEHBqBvMG0CAQAwaAYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAzXwbIvhVJ20Vol3jECARCAO6fz8aRcfhdxolqKg5ln%2BZtWN69qIqBhSH%2FRKOXbwneM3M3j6SlpGuirxtWGdUBpc4fVYxuMKWdOVZy4AgAAAAAMAAAQAAAAAAAAAAAAAAAAAH3OtnR7o6He8ecKJJDu7IH%2F%2F%2F%2F%2FAAAAAQAAAAAAAAAAAAAAAQAAADJEzAM7Onn5ZftDy3S6ichBYjHQr%2BkyS2woPvQt%2Fb0pL%2FAPvvHfFXeoTZrU%2BRubJdPLUVjnr2VSjjr8m%2FOSsJyjGH8%3D&product=bitbucket) 3. **Review Permissions** The app will request access to certain data (e.g., repositories, pull requests). 4. **Click "Get app"** Start the installation via the Button "Get app" ![SmartCommitsGetApp.png](https://help.devopssystems.de/__attachments/a_bd76a7771ef19a8c98aaa64aaaaabca21c05a87089a72529d028ebe29c9e3bf1/SmartCommitsGetApp.png?cb=fe2418e01d66bcd02877608fac5c0b94) 5. **Choose a Workspace** Select the workspace where you want to install the app 6. **Click "Install"** Confirm the installation by clicking the **Install** button. ![SmartCommitsWorkspaceSelection.png](https://help.devopssystems.de/__attachments/a_03b1093be34aad4176bfaca966ebcf2bab81f943ed34db59a150c463482445e3/SmartCommitsWorkspaceSelection.png?cb=16315353c0196bf8afdc4e7b617763a2) ## Next steps [++**Read the User Guide**++](https://help.devopssystems.de/scfb/user-guide.md)**:** Define the global behavior of the Process Guardian, such as issue key detection, validation mode, and review behavior. --- language: "en" --- # How to maintain and set the configuration externally? In general the process can be done via the standard REST-API of Bitbucket. The REST-API offers an interface which enables you to set the settings of hooks via JSON. This JSON representation of the settings you can get and put to/from the hook ([see Bitbucket REST Resources](https://docs.atlassian.com/bitbucket-server/rest/7.8.0/bitbucket-rest.html?utm_source=%2Fstatic%2Frest%2Fbitbucket-server%2Flatest%2Fbitbucket-rest.html&utm_medium=301#idp382)) Since version 3.0.x ## The settings This example shows and describes the possibilities via JSON JavaScript { //enable the Jira transition action "jira.transitions.action.enabled": true, //enable the Jira comments action "jira.comments.action.enabled": true, //enable the Jira worklog action "jira.worklog.action.enabled": true, //enable printing of the remaining time "jira.worklog.action.remain.enabled": true, //enable the possibility to set the remaining effort "jira.remain.action.enabled": true, //enable the possibility to set the assignee "jira.assignee.action.enabled": true, //enable the possibility to set/add the component "jira.component.action.enabled": true, //enable the possibility to set/add labels "jira.label.action.enabled": true, //enable the possibility to set priority "jira.prio.action.enabled": true, //enable the possibility to set fixed version "jira.fixversion.action.enabled": true, //enable the possibility to set the affected "jira.affectedversion.action.enabled": true, //set the regular expression to detect issue keys "jira.issue.regex": "([A-Z][A-Z\\d_]*)-(\\d+)", //enable the possibility to add a heater to Jira comments "jira.comments.header.enabled": true, //Create jira comment with the following header "jira.comments.header": "my new header", //enable the possibility to create a pull request "bb.pull.action.enabled": true, //enable the possibility to add a comment to existing pull request "bb.comment.action.enabled": true, //enable the possibility to add a reviewer to existing pull request "bb.reviewer.action.enabled": true, //enable the possibility to add tasks to existing pull request "bb.task.action.enabled": true, //enable the approval strategy "bb.approve.action.enabled": true, //enable Set the approval strategy: KEEP: keep approvals UNAPPROVE: discard existing approvals "bb.approve": "KEEP", //the response level (ERROR,WARNING,INFO,DISABLED) "bb.response.level": "info", //in ms -> how long does the hook wait for a response "bb.action.timeout": "500" } Please remove the comments in the json file, because JSON is data only and do not support comments ## How to put the JSON Settings to the hook As you can see in the REST Resources of Bitbucket, you need to configure the REST call with the following: repository: /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/hooks/{hookKey}/settings project: /rest/api/1.0/projects/{projectKey}/settings/hooks/{hookKey}/settings To automatically enable the addon in addition use the endpoints repository: /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/hooks/{hookKey}/enabled project: /rest/api/1.0/projects/{projectKey}/settings/hooks/{hookKey}/enabled ++*Endpoint variables, URL, user and password:*++ * **hookKey** ***:*** *com.lb.software.stash.smart.commit.lb* ***-software-stash-smart-commit:*** ***smart-post-hook*** *-* ***The unique hook ID*** * **projectKey:** PROJECT_1 - **The slug of the project in this example** * **repositorySlug:** rep_1 - **The slug of the test repository in this example just if you would like to define a repository specific confirguration** * **Username and password:** admin:admin - **username and password to access the settings via REST-API ( has the user the permission to access the configuration page?)** * **Bitbucket-URL:** http://admin:admin@bitbucket:7990/bitbucket/rest/api/1.0/projects/PROJECT_1/repos/rep_1/settings/hooks/com.lb.software.stash.smart.commit.lb-software-stash-smart-commit:smart-post-hook/settings Based on this configuration, we can put the above settings to the repository "rep_1" in the project "PROJECT_1" via the tool curl. Bash curl -H 'Content-Type: application/json' -X PUT -d '{ "jira.transitions.action.enabled": true, "jira.comments.action.enabled": true, "jira.worklog.action.enabled": true, "jira.worklog.action.remain.enabled": true, "jira.remain.action.enabled": true, "jira.assignee.action.enabled": true, "jira.component.action.enabled": true, "jira.label.action.enabled": true, "jira.prio.action.enabled": true, "jira.fixversion.action.enabled": true, "jira.affectedversion.action.enabled": true, "jira.issue.regex": "([A-Z][A-Z\\d_]*)-(\\d+)", "jira.comments.header.enabled": true, "jira.comments.header": "my new header", "bb.pull.action.enabled": true, "bb.comment.action.enabled": true, "bb.reviewer.action.enabled": true, "bb.task.action.enabled": true, "bb.approve.action.enabled": true, "bb.approve": "KEEP", "bb.response.level": "info", "bb.action.timeout": "500" }' http://admin:admin@bitbucket:7990/bitbucket/rest/api/1.0/projects/PROJECT_1/repos/rep_1/settings/hooks/com.lb.software.stash.smart.commit.lb-software-stash-smart-commit:smart-post-hook/settings --- language: "en" --- # Jira Connection A **Jira connection** establishes the link between the add-on and a Jira instance. It is required to access and validate Jira issues that are referenced in branches, commits, or pull requests. Without a configured Jira connection, the system cannot resolve issue keys or perform checks such as **issue key validation** or **JQL-based validation**. Jira connections can only be created and managed at the **workspace level**, and can then be enabled or disabled per repository as needed. **Important notes** This app is **not eligible for the Runs on Atlassian program** because it communicates with an external system. **In this case, the external system is Jira.** No information is exchanged with unrelated third-party systems as part of this integration. ## User an Access Token for Jira Communication Before you configure a Jira connection, first set up a **dedicated technical user account** that will be used for all communication with Jira. Then generate a **personal API token**, not a scoped token, for this technical user in its Atlassian account settings. Keep the personal API token available for the connection setup. All requests to Jira are executed in the account of this technical user. For automation, use a dedicated technical account instead of a personal user account. We recommend that this account: * is not linked to a real person * has only the permissions required for the integration (e.g Browse Permission) * is used exclusively for technical automation processes → Tokens can be created here: . → For more information see the official Atlassian documentation for detailed steps: . Currently, Jira requests cannot be executed with the permissions of the individual user who triggers the evaluation, as this is not yet supported by the Atlassian API. Therefore, a central technical user must be configured, and all communication with Jira is performed on behalf of this user. ## Create a Jira connection The **Jira connections** tab in the **workspace settings** is used to create and manage Jira connections. When you select **Create new connection**, a dialog opens where you enter the required connection details. ![create-workspace-jira-connection.png](https://help.devopssystems.de/__attachments/a_b1127fb99e16cc7ca92ef6b5c1fa1923f56f4acd25bf19b8a69cf013d4fd17b7/create-workspace-jira-connection.png?cb=428a8dccfcebd02168e58709aa4085bf) **Where can I find the settings?** * Workspace Settings → Forge → Jira Hooks for Bitbucket → Jira connections * Repository Settings → Forge → Jira Hooks for Bitbucket → Jira connections ### Required information | Field | Description | |----------------|-------------------------------------------------------------| | **Email** | The email address used for the Atlassian account. | | **Account ID** | The Atlassian account ID used for the technical user. | | **Jira URL** | The base URL of the Jira instance that should be connected. | | **API token** | The API token generated for the Atlassian account. | ### Account ID The **Account ID** is required because the app stores limited personal data within the Atlassian infrastructure to enable communication between Bitbucket and Jira. Reason: At the moment, Atlassian does not provide a fully reliable built-in mechanism for this communication. According to Atlassian requirements, whenever an app stores personal data, it must report the **Account ID** of the user whose data is stored. Therefore, the Account ID is needed for compliance with Atlassian platform policies. See also: [Where can I get my Account-ID?](https://help.devopssystems.de/jhfb/where-can-i-get-my-account-id-.md) ### User interface The following screenshot shows the Jira connection dialog: After all fields are completed, select **Submit** to create the connection. If the connection is created successfully, it appears in the list of Jira connections. ![image-20260411-170123.png](https://help.devopssystems.de/__attachments/a_00c46eaffd2e642e98d71b10fa4c56fa50b1937702ba3658e14da81fed5fa1ed/image-20260411-170123.png?cb=4e9343e5552746b8de9944a6732848a8) ## Multiple Jira connections It is possible to configure multiple Jira connections. When multiple connections are available, the system searches for issue keys across all configured connections. Connections are processed sequentially from top to bottom. * The order of connections can be adjusted in the table * Processing stops as soon as all required issue keys are found * The checks continue after the required issue keys are resolved This makes it possible to support environments with multiple Jira instances. ## Workspace and repository connections Jira connections are created and managed exclusively at the **workspace level**. This means that only **workspace administrators** can create, edit, or delete Jira connections. This centralization ensures consistent governance, reduces misconfiguration risks, and enforces a uniform security and compliance model across all repositories. ### Workspace connections Workspace connections are available across all repositories in the workspace and are centrally maintained by workspace administrators. ### Repository usage Repository administrators cannot create or modify Jira connections. However, they can: * enable or disable existing workspace connections for their repository * control which connections are active for their repository ![repo-jira-connections.png](https://help.devopssystems.de/__attachments/a_94e53e3480914b465f9b556cda3e0a20f5a049990c19196ace7c4cc2bfd1768d/repo-jira-connections.png?cb=6773cd2661a5c75c7a3d616ebb249256) This model ensures centralized governance of Jira integrations while still allowing repository-level flexibility in how connections are used. **Key takeaway** Jira connections provide the technical link between the add-on and Jira and enable validation, traceability, and compliance checks across the development workflow. --- language: "en" --- # Known Bugs KeyPriorityStatusSummaryDescriptionAffects versionsSCFB-53ClosedFixing the vulnerability CVE-2024-57699Please update to the version 5.0.1. Because this version contains the vulnerability CVE-2024-57699. This vulnerability occurs because the library json-smart-2.5.1.jar which was shipped and used in earlier versions. This version contains json-smart-2.5.2.jar.3.0.1, 3.0.2, 3.0.3, 3.0.4, 3.0.5, 4.0.0, 4.0.1, 5.0.0SCFB-51ClosedFixing the vulnerability CVE-2023-1370Jira actions are performed with a JSON payload. In this case the libray "net.minidev-json-smart", which is affected by CVE-2023-1370, was used to create this payload. However, the critical functionality had no negative impact on the add-on. Nevertheless, the library was updated. 1.2.0, 2.2.0, 1.2.1, 2.2.1, 2.3.0, 3.0.0, 3.1.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4, 3.0.5, 4.0.0SCFB-47ClosedFixing the vulnerability CVE-2021-27568Please update to the version 3.0.5. Because this version contains the vulnerability CVE-2021-27568 . This vulnerability occurs because the library json-smart-1.1.1.jar which is shipped and used with this version. 0.8.0, 0.8.1, 0.8.2, 0.9.0, 0.9.1, 0.9.2, 0.9.3, 0.9.4, 0.9.5, 0.9.6, 0.9.7, 0.9.8, 1.0.0, 2.0.0, 2.1.0, 1.1.0, 1.2.0, 2.2.0, 1.2.1, 2.2.1, 2.3.0, 3.0.0, 3.1.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4SCFB-42ClosedHook is not working if the header option as not been set.If the option "Enable or disable the Jira comment header" is initially not set, the hook runs into a exception case an do not continue the processing of the smart actions.3.0.0, 3.0.1, 3.0.2SCFB-41ResolvedWorklog will not be createdEven the worklog action is enabled ("Work logs - add work logs to issues"), a worklog will not be created. A worklog will only be created if the option is enabled in combination with a further option ("Time tracking - return the time tracking values")3.0.0, 3.0.1SCFB-39ResolvedA reviewer action was not possible together with a pull request creationIn some situations it was not possible to create a pull request and add a reviewer in the same commit message. Example: #pull master #reviewer @tester 2.0.0, 2.1.0, 2.2.0, 2.2.1, 2.3.0SCFB-29ClosedSome general refactorings to improve the performanceThe code has been refactored to improve the general workflow. The results is a more performant way to parse and execute commands.1.0.0, 2.0.0, 2.1.0, 1.1.0, 1.2.0, 2.2.0SCFB-28ClosedNo empty tags and branches are handled by the pluginThe hook does not longer handle empty branches, notes and tags. This will improve the performance is some cases (factor 10)1.0.0, 2.0.0, 2.1.0, 1.1.0, 1.2.0, 2.2.0SCFB-27ClosedImproved the handling of magic keywordsKeywords are now better organized to reduce the traffic to Jira1.0.0, 2.0.0, 2.1.0, 1.1.0, 1.2.0, 2.2.0SCFB-14ClosedConfusing licensing error message The error message does not contain the plugin name, if no valid license is available.1.0.0, 2.0.0SCFB-6ResolvedThe keyword @stash is used to create a Pull-Request commentThe plugin has been developed for Stash. Thats the reason, why magic keywords in the commit messages are based on the name @stash. Since the renaming to Bitbucket, the magic comments needs to be renamed also. Both keywords should be supported. Since the version 3.0.0 in addition also @bb is possible to create comments 1.0.0, 2.0.0, 2.1.0, 1.1.0, 1.2.0, 2.2.0, 2.3.0 [Next Page](https://help.devopssystems.de/llms-full.txt/1)