Azure DevOps

Trustle reads work item changes from Azure DevOps and ends access when a linked work item closes. If you configure write-back, Trustle can also comment on work items, set their status, and open new work items.

Prerequisites

• The Project Collection Administrator role in Azure DevOps, or permission to edit service hooks in each project.
• An identity provider connected in Trustle, for example Okta or Microsoft Entra ID. Trustle hides Issue Tracking Applications until one is connected.
• For write-back only: permission to create an app registration in Microsoft Entra ID, and permission to add users under Organization settings in Azure DevOps.

Configure Azure DevOps

Step 1: Get the values from Trustle

1. In Trustle, go to Connections.
2. Under Issue Tracking Applications, find Azure DevOps and click Connect.
3. In Azure DevOps Organization, enter the organization name from dev.azure.com/<organization>. Trustle also accepts the full URL. Description is optional.
4. Click Generate Key.
5. Copy each value. Keep this Trustle tab open. You return to it in Connect in Trustle.

Value from Trustle	Where it goes in Azure DevOps
Payload URL	Service hook → URL
HTTP Headers	Service hook → HTTP headers. The value is one line: X-Api-Key: <key>.

Caution

Trustle shows the full key only while this page is open. If you lose it, generate a new key. See Security notes.

Step 2: Create the service hooks

Each project needs its own 3 service hooks. Do this step in every project whose work items people cite in access requests.

1. In Azure DevOps, open the project. Go to Project settings → Service hooks.

2. Click + to create a subscription.

3. Select Web Hooks. Click Next.

4. Select the trigger for the first subscription in this table:

   Subscription	Trigger	Filter	What Trustle does with it
   1	Work item created	None	Records the new work item.
   2	Work item updated	Field: State	Finds out when a work item closes.
   3	Work item updated	Field: Title	Shows the current title of a cited work item.

5. Click Next. On the action page, enter these values:

   Field	Value
   URL	The Payload URL from Step 1
   HTTP headers	The HTTP Headers line from Step 1
   Resource details to send	All
   Messages to send	None

6. Click Test to send a sample event. Then click Finish.

7. Do the same for subscriptions 2 and 3. All 3 use the same URL and the same header.

Step 3: Create an app registration for write-back (optional)

Without write-back, Trustle only reads. It does not comment on, change, or open work items.

1. In the Azure portal, go to Microsoft Entra ID → App registrations. Click New registration.
2. Enter a name, for example Trustle Azure DevOps. Click Register.
3. On Overview, copy the Application (client) ID and the Directory (tenant) ID.
4. Go to Certificates & secrets. Click New client secret. Copy the secret Value.

Caution

Azure shows the secret value once. If you lose it, create a new client secret.

Step 4: Grant permissions (write-back only)

Trustle signs in as the app. Azure DevOps refuses every call until you add the app to the organization.

1. In Azure DevOps, go to Organization settings → Users. Click Add users.

2. Search for the app by its display name. If it does not appear, paste its Object ID from Enterprise applications in Microsoft Entra ID. Do not use the app registration’s client ID.

3. Set the access level to Basic.

4. Add the app to each project from Step 2, and to the project where Trustle opens work items:

   Permission	Required	What Trustle does with it
   Member of the organization, Basic access level	Yes, for write-back	Signs in to Azure DevOps. Without it, every call fails with TF401444.
   Member of each project, in the Contributors group	Yes, for write-back	Comments on work items, sets their status, and opens new work items. Without it, write-back fails for that project.

Step 5: Collect the values for Trustle

Do this step only for write-back.

Trustle field	Where to find it	Example
Directory (Tenant) ID	App registration → Overview	00000000-0000-0000-0000-000000000000
Application (Client) ID	App registration → Overview	12345678-1234-1234-1234-123456789012
Client Secret	The secret Value from Step 3	<client-secret>
Project	The Azure DevOps project where Trustle opens work items	<project-name>
Work Item Type	A work item type in that project. The default is Issue.	Issue
Status When Approved	A state of that work item type. The default is To Do.	To Do
Status When Denied	A state of that work item type. The default is Done.	Done
Assign Work Items To	Optional. An email address or a display name. Leave it empty to assign the requester.	admin@yourcompany.com

The default statuses come from the Basic process. A project on the Agile process uses New, Active, Resolved, and Closed instead. Trustle checks each status name against the project when you save.

Connect in Trustle

1. Return to the Trustle tab from Step 1. Trustle saved the connection when you clicked Generate Key.
2. To finish without write-back, click Finish.
3. To add write-back, click Add Write-Back Settings. Enter the values from Step 5.
4. Optional: turn on Open a Work Item for Every Request. Trustle then opens a work item for each decided request that cites none.
5. Click Test Connection. After the test passes, click Save Settings.

Note

A webhook connection has nothing to test. Azure DevOps sends events to Trustle. Verify shows that the first event arrived. Test Connection checks only the write-back credentials: that the app can sign in and reach the organization.

To add write-back later, open the Azure DevOps connection. Enter the credentials on the Credentials tab. Then fill in Write-Back Settings on the Settings tab.

With write-back on, Trustle does this:

Event	A work item is linked to the request	No work item is linked
Request approved	Sets Status When Approved. Posts the request reason and the approver’s reason.	Opens a work item only if Open a Work Item for Every Request is on.
Request denied	Sets Status When Denied. Posts both reasons.	Opens a work item only if Open a Work Item for Every Request is on.
Access ends	Posts a comment. Never changes the status.	Nothing.

Verify

1. In Trustle, request access. Paste the URL of a test work item into the reason, for example https://dev.azure.com/<organization>/<project>/_workitems/edit/<id>. Get the request approved.
2. In Azure DevOps, close the test work item.
3. In Trustle, open the access request. Check that it shows the linked work item and that the access ended within a few minutes.
4. If you configured write-back, check that the work item has a Trustle comment and the Status When Approved.

If something is missing, see Troubleshooting.

Security notes

Note

• Azure DevOps service hooks cannot sign their payloads. The X-Api-Key header is the only credential. A payload can only end access early. It cannot grant, extend, or approve access.
• Trustle ignores an event whose payload names a different Azure DevOps organization from the one on the connection.
• To replace the key, open the connection. On the Settings tab, in the Webhook card, click Generate New Key. The old key stops working at once. Paste the new HTTP Headers line into every service hook. The Payload URL does not change.
• To stop Trustle from acting on events, disable the connection on its Settings tab. Trustle then ignores incoming webhooks.
• For write-back, use a dedicated app registration for Trustle only. Store the client secret in a secret manager. Never commit it to a repository.
• Azure client secrets expire. Create a new secret before the old one expires. Then enter it on the connection’s Credentials tab.

Troubleshooting

Trustle receives no events

Open the service hook in Azure DevOps and look at its History. Then check these values:

• HTTP 401: the key is wrong. Paste the whole HTTP Headers line, X-Api-Key: <key>. After a key rotation, update every service hook.
• HTTP 404: the URL is wrong, or the connection is disabled. Copy the Payload URL again from the connection’s Settings tab.
• Success, but nothing in Trustle: the organization on the connection does not match the organization that sent the event. Trustle accepts the event and ignores it.
• One project works, another does not: each project needs its own 3 service hooks.

Access does not end when the work item closes

• The request reason must contain the full work item URL. Trustle links only the work items it finds in the reason.
• The project must have subscription 2: Work item updated with Field: State.
• Trustle ends access when Azure DevOps sets the work item’s Closed Date. A state that does not set it, for example Resolved in the Agile process, does not end access.
• The connection must be enabled.

Test Connection fails: the service principal is not a member of the organization

The app can sign in, but it is not a user in the organization. Do Step 4. Search by the app’s display name. If it does not appear, paste its Object ID from Enterprise applications.

Save Settings fails: a status is not a state of the work item type

The status names must exist in the project’s process. The error names the project and the work item type. Enter states that the work item type has, for example Active and Closed for the Agile process.

Trustle opens a work item with no assignee

Azure DevOps cannot find the person in Assign Work Items To. Trustle then opens the work item without an assignee. Enter an email address or a display name that exists in the organization.

None of these fixes work

Email support@trustle.com. Include the error message, the connection name, and the Azure DevOps organization name and the Application (client) ID. Never send a secret, key, or token.