Onboard Azure DevOps to DevOps Change Velocity — Workspace
Connect to your Azure DevOps instance using the DevOps Change Workspace playbook to collect data for planning, coding, orchestration, artifact, and software quality functions.
You can connect to Azure DevOps (ADO) at your organization level or at individual project level. If you're connecting at the project level, for each project at your organization, you must repeat the connection process. After connecting to an instance of the tool, you can configure additional settings that enable DevOps to import pipelines, task execution records, and step execution records.
When you configure webhooks in your Azure DevOps instance to send data to DevOps Change Velocity, Azure DevOps uses token authentication for the integration user by default. The DevOps Change Velocity APIs are invoked using token authentication and you don’t have to enter the integration user name and password while configuring. If the devops.system user isn’t available in your ServiceNow instance, you must set the Switch to this user after token based authentication is successful property. For more information, see DevOps Change Velocity properties. The step to enter the integration user name and password is required only in the following scenarios:
If DevOps Config is installed, as DevOps Config APIs are invoked using basic authentication.
If you use the Azure Invoke REST API service connection. You must enable the This property decides whether to create a Generic Connection on configure operation for Azure DevOps property in this case.
Note: DevOps Change Velocity uses the term instance to refer to a particular occurrence of a tool. Azure DevOps uses the term project instead.
Connect and configure your Azure DevOps instance directly at your Azure DevOps organization level. All the projects within the organization can be discovered, and you can choose to configure multiple projects within the organization. You can manage the tool at the organization level.
From the Recommended actions pane, select the **Connect a tool ** card.
On the Connect to a tool modal, select Azure DevOps from the appropriate category (Orchestration, Plan, Code, Artifact, or Software quality).
Tools module
Select Tools (
Image omitted: tools-icon-wkspc.png Tools icon.) from the primary navigation.</li>
From the Capability list, select the appropriate category (Orchestration, Planning, Coding, Artifact, or Software quality).
Select Connect a tool.
On the Connect to a tool modal, select Azure DevOps.
**Important:** If you want to discover and track tool objects like pipelines, plans, or repositories while connecting to the tool, you must connect your tool from the Application module.
In the Connect to a tool modal, enter the connection details.
Select Connect an organization from the drop-down list.
Enter the Azure DevOps URL for the organization.
In the Tool name field, enter a name for the tool.
Select Next.
Image omitted: azure-plybk-09.png Connect to organization.
The DevOps playbook opens to help you complete the onboarding tasks.
In the Enter Azure DevOps instance details section, select one of the following values in the Credential type field.
Personal Access Token
Enter the password or access token to access this instance.For information on creating a PAT, see Personal access token (PAT).
Image omitted: ado-pat-01.png Connect to a tool - ADO PAT
Permission checks are run on the credentials that you entered.
Permissions required and permissions that are available are displayed. If you want to enter credentials with better permissions, select Re-enter credentials. For detailed information on all the required permissions, see Azure DevOps permissions in Permissions required for DevOps tools.
You can choose to continue with the tool connection even if you don't have all the required permissions.
Note: When onboarding an Organization, the Project Administrators privilege requires the owner of the PAT to be a member of the organization's Project Collection Administrators group.
You need the Project Administrators privilege only for onboarding the tool. Once the tool is successfully onboarded, you can choose to turn off the Project Administrators privilege from the PAT.
Image omitted: azure-plybk-03.png Permissions required for Azure PAT.
Specify the access for the tool.
If you want to control access to the tool, add the groups that must be given access to the tool in the Maintained by field.
The tasks these users in the groups can perform depends on the role assigned to them.
DevOps Tool Owner role: Can view and edit the tool.
DevOps App Owner role: Can view the tool and can associate, discover, import historical data, and modify pipeline steps (if applicable) of the tool's objects (such as plans, repositories, and pipelines).
DevOps Administrator role: Can edit all tools.
Other DevOps roles: Can view the tool. Note: If you don't select a group and skip this step, all users with the DevOps Tool Owner role will be able to edit the tool.
If you choose to control access to the tool, the All DevOps App Owners can view and associate tool objects to applications option becomes available for selection.
This option enables all users having the DevOps App Owner role to access the tool. If selected, they’ll be able to view, associate, discover, import historical data, and modify pipeline steps (if applicable) of the tool's objects.
Install the ServiceNow DevOps extension in your Azure DevOps instance.
The ServiceNow DevOps extension will automatically create service connections while configuring webhooks. Service connections are required for sending build and release notifications from Azure DevOps. The extension also contains custom tasks to modify the Azure DevOps pipelines for change control, artifacts, and packages.
Note: If you skip this step, to send notifications from Azure DevOps, you must manually create service connections after configuring webhooks.
After installing the extension, select Marked as installed.
Image omitted: azure-plybk-01.png Install the ServiceNow DevOps extension.
Configure webhooks automatically in your Azure DevOps instance to send data to DevOps Change Velocity.
Choose to send data by either nightly polling or configuring webhooks to send real-time data.
Webhooks: Enable real-time notifications for your pipeline executions. Real-time notifications are ideal to maintain the most up-to-date information particularly for automating change requests.
To use webhooks, select Configure.
Nightly polling: If you don’t choose to configure now, you can enable nightly polling later to fetch data for any tracked plans by setting the Enable Polling property to Yes.
Enter the DevOps integration user name and password.
The step to enter the integration user name and password is required to configure only when DevOps Config is installed or the This property decides whether to create a Generic Connection on configure operation for Azure DevOps property is enabled. If this step is not required, webhooks are configured using token-based authentication.
When DevOps Config is installed or the Generic Connection on configure operation for Azure DevOps property is enabled, you can regenerate token (auto-configure with new token) from the workspace UI only, which will update the integration user password. When DevOps Config is not installed, token can be regenerated from both the workspace and classic UI for token based authentication. Re-generate your token periodically for better security.
Select the projects for which you want to configure webhooks.
Select Configure.
Image omitted: azure-plybk-13.png Configure Azure DevOps for organization.
To configure webhooks manually, select **Configure manually**. See [Configure webhooks in Azure DevOps manually](configure-test-webhooks.md) for more information.
Webhook configuration and discovery happen in the background, and you’re taken to the Summary page.
From the Summary page, select View tool record to review the details of the connected tool.
Result
You’ve successfully onboarded your Azure DevOps tool to DevOps Change Velocity at the organization level.
What to do next
From the Projects tab on the tool record page, select a project to navigate to the project record page. From here, you can discover project objects, and configure webhooks for the project.
Select Discover to discover the project objects, including existing plans (boards), repositories, and pipelines.
If you created the tool directly at the project level, then selecting Discover projects from the Projects tab of the tool record page will discover all the projects in your organization as well.
Select Configure and enter the integration user credentials to configure webhooks for the project.
If you're on the tool records page, selecting Configure projects and entering the integration user credentials gives the list of unconfigured projects in your organization. Select the projects that you want webhooks configured for and select Configure.
Note: The step to enter the integration user name and password is required to configure webhooks only when DevOps Config is installed or the Generic Connection on configure operation for Azure DevOps property is disabled. If this step is not required, webhooks are configured using token-based authentication.
To import historical data to the project objects like plans, repositories, or pipelines, associate the objects with an application, and import the data. For more information, see Associate tool objects to applications - Workspace.
Connect a project
Connect and configure your Azure DevOps instance directly at the project level. If you have multiple projects within the organization, you must connect each of them separately.
From the Recommended actions pane, select the **Connect a tool ** card.
On the Connect to a tool modal, select Azure DevOps from the appropriate category (Orchestration, Plan, Code, Artifact, or Software quality).
Tools module
Select Tools (
Image omitted: tools-icon-wkspc.png Tools icon.) from the primary navigation.</li>
From the Capability list, select the appropriate category (Orchestration, Planning, Coding, Artifact, or Software quality).
Select Connect a tool.
On the Connect to a tool modal, select Azure DevOps.
**Important:** If you want to discover and track tool objects like pipelines, plans, or repositories while connecting to the tool, you must connect your tool from the Application module.
In the Connect to a tool modal, enter the connection details.
Select Connect a project from the drop-down list.
Enter the Azure DevOps URL for the project.
In the Tool name field, enter a name for the tool.
Select Next.
The DevOps playbook opens to help you complete the onboarding tasks.
Image omitted: azure-plybk-10.png Connect to project.
Enter the instance details for your tool.
In the Enter Azure DevOps instance details section, select one of the following values in the Credential type field.
Personal Access Token: Enter the password or access token to access this instance.
Image omitted: ado-pat-01.png Connect to a tool - ADO PAT
- **OAuth 2.0**: Pre-requisites:
- [Create a tenant in Microsoft Entra](set-up-azure-devops-oauth-2-0-credential.md)
- [Add a user to tenant in Microsoft Entra](set-up-azure-devops-oauth-2-0-credential.md)
- [Create an organization in Azure portal](set-up-azure-devops-oauth-2-0-credential.md)
- [Create an Azure DevOps app](set-up-azure-devops-oauth-2-0-credential.md)
- [Register Azure DevOps as an OAuth provider](set-up-azure-devops-oauth-2-0-credential.md)
- [Configure organization and project level settings](set-up-azure-devops-oauth-2-0-credential.md)
- [Create credential record and get OAuth token](set-up-azure-devops-oauth-2-0-credential.md)
**Use an existing OAuth credential record**
1. Select the **Use an existing OAuth credential record** option.
2. Select a value in the **Credential** field.
**Create a new credential record**
1. Clear the **Use an existing OAuth credential record** option.
2. Enter the application ID of your Azure application \(available in the Overview section of your Azure application registry in Azure\) in the **Application \(client\) ID** field.
3. Enter the directory ID of your Azure application \(available in the Overview section of your Azure application registry in Azure\) in the **Directory \(tenant\) ID** field.
4. Enter the client secret of your Azure application \(available in the Certificates & secrets section of your Azure application registry in Azure\) in the **Client secret** field.
Image omitted: ado-prj-oauth.png Connect to a tool - ADO OAuth
2. If your tool instance is attached to a MID Server, select the **MID Server** option and enter its details.
For more information about MID server, see [MID Server selection](../../servicenow-platform/mid-server/c_MIDServerSelector.md).
3. Select **Connect**.
4. Permission checks are run on the credentials that you entered.
Permissions required and permissions that are available are displayed. If you want to enter credentials with better permissions, select **Re-enter credentials**. For detailed information on all the required permissions, see Azure DevOps permissions in [Permissions required for DevOps tools](tool-req-permission.md).
You can choose to continue with the tool connection even if you don't have all the required permissions.
**Note:** When onboarding a Project, the **Project Administrators** privilege requires the owner of the PAT to be a member of the project's **Project Administrators** group.
You need the Project Administrators privilege only for onboarding the tool. Once the tool is successfully onboarded, you can choose to turn off the Project Administrators privilege from the PAT.
Image omitted: azure-plybk-03.png Permissions required for Azure PAT.
5. Select **Next**.
Specify the access for the tool.
If you want to control access to the tool, add the groups that must be given access to the tool in the Maintained by field.
The tasks these users in the groups can perform depends on the role assigned to them.
DevOps Tool Owner role: Can view and edit the tool.
DevOps App Owner role: Can view the tool and can associate, discover, import historical data, and modify pipeline steps (if applicable) of the tool's objects (such as plans, repositories, and pipelines).
DevOps Administrator role: Can edit all tools.
Other DevOps roles: Can view the tool. Note: If you don't select a group and skip this step, all users with the DevOps Tool Owner role will be able to edit the tool.
If you choose to control access to the tool, the All DevOps App Owners can view and associate tool objects to applications option becomes available for selection.
This option enables all users having the DevOps App Owner role to access the tool. If selected, they’ll be able to view, associate, discover, import historical data, and modify pipeline steps (if applicable) of the tool's objects.
Install the ServiceNow DevOps extension in your Azure DevOps instance.
The ServiceNow DevOps extension will automatically create service connections while configuring webhooks. Service connections are required for sending build and release notifications from Azure DevOps. The extension also contains custom tasks to modify the Azure DevOps pipelines for change control, artifacts, and packages.
Note: If you skip this step, to send notifications from Azure DevOps, you must manually create service connections after configuring webhooks.
After installing the extension, select Marked as installed.
Image omitted: azure-plybk-01.png Install the ServiceNow DevOps extension.
Configure webhooks automatically in your Azure DevOps instance to send data to DevOps Change Velocity.
Choose to send data by either nightly polling or configuring webhooks to send real-time data.
Webhooks: Enable real-time notifications for your pipeline executions. Real-time notifications are ideal to maintain the most up-to-date information particularly for automating change requests.
To use webhooks, select Configure.
Nightly polling: If you don’t choose to configure now, you can enable nightly polling later to fetch data for any tracked plans by setting the Enable Polling property to Yes.
Enter the DevOps integration user name and password.
The step to enter the integration user name and password is required to configure only when DevOps Config is installed or the This property decides whether to create a Generic Connection on configure operation for Azure DevOps property is enabled. If this step is not required, webhooks are configured using token-based authentication.
When DevOps Config is installed or the Generic Connection on configure operation for Azure DevOps property is enabled, you can regenerate token (auto-configure with new token) from the workspace UI only, which will update integration user password. When DevOps Config is not installed, token can be regenerated from both the workspace and classic UI for token based authentication. Re-generate your token periodically for better security.
Select Configure.
Image omitted: azure-plybk-14.png Configure Azure DevOps for a project.
To configure webhooks manually, select **Configure manually**. See [Configure webhooks in Azure DevOps manually](configure-test-webhooks.md) for more information.
**Important:**
- If you're connecting from the Home page or Tools module, the connection is complete and you're taken to the Summary page.
- If you're connecting from the Applications module, then plans, repositories, and pipelines available in your project are discovered. You can track and import historical data from them.
Select the plans to track.
Select the plans for which you want to track updates and associate to the application.
Select Next.
Image omitted: azure-plybk-02.png Select plans to track.
3. If you want to import plan data, select the date range and select **Submit**.
You can import up to 90 days of data.
Image omitted: azure-plybk-04.png Import plan data.
Select the repositories to track.
Select the repositories for which you want to track updates and associate to the application.
Select Next.
Image omitted: azure-plybk-05.png Select repositories to track.
3. If you want to import repository data, select the date range and select **Submit**.
You can import up to 90 days of data.
Select the pipelines for which you want to track updates and associate to the application.
Select Next.
Image omitted: azure-plybk-07.png Select pipelines to track.
3. For each selected pipeline, all steps or stages are imported for the last successful execution. In the Assign services to pipeline steps activity, you can select the following for each pipeline step:
1. **Pipeline step type**: Select a step type for which you want to assign a service.
**Tip:** Specify at least the **Prod deploy** step type for steps that represents the production deployment to enable DevOps to identify successful pipeline executions as production deployments.
2. **Service**: Select the CMDB application service that the pipeline step maps to.
Application service maps approximately to the environment. If you use the same pipeline step to deploy to different environments, leave the field empty. Service information enables DevOps to identify and report on operational metrics such as incidents, outages, and so on.
4. Select **Next**.
Image omitted: azure-plybk-08.png Assign services to pipeline steps.
5. If you want to import pipeline data, select the date range and select **Submit**.
You can import up to 90 days of data.
You’ve successfully onboarded your Azure DevOps tool to DevOps Change Velocity at the project level.
What to do next
From the Projects tab on the tool record page, select a project to navigate to the project record page. From here, you can discover project objects, and configure webhooks for the project.
Select Discover projects to discover the project objects, including existing plans (boards), repositories, and pipelines. This will discover all the projects in your organization as well.
Select Configure projects to configure webhooks for the project.
If you're on the tool records page, selecting Configure projects and entering the integration user credentials gives the list of unconfigured projects in your organization. Select the projects that you want webhooks configured for and select Configure.
Note: The step to enter the integration user name and password is required to configure webhooks only when DevOps Config is installed or the Generic Connection on configure operation for Azure DevOps property is disabled. If this step is not required, webhooks are configured using token-based authentication.
To import historical data to the project objects like plans, repositories, or pipelines, associate the objects with an application, and import the data. For more information, see Associate tool objects to applications - Workspace.