This guide discusses Behave Pro for Jira Cloud. If you want to configure a Server or Data Center deployment of Behave Pro with Gitlab please read this article for Gitlab git integration and read this article for connecting Gitlab repository to a Jira.

​
There are two steps to connect Behave Pro with GitLab:

Behave Pro needs to be installed into GitLab to enable communication to and from Jira. This installation to be done by Users with Administrator privileges in Jira and GitLab.

Within Jira open the settings menu on the right-hand side of the top navigation bar and select Apps. This will open the App manage for Jira.

​
​

Within Jira's Apps manager find Behave Pro on the left-hand navigation and select Getting started. This will open the setup task for Behave Pro.

​

Behave Pro's setup process will allow you to choose which repository provider to connect to and clicking on Connect will start the installation process for Behave Pro on GitLab.
​

Once you click the connect, you will see the page includes Behave Pro redirect URI from below.

Before you connect Behave Pro to GitLab, you will need to set up an OAuth application on your GitLab. This OAuth application will be used by Jira to create, modify, or delete feature files in your repositories. This part needs to be done in your GitLab instance and please copy the redirect URI by clicking copy icon before leaving this page. Once you finish OAuth application setup you will come back to this page.
​

To make this setup, first, you need to navigate to the admin area on your GitLab instance:
​

Select the "Applications" from the left menu.

Next, create a new application. You will need to put in the redirect URI which you copy before and any arbitrary name of your choice. And also, please make sure you checked the "api" from the list of Scopes.

​

Create the application by clicking on the "Save Application" button and a new page will appear as shown in the image below. Make sure you have the "Application ID" and "Secret" values. You will need those within the next step to create a connection from Jira.
​
​

After you have created the application, you please go back to Jira and click on the Next button then you will see the GitLab connection page.
​
​

Fill in the name which can be any name you wish to choose. Fill in the GitLab's base URL and paste the "Application ID" and "Secret" when you have created the application on GitLab.
​
When you click "Connect" you will be redirected to GitLab and will be asked to Authorize the connection. Click on "Authorize"
​

Once Behave Pro has been successfully installed into GitLab you will be automatically returned to Jira. Once back in Jira you will be given a choice of projects to select for configuring Behave Pro. If you are the project administrator you can select your project or leave the next section to be completed by the project administrator.

Once you have completed the previous section then you will be able to search and select a project to configure for Behave Pro and this will send you to Select Your Workflow page.

The first step of the connecting a GitLab repository is to click Select within the git section.

Next, you will need to select the correct GitLab group from the top dropdown. If your GitLab instance is not shown in the list.

Once you have selected your GitLab group, select the repository from the dropdown below.

To continue, you will also need to select the preferred branching strategy. The options are the following:

If you are still unsure about your team's strategy please read this article to help you decide which strategy works for you.

Once you have configured these settings and click Continue you will be presented with the Branch Settings page.

In the branch list, you should select your base or default branch for the repository. This is usually called master, main, or trunk for Feature Branching or Trunk based development projects. For a repository using a Gitflow strategy then the branch will be called develop instead of master.
​
Behave Pro needs to understand where feature files should be stored within your repository and this is specified in the Feature file directory. This directory should already exist within the repository and any feature files stored at this location will be automatically imported into Behave Pro.
​
After setting up the branch and directory, click the Continue button, you will be shown a webhook settings page for GitLab.

When anyone creates, updates, or deletes a feature or a scenario within your Jira project, the changes are pushed to your GitLab project. To enable receiving changes from the GitLab (when someone pushes a commit to your repository with feature changes) you will need to add a webhook with a secret token generated by Behave Pro.
​
Go to your GitLab repository click the "Visit here to create a webhook" link on this page or from the left navigation menu, select "Settings" and click "Webhooks" on your GitLab instance.

Create a webhook with the URL and the secret token generated by Behave Pro. Please make sure you check the "Push events" checkbox. Without this, the synchronization will not work.

After you have created the webhook, send a test payload webhook by clicking on the "Test" dropdown button and selecting "Push events" from the list of payloads. This will send a sample webhook to Behave Pro for Jira. No real synchronization will happen.

After sending the test webhook, you should be notified with the following message.

​

Finally, go back to the Behave Pro project setup page and click the "Test" button. You will be shown a dialogue that will check if the test payload has been successfully received from GitLab. After that, simply click the "Finish" button to complete the setup.

Once all this has been done you've successfully configured Behave Pro.

At the end of this installation flow, you will be redirected to the requirements page of your project where you can begin to create feature files, write scenarios and see them appear in your GitLab project.