Configuring Your Bitbucket Repository¶
Upon receiving a DXP 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 DXP 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 DXP 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 DXP Cloud instance already, then your Jenkins service is already compatible with Bitbucket. See Upgrading Your DXP 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 firstname.lastname@example.org:dxpcloud/example.git
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@example.com: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 DXP 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 DXP Cloud Console and navigate to your Jenkins service in the
Navigate to the Environment Variables tab.
Configure the following environment variables:
[list of prefixes]
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 DXP 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 DXP 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 DXP Cloud Console.
Click the links for the branch and commit in the appropriate build.
Verify that the links redirect to the correct BitBucket pages.