Configuring Your Bitbucket 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 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 is 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.

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’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 git@github.com: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 Bitbucket:

git remote add bitbucket git@bitbucket.org: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 an API Token for Bitbucket

Important

Atlassian is replacing Bitbucket App Passwords with API tokens. Use Atlassian API tokens for new Bitbucket integrations.

To switch from an App Password to an API token, generate a new Atlassian API token and update LCP_CI_SCM_TOKEN and LCP_CI_SCM_USERNAME in your Jenkins service. Otherwise, authentication breaks when Atlassian removes App Passwords.

Generate an Atlassian API token with Bitbucket scopes. The webhook uses this token to authenticate with Bitbucket and trigger Jenkins builds. The Atlassian account used to create the API token must have admin-level access to the Bitbucket repository.

Navigate to the API token management page and log in if prompted.
Click Create API token with scopes.
Provide a label for the token.
Select an expiration period for the token and click Next.
Select Bitbucket as the app and click Next.
Select the required scopes:
- Pull requests: Read
- Pull requests: Write
- Webhooks: Read
- Webhooks: Write
Click Create.
Copy the API token value (it does not appear again) and store it securely.

Important

Use the generated API token for the LCP_CI_SCM_TOKEN environment variable.

Use the Atlassian account email associated with the token 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 appears. Take note of each of these prefixes to add them to the LCP_CI_SCM_BITBUCKET_BRANCH_PREFIXES CI environment variable.

The default branch types (and prefixes) for a Bitbucket repository are bugfix/, feature/, hotfix/, and release/.

Connecting BitBucket to Your Jenkins Service

Lastly, set 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`	bitbucket
`LCP_CI_SCM_REPOSITORY_OWNER`	[repo owner]
`LCP_CI_SCM_REPOSITORY_NAME`	[repo name]
`LCP_CI_SCM_TOKEN`	[API token]
`LCP_CI_SCM_USERNAME`	[account email]
`LCP_CI_SCM_BITBUCKET_BRANCH_PREFIXES`	[list of prefixes]

Important

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

Define LCP_CI_SCM_USERNAME as the Atlassian account email associated with the API token. 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 restarts. 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:

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 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.

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 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.