Configuring Your Bitbucket 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 BitBucket repository as of version 3.2.0 of the Jenkins service. This must be done with administrative access to the BitBucket repository.
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 Bitbucket. 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:
If not, then follow these steps to upgrade:
Update the Jenkins service to version
Jenkinsfilelocated on the root folder.
Add the following environment variable:
Deploy the Jenkins service.
If you’ve customized your Jenkinsfile, follow this guide to extend the Default Jenkinsfile_.
Creating a Bitbucket Repository
First, create a new Bitbucket repository.
Go to Bitbucket.
Click the “+” icon in the sidebar under the search icon.
Click Repository to start creating a new repository.
Provide a name for the repository.
Ensure the access level is set to private.
Set Include a README? to No.
Click Create repository.
Transferring from GitHub to Bitbucket
Follow these steps to transfer the provisioned GitHub repository to your own Bitbucket repository:
Clone the provisioned GitHub repository locally:
git clone [email protected]:dxpcloud/example.gitnote
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 Bitbucket:
git remote add bitbucket [email protected]:example/example.git
Push the cloned repository to the new remote repository:
git push bitbucket master
If you need help creating, cloning, and pushing repositories, see Bitbucket’s documentation.
Generating App Password for BitBucket
Next, create an app password that will be used by the Webhook to authenticate with Bitbucket and trigger Jenkins builds. The Bitbucket user that generates the app password must have admin-level access to the repository.
Perform the following steps to generate an app password:
From your user settings page, under Access Management click App passwords.
Click Create app password.
Provide a label for the app password.
Grant the app the following permissions:
Pull request - read, write(this should also flag Repositories - read, write)
Webhooks - read, write
Copy the app password (you won’t see it again otherwise). This is BitBucket’s equivalent of a personal access token.
The user that generated the app password must use their username for the
LCP_CI_SCM_USERNAME environment variable.
Checking Branch Types and Prefixes
In order for Liferay Cloud to be able to properly link to your branches, you must provide it with a complete list of the branch prefixes in use in your repository. Each of the branch types used in your repository has its own prefix, which is defined in the repository’s settings.
On the Bitbucket website, click Repository settings → Branching model from the menu on the left. This brings you to the Branching model page, where the prefix for each of your branches is listed. Take note of each of these prefixes to add them to the
LCP_CI_SCM_BITBUCKET_BRANCH_PREFIXES CI environment variable.
Connecting BitBucket 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
Navigate to the Environment Variables tab.
Configure the following environment variables:
||[list of prefixes]|
LCP_CI_SCM_USERNAME as the user that generated the app password. Define
LCP_CI_SCM_BITBUCKET_BRANCH_PREFIXES as a list of all prefixes used in your repository’s branches, separated by spaces.
After updating these environment variables, the Jenkins service will restart. Any pushed branches and pull requests in your new repository should now trigger.
Connecting to a Private Bitbucket Server
To use a private Bitbucket server, you must set an additional environment variable in your Jenkins service:
||[private host URL]|
LCP_CI_SCM_SERVER_HOST variable to the base URL of your private Bitbucket server (for example,
http://private.bitbucket.org/). 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://bitbucket.org/ as the base URL for Bitbucket.
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 BitBucket:
git push bitbucket 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 Pull Requests
Verify that new pull requests trigger Jenkins builds:
Create a pull request from any branch to the
Verify that a new build is created for the pull 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 BitBucket pages.