In this page

VCS connections

What is a VCS connection?

The Better Commit Policy app uses so-called VCS connections as secure communication channel between your Jira Cloud site and your Git workspace (hosted on Bitbucket Cloud or GitHub, e.g.).

The VCS connection is used to run JQL searches when checking work item references in commit messages, pull request titles, branch names, and other related metadata. It's a restricted and read-only channel, meaning that the VCS connection will not allow anything else for the Git workspace, but running searches against your Jira work items.

As you manage the VCS connections on the Jira side, you can also consider it as an allowlist that defines which VCS workspaces are allowed to run JQL searches against this Jira Cloud site.

Connection topology options

Several common configurations are supported:

  1. connecting a single Jira site to a single Git workspace (most common)
  2. connecting a single Jira site to multiple Git workspaces (useful if you have multiple Git workspaces but only one Jira site)
  3. connecting multiple Jira sites to a single Git workspace (useful if you have multiple Jira sites but only one Git workspace)

You can also connect a Jira site to different types of workspaces. For example, the same Jira site can be connected to two Bitbucket workspaces and a GitHub workspace, which is useful for organizations that use multiple platforms for different teams or projects. These kinds of complex topologies are absolutely supported!

Manage VCS connections

VCS connections can be managed on the dedicated VCS connections page. To access it, log into Jira as an administrator, navigate to Apps → Better Commit Policy, and click the Manage VCS connections link. (If there are no connections created yet, you can see the Connect a VCS workspace now button instead of the link.)

You can see the list of the existing VCS connections with their details:

  1. Connected VCS workspace: the icon that represents the connected Git hosting service (e.g. Bitbucket) and the name of the connected Git workspace.
  2. Status: the status of the VCS connection.
  3. Connection ID: the system-assigned, alphanumeric ID of the VCS connection (which identifies it in commit policy configuration files).

Refer to the table below for the meaning of each VCS connection status.

Status Description
Active The VCS connection is actively used.
Not used recently The VCS connection was not used in the past 100 days.
(It still works though! This status is primarily a signal about unused connections for administrators.)
Not used yet The VCS connection exists, but the connected Git workspace didn't use it yet.
Disabled The VCS connection is disabled.
(Connected Git workspaces will not be able to run their checks, but fail with an intuitive error message.)
Error The VCS connection is not working due to a technical error.
(If the problem persists, open a support ticket and we will help.)
Add a new VCS connection

To create a connection:

  1. Click the Add VCS connection button at the top of the page.
  2. Select the hosting platform you want to establish the connection with in the VCS hosting service dropdown.
  3. Enter your workspace URL to the Workspace URL field.
  4. Leave the Enabled toggle on (default).
  5. Save.

Note that the app will validate if the workspace URL you entered points to an existing Git workspace, but it will not check if you that is actually managed by you.

Edit a VCS connection

To edit an existing VCS connection, click the Edit link in the corresponding row, update the necessary fields, and save your changes.

Delete a VCS connection

To delete an existing VCS connection, click the Delete link in the corresponding row.

⚠️ Be careful with deleting VCS connections! If a connection is deleted, the commit policy configurations that use it to connect to this Jira Cloud site will stop functioning as expected. Even If you create a new connection from the same VCS workspace to the same Jira Cloud site later, the new connection receives a new ID. For example, if your previous connection ID was "abc123" and the new connection ID is "def456", you will need to replace "abc123" with "def456" in all relevant commit policy configuration files!

If you need to turn off a VCS connection for a while, don't delete it, just disable it. You can re-enable it later, and it will keep the same ID, so any commit policies that use it will still work.

Connectors

What is a connector app?

On the Git workspace side of the VCS connection, you need to install a "connector app". These free apps integrate commit policies seamlessly into the native experience of your Git hosting platform.

For example, the Better Commit Policy Connector for Bitbucket Cloud app allows you to configure and enforce commit policies directly within the Bitbucket UI, as if they were built-in features:

Connector app provide the following features integrated to the Git hosting platform UI:

  • Configure, validate and view the commit policy
  • Configure and use merge checks
  • Configure and use local checks
  • ... and more!

Supported Git hosting platforms

Connector apps are available for various platforms. Refer to the documentation specific to your Git platform for detailed guidance:

Questions?

Ask us any time.