Azure DevOps integration
Customers use the Azure DevOps integration to help plan, develop, test, deliver, and monitor applications efficiently.
Using the Azure API and our Custom Integration, you can learn how to run and track the progress of a pipeline. Once the Cutover task is triggered, a HTTP Post request will be sent to Azure to run the pipeline and return the Run ID and Run status in the response. The Cutover integration task will then poll to check the status in Azure. When the status has been set to ‘completed’ in Azure, the Cutover task will finish.
Note: This guide illustrates how to set up an Integration to Azure DevOps to run a pipeline, your integration may require additional or fewer fields to be included in the payload.
Set up your integration in 7 easy steps, read on to find out how in just 12 minutes.
Prerequisites
- Have an understanding of how our Custom Integration works.
- In Cutover, you will need to assign both the Integration Admin and Custom Fields Admin role types to the user who is configuring the integration.
- If you are using OAuth as a chosen authorization method ensure you have the OAuth application created in your Azure - see the Authorization tab section to setup your OAuth app in Azure.
Steps for creating a custom integration
In order to create a Custom integration, you will need to follow the steps listed below - each step will be explained in more detail further in the guide:
- Set up your integration connection
- Add in an integration action
- Add in your integration settings in the General tab
- Create your Custom Fields
- Include the authorization type to be used by the integration requests in the Authorization tab
- Add in your request properties in the Request tab
- Fill in any polling settings in the Polling tab - (if you are using Polling)
Create a custom integration connection
Once the prerequisites are met, you can create your custom integration in Cutover by following these steps:
1. Click Settings (the cog icon at the bottom of the sidebar), then click Integrations.
2. Any previously configured custom integrations will be displayed on the Integrations Connections page.
3.To find out how to set up a custom integration or see step by step guides for some of our most requested integrations, click on Learn more at the top of the Integrations Connections page .
4. If you’re ready to build your integration, click Create Integration.
5. The New Integration Connection modal is shown. You can choose from two types of integration:
Custom integration: This type of integration gives you the flexibility to create integrations based on your requirements via any authorization.
Predefined integration: This type of integration has been set up with predefined fields and default authorization.
To find out more about the types of integration, click the appropriate radio button and then click the Learn more button inside the New Integration Connection modal window.
6. If you select the Predefined Integration radio option, select an integration from the Integration dropdown list. The information required will change depending on the integration chosen. Enter any mandatory fields and click Create.
The newly created integration will be listed at the bottom of the Integrations Connections page.
Note: As this guide is based on our Custom Integration, please see our Help Center for further information on setting up any predefined integrations.
7. If you select the Custom Integration radio option, you will need to enter a name and (optionally) an image URL for your integration (if this is left blank, a default image URL will be displayed). Click CREATE.
The newly created integration will be listed at the bottom of the Integrations Connections page.
Add an integration action
An integration connection has now been created, the next step is to create an Integration action. An Integration action is the configuration of the integration to ADO, in this case to run and keep track of a pipeline.
Add an integration action to your newly created custom integration connection by following these steps:
1. In Settings > Integrations, click on your new custom integration from the list in the Integration Connections screen.
2. In the Edit panel, click + New in the Integration Actions section.
3. In the new action modal, select Build a custom integration from the Action dropdown.
A window will appear with a number of tabs, which are required to be completed in order for the integration to work. We will step through each of these now.
Create custom fields
Before filling out the rest of your integration action, you will need to set up your custom fields. These custom fields will match up with our mandatory fields when running a pipeline in Azure. In order to create your custom fields, you will need to make sure you have the Custom Fields Admin role.
Note: You can read more about creating custom fields in our Help Center.
To create a custom field:
1. Click Settings>Custom Fields.
2. Click the + icon in the bottom right to add a new custom field.
3. Add your custom field name
4. Select the visibility of your custom field
5. Select the field type
6. In the displays on field - select Task Edit
7. Under ‘Restrict to integration’, select your integration action
8. For additional settings, choose which properties fulfill your use case - in this example we have chosen Transient (this means any values stored will not be duplicated or copied), Required and Display in list view.
9. Click Create. You should repeat this for all of the custom fields required for your integration.
Below is a list of the custom fields, fields types and additional settings. This information should be entered when creating the custom fields in the above example:
General tab
In the General tab, enter the following details:
Name: Enter a name for your integration action. In our configuration, we have used the integration action name ‘Run pipeline’.
Image URL: This is the image of the icon that is associated and displayed with the integration action, in this example we have used our Azure image - but you are able to choose an image url of your choice.
Trigger: Select On Task Start.
Visibility: Select which workspace(s) you would like your integration action to appear or select global for your integration to appear in all workspaces.
Note: You cannot change the visibility of an integration action once it has been created. Also, you will need to set up the integration action for every workspace it is required for.
Additional Settings: Ensure that Auto start, Cancelable and Finish task on success are selected. These three options are used for the example being configured in this guide, however you may want to add additional options.
Click CREATE.
Authorization tab
In this example we are using OAuth.
For further information of Microsoft’s OAuth please read Authorize access to REST APIs with OAuth 2.0 - Azure DevOps.
In order to use OAuth for the ADO Integration you first need to create an app in ADO by completing the form https://app.vsaex.visualstudio.com/app/register. Depending on how your ADO has been configured, this step will probably require an Admin to complete.
Application name : Your Cutover Application
Description : Appropriate Description
Logo URL : This would typically be the Cutover Logo, which we can provide
Application Website : https://{CutoverInstanceName}.cutover.com
Authorization URL : https://{CutoverInstanceName}/api/integrations/oauth/authentications/payload_transformer/callback
Authorized Scopes : Identify (read), Build (read and execute), Pipeline Resources (use and manage)
It is important that the correct scopes are selected for the use case, the meanings of each of the scopes are documented here: Authorize access to REST APIs with OAuth 2.0 - Azure DevOps.
Once the app is created, we need to ensure that the option ‘Third-party application access via OAuth’ has been enabled, again you will probably require an Admin for this step. For reference, the Organization Settings screen is shown below and this is where you check and enable third-party access.
You are now ready to populate the Authorization tab in your integration action. Before filling in the Auth tab there are two options when using OAuth authorization type.
Option 1: Authorization code - requires a user to manually authenticate
Option 2: Client credentials - does not require user authentication, but uses the service principal account.
Using Authorization code with Client Assertion
Authorization Type: OAuth
OAuth Flow: Authorization Code
Requires Client Assertion: Check this
Client ID: The ID provided by the third party OAuth provider. This refers to the App Id in the Application Information that was previously set.
Client Secret: The secret associated with the client ID.
OAuth2 provider host: This is the base URL for the OAuth provider (e.g. https://app.vssps.visualstudio.com)
Authorization endpoint: The endpoint defined by the OAuth provider to perform authorization (e.g. /oauth2/authorize)
Token endpoint: The endpoint defined by the OAuth provider to exchange the authorization token for an access token (e.g. /oauth2/token)
Scopes: The types of operations that Cutover will be allowed to perform on behalf of an authorized user. Scopes are defined by the OAuth provider and usually allow restricted permissions to certain functions (e.g. vso.build_execute vso.identity vso.pipelineresources_manage )
Redirect URI: The URI that the OAuth provider must redirect to after the authorization step, where {YourClientInstance} is the base URL for your Cutover instance. https://{YourCutoverinstance}/api/integrations/oauth/authentications/payload_transformer/callback
The last step is to make sure ‘Requires Client Assertion’ is checked. Once you have completed all fields, click Save.
Once the OAuth tab has been set up, you can now either authenticate at two levels:
- At the Custom Integration Level - Functional User, so all executions of the integration will use the same OAuth credentials or;
- At a task level - Task User, where each user wishing to execute the integration must authenticate
Authenticating as a functional user
When authenticating as a functional user, the same user’s credentials are used each time the integration is executed. To authenticate as a functional user, click on the ‘Authenticate’ button in the OAuth tab of the Custom Integration.
Authenticating as a task user
When authenticating as a task user, each individual who wants to execute the integration will need to authenticate. When required, each user can do this by navigating to the task in the runbook and clicking on the ‘Authenticate’ button.
Using Client Credentials
You would use this authorization type if you are using a Service/principal account to run the integration. This is mostly used if the actions don't need to be tied to a user.
Choose the Authorization type as OAuth and the OAuth Flow as Client Credentials.
Client ID: The ID provided by the third party OAuth provider. This refers to the App Id in the Application Information that was previously set.
Client Secret: The secret associated with the client ID.
OAuth2 provider host: This is the base URL for the OAuth provider
(e.g. https://app.vssps.visualstudio.com)
Token endpoint: The endpoint defined by the OAuth provider to exchange the authorization token for an access token (e.g. /oauth2/token)
Scopes: The types of operations that Cutover will be allowed to perform on behalf of an authorized user. Scopes are defined by the OAuth provider and usually allow restricted permissions to certain functions (e.g. vso.build_execute vso.identity vso.pipelineresources_manage)
Once you have completed all fields, click Save.
When an integration action is created, we check the configuration contained in the Authorization tab is valid. When an update is made on the Client ID, Client Secret, Token Endpoint, OAuth2 Provider Host and Scopes, the system will perform a re-validation.
When you create or make an update to the Authorization tab, if those settings are valid, we will fetch and store the token to the current user’s OAuth session and the current user automatically becomes the functional user which means all executions of the integration will use the same oAuth credentials.
Note: When using the Client credentials flow, the authenticate button will not be there as the service account will be performing the action - therefore authenticating as a functional user is not required.
Request Tab
1. Select your chosen request type, in this example we are using a HTTP POST request.
2. Fill in your URL: https://dev.azure.com/{organization}/{project}/_apis/pipelines/{{CustomField['Pipeline ID']}}/runs?api-version=7.0
Note: In the URL we have used dynamic fields for the Pipeline ID. To find out more about dynamic fields, click here to visit our Help Center.
3. In the request header, fill in your request headers as defined by Azure:
{"Content-Type':"application/json"}
4. In the ‘Execution mode’, set this to Response mapping as this example will return the new created Run ID and Run Status.
5. Set the ‘Response handling’ to be Synchronous as we want the response to be returned immediately.
6. Click ‘Add new row’ under the ‘On success’ section to insert your response parameters.
7. In this example we use the Run ID and Run Status custom fields.
Polling Tab
1. Tick ‘Use Polling’
2. Set the request type to GET (as we want to retrieve the Run status.
3. URL: Enter the API URL of your Azure instance
https://dev.azure.com/{organization}/{project}/_apis/pipelines/{{CustomField['Pipeline ID']}}//runs/{{CustomField['Run ID']}}/?api-version=7.0
Note: We have used dynamic fields in the URL for the Run ID and Pipeline ID as this already exists in the request — as a result, this field will need to be included, but won’t need to be created again.
4. Set the ‘Request headers’ to the same as the previous request tab e.g:
{"Content-Type':"application/json"}
5. Set the ‘Response handling’ to Synchronous
6. Set the polling interval to your requirements, in this example we have set this up to poll for the status every 10 seconds
7. Set your ‘Stop polling conditions’. For this example we have chosen to poll for just the status and have set the condition value to ‘completed’. This means that when the Run status has been set to this condition, the Cutover task will be completed.
Next steps
In this guide you have learned how to successfully build and set up the Azure DevOps integration. By following the steps, you should now have a functional integration. You should thoroughly test your integration and address any issues that may arise during the testing phase. We encourage you to maintain detailed documentation of your integration configuration and any changes you make in the future. This will be invaluable for troubleshooting and maintenance.
If you are interested in integrations and would like to create further integrations in Cutover, please get in touch with your Customer Success Manager (CSM).
If you would like to know more about Cutover please contact info@cutover.com.
Thank you for using this guide, and we wish you every success with your integration project. If you have any feedback or suggestions for improving this documentation, please feel free to send it to docs@cutover.com.
