From 96225898e64a14926e104a54bacc887cbda9543b Mon Sep 17 00:00:00 2001
From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com>
Date: Tue, 24 Dec 2024 22:24:16 +0000
Subject: [PATCH] clarify ado behavior (#6705)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

this pr clarifies that for ado, private packages have to be configured
using the `org/repo` path.

more details in internal slack:
https://dbt-labs.slack.com/archives/C07C793M6EB/p1734715084356599?thread_ts=1734359013.848149&cid=C07C793M6EB

<!-- vercel-deployment-preview -->
---
🚀 Deployment available! Here are the direct links to the updated files:


-
https://docs-getdbt-com-git-mirnawong1-patch-28-dbt-labs.vercel.app/docs/build/packages

<!-- end-vercel-deployment-preview -->

---------

Co-authored-by: Leona B. Campbell <3880403+runleonarun@users.noreply.github.com>
---
 website/docs/docs/build/packages.md | 35 +++++++++++++++++++++--------
 1 file changed, 26 insertions(+), 9 deletions(-)

diff --git a/website/docs/docs/build/packages.md b/website/docs/docs/build/packages.md
index 7a2c08d3e70..5ee619989bc 100644
--- a/website/docs/docs/build/packages.md
+++ b/website/docs/docs/build/packages.md
@@ -165,27 +165,44 @@ dbt Cloud supports private packages from [supported](#prerequisites) Git repos l
 
 #### Prerequisites
 
-To use native private packages, you must have one of the following Git providers configured in the **Integrations** section of your **Account settings**:
-- [GitHub](/docs/cloud/git/connect-github)
-- [Azure DevOps](/docs/cloud/git/connect-azure-devops)
-- Support for GitLab is coming soon.
-
+- To use native private packages, you must have one of the following Git providers configured in the **Integrations** section of your **Account settings**:
+  - [GitHub](/docs/cloud/git/connect-github)
+  - [Azure DevOps](/docs/cloud/git/connect-azure-devops)
+    - Private packages only work within a single Azure DevOps project. If your repositories are in different projects within the same organization, you can't reference them in the `private` key at this time.
+    - For Azure DevOps, use the `org/repo` path (not the `org_name/project_name/repo_name` path) with the project tier inherited from the integrated source repository.
+  - Support for GitLab is coming soon.
 
 #### Configuration
 
-Use the `private` key in your `packages.yml` or `dependencies.yml` to clone package repos using your existing dbt Cloud Git integration without having to provision an access token or create a dbt Cloud environment variable:
+Use the `private` key in your `packages.yml` or `dependencies.yml` to clone package repos using your existing dbt Cloud Git integration without having to provision an access token or create a dbt Cloud environment variable. 
+
 
 <File name="packages.yml">
 
 ```yaml
 packages:
-  - private: dbt-labs/awesome_repo
+  - private: dbt-labs/awesome_repo # your-org/your-repo path
   - package: normal packages
-
-	[...]
+  [...]
 ```
+</File>
+
+:::tip Azure DevOps considerations
+
+- Private packages currently only work if the package repository is in the same Azure DevOps project as the source repo.
+- Use the `org/repo` path (not the normal ADO `org_name/project_name/repo_name` path) in the `private` key. 
+- Repositories in different Azure DevOps projects is currently not supported until a future update.
 
+You can use private packages by specifying `org/repo` in the `private` key:
+
+<File name="packages.yml">
+
+```yaml
+packages:
+  - private: my-org/my-repo # Works if your ADO source repo and package repo are in the same project
+```
 </File>
+:::
 
 You can pin private packages similar to regular dbt packages: