Connect Almo to Azure DevOps: a complete setup guide

Almo runs inside Outlook and connects it to your Azure DevOps organisation, so you can create, track, and manage work items without switching applications. Before any of that, you connect the two.

There are two ways to do it.

1. The first is to sign in with the Microsoft account you already use for Outlook, which is the route most people take and is close to automatic.
2. The second is to connect with a Personal Access Token, a scoped Azure DevOps credential you use in place of a password. You need it only when a Microsoft sign-in cannot reach the organisation you are after. This guide covers both routes, the one-time IT approval some organisations require, and the issues that come up on a first connection.

Before you start

You will connect faster if these are in place:

• New Almo installed from Microsoft AppSource and open in Outlook (Windows, Mac, or Outlook on the web – the steps are the same everywhere).
• The Microsoft account you use for Outlook, which is usually your work account.
• Access to at least one Azure DevOps organisation and project. If you can open work items in the Azure DevOps web portal, you have what you need.

Some organisations also require their IT administrator to approve Almo once before anyone in the organisation can sign in. The IT approval section below covers what to do if that applies to you.

Option 1: Sign in with Microsoft (recommended)

This is the route to take whenever your Azure DevOps organisation sits under the same Microsoft account as your Outlook. It needs no new credentials and no manual server URLs.

1. Open Almo in Outlook and select Sign in with Microsoft. Almo uses the account you are already signed into Outlook with, so there is nothing new to type.
2. Let Almo discover your organisations and projects. Once you are signed in, Almo reads the Azure DevOps organisations and projects your account is permissioned on and lists them for you. Classic Almo made you type a server URL by hand; New Almo finds them for you, which is why this step is close to instant.
3. Choose your Working Project and select Continue. Pick the one project you want Almo to focus on by default. You can change it later at any time.

That is the whole flow. From here you can create, update, link, and track Azure DevOps work items from any email in Outlook.

What a Working Project is, and why you set it now

Your Working Project is the project Almo treats as home. When you open Almo next to an email, the items it surfaces by default – the ones linked to that email, related items from the same thread, and recently updated work items – all come from your Working Project. Setting it during connection means Almo shows you relevant work from the first email you open rather than an empty screen.

You are not locked in. Most people work across more than one project over a sprint, and switching takes a few seconds from Almo’s settings. We cover that in its own guide: Change your Working Project in Almo.

Option 2: Connect with a Personal Access Token (PAT)

A Microsoft sign-in reaches every organisation your account is permissioned on. When the organisation you need sits outside that account, you connect it with a Personal Access Token instead. This covers a few real situations: you are a guest in another company’s tenant, the organisation sits in a separate Microsoft tenant from your Outlook account, you work with a contractor or client organisation, or you keep a personal Azure DevOps organisation under a different login.

A PAT is an Azure DevOps token that acts as an alternative password. It is scoped to specific permissions, you set its expiry, and you can revoke it whenever you want. You create it once in Azure DevOps and paste it into Almo. Microsoft’s own guide, Use personal access tokens, explains what a PAT is and how it works in full.

Where to add a PAT in Almo

You can add a server with a PAT at two points, and both open the same dialog. During your first connection, the Set Working Project screen carries an Add Server (via PAT) link at the bottom. After that, you reach the same place from Settings at any time: select Modify next to your Working Project to open the Modify Working Project screen, which lists every server you have connected and carries the same Add Server (via PAT) link.

That screen is also where you manage your connections. You can add as many servers as you need, edit or remove the ones you already have, and switch your Working Project between any of their projects as often as you like. Change your Working Project in Almo covers the switching side in detail.

Selecting Add Server (via PAT) opens the Add New Server dialog, with two fields: Organization URL and Personal Access Token (PAT).

Keep the dialog open, then create the token.

Create the token in Azure DevOps

1. In the Azure DevOps web portal, open User settings (the gear icon near your avatar) and select Personal access tokens.
2. Select + New Token.
3. Give it a recognisable name (for example, Almo Outlook add-in), choose the organisation it applies to, and set an expiry. A shorter expiry is safer; you can always create a new token later.
4. Under Scopes, choose Custom defined, then enable the three scopes Almo needs.

These three are the minimum for Almo to work correctly:

• Work Items – Read, write, & manage. This is the core permission. It lets Almo create, read, update, and delete work items, manage links between them, handle attachments, and add comments.
• Project and Team – Read. This lets Almo list your organisations and projects, and read work item types and fields. Without it, the project list comes back empty.
• User Profile (vso.profile) – Read. This lets Almo populate the Assigned To list with the people in your organisation. Without it, you cannot assign work items to anyone.

A token missing any of these will appear to connect and then fail the moment Almo tries to read project types or list users, so it is worth setting all three now rather than diagnosing a half-working connection later.

Two more scopes are optional. Add Code – Read if you want to link work items to pull requests, commits, or branches, and Graph – Read for richer user and group search. You do not need Build, Release, Test, Analytics, or any other scope.

When you select Create, Azure DevOps shows the token once. Copy it straight away and keep it somewhere safe, because it is not shown again.

For Microsoft’s own reference on this, see Use personal access tokens for the full creation walkthrough and the available scopes reference for what each scope grants.

Connect from Almo

Back in the Add New Server dialog:

1. Enter your Organization URL in the form https://dev.azure.com/your-organisation.
2. Paste your token into the Personal Access Token (PAT) field.
3. Select Connect. Almo validates the token and its scopes, then adds the organisation to your server list so you can pick a project from it.

Keeping the token safe

A PAT is as sensitive as a password, so treat it that way. Grant only the scopes above, set an expiry rather than letting it run indefinitely, and revoke it from Azure DevOps user settings if you stop using Almo or suspect the token has been exposed. When a token expires, create a fresh one and reconnect.

If your IT team needs to approve Almo first

Organisations that manage app access centrally need an administrator to grant consent once before anyone in the organisation can sign in. After that single approval, every user can connect with the Microsoft sign-in route above, and new team members get access automatically.

If you are the IT administrator, the quickest path is one-step admin consent, where you approve Almo’s Microsoft and Azure DevOps permissions in a single visit. The alternative is to grant the two sets of permissions separately in the Azure and Entra portals. Adding Almo to Entra: a guide for IT admins walks through both, with screenshots.

If you are not the administrator and you hit a Microsoft “Approval required” screen when signing in, request access from that screen directly. Submit it with a short note on why you need Almo, and your administrator approves the request once. Requesting access to Almo shows exactly what that looks like.

Troubleshooting a first connection

Why is my organisation or project list empty after signing in? This almost always means your account is not permissioned on any Azure DevOps organisation that the sign-in can reach, or your IT team has not yet approved Almo. Confirm you can open the project in the Azure DevOps web portal, check the IT approval section above, and use a PAT if the organisation sits under a different account.

Why is a project I expected missing from the list? You are likely connected, but not permissioned on that specific project. Ask the project administrator to add you, then reopen the project list in Almo.

Why won’t my Personal Access Token connect? Check the token in this order: it has not expired, it has all three required scopes (Work Items, Project and Team, and User Profile), the Organization URL is exactly https://dev.azure.com/your-organisation, and your account actually has access to that organisation. A scope gap is the most common cause, so re-check those first.

Why can’t I connect with a guest account? Guest access often will not surface the host organisation through a standard sign-in. Connect that organisation with a PAT instead, following Option 2 above.

Why does sign-in keep looping or show “Approval required”? Your organisation requires admin consent. Submit the access request from the approval screen as described above, and you will be able to sign in once it is granted.

You are connected

Once Almo is connected, the rest follows from your inbox: open an email, see the work items linked to it, and create or update Azure DevOps work items without leaving Outlook. Setting your Working Project during connection means that view is useful from the very first email you open.

If your connection does not behave as described here, the Almo team can help. Write to [email protected] or raise a support ticket from inside Almo.