Azure DevOps Integration

Last updated: October 2026

This document explains how to set up and manage an Azure DevOps integration in Katalon True.

Connect Azure DevOps to Katalon True to sync requirements, bugs, and release planning data, link Azure DevOps Test Plans cases, and push test results between the two systems.

Find your starting point:

• You are setting up Azure DevOps for the first time? -> Start from Step 1
• Your organization is already connected and you need to configure a project link? -> Skip to Step 2
• You need to manage an existing integration (disconnect, archive, or restore)? -> Skip to Managing Your Azure DevOps Integration
• You need to link Azure DevOps Test Plans cases? -> Go to Link Azure DevOps Test Plans cases
• You need to export test cases into Azure DevOps? -> Go to Push test cases to Azure DevOps
• You need to publish execution results to Azure DevOps? -> Go to Push test results to Azure DevOps
• Each project needs its own restricted PAT? -> See the Use project PAT option in Step 2

---

Step 1: Authorize the Azure DevOps Connection (Account-level)

This step establishes the connection between Katalon True and Azure DevOps. No project data is synced yet.

requirements

• You must have the Account Admin or System Admin role in Katalon True.

1. Go to Account Settings > Integrations and click + Create Integration.

2. In the Available Integration list, select Azure DevOps.

3. Fill in the required fields:

   • Integration Name: A custom label (max 50 characters).
   • Organization Account URL: Your Azure DevOps organization URL (must start with https://).
     • Example: https://dev.azure.com/your-workspace
   • Personal Access Token (PAT): Refer to Microsoft documentation on creating a PAT. Ensure your PAT includes required permissions.
   Azure DevOps Permissions Required for Katalon True Integration

   Integration Feature	Required Permissions	Notes
   Manual Sync	Read Project and Team, Read Work Items, Read Analytics Access level: at least Basic	Required to fetch test and work item data.
   Link Defect	Read Project and Team, Read Work Items	Enables linking Azure DevOps work items to Katalon True.
   Create Defect	Read Project and Team, Read & write Work Items	Needed to create new Azure DevOps work items (for example, bugs) from Katalon True.
   Push Test Result	Read Project and Team, Read & write Test Management	Enables pushing test execution data from Katalon True to Azure DevOps.
   Link Test Case to KS	Read Project and Team, Read & write Test Management	Required to associate Katalon Studio test cases with Azure DevOps test cases.
   Handle Webhook Events	Read Project and Team, Read Work Items, Read Analytics Access level: at least Basic	Needed for syncing Azure DevOps events to Katalon True.
   Webhook Setup	Member of the Project Collection Administrators group	Required only when configuring webhooks from Azure DevOps to Katalon True.

   • Description (Optional): Max 255 characters.

4. Click Test Connection to validate, then click Save.

Result

To verify the connection is active, navigate to Account Settings > Integrations.

• If the status initially shows Inactive, reload the page to update it to Active.
• If the status shows Error, verify all required configuration fields, especially the PAT.

---

Step 2: Link Azure DevOps to Project (Project-level)

This step shows how to connect an Azure DevOps project to your Katalon True project and configure synchronization settings.

requirements

• You must have the Project Admin role in this project.
• An Azure DevOps account must already be connected at the Account-level (Step 1).

1. Navigate to your project > Settings > Integrations.
2. On your linked Azure DevOps connection, click the right edge and select New configuration (Settings icon).

3. [Optional] By default, the integration uses the PAT saved on the account-level Azure DevOps connection. To use a separate PAT for this project, select Use project PAT, enter the PAT, and click Test Connection to validate it. The projects this PAT can access become available for selection. If the Use project PAT option is not available, ask an Account Admin to allow project-level PAT management for Azure DevOps in Account Settings.

   
   How the project-specific PAT behaves

   • All Azure DevOps requests for this integration use the project PAT instead of the account PAT. The saved PAT belongs to the project integration, not to your user account. Background sync, webhooks, and enabled Test Plans, result, and defect operations for this integration use it.
   • Rotating or revoking one project's PAT does not affect other projects. A valid project PAT keeps working even when the account PAT reports an error.
   • If the project PAT fails, the integration does not fall back to the account PAT. Fix or replace the project PAT.
   • Disconnecting the account connection still disables all its project integrations, including those with their own PAT.

4. Configure the project-level settings:

   Step 1: Select the Project and Team

   • Project: Select the Azure DevOps project to link.
   • Team (Optional): Select a team to support team-based board mapping.
   • Description (Optional): Max 255 characters.

   Step 2: Additional Integration Settings

   • Pull Requirements: Enable generation of test cases from requirements and requirement-to-test-case traceability.
   • Bug Mapping (Pull bugs from ADO): Enable bug synchronization from Azure DevOps.
   notes

   Enabling either option above controls which mapping sections are available in later steps.

   

   Step 3: Map Iteration Path to Release and Sprint

   info

   • This step is enabled only if Pull Requirements and/or Bug Mapping is selected in Step 2.
   • Tier levels follow your Azure DevOps work-item hierarchy configuration.

   Select an iteration path and map it to Release/Sprint in Katalon True.

   • Use Full path when you need full hierarchy paths for clearer resource mapping.
   • To enable For ADO - Team Board, you must select a Team in Step 1.
   

   Step 4: Common Fields and Values Mapping

   Map ADO Priority levels (1 to 4) to Katalon True Priority levels.

   

   Step 5: Requirement Fields and Values Mapping

   info

   This step is enabled only if Pull Requirements is selected in Step 2.

   • Release Date for Requirement (Optional): Select up to three Azure DevOps date fields.
     • The system uses these fields in priority order (left to right) and picks the first available date.
   • Map ADO State to Katalon True Status.
   • Select Work Item Types to sync.
   

   Step 6: Bug Fields and Values Mapping

   info

   This step is enabled only if Bug Mapping is selected in Step 2.

   • Map ADO Severity to Katalon True Severity.
   • Map ADO State to Katalon True Status.
   

5. Click Proceed to sync data and finalize the connection.

   • If the status initially shows Inactive, reload the page to update it to Active.
   • If you click Save after modifying details, changes are saved but status may remain Inactive.
   • To complete syncing, click Proceed.

6. [Optional] To edit an existing linked Azure DevOps integration, click the Edit (pen) icon, update the settings, and click Proceed.

Result

Your Azure DevOps integration is now active within your project.

---

Link Azure DevOps Test Plans cases

Link an Azure DevOps Test Plans case to a Katalon True test case when you need test-case traceability. This linkage is separate from linking a requirement or defect.

Before you begin, make sure the project-level Azure DevOps integration is active and the connected Azure DevOps identity has Read Project and Team and Read & write Test Management permissions.

1. Go to Tests > Test Cases and open the Katalon True test case.
2. In the test case detail view, open Linkages.
3. Under ADO Test Cases, click Click to link ADO Test Cases.
4. Search for and select the Azure DevOps test case you want to link, then click Link.

A Katalon True test case can link to multiple Azure DevOps test cases. For the generic linkage-management workflow, see Manage test cases: Linkages.

To copy Azure DevOps test cases into Katalon True instead of linking to them, see Import test cases from Azure DevOps.

note

ADO Test Cases creates test-case-to-test-case links for Azure DevOps Test Plans. Use Requirements or Defects in the Linkages panel for those artifact types instead.

Push test cases to Azure DevOps

Push to ADO exports Katalon True test cases into Azure DevOps as native ADO Test Cases. This is the reverse direction of Import test cases from Azure DevOps: Katalon True is the source and Azure DevOps is the destination, so stakeholders who work in Azure DevOps can see the test cases your team authors in Katalon True.

requirements

• An active Azure DevOps project integration with Read Project and Team and Read & write Work Items permissions.
• Test cases in a Cloud repository. Push to ADO is not available for Git or custom repositories.

1. Select the test cases or folders to push. Folder selections include all nested test cases.
2. Beside the Export button, select Push to ADO.
   • With a selection, a scope step opens with Selected as the default. Click Next.
   • With no selection, the configuration wizard opens directly and an inline message states that the current view, including active filters, is the scope.
3. In the configuration wizard, select the Azure DevOps integration and destination, choose the export mode, and review the field mapping:
   • Fresh always creates new ADO Test Cases. Repeated pushes create duplicates in Azure DevOps.
   • Linkage updates every ADO Test Case already linked to the Katalon True test case on the selected integration, and creates a new one (with a link back) when no link exists.
   • Field mapping maps Katalon True Status, Priority, and Automation Status values to the Azure DevOps values, in the Katalon True -> ADO direction. Mappings reset when you change the destination.
4. Confirm to start the push. The export runs as a background task; you can follow it in the task list.

What gets exported: the test case name, description, ordered steps with expected results, and attachments. Step order is preserved, and attachments are re-uploaded to Azure DevOps.

note

Exporting folder structure as ADO Test Plans and Test Suites is not supported yet. Scheduled or automatic sync is also not supported — each push is a one-time action.

Push test results to Azure DevOps

You can push a completed run manually or configure results to be pushed automatically. The Azure DevOps integration requires Read Project and Team and Read & write Test Management permissions.

Push manually

1. Open a completed run's Test Run Details page.
2. Select Push Test Result to ADO.
3. Complete the push configuration and confirm the action.

When the push strategy is Push manually, selecting an Azure DevOps Test Plan is optional.

Target a specific Test Suite and Test Point

After you select a Test Plan, the push configuration also lets you select an Azure DevOps Test Suite within that plan — including child and requirement-based suites, not only the plan's root suite. The push then resolves the Test Point from the selected suite, the linked Azure DevOps test case, and the execution's configuration, and records the result against that suite-specific Test Point.

• Selecting the root suite keeps the previous behavior.
• If the selected suite has no compatible Test Point for the linked test case and configuration, the push reports an actionable error instead of a false success.

Suite selection is available in both the manual push dialog and the automatic push configuration.

Push automatically

When configuring the Azure DevOps integration for a run or schedule, select the push strategy appropriate for that execution. Scheduled manual test runs support automatic Azure DevOps result pushes. The Push on passing runs strategy pushes results only when every test in the run passes.

Verify the push

After a successful push, Test Run Details includes a link to the corresponding Azure DevOps test run. The pushed Azure DevOps result also includes a link back to the corresponding Katalon True test result.

---

View Release Plans Synced from Azure DevOps

To view release plans synced from your linked Azure DevOps integration:

1. Navigate to your project > Plans.
2. In the top-right dropdown, select the linked Azure DevOps integration.
3. Click Sync to fetch the latest data.

---

Managing Your Azure DevOps Integration

Katalon True provides multiple ways to manage Azure DevOps integrations without losing historical data.

• Use Disconnect to disable the Azure DevOps integration across all projects (Account-level).
• Use Archive to disable an Azure DevOps connection for a single project (Project-level).

Katalon does not support permanently deleting integrations. This ensures audit history is preserved and enhances security and traceability.

Disconnect an Azure DevOps Connection

Required role: Account Admin or System Admin.

Disconnecting makes the integration inactive across all projects. Katalon True does not support fully deleting integrations to preserve audit history.

For any Azure connections, modifying this connection can also affect Azure Repos configuration when both are set up.

1. Go to Account Settings > Integrations.

2. Click the Disconnect icon next to the connection.

3. Confirm by clicking Disconnect in the dialog.

   => The status changes to Inactive. All projects using this integration lose the ability to sync with Azure DevOps.

4. To reconnect, click the Reconnect icon next to the integration and confirm. All projects will resume syncing once reconnected.

Archive a Linked Jira integration

Required role: Account Admin or System Admin to perform this action

Archiving disables the connection for that project only — other projects using the same Jira integration are unaffected. Archived configurations no longer appear in Project Integrations list, and any scheduled test runs will be canceled at runtime.

1. Go to Project Settings > Integrations.
2. Click the right edge of your linked connection and select Archive.
3. Confirm by clicking Archive in the dialog.

Restore an Archived integration

1. Go to Project Settings > Integrations.
2. Click New configuration (settings icon) on the Azure DevOps connection.
3. Enter the same repository URL as the archived configuration and click Proceed.

Katalon True will restore the archived configuration rather than creating a duplicate.