12 Things you Should Know when Implementing Azure DevOps in your Organization

Azure DevOps is a really fantastic part of any DevOps tool chain. But when you’re first starting out with it in an organization, there are a few things you should know that will make it even better… and avoid making some doing some things you’ll later regret. These tips are most important if you’re implementing it across multiple teams or in a medium to large organization. Even if you’re implementing it in a small start-up, most of these tips will still help.

These tips are all based on my experience with implementing and using Azure DevOps, Visual Studio Online (VSO) and Visual Studio Team Services (VSTS). These are all things I wish I’d known earlier as they would have saved me time, made my life easier or kept me more secure. They are also just my opinion, so I encourage you to investigate further and decide what is best for you in your situation/environment.

This is by no means an exhaustive list either and they are in no particular order.

So, let’s get into it:

Less projects are better

Most things (work items, repositories, pipelines etc.) in Azure DevOps are organized into containers called Projects. It is tempting to try to break your work into lots of small projects (e.g. one for each library, or one per team, or one per department). This results in a lot of management overhead trying to keep everything organized and adds little value in most cases (there are exceptions). Implementing a project per team or a project per software component is usually wrong.

Recommendation: The less projects you have the better. Use Area Paths (covered next) to organize work in your project.

Documentation Reference: When to add another project

Organizing Area Paths

Area Paths allow you to divide the work items and test plans into a hierarchy to make them easier to manage. Teams can be assigned to one or more area paths.

Area’s are easily moved around, so they are much better suited to arranging your work by software component/product and organizational hierarchies.

Recommendation: For your project, set up Area Paths and assign teams to them.

Documentation Reference: Define area paths for your project

Connect AAD.

If you are using Azure AD as your primary identity source for your organization, then you should connect your Azure DevOps organization to Azure AD. This will allow your Azure AD identities to be used within Azure DevOps.

If you aren’t using Azure AD, but have Active Directory, consider setting up hybrid identity with Azure AD.

You should manage access to your Azure DevOps organization and to projects and other resources (e.g. Service Connections) using Azure AD Groups. I’d also strongly recommend reading the documentation on security groups and permissions for Azure DevOps as there are a lot of nuance to these and they deserve an entire post on their own.

Recommendation: Use Azure AD as the identity source for Azure DevOps. Create and manage users and security groups within Azure AD.

Documentation Reference: Connect organization to Azure Active Directory, Access with Active Directory Groups.

Importing a TFVC repository as Git

This might be controversial, but it shouldn’t be. Unless you have a legacy TFVC repository that you need to keep around for historic/support reasons or some tools that only support TFVC that you can’t live without (or can’t replace) then you should be using Git as your version control system.

If you do have legacy TFVC repositories that you need to bring over, consider importing them as Git repositories.

Recommendation: Use Git. Make sure all your teams know how to use Git well.

Documentation Reference: When to add another project

Create a Sandbox Project

You and your teams will often need a place to experiment and learn about Azure DevOps safely. A sandbox project is a great place to do this. You can create a sandbox project and give teams higher levels of permissions over it project to allow them to experiment with different settings (for example try out an alternate area path structure)

Don’t confuse a sandbox project with a project for building proof-of-concepts/experimental code: you should not use a Sandbox project for creating anything that could end up in production or anything that has any value. Content in sandbox projects often accidentally get deleted.

Recommendation: Create a Sandbox Project. Assign an image and description for the project to make it clear that it is a Sandbox and what it can be used for.

Documentation Reference: When to add another project

The Azure DevOps Extensions Marketplace

The Azure DevOps marketplace is filled with many great extensions that really enhance the value of Azure DevOps. It is well worth browsing through the extensions created by both Microsoft, Microsoft DevLabs and the hundreds of 3rd party ones to really experience the full power of Azure DevOps.

You should set up a formal process around validating, on-boarding and off-boarding extensions from your organization. It is all too easy to end up with “extension sprawl” that results in a management nightmare, especially if you have strict security or governance practices (you might be familiar with this if you’ve ever managed Jenkins within a large organization).

It is also tempting to install pipeline extensions for any minor task that you might want to execute in a CI/CD pipeline. But you should consider if the governance & management of a task is worth the time that might be saved using it, especially when a short Bash or PowerShell task might do just as well.

Recommendation: Install important extensions from marketplace. Formalize a process for validating, on-boarding and off-boarding extensions.

Documentation Reference: Azure DevOps marketplace, Install Azure DevOps Extension

Do NOT use “Classic Editor” and create pipelines without YAML

Early on the evolution of Azure DevOps pipelines, all pipelines had to created using a visual designer. The structure of this visually designed pipeline was not stored in code, rather it was stored separately without proper version control. This is no longer the case.

You should always create new build pipelines using YAML and store them in your repository with your source code (pipeline as code). You can still use the assistant to help you design your YAML:

Click Show Assistant to edit your YAML.

The exception is release pipelines which don’t support YAML and being stored in version control.

Recommendation: Create all pipelines a multi-stage YAML pipelines.

Documentation Reference: Define pipelines using YAML syntax

Release Pipelines are awesome, but are they worth missing out on pipeline as code?

Release pipelines don’t support YAML. However, in many cases you don’t need release pipelines. Instead, you can use your multi-stage YAML build pipeline to release your software as well by adding a deployment job. This also aligns much more closely to GitHub, where there is no concept of a Release Pipeline and would make moving to GitHub Actions much easier should you want to.

As of writing this post, there are two key feature that are missing from YAML build pipelines: Gates and Deployment Group jobs. Also, the release pipeline visualization and dashboard widgets are quite useful, so you may prefer these over the build pipeline visualization. But in my opinion the visualization is not worth losing version control over your pipeline.

Recommendation: Use multi-stage YAML pipeline deployments if you don’t need Gates or Deployment Group Jobs. Use conditions to determine if a deployment job should be executed. Use approvals and checks on the environment to control deployment.

Documentation Reference: Deployment Job, Conditions, Approvals, Environments.

Add a machine to a Deployment Group.

If the applications you are building and releasing need to be deployed to a physical or virtual machine (e.g. not to a Kubernetes cluster or managed service) that is not accessible by an Azure DevOps Hosted agent, then you can use a Deployment Group agent.

This is just the Azure DevOps Hosted agent installed onto the machine and registered with Azure DevOps as a Deployment Group agent in a Deployment Group. Deployment Group agents only require outbound connectivity to Azure DevOps services.

This is a good solution if you’re deploy to machines on-premises or on machines where inbound internet connectivity is blocked, but outbound internet is allowed.

Recommendation: If you have to deploy your application to a machine that is not accessible from Azure DevOps Microsoft Hosted Agents.

Documentation Reference: Deployment Group agent, Deployment Group

Get a list of Azure DevOps projects using Azure DevOps CLI

Just like most other Microsoft tools, you can automate them from the command line using either PowerShell, CMD or Bash (or even REST API). If you have to perform repetitive tasks in Azure DevOps, you might want to consider automating these processes.

This is also a good way to control certain processes and practices, such as creating Service Connections from code in a repository, or rolling secrets in a Library Variable Group.

You can also use these tools to interact with Azure DevOps from within Azure DevOps pipelines, leading to some interesting techniques such as release orchestrations (beyond the scope of this doc).

Recommendation: Use Azure DevOps CLI or the VSTeams PowerShell module (created by Donovan Brown) to automate Azure DevOps. Alternatively, use Azure DevOps REST API.

Documentation Reference: Azure DevOps CLI, VSTeam PowerShell module, Azure DevOps REST API.

The best way to learn Azure DevOps is to get hands-on practical experience. Azure DevOps Labs provides free hands-on labs environments (via your own DevOps organization) and covers practically everything you could ever want to know. The Azure DevOps content on Microsoft Learn also has detailed walk throughs of the product and processes.

Making sure everyone in your organization has the skills/knowledge to work with Azure DevOps will help them be more successful and happy.

Recommendation: Do some of the hands-on labs and complete some Microsoft Learn learning pathways.

Documentation Reference: Azure DevOps Labs, Azure DevOps content on Microsoft Learn

There are definitely lots more recommendations and considerations I could suggest, especially security and DevOps best-practices but to keep this (reasonably) short, I’ll leave them for another post.

I hope you find this useful and it helps you avoid some of my mistakes.