In this page

Overview

This page is about implementing the Commit Policy Plugin with the Git version control system and Bitbucket Server. If you use Git alone (i.e. without Bitbucket Server), please see the Git page instead.

Please note that Bitbucket Server was called Stash until its 4.0.0 version, when Atlassian decided to re-brand it. As this was essentially just a name change, everything written below is also applicable to Stash.

Working with Bitbucket Server commit policies

Bitbucket Server builds on the top of the Git version control system, extending that with repository, user and permission management capabilities, workflows and other high level functionality. Therefore, everything written in the Git page also applies when using Bitbucket Server.

From the Commit Policy Plugin's angle, the only difference between using Git alone and Git with Bitbucket Server is the set-up steps of the commit hook. This is detailed in the next section, but this is only relevant to you if you are an administrator of the Bitbucket Server. If you are a developer (making commits and pushing those to the Bitbucket Server), you can use your Git client regardless if the server runs Git alone or Git with Bitbucket Server.

In any case, make sure you read the Git page. It explains fixing rejected commits, working with Git features (branching, merging, rebasing, tagging, cherry-picking) and helps to resolve common problems.

Installing Bitbucket Server commit hooks

With other version control systems, integrating with Commit Policy Plugin for JIRA requires installing hook scripts to the repositories in the filesystem. For Bitbucket Server, we offer completely web-based integration in the form of a Bitbucket Server add-on: Commit Policy Plugin for Bitbucket Server.

At its core, this add-on implements a new Bitbucket Server repository hook, that connects to JIRA, passes the commits, receives the verification result and accepts or rejects commits based on that. This is essentially a bridge between Bitbucket Server and JIRA.

Version compatibility

As this integration is composed of 3 components, each with its own versioning, the following table defines the recommended combinations:

Bitbucket ServerCommit Policy Plugin for Bitbucket ServerCommit Policy Plugin for JIRA
4.0.x or newer2.0.x or newer1.3.x or newer
3.7.x - 3.11.x0.8.x1.3.x or newer

Note: the compatible JIRA version is any version that is compatible with the corresponding Commit Policy Plugin for JIRA version.

Installing the Commit Policy Plugin for Bitbucket Server

You will need to execute these installation steps only once, to set up the integration between Bitbucket Server and JIRA.

Steps:

  1. Install the Commit Policy Plugin for JIRA to your JIRA.
  2. Install the Commit Policy Plugin for Bitbucket Server to your Bitbucket Server.
  3. Create the application link between Bitbucket Server and JIRA (see next section).
Linking Bitbucket Server to JIRA

To establish connection between Bitbucket Server and JIRA, the add-on is using a so-called application link. Application links are the standard and secure way of integrating Atlassian applications. If you already linked Bitbucket Server to JIRA, then just review the existing link based on the next section, to make sure that the connection supports OAuth requests with impersonation.

If you haven't created the link yet, here is a short how-to video:

These are the required settings on the two end-points of the application link:

  1. At the Bitbucket Server side of the link:
    1. Login to Bitbucket Server as admin, go to AdministrationApplication Links
    2. Click Edit (pencil icon) at the application link pointing to your JIRA
    3. Select OAuth (impersonation) as Local authentication for Outgoing direction
    4. Click Save changes
  2. At the JIRA side of the link:
    1. Login to JIRA as admin, go to AdministrationApplicationsApplication links
    2. Click Edit (pencil icon) at the application link pointing to your Bitbucket Server
    3. Select OAuth (impersonation) as Local authentication for Incoming direction
    4. Click Save changes

If you are using some older version of Bitbucket or JIRA, then the application link editing interface may look differently. In that case follow these instructions:

  1. At the Bitbucket Server side of the link:
    1. Login to Bitbucket Server as admin, go to AdministrationApplication Links
    2. Click Edit at the application link pointing to your JIRA → Outgoing AuthenticationOAuth
    3. Check Enable outgoing 2-Legged OAuth requests
    4. Check Enable outgoing 2-Legged OAuth with Impersonation requests
  2. At the JIRA side of the link:
    1. Login to JIRA as admin, go to AdministrationApplicationsApplication links
    2. Click Edit at the application link pointing to your Bitbucket Server → Incoming AuthenticationOAuth
    3. Check Allow 2-Legged OAuth
    4. Check Allow user impersonation through 2-Legged OAuth

Note: the add-on will automatically detect if the link is not configured properly for OAuth impersonating authentication. If it finds so, it will display a warning message with some guidance directly in the hook configuration form.

About impersonating authentication

The link created in the previous section is a so-called impersonating link. Impersonating is a simple, but powerful concept. It technically means that the Git user's identity will be used to connect to JIRA, and then the policy verification will be executed on his/her behalf! It may sound trivial, but this allows more precise verification than using a super-user account with "can-see-anything" permissions.

For example, you can use the currentUser() JQL function to enforce developers to commit against only those issues that are assigned to them:

project = FOOBAR and assignee = currentUser()

On the contrary, you have to pay attention and check if your developers have access to those resources (ex: projects) that are used for the verification. This is usually not a problem with the super-user scenario (as they have access to everything), and very rarely a problem in the impersonation scenario, but this is useful to be aware of.

Configuring commit policies for Bitbucket repositories

Execute these (trivial) steps every time when you want to activate a commit policy in a repository:

  1. Login to JIRA as administrator, then go to AdministrationCommit Policies and create the policy.
    If you already have an existing policy that you want to use, you can skip this step. (Note that the same policy can be reused by multiple repositories, if they require the same set of commit conditions.)
  2. Switch to Bitbucket Server, go to the repository → SettingsHooks.
  3. Click Enabled for the hook called Commit Policy Verification.
  4. Select the policy from the drop-down. (Please note that the selectable options are the commit policies defined in JIRA.)
    You may eventually see a warning box above the drop-down if the add-on finds some problems:
    1. If the application link is not created yet: create the application link!
    2. If the application link exist, but is not configured properly: review the configuration of the application link at both ends!
    3. If the Commit Policy Plugin for JIRA is not installed to JIRA: install that add-on!
    4. If there is no policy created yet: create a policy that you can use!
  5. Test:
    1. Try to commit something that should be rejected.
      Ex: if your policy requires at least one issue key, then make a commit with the message "No issue key here". Check if it is rejected.
    2. Try to commit something that should be accepted.
      Ex: if your policy requires at least one issue key, include a proper issue key in the commit message: "Fix for MYDB-17". Check if it is accepted.
  6. Have some chocolate, you did a great job!

Installing Bitbucket Server commit hooks using Git hook scripts

This section describes an alternative method to integrate Bitbucket Server with JIRA. It takes a lower level approach, based on native Git hooks (instead of Bitbucket Server hooks). It should be used very rarely, in situations when you want more control or custom behaviour. It works by adding actual Git hook scripts to the repositories managed by Bitbucket Server, without conflicting with the hook scripts dynamically generated by Bitbucket Server.

The idea is that we will use a Bitbucket Server hook type called External Pre Receive Hook, which can execute external commands on the server. We will configure this hook to execute the Python interpreter with the Commit Policy Plugin's hook script! That way the policy checker hook script becomes a natural part of the Bitbucket Server managed hooks.

Before starting the hook installation, we strongly suggest reading this section. It is about Git workflows in general, and about deciding which repositories you should install the hooks into.

Actual installation steps:

  1. If it is not installed yet, install the External Hooks Plugin to Bitbucket Server. It is free and it provides the hook type we're going to use. If it is already installed, skip this step.
    Installing the plugin requires administrator permissions to Bitbucket Server, and it is described in the Installation tab here.
  2. Generate a hook script package for Git, the same way you'd do when using Git without Bitbucket Server.
  3. Extract the ZIP to some temporary directory.
  4. Because Bitbucket Server has its own hook script called pre-receive, we need to avoid the conflict: rename the file pre-receive to pre-receive.jcp in the temporary directory.
  5. Login to Bitbucket Server as administrator. Go to the SettingsRepository details page of the repository to which you want to install the hook script. The Location on disk field will show you the repository's directory in the server's filesystem.
  6. Go to that directory in the filesystem, and then to its hooks subdirectory. Move the files from the temporary directory to this directory.
  7. As instructed by the Hook Script Generator's guide (step 4), add the execution permission to pre-receive.jcp (not pre-receive!) and run pre-receive.jcp (not pre-receive!) in diagnostic mode to verify if it works.
  8. Open pre-receive.jcp in a plain text editor and change this line (around line 28):
    return not sys.argv[0].startswith("hooks")
    to:
    return False
  9. Go back to Bitbucket Server, to the SettingsHooks page of the repository. Enable the External Pre Receive Hook with the following parameters:
    • Executable: /usr/bin/python
      This is the full path of the Python executable in your server which will be launched by this hook. If you mistype this, the hook will fail to execute Python.
    • Safe mode: leave it unchecked
    • Positional parameters: <YOUR_REPOSITORY_DIRECTORY>/hooks/pre-receive.jcp
      This is the full path of the Commit Policy Plugin's hook script. Don't forget to enter the actual directory path to the <YOUR_REPOSITORY_DIRECTORY> placeholder. The final path should be similar to this: /srv/atlassian-stash-data/shared/data/repositories/71/hooks/pre-receive.jcp. If you mistype this, Python will fail to find the script.
  10. Do some testing by commiting changes that should be rejected (negative testing) or accepted (positive testing).
  11. Have a chocolate, coffee or beer - depending on the period of the day.

Questions?

Ask us any time.