A lot of Azure DevOps confusion starts before the first pipeline even runs.
Teams open the portal, create a few repos, maybe a couple of boards, and keep moving. That works for a while. Then a few months later, nobody is fully sure which project owns what, where the shared code should live, or whether a new team should create another project or just add one more repo somewhere random.
That is usually not a tooling problem.
It is a structure problem.
If your Azure DevOps layout is clean, permissions stay easier to manage, pipelines stay easier to reason about, and new developers can understand the system faster.
In this post, I will break down the practical hierarchy in simple words:
- Organization
- Project
- Repository
And more importantly, I will explain how I think about the boundaries between them.
The basic hierarchy
Azure DevOps usually works like this:
- Organization is the top-level container
- Projects sit inside the organization
- Repos sit inside projects
- Pipelines, boards, artifacts, and permissions usually attach at the project level and then get refined further
Here is the structure visually:
What an organization should represent
An Azure DevOps organization is the highest-level workspace.
In most real setups, one organization maps to one company, one startup, one internal platform group, or one major business unit.
Think of it as the outer shell that owns:
- users
- billing
- global access patterns
- the set of projects your teams work in
A good default is:
- one company = one organization
You usually do not want a new organization for every product or every team unless there is a strong reason such as:
- legal separation
- isolated billing
- hard security boundaries
- completely different admin ownership
If you split organizations too early, you create extra admin work and make cross-team visibility worse.
What a project should represent
A project is where most teams should make their main structural decisions.
This is the level where Azure DevOps starts to feel like a working delivery environment instead of just a container.
A project commonly groups together:
- boards
- repos
- pipelines
- service connections
- artifacts
- team-specific permissions
- delivery workflows
The clean mental model is:
- one project = one product, platform, or delivery stream
That means a project should represent a chunk of work that has enough internal connection to belong together.
Examples:
- customer web platform
- internal data platform
- mobile app ecosystem
- infrastructure automation platform
That does not always mean one project per microservice.
If you create too many projects, you make navigation, permissions, reporting, and pipeline management more annoying than they need to be.
What a repo should represent
A repo is where the actual code lives.
Inside a project, you can have one repo or many repos depending on how your system is built.
A repo might represent:
- one application
- one backend service
- one frontend
- one infrastructure codebase
- one shared SDK or library
A healthy repo split usually follows ownership and deployment boundaries.
Good repo examples inside a project:
customer-platform/
frontend-app
backend-api
infra-terraform
shared-components
That split makes sense when those codebases:
- change at different speeds
- deploy independently
- have different owners
- need different pipeline logic
If everything always ships together and is maintained by the same small team, a monorepo can also be totally fine.
A practical way to decide the boundary
Here is the shortcut I use.
Use a new organization when:
- admin ownership is fully different
- billing or compliance must be isolated
- the systems should not share visibility by default
Use a new project when:
- a product or platform has its own delivery lifecycle
- the team wants separate boards, pipelines, and permissions
- the work is important enough to deserve its own operating space
Use a new repo when:
- code should version separately
- deployment should happen separately
- ownership is different
- the codebase is becoming noisy or hard to review as one unit
That is the cleanest rule set for most teams.
Example setup that scales well
Say your company has three main delivery areas:
- customer-facing web product
- mobile app stack
- data platform
A clean Azure DevOps layout could look like this:
Organization: nimay-tech
Project: Customer Platform
Repo: frontend-app
Repo: backend-api
Repo: infra-terraform
Project: Mobile Platform
Repo: mobile-app
Repo: shared-sdk
Project: Data Platform
Repo: data-platform
That structure works because each project has a clear mission, and each repo has a clear code boundary.
It is easy to answer:
- where the mobile shared code lives
- where the web infra code lives
- which project owns the related pipelines
- which team should get access
That clarity saves time every single week.
The mistake people make too early
The most common mistake is either:
- throwing everything into one giant project forever
- splitting into too many projects too early
Both create pain.
If everything is in one giant project
You usually get:
- messy repo lists
- unclear board ownership
- too many pipelines in one place
- broad permissions that are harder to manage
- shared noise across unrelated teams
If you create too many projects too early
You usually get:
- duplicated setup work
- scattered dashboards
- more service connection management
- harder cross-team reporting
- random inconsistency in how teams configure things
The win is not maximum separation.
The win is useful separation.
How pipelines fit into this
Pipelines usually follow the repo and project structure.
A common pattern is:
- repo-specific build pipeline
- environment-specific release or deploy stages
- project-level visibility for delivery flow
For example:
trigger:
branches:
include:
- main
pool:
vmImage: ubuntu-latest
steps:
- script: npm ci
- script: npm test
- script: npm run build
That pipeline belongs naturally with the repo that owns the code. But it still benefits from project-level organization because related teams can find the rest of the delivery assets in one place.
Monorepo vs multi-repo in Azure DevOps
This question comes up a lot.
There is no universal winner.
Monorepo is usually better when:
- one team owns the whole system
- components change together often
- shared tooling matters more than separation
- the deployment model is still simple
Multi-repo is usually better when:
- teams own different services
- services deploy independently
- access should differ across codebases
- the platform is growing and review boundaries matter more
Do not force multi-repo because it sounds more advanced.
Do not force monorepo because it feels simpler today.
Pick the one that matches ownership and deployment reality.
The rule that keeps the whole thing sane
If you are stuck, ask one question:
Will this boundary make ownership clearer or more confusing six months from now?
That question cuts through a lot of overthinking.
Good Azure DevOps structure is really about:
- clean ownership
- clean visibility
- clean delivery flow
- clean permission boundaries
If your structure improves those four things, you are probably making the right call.
Final takeaway
The easiest model to remember is this:
- Organization = company or top-level admin space
- Project = product, platform, or delivery stream
- Repo = code boundary
Start there.
Do not over-split on day one, but do not let everything pile into one bucket either.
A clean Azure DevOps structure makes every other part of DevOps easier: pipelines, boards, permissions, onboarding, and ownership.
That is the real W.
References
- Microsoft Learn, About organizations, projects, and collections https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/about-accounts
- Microsoft Learn, Create a project in Azure DevOps https://learn.microsoft.com/en-us/azure/devops/organizations/projects/create-project
- Microsoft Learn, About Azure Repos https://learn.microsoft.com/en-us/azure/devops/repos/get-started/what-is-repos
- Microsoft Learn, What is Azure Pipelines? https://learn.microsoft.com/en-us/azure/devops/pipelines/get-started/what-is-azure-pipelines
