Submit Feedback

Configuring Your GitHub Repository

Your Liferay Cloud onboarding email contains a link to 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 GitHub repository.
Integrate their private repository with the Jenkins (CI) service in Liferay Cloud using a Webhook.

Note

If you are using an organization account, you must have administrative privileges to transfer the repository to the organization. The repository’s administrators are not necessarily the same as your project’s administrators in the Cloud console.

Transferring the Repository

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

Create a new private GitHub repository.
Clone your provisioned dxpcloud repository locally.
Push the cloned repository from step two to the remote repository you created in step one.

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

Integrating with the Jenkins Service

Now you must integrate your new repository with the Jenkins service in Liferay Cloud. Set up a webhook in GitHub that pushes to the Jenkins service:

In GitHub, go to your repository’s Settings page and select Webhooks.
Click Add Webhook. This opens the Add webhook form.
In the Payload URL field, add the domain of your Liferay Cloud infra environment’s Jenkins service. For example, the URL of the infra environment’s ci service for a project named acme is https://ci-acme-infra.lfr.cloud/github-webhook/. Note that the relative path github-webhook is required to integrate with the Jenkins GitHub plugin.
In the Content type selector menu, select application/json.
Leave the Secret field blank and ensure that Enable SSL verification is selected.
Under Which events would you like to trigger this webhook?, select Let me select individual events. A list of events then appears.
Select Pushes and Pull Requests from the list of events.
Make sure Active is selected, then click Add webhook.

Setting Environment Variables

Set these environment variables in the Jenkins service 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`	github
`LCP_CI_SCM_REPOSITORY_OWNER`	[repo_owner]
`LCP_CI_SCM_REPOSITORY_NAME`	[repo_name]
`LCP_CI_SCM_TOKEN`	[access_token]

Important

For added security, store the value of LCP_SI_SCM_TOKEN in a secret variable.

For the LCP_CI_SCM_TOKEN value, use the personal access token created for your GitHub organization. For instructions on creating and accessing this token, see GitHub’s documentation.

The personal access token created must have all of the scope permissions under repo and admin:repo_hook checked. The admin:repo_hook scope permissions specifically can be removed later if you disable automatic web hook management after your repository is successfully integrated with Liferay Cloud.

Check the correct permissions to ensure that the PAT can be used successfully.

Note

If you are using an organization account with SAML single sign-on authentication, then you must take additional steps to authorize your access token. See GitHub’s official documentation for more information.

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

Note

Jenkins versions before 2.222.1-3.2.0 use the environment variables GITHUB_REPOSITORY and GITHUB_TOKEN instead. To use the LCP_CI_SCM_* environment variables, ensure you are running Jenkins 2.222.1-3.2.0 or higher.

Personal Access Token Usage

The personal access token referenced by the LCP_CI_SCM_TOKEN value is needed for Liferay Cloud to integrate with your repository.

Warning

If the personal access token belongs to a personal user account and that user is removed from the organization, all builds fail to complete. Instead, use an account specifically belonging to the organization. See GitHub’s official documentation for more information.

By default, the GitHub organization’s Personal Access Token must also have the admin:repo_hook permissions in order for the CI service to successfully integrate using the default web hook.

However, you should set the LCP_CLI_SCM_MANAGE_HOOKS environment variable to false in your CI service. This disables automatic management of the web hook (which is no longer needed after you have finished setting up integration with your repository), and you can remove the (admin-level) admin:repo_hook permissions from the personal access token Liferay Cloud uses.

You can remove the admin:repo_hook permissions from the personal access token if you disable automatic web hook management.

Removing these permissions from the web hook improves security by minimizing access given to your repository.

Verifying Builds

Pushed branches and 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 GitHub:
```
git push origin 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.