ADO project strategy
Standard scope
Applies to: All HCS-governed repos (hcs-authoritative; informational for other scopes) Domain: ado-project-strategy Status: Active
This document defines which repositories get an Azure DevOps project, which stay GitHub-only, and how ADO projects are structured across HCS and associated work.
Decision framework
| Scenario | Use ADO | Use GitHub only |
|---|---|---|
| Actively deployed infrastructure or services | Yes | |
| Client-facing delivery work (TierPoint, customer PoCs) | Yes | |
| Internal HCS tooling that has CI/CD pipelines | Yes | |
| Open-source or community repos (blog, demos, conference) | Yes | |
| Personal or experimental repos with no pipelines | Yes | |
| Repos that only consume GitHub Actions | Yes |
The deciding factor is whether the work needs ADO Pipelines, ADO Boards for work tracking, or is part of a client engagement. If yes to any of these — ADO. If none — GitHub Actions is sufficient.
ADO org
All ADO work lives in a single org: https://dev.azure.com/hybridcloudsolutions
No secondary ADO orgs are created for HCS work. Client orgs (TierPoint, customers) are tracked separately in their own ADO orgs and mirrored into the work item strategy below.
ADO project structure
One ADO project per solution — not per repo.
A solution is a product, application, or engagement that builds, ships, and versions as a single thing. A solution may be made up of many repos. The unit of an ADO project is the solution, not the individual repo.
Apply this test to each GitHub org / GitLab group:
- The org's repos are components of one product (they build/deploy/version together) → one ADO project for the whole solution ("app-solution" org). Every repo in it shares that one project, current and future alike. Examples: CloudSmith (one product, ~57 repos), Turner Legacy (one platform, ~12 repos), ApiaryLens, Holdfast Press, Gunner The Lab, StoryLark.
- The org/group is a collection of independent, unrelated repos (each repo is its own product, tool, or client engagement) → one ADO project per independent repo ("per-repo" org). Examples: Azure Local (each tool is independent), This Is My Demo (independent demos), TierPoint (independent customer deployments, PoCs, and lab environments).
- A per-repo org can still group a handful of repos that are one product without becoming a full app-solution org — grouping happens at the repo level (shared
ado_project), not the org level. Example: Hybrid Cloud Solutions is a per-repo org overall, butrepo-wrangler+repo-wrangler-opsshare oneRepo Wranglerproject, andstudio-foundry+my-studio-foundryshare oneStudio Foundryproject, whilebuildserverkeeps its own.
A brand-new solution defaults to one project even if it starts as a single repo and later grows to many — pull the new repos into the existing solution project rather than minting a project per repo.
Registry encoding — ado_model
The classification above is machine-readable in master-registry.db, on each orgs[] entry:
ado_model: solution— every repo in this org, present and future, shares the org-levelado_project:. Onboarding and repo-discovery must reuse that project rather than creating a per-repo one.ado_model: per-repo(default, may be omitted) — each repo carries its ownado_project:. Multi-repo product grouping within a per-repo org (e.g. Repo Wrangler) is expressed purely by repeating the sameado_project:string across the repos that share it — there is no separate "grouped" org-level flag.
Within a solution project, area paths reflect either the component repos or the internal work structure (Documentation, Pipelines, Testing, Automation). Cross-solution work is modeled with linked items across projects, never by sharing a project.
ADO project naming
- Solution project (app-solution org, or a product-grouped cluster inside a per-repo org) — the solution/product display name itself, in Title Case, no org prefix. Examples:
CloudSmith,ApiaryLens,Turner Legacy Platform,StoryLark,Repo Wrangler,Studio Foundry. - Independent per-repo project —
<Org/Group Display Name> — <Repo Display Name>(em dash, Title Case both sides). Examples:Azure Local — Ranger,This Is My Demo — Azure Scout.
Project names use human-readable Title-Case display names, not the raw repo slug. The whole live estate follows this — Azure Local — Ranger, never azurelocal-ranger.
Product-grouped clusters (Repo Wrangler, Studio Foundry) intentionally drop the org prefix even though their org (Hybrid Cloud Solutions) is per-repo, not app-solution — they're named for the product, not the org, matching solution-project naming.
Buildserver(also in that org) keeps its own project under the same bare-name convention since it has no sibling repo to group with.
TierPoint sub-categories
TierPoint's GitLab estate is organized into distinct engagement categories, so its per-repo projects carry a category token between the org name and the repo name:
| Category | Naming | Example |
|---|---|---|
| Lab environments | TierPoint — LABMGMT — <Env> | TierPoint — LABMGMT — AzureLocalCloud |
| Customer deployments | TierPoint — Customer — <Name> | TierPoint — Customer — Keller Construction |
| Proofs of concept | TierPoint — POC — <Name> | TierPoint — POC — Azure Local SAN Attach |
| Documentation / toolkits | TierPoint — ProdTech Docs (one project collecting all doc/toolkit repos) | — |
| Standalone 1:1 | TierPoint — <Repo> | TierPoint — Hyper-V as a Service |
The documentation/toolkit repos are the one sanctioned multi-repo TierPoint project — docs, azl-poc-toolkit, hyperv-poc-toolkit, poc-config-builder, and the two prodtech toolkits all share TierPoint — ProdTech Docs.
Azure Local is the only managed org that needed no renaming. Its projects already carried the
Azure Local <Repo>form before this standard was formalized, so the em-dash normalization and org-prefixing effort applied to This Is My Demo and TierPoint left Azure Local untouched.
Area paths
Each ADO project defines its own area paths. Common area paths:
| Area path | Use |
|---|---|
| Documentation | Docs, runbooks, READMEs |
| Pipelines | CI/CD, ADO pipeline changes |
| Automation | Scripts, tooling, scaffolding |
| Testing | Test coverage, Pester, drift audits |
| Standards | Standard definitions (platform repo only) |
| Infrastructure | IaC, Bicep, Terraform |
| Identity | Service principals, KV, PATs |
Define only the area paths a repo actually uses. Do not create placeholders.
Org / group classification
Locked with Kris 2026-07-14 (see pmo/ado-consolidation-and-github-issues-plan.md for the full change record). Each managed org or group is classified as app-solution (ado_model: solution, one project for the whole org, current and future repos alike) or per-repo (ado_model: per-repo/default — either one project per repo, or a handful of repos grouped by shared ado_project: within an otherwise per-repo org):
| Org / group | Classification | ADO project(s) |
|---|---|---|
| CloudSmith (cloudsmith-cloud) | App-solution (~57 repos) | CloudSmith |
| Turner Legacy (turnerlegacy) | App-solution (~12 repos) | Turner Legacy Platform |
| ApiaryLens | App-solution | ApiaryLens |
| Holdfast Press | App-solution (3 repos) | Holdfast Press |
| Gunner The Lab (gunnerthelab) | App-solution (3 repos) | Gunner The Lab |
| StoryLark | App-solution (5 repos) | StoryLark |
| Faithful Craftsmen, Heritage Community Hub, Project 42, Sunpath Dev | App-solution (one repo each today, future repos join automatically) | one project each — Faithful Craftsmen, Heritage Community Hub, Project 42, Sunpath Dev |
| Hybrid Cloud Solutions (hybrid-solutions-cloud) | Per-repo org, product-grouped | repo-wrangler+repo-wrangler-ops → Repo Wrangler; studio-foundry+my-studio-foundry → Studio Foundry; buildserver → Buildserver |
| Azure Local (AzureLocal) | Per-repo (~35 tools, independent) | one project per repo — Azure Local — <Repo> |
| This Is My Demo (thisismydemo) | Per-repo (independent demos/blog) | one project per repo — This Is My Demo — <Repo> |
| hybridsolutionscloud, iFarted Cloud | Per-repo (one repo each, trivially one project) | one project each |
| TierPoint (GitLab) | Per-repo, independent engagements | one project per repo, category-tokened — TierPoint — LABMGMT/Customer/POC — <Repo> (plus the shared TierPoint — ProdTech Docs) — untouched by the 2026-07-14 consolidation |
The authoritative repo → ADO project mapping lives in master-registry.db (ado_project: on each repo entry, ado_model: on each org entry). The full old-project → new-project mapping across the whole estate is maintained separately and tracked under AB#13, AB#14.
Work item strategy
Split source of truth, effective 2026-07-14 (superseded the earlier "ADO Boards only" rule):
- All work is tracked in ADO Boards using the Agile process; Epics → Features → User Stories → Tasks is the hierarchy
- Work items reference the repo they affect using
AB#<id>in commit messages and PR descriptions - GitHub is now the master for Issues / Bugs / Feature-Requests (public intake, remote-agent-workable) — see
work-item-sync.mdandgithub-issues.md. They mirror UP into ADO for rollup/reporting. - ADO stays the master for Epics / Features / User Stories / Tasks (the planning hierarchy above) — projected DOWN into GitHub as locked, bot-owned, read-only items so the roadmap is visible without being editable there.
- GitLab issues are acceptable for GitLab-hosted repos (TierPoint) where ADO integration is not set up — unchanged, out of scope for the GitHub split above.
Pipeline strategy
- All CI/CD pipelines are ADO Pipelines (YAML, stored in the repo)
- GitHub Actions is used only for open-source repos or repos that have no ADO project
- No mixed pipelines — a repo uses either ADO Pipelines or GitHub Actions, not both
- Pipeline YAML files live in
.ado/at the repo root
Variable groups
Every ADO project that has pipelines must have at least one KV-linked variable group. Naming: <project-short>-<env>-secrets.
Examples: platform-prd-secrets, azl-prd-secrets
See ado-variable-groups.md for the full registry.