We're here to help
Now that the Jenkins server is setup for Provar test execution, we can begin setting up the Salesforce org with the Copado installation to queue the Jenkins job that 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 Permissioner
- Copado Selenium Testing
Note: Instructions for installing the Provar 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 begin setting up our Copado to Jenkins integration. For the most part we will be operating in the Copado Release Manager, although it is advisable to read all of Copado’s documentation regarding their other applications. Follow Copado’s documentation on how to set up an external CI job here: https://docs.copa.do/article/nl2v8znpeh-external-ci-jobs
Note: We will also be walking through how to set up our integration.
From here, select External CI Settings, then select New on the following page.
You can name this External CI Setting whatever you wish, but it is advisable that you choose something that is 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: In our case, 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 that has the correct privileges to authenticate 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.
From here, fill in the fields necessary to create this External CI Job.
External CI Jobs Name: Name of the External CI Job. It is useful to classify this name similarly to the Jenkins Job name, since the two will be linked 1-to-1.
External CI Setting: Select the External CI Setting that was created in the previous step.
Environment: Leave blank for now, but can be filled in once you define environments in your org via Copado.
User Story: Leave blank for now, but can be filled in once you create User Stories in your org via Copado.
Order: Set this value to 1; it is the order in which to execute this job in relation to other jobs.
Invoke On: Can be set to before or after 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 for selecting which Jenkins Job you would like this external CI job to queue via a webhook. Select Select CI Job and choose the Jenkins job we created in the Jenkins Configuration section.
We will also be adding our build parameters that correspond to the build parameters created in that same Jenkins job earlier.
Add each build parameter in 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 be using a URL callout for the main deployment step. However, it is good practice to have this job setup for future use.
Once this is done, save the external CI job.
Testing the external CI job (Optional: if you setup an External CI Job, then test 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 simply wait for the job to complete and report the results back to the External CI Job in Copado. 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 be walking 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 source of the deployment.
To Org: Use the org lookup to find the desired org as the destination org to deploy to.
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 setup an External CI Job/Settings, then 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.
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.
TEST_PLAN (Optional): Test Plan Name
BUILD_FILE (Optional): ANT/build.xml
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 the API Token is registered to as well as the API token.
Copy the entire string that it generates and this is the Authorization Header in the Copado URL Callout.
Click Save once the URL Callout has been added to the step.
Scroll down to the Copado Deployment History to ensure each step has been added and saved successfully.
Your Deployment/External CI jobs are now both setup and your Copado configuration is complete!
To test this deployment, you can click Deploy directly from the deployment screen view.
Make sure to Deploy All on the next screen.
You can view the results from this deployment on this screen as well 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.