Configuring Your GitHub 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 GitHub repository.
Integrate their private repository with the Jenkins (CI) service in DXP Cloud using a Webhook.
If you are using an organization account, then you must have administrative privileges to transfer the repository to the organization.
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
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 DXP 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 DXP Cloud
infraenvironment’s Jenkins service. For example, the URL of the
ciservice for a project named
https://ci-acme-infra.lfr.cloud/github-webhook/. Note that the relative path
github-webhookis 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 DXP Cloud Console and navigate to your Jenkins service in the
Navigate to the Environment Variables tab.
Configure the following environment variables:
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 DXP Cloud.
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 will restart. Any pushed branches and pull requests in the new repository now trigger builds.
Jenkins versions prior to
2.222.1-3.2.0 use the environment variables
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 DXP Cloud to integrate with your repository.
If the personal access token belongs to a personal user account and that user is removed from the organization, all builds will 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, it is recommended to 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 allows you to remove the (admin-level)
admin:repo_hook permissions from the personal access token DXP Cloud uses:
Removing these permissions from the web hook improves security by minimizing access given to your repository.
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 GitHub:
git push origin 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 GitHub pages.