GitLab CI/CD

GitLab is a robust Continuous Integration/Continuous Delivery (CI/CD) tool that operates on Git repositories. It provides an administrative layer over Git, enabling the organization of repositories into groups and managing access, while supporting various CI/CD workflows.

The integration between GitLab and Allegra offers the following capabilities:

• Assignment of Git commits to items

• Assignment of Git Pull Requests to items (in progress)

• Display of Git commits related to items in the cockpit widget

• Direct links to the GitLab repository browser

Setting Up GitLab Integration

Prerequisites

To establish a connection between Allegra and GitLab, ensure the following prerequisites are met:

• You have system administrator access to Allegra.

• Your Allegra instance has network connectivity to your GitLab instance.

• You have the necessary permissions to create GitLab access tokens, which are required to access commit messages in GitLab.

Step 1: Accessing Allegra GitLab Configuration Menu

Go to “Administration”, then select “Integrations” and click on GitLab. Here you can set up the GitLab integration.

Step 2: Creating a New Connection

Create a new connection to a Gitlab server by clicking on Add.

Step 3: Configuring the Connection

You can set the following parameters when configuring the connection:

Parameter	Description
GitLab server URL	The URL of your GitLab server. For example: https://build.alltena.com. Replace this with your GitLab server URL or static IP.
GitLab server name	An identifier for the connection. You can use the automatically generated name or customize it as needed.
GitLab access token	A token generated within GitLab that determines which projects are accessible. Replace this with your GitLab access token. Refer to Retrieving GitLab Access Token for details.
Start date of first synchronization	The starting date for Allegra to look for commit messages containing Allegra item numbers.
Item no. regular expression	The regular expression used by Allegra to identify patterns in commit messages. Defaults include: #<Allegra item number> (e.g., #4711) #<Allegra workspace-specific item number> (e.g., #WORK-4711) Here is an example for a commit message: “Implement new authentication flow to enhance security #WORK-4711”

After saving a configuration you can validate the connection by clicking on Test.

Once the server connection has been successfully validated, you can proceed to initiate the synchronization Step 4: Start Synchronization.

Step 4: Start Synchronization

After validating the server connection, select the GitLab projects you want to synchronize and click Save.

Once the repository configuration is saved, the initial synchronization will begin automatically.

Hint

You can always change the synchronised repository selection. E.g. a new GitLab project was added.

Hint

By default, changes from the GitLab server are synchronized every 10 minutes. Configuring a webhook allows you to receive immediate updates in real-time. For setting up the webhook continue here Optional Step: Webhook for Direct Sync

Retrieving GitLab Access Token

Allegra uses a token to communicate with your GitLab server. This token determines which GitLab projects Allegra can access. Only repositories that are accessible with this token will be read and synchronized by Allegra. You can for example use a Personal GitLab Token or a Project GitLab Token, depending on your use case.

Please refer to the GitLab documentation (https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) on how to create an access token:

Attention

Please generate an access token with the following scopes: `read_api` and `read_repository`. For more details, refer to the GitLab documentation (https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html).

Optional Step: Webhook for Direct Sync

By default, changes from the GitLab server are synchronized every 10 minutes. Configuring a webhook allows you to receive immediate updates in real-time.

Allegra can synchronize its version control data with a GitLab server in two ways:

• Via a time-controlled automatic process every x minutes, where x can be adjusted in the file

  $ALLEGRA_HOME/quartz-jobs.xml.

• Via a GitLab webhook calling the Allegra REST-API, allows you to receive immediate updates in real-time.

Steps to set up webhook connection:

1. Navigate to your GitLab project’s Settings and select Webhooks.

2. Copy the webhook URL generated in the Allegra GitLab Integration menu which was automatically generated after a successful connection(Step 3: Configuring the Connection).

3. Paste the URL into the appropriate field in GitLab.

4. Activate the following triggers: - Push Events - All Branches

Attention

Ensure that you configure a separate webhook for each GitLab project you synchronize.

Optional Step: Customizing the Regular Expression

By default, Allegra scans your GitLab commit messages for strings matching the following pattern:

• (#([a-zA-Z-0-9]+))

This regular expression matches strings such as #4711 or #WORK-4711 in commit messages.

If you want Allegra to recognize a different format, you can modify the regular expression accordingly. For example, to match strings like #AL:4711 or #AL:WORK-4711, you can use this pattern:

• (#AL:([A-Z0-9-]+))

Using GitLab Integration

The GitLab integration offers multiple ways to enhance your workflow. All methods require a commit message containing an Allegra item ID within a connected GitLab project.

Create a Commit in GitLab

Hint

We recommend using the “Copy to Clipboard” feature in the item form for a quick and convenient way to copy the Allegra item number.

Version Control in Item View

In the lower part of the item editing mask, the “Version Control” tab shows all commits, branches, and pull requests (soon) assigned to this item. The linking is done as described above using the item numbers as part of the commit text or the name for branches and pull requests.

Commits, branches and pull requests (soon) assigned to the item

Version Control Cockpit Widget

The version control cockpit widget can display all version control activities in an Allegra project, regardless of the underlying version control system. If you click on the associated link, you will be taken to the version control browser, depending on the configuration, to the internal or an external one.

Cockpit tile for version control display

Version Control Notifications

The version control notifications can be controlled via customizing the notifications.

Example for version control notification