Configuring Your GitLab Repository

Upon receiving a Liferay Cloud onboarding email, you’re provisioned a GitHub repository hosted in the dxpcloud organization. This repository is a template for a team’s separate private Liferay Cloud development repository and is typically removed after 10 business days. Users must:

Transfer the provisioned repository to their own private repository.
Integrate their private repository with the Jenkins (CI) service in Liferay Cloud using a Webhook.

The provisioned repository will be on GitHub, but you can transfer it to a GitLab repository as of version 3.2.0 of the Jenkins service. This must be done with administrative access to the GitLab repository.

note

The repository’s administrators are not necessarily the same as your project’s administrators in the Cloud console.

Preparing the Jenkins Service

If you are using version 4.x.x services in your Liferay Cloud instance already, then your Jenkins service is already compatible with GitLab. See Upgrading Your Liferay Cloud Stack for more information on upgrading.

If you are using version 3.x.x services, then check the LCP.json for your ci service, and ensure you’re running the following Jenkins service or higher:

liferaycloud/jenkins:2.222.1-3.2.0

If not, then follow these steps to upgrade:

Update the Jenkins service to version liferaycloud/jenkins:2.222.1-3.2.0.
Delete the Jenkinsfile located on the root folder.
Add the following environment variable: LCP_CI_USE_DEFAULT_JENKINSFILE: true.
Deploy the Jenkins service.

note

If you’ve customized your Jenkinsfile, follow this guide to extend the Default Jenkinsfile_.

Creating a GitLab Repository

First, create a new GitLab repository:

Go to GitLab.
Click New project.
Provide a project slug (the repository name in the url).
Configure the visibility level to private (free users have unlimited private repositories).
Ensure Initialize repository with a README is unchecked.
Click Create project.

Transferring from GitHub to GitLab

Follow these steps to transfer the provisioned GitHub repository to your own GitLab repository:

Clone the provisioned GitHub repository locally:

git clone [email protected]:dxpcloud/example.git

note

If you have already cloned the repository for work with another provider, then you can skip this step and work within the same clone.
Add a new Git remote and point to GitLab:

git remote add gitlab [email protected]:USERNAME/REPOSITORYNAME.git
Push the cloned repository to the new remote repository:

git push gitlab master

If you need help creating, cloning, and pushing repositories, see GitLab’s documentation.

Generating Access Tokens for GitLab

Next, create an access token that will be used by the Webhook to trigger Jenkins builds:

Navigate to the personal access tokens page.
Provide a name and an expiration date for this access token.
Configure the access token to have the following permissions:
- api
- read_repository
- write_repository
Click Create personal access token.
Copy your access token and save it somewhere (you won’t see it again otherwise).

Connecting GitLab to Your Jenkins service

Lastly, set environment variables in the Jenkins service’s to point to your new repository:

Log in to the Liferay Cloud Console and navigate to your Jenkins service in the infra environment.
Navigate to the Environment Variables tab.
Configure the following environment variables:

Name	Value
`LCP_CI_SCM_PROVIDER`	gitlab
`LCP_CI_SCM_REPOSITORY_OWNER`	[repo_owner]
`LCP_CI_SCM_REPOSITORY_NAME`	[repo_name]
`LCP_CI_SCM_TOKEN`	[access_token]

After updating these environment variables, the Jenkins service restarts. Any pushed branches and pull requests in your new repository trigger builds.

Connecting to a Private GitLab Server

To use a private GitLab server, you must set an additional environment variable in your Jenkins service:

Name	Value
`LCP_CI_SCM_SERVER_HOST`	[private host URL]

Set the LCP_CI_SCM_SERVER_HOST variable to the base URL of your private GitLab server (for example, http://private.gitlab.server.com/). This sets the server URL that CI uses to retrieve your code base when generating builds and linking to your repository’s branches. By default, CI uses https://gitlab.com/ as the base URL for GitLab.

Additional GitLab Webhook Configurations

Liferay Cloud’s Jenkins service creates a webhook for your selected git SCM provider; however, it only creates the default one. GitLab’s default webhook requires additional configuration to match the functionality of GitHub and BitBucket’s webhooks.

Navigate to your GitLab repository.
Navigate to Settings and select Webhooks.
Under Project Hooks, verify the created webhook is listed.
Click the Edit button for the CI webhook.
Uncheck Tags push events and Comments.
Check Enable SSL verification.
Click Save changes.

Verifying Builds

Pushed branches and merge requests (GitLab’s equivalent of pull requests) trigger builds that you can see or deploy from the Builds tab in the Liferay Cloud Console. After setting up integration with the Jenkins service, a good next step is to verify these builds, to ensure that the integration was successful.

Verifying Builds from Pushed Branches

Verify that new Git pushes trigger Jenkins builds:

Make a change to the repository (like adding a file), then commit it to the branch:
```
git commit -m "Add file to test builds"
```
Push the branch up to GitLab:
```
git push gitlab branch-name
```
Navigate to the Builds page in the Liferay Cloud Console.
Verify that the build displays for the pushed branch on the Builds page.

Verifying Builds from Merge Requests

Verify that new merge requests trigger Jenkins builds:

Create a merge request from any branch to the develop branch.
Verify that a new build is created for the merge request.
Navigate to the Builds page in the Liferay Cloud Console.
Click the links for the branch and commit in the appropriate build.
Verify that the links redirect to the correct GitLab pages.

Configuring Your GitLab Repository

Not finding what you're looking for?