Copado Configuration
Now that the Jenkins server is set up for Automation test execution, we can begin setting up the Salesforce org with the Copado Configuration installation to queue the Jenkins job we just created.
Once your Copado installation is complete and your user has been granted the correct permissions, you should see the following Copado applications in your App Launcher for that Salesforce Org.
Namely, the following:
- Copado Release Manager
- Copado Pipeline Manager
- Copado Developer
- Copado Compliance Hub
- Copado Permission
- Copado Selenium Testing
Note: Instructions for installing the Automation Test Results package are in a later section of this guide. This package will be used to capture our test results written back from the Jenkins job.
Creating the External Continuous Integration Setting in Copado (Optional)
First, we will search for External CI in the AppLauncher to set up our Copado to Jenkins integration. For the most part, we will operate in the Copado Release Manager, although it is advisable to read all of Copado’s documentation regarding their other applications. Follow Copado Configuration documentation on how to set up an external CI job here: https://docs.copa.do/article/nl2v8znpeh-external-ci-jobs.
Note: We will also walk through how to set up our integration.
From here, select External CI Settings, then choose New on the following page.
You can name this External CI Setting whatever you wish, but you should choose something easily identifiable. For instance, if you have multiple Jenkins instances you want to integrate, name each setting according to the Jenkins instance it belongs to.
External CI Settings Name: This is a demo Jenkins server, so we have named it accordingly.
CI Tool: Jenkins in this case, but Bamboo and TeamCity are also supported here.
Endpoint: This should be the base URL of your Jenkins server.
Username: A user with the correct authentication privileges to Jenkins and queue jobs.
Password: The user’s password.
API Token: Also, recall the value of your API token from setting up the Jenkins bob. This will be used to authenticate the External CI.
Once you have completed your External CI Setting, save it and test the connection before proceeding.
Click the Validate Connection button in the top right of this External CI Setting page:
Now, we can create an External CI Job that utilizes this connection.
Creating an External CI job in Copado (Optional)
From the External CI Setting page, click New External CI Job.
Fill in the fields necessary to create this External CI Job from here.
External CI Jobs Name: Name of the External CI Job. Classifying this name similarly to the Jenkins Job name is helpful since the two will be linked 1-to-1.
External CI Setting: Select the External CI Setting created in the previous step.
Environment: Leave blank for now, but it can be filled in once you define environments in your org via Copado.
User Story: Leave blank for now, but it can be filled in once you create User Stories in your org via Copado.
Order: Set this value to 1; it is the order to execute this job concerning other jobs.
Invoke On: Can be set to before or after the deployment phase (typically set to before deployment).
Continue on failure: Leave this unchecked (want to exit on failures).
Timeout in minutes: Leave this set to 15 minutes (will timeout the job if no response is received in that time frame).
The bottom part of this setup is selecting which Jenkins Job you would like this external CI job to the queue via a webhook. Select CI Job and choose the Jenkins job we created in the Jenkins Configuration section.
We will also add our build parameters corresponding to the build parameters created in that same Jenkins job earlier.
Add each build parameter in the name/value pairs you wish to pass to the Jenkins job.
The DEPLOYMENT_ID (or EXTERNAL_ID, depending on how you named the build parameter in Jenkins) cannot be passed in via the External CI job. This is the primary reason we will use a URL callout for the main deployment step. However, it is good practice to set up this job for future use.
Once this is done, save the external CI job.
Testing the External CI job (Optional: if you set up an External CI Job, try it!)
You can test this External CI job by clicking Build Job in the top right.
Once you do, you should see the confirmation message notifying you of your job being started:
You can also track the status in Jenkins or wait for the job to complete and report the results to the External CI Job in Copado Configuration. You may have to refresh the page before the Related tab displays any Job result information.
Creating a Deployment Job in Copado
Follow Copado’s documentation on how to set up a deployment here: https://docs.copa.do/article/afa12a7uwv-creating-a-deployment
Note: We will also walk through how to set up our integration.
Open the AppLauncher and search for Copado Release Manager.
Open this application and navigate to the Deployments tab. From here, create a new Deployment by selecting the New button.
Firstly, enter a deployment name and save the deployment.
From here, fill in the fields as necessary to create the deployment Job.
Source Org: Use the org lookup to find the desired org as the deployment source.
To Org: Use the org lookup to find the desired org as the deployment destination.
Add Steps to Deployment Job
In the Steps section, click Add Step to create a deployment step for this job.
Step Name: The name of the step (Note: This step will be calling the Jenkins Job via a URL Callout).
Type: Select URL Callout from the dropdown.
If you set up an External CI Job/Settings, you can also select External CI Job here and use that instead. Use the Lookup to find the External CI Job you set up previously. Also, the name used here may be different from yours.
URL Callout
Type: Perform callout and continue with deployment.
Method: Set the Method to POST.
Dynamic Parameters: None.
URL: Set this value to http://my.jenkins.server.com/job/JobName/buildWithParameters.
URL Parameters:
TEST_PLAN (Optional): Test Plan Name
DEPLOYMENT_ID/EXTERNAL_ID: {!Deployment.RecordId}
BUILD_FILE (Optional): ANT/build.xml
Headers:
Authorization: Basic XXXX
You will need to convert your Jenkins API token to an authentication header. There are various tools online where you can do this. One such tool is here: https://www.blitter.se/utils/basic-authentication-header-generator/
You provide the username to which the API Token is registered and the API token.
Please copy the entire string it generates, which is the Authorization Header in the Copado URL Callout.
Content-Type: application/json
Click Save once the URL Callout has been added to the step.
Scroll down to the Copado Configuration Deployment History to ensure each step has been added and saved successfully.
Your Deployment/External CI jobs are now set up, and your Copado configuration is complete!
To test this deployment, click Deploy directly from the deployment screen view.
Make sure to Deploy All on the next screen.
You can also view the results from this deployment on this screen by clicking Result for the Call Jenkins Job step.
You can also select View in Jenkins on the External CI Job itself once the job is complete in Jenkins to view the build log.