GitLab Integration

Step-by-step instructions on how to set-up two-way synchronization with GitLab.

Important: In order to connect to GitLab, you will need to have the login credentials with Owner permissions to GitLab projects.

Syncing to GitLab

Data synchronization from to GitLab is by manual push. The first step of the configuration will connect to Gitlab. 

Connecting to Gitlab

Click 'Integrations' from the user menu at the lower left, and choose to connect to GitLab:


You will be asked to enter your GitLab Private Token and Enterprise URL: (


Note: To generate your GitLab Access Token, go to User Settings > Access Tokens and create a Personal Access Token with scope 'api', then copy it to clipboard.


Select the GitLab project to sync with, and click 'Next'.

Additional Integration Settings

In this step you are asked to finalize your integration configuration:

  • syncs all Stories and Requirements as GitLab issues. Tasks, Bugs, and Improvements will be synced only for the selected team or teams you choose in this step.
  • You can choose whether or not to sync team workflow statuses (i.e To Do In Progress, Done) between and GitLab and select a team to sync statuses with. Review more with our article on the Kanban View
  • You can choose if you want to sync GitLab Milestones as Releases, Sprints, or not synced at all.


  • Closing a story in GitLab will immediately release the Feature in, and vice versa.
  • Releasing a Feature in will close the story in GitLab on sync, and vice versa.

Mapping Between and GitLab

The following items will be synced Through the two-way integration between and GitLab. Note: Syncing will never delete any items on both sides.

Type Mapping

Name in Name in GitLab Notes
Feature Issue -
Requirement Issue -
Bug Issue Only for selected teams
Task Issue Only for selected teams
Improvement Issue Only for selected teams
Labels Labels -

Field Mapping

Name in Name in GitLab
Title Title
Description Description
Version/Sprint Milestone
Labels Labels


Congratulations! You are now ready for your first sync! 

You can synchronize the systems for the first time or you can do it later. You can also choose to skip this step and sync selected stories instead. For more information about syncing a specific Feature, see β€˜Sync a Single Feature’ section below. 

Note: you can always return to this step by clicking the Push button:

First-time sync between and GitLab

You can select between the following override options when syncing to GitLab:

: On the first sync, the GitLab project is synced to Craft. The import is performed once. To enable automatic updates from GitLab to, you will need to set a webhook in GitLab. See β€˜Syncing GitLab back to’ below for more.


Select the parts of your product in that you want to push to GitLab.

The following options are available:

  • All Product - Syncs the entire product to GitLab.
  • Releases - Allows you to select one or more releases to be pushed to GitLab.
  • Sprint Backlog - Allows you to select one or more sprint backlogs to be pushed to GitLab.

Once you have completed your selection, click 'Sync'. Depending on the size of your product, the procedure could take several minutes to complete.

When the sync is completed, you will see messages showing what was synced and/or skipped. 

You can also download a more detailed log.

Note: All GitLab issues are created in under the GitLab Theme feature, ordered by their Epics. You can move them to different features across using drag and drop in the Editor, or by bulk action in the Search and Filter tool. Learn more in our Search and Filtering article.

Syncing GitLab back to

The second step in synchronizing GitLab with is to configure the settings in GitLab so that changes made in GitLab will be updated in automatically.

From the user menu, select Integrations and click 'Sync GitLab back to'. You will see information on how to create a webhook in GitLab, as well as the webhook listener URL to use in the webhook configuration. This is a unique URL that contains your product ID. Copy the URL to your clipboard and continue to the webhook configuration in GitLab.

In GitLab, go to System > Integrations and paste your webhook URL into the URL field.

Select Issues Events and Confidential Issues Events. Everything else should be unchecked. 

Click to add the webhook.

Syncing a Single Feature

At times you may want to update or send a single Feature to GitLab. This can be a new Feature created or one that you updated. You can do this from the GitLab section in the Feature's right panel: 

Click Sync Item to sync the Feature to GitLab. 

Click the GitLab issue ID to open the corresponding issue in GitLab.

Modifying Integration Settings 

You can always return and update your configuration from the 3 dots integration menu:

You can also choose to view a detailed log of the last sync and disconnect the GitLab integration.