Skip to main content
The Azure DevOps integration captures Git repository activity: pushes, pull requests (opened, updated, merged, abandoned), review votes, and pull request comments. This is how Cogniscape connects delivery work to your knowledge graph — what changed, who did it, how it was done, and when it happened. It works through service hooks, which Azure DevOps configures per project. The Customer Portal generates a script that creates them in every project of your organization in one run.
Only Azure DevOps Services (the cloud service at dev.azure.com) is supported. Azure DevOps Server (on-premises) is not.
We never store any source code. Cogniscape only processes event metadata — commit hashes, pull request titles, comments, and similar structured data. Your code stays in Azure DevOps. See Data Privacy for details.

​
Before you start

  • You need to be a Project Administrator in each project you want to observe. Creating a service hook requires that permission.
  • Cogniscape never stores an Azure DevOps credential. You create the hooks with your own login, and nothing from it reaches Cogniscape.
  • For the script, your organization must be connected to Microsoft Entra ID (Organization settings → Microsoft Entra). If it is linked only to a personal Microsoft account, use the manual setup instead.

​
Set up the hooks

1

Enter your organization

Open Get Started → Azure DevOps in the Customer Portal and type the organization name — only the part after dev.azure.com/ in the URL.Select Verify organization. Cogniscape checks that the organization exists and records its identifier before you create any hook, and generates the secret that protects your hooks.
2

Run the script (recommended)

Choose Script and pick your shell: Bash (macOS, Linux) or PowerShell (Windows). Download the script file (.sh for Bash, .ps1 for PowerShell), copy the secret with its copy button (it is masked on screen), and run the file in your terminal. The file name carries your organization and a short code (for example cogniscape-azure-devops-contoso-1a2b3c4d.sh), and the page shows the exact command for your file:
On Windows, the downloaded file is marked as coming from the internet, so run it with an execution policy that allows it:
The script asks for the secret with hidden input. The file itself does not contain the secret, so you can read it, share it, or have an assistant review it before you run it. If you prefer not to type the secret, set the COGNISCAPE_SECRET environment variable before running. The script checks the value against the secret that was current when you downloaded the file, and stops without creating anything if it does not match.Requirements:
  • The Azure CLI (az), signed in with az login by a Project Administrator.
  • For Bash, also curl, jq, and sha256sum or shasum. PowerShell needs nothing else.
The script uses a short-lived token from your own az login session. It creates 4 service hooks per project, in every project of the organization, and prints a summary per project. To limit it to some projects, edit the PROJECT_FILTER line (Bash) or $ProjectFilter (PowerShell) in the file before running.
3

Run it again when something changes

The script is safe to run as many times as you want: hooks that already exist are updated and re-enabled instead of duplicated. Run the same file again when you create a new project or when a hook was disabled. After you generate a new secret, download the script again and run the new file with the new secret (if you use COGNISCAPE_SECRET, update the variable too): the old file only accepts the old secret.
The script checks that the organization you are logged in to is the one you verified in the portal, and stops without creating anything if it is not.

​
Set up the hooks manually

If you cannot run the script, create the hooks by hand. Repeat this for every project and for each of the 4 events.
1

Open the service hooks

In Azure DevOps, go to Project settings → Service hooks, select +, and choose Web Hooks.
2

Pick the event

The screen opens with the Advanced Security alert created trigger already selected. Change it to the event below before continuing.
Keep the filters (repository, branch, and the others) at [Any].
3

Paste the URL and the header

Copy both from the Customer Portal — it shows them already filled in with your customer key and secret.
4

Choose the level of detail

Set Resource details to send to All, Messages to send to None, and Detailed messages to send to None.
5

Test and finish

Select Test to confirm that Azure DevOps can reach Cogniscape, and complete with Finish. The test does not check your secret; see Verify the hook.

​
Verify the hook

The Test button only confirms that Azure DevOps reached Cogniscape. Cogniscape always answers HTTP 200, so the test succeeds even when the customer key or the secret is wrong. To confirm that events are flowing, create some activity — a push to one of the recorded branches or a pull request — and check that it shows up in Cogniscape within a few minutes. If it does not, check the URL and the secret in the hook header (or download the script again and run it) and contact support.

​
Troubleshooting the script

If the script stops with Could not read organization …: your Azure CLI sign-in is not accepted by it., the Azure CLI is probably signed in to a different Microsoft Entra tenant than the one your organization belongs to. The tenant is shown under Organization settings → Microsoft Entra. Sign in to it and run the script again:
If the script stops with The secret does not match the one on the Cogniscape page, the value you typed (or set in COGNISCAPE_SECRET) is not the secret this file expects. Nothing is created in that case. There are two causes:
  • A copy mistake. Copy the secret again with the copy button and run the same file again.
  • A file from before a new secret. A file downloaded before you generated a new secret only accepts the old secret, even when you type the current one. Download the script again and run the new file: the code in the file name changes with the secret, and the organization is part of the name too.
In both cases, if you set COGNISCAPE_SECRET, update it with the current secret or remove it so the script asks for the secret again.

​
Supported events

Builds, pipelines, and work items are not captured yet. Events not listed above are received but ignored.

​
Current limits

  • Azure DevOps does not include changed lines or the list of changed files in push and pull request hooks, so Cogniscape does not have them.
  • A push lists at most 25 commits per branch.
  • Pushes are only recorded on the main working branches: main, master, develop, and branches named release/*, hotfix/*, feat/*, or feature/*. Pushes to other branches are not recorded. Pull requests are recorded from any branch.

​
Good practices

  • Hooks are per project. The script creates four in each project, one per event. When you create a new project, run the script again (or repeat the manual setup).
  • Use a service account, not a person. Azure DevOps disables a hook if the user who created it leaves the organization. Run the script, or create the hooks, with a dedicated service account that has the Project Administrator role.

​
Security

Azure DevOps does not sign webhook payloads (there is no HMAC). Protection comes from two things:
  • The secret sent in the X-Cogniscape-Secret header, which Cogniscape checks on every delivery.
  • The organization check: events from an organization other than the one you verified are refused.
Treat the secret like a password. If you suspect it was exposed, select Generate new secret in the portal.
Generating a new secret invalidates the previous one within about a minute. Your existing hooks stop working until you download the script again and run the new file (or update the header in each hook), and events sent in the meantime may be lost.
Full Azure DevOps reference: Service hooks documentation.