Connect Azure DevOps Repos

Connect Azure DevOps Services or Server with a token that can only read code, and its service hooks.

In short

Connect Azure DevOps once for the whole organization: name the organization, make a token that can only read code, try it on one repository and add the service hooks.

Before you start

• Who: someone who may manage the organization's connections - owners and admins have it by default.
• Plan: every plan keeps one code host; Business keeps 10 connections and Enterprise any number. Azure DevOps Server comes with the Enterprise plan.
• First: an Azure DevOps account that can read the repositories, and the Project Administrator role to add service hooks.

Where it lives

1. Open your organization, then Settings › "Connections", and press "Connect a code host".
2. Choose "Azure DevOps Repos". The wizard opens; each step is checked before the next one opens.
3. Choose "Azure DevOps Services" and type the "Organization" - the name after dev.azure.com/ - or choose "Azure DevOps Server" and type its "Address".
4. Press "Check this step".

Sign in

1. Press "Open the token page". Azure DevOps opens Personal access tokens.
2. Press New Token, choose Custom defined under Scopes, tick Code: Read and nothing more, and press Create.
3. Copy the token, paste it into "Token".
4. Type one repository into "A repository to check with", as organization/project/repository - such as acme/Payments/payments-api.
5. Press "Check this step": it signs in and reads it.

Give it Code: Read only Azure DevOps cannot tell {{brand}} what a token may do, so the check cannot refuse one that writes.

Webhook

The webhook tells {{brand}} the moment something changes in Azure DevOps, so nothing waits for the next read.

1. Press "Make the address and secret". Copy each with "Copy address" and "Copy secret" - the secret is shown only now.
2. In Azure DevOps, open the project, then Project settings, Service hooks, Create subscription, Web Hooks.
3. Choose the trigger Code pushed. Make the same subscription for Pull request created and Pull request updated.
4. Paste the address as the URL. Under HTTP headers paste the line "Copy header" copied.
5. Press Test to send a first delivery, then Finish.
6. Back in the wizard, press "Look for a delivery". You can also go on with "Next"; deliveries show up under "Deliveries".

Check and use

1. Press "Run the full check". Every step should say Passed; a step that failed names what to change.
2. Under "Where will you use it?" tick the modules that will use it - Boards, Designer and API Tester.
3. Optional: under "Only these teams" tick the teams that may pick it. Leave it empty for everyone who may use those modules.
4. Check the "Name" - boards, designs and projects show it - and press "Finish". The connection shows under "Connections" with its health.

If a step fails

• A failed step names its code, what it means and what to change. The code's section of /help/settings/fix-a-company-connection says more.
• Change what the step says and press "Check again". The next step opens only when this one passes.
• Closing the wizard keeps every step that passed. Press "Continue setup" on the connection's row to go on where you stopped.

Good to know

• Azure DevOps signs nothing, so the secret goes in a header; "Copy header" copies the whole line.

• A connection's row shows its health, its last delivery and "Where used".
• "Deliveries" lists what the webhook address received in the last 30 days and where each delivery went.
• "Disconnect" first lists every board, design and project that would stop using it.
• Nobody else pastes a token: boards, designs and API projects pick this connection.

Related

• /help/settings/fix-a-company-connection
• /help/settings/webhooks-and-site-ownership