From 9a72ae560e84ee736683654dde98734ad32b1258 Mon Sep 17 00:00:00 2001 From: Gianluigi Liguori Date: Thu, 22 Feb 2024 14:56:47 +0100 Subject: [PATCH 1/5] Document usage of TenantID and Clone without PAT --- src/external-repository/NOTES.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/src/external-repository/NOTES.md b/src/external-repository/NOTES.md index 06d4e9b..0e0f242 100644 --- a/src/external-repository/NOTES.md +++ b/src/external-repository/NOTES.md @@ -15,6 +15,18 @@ process. It is always possible to provide a token via the `userSecret` and this is what works with other Git hosting providers. +#### Microsoft Entra ID Tenant Configuration +The authentication happens on the common tenant. If the user is present on multiple tenant and the Azure DevOps organization for the reposiotory belongs to a specific one the repo opearations may fail (unauthorized). You can configure the tenant for the authenthication by providing it as setting customization to the the underlying extension, following an example: +```json +"customizations": { + "vscode":{ + "settings": { + "adoCodespacesAuth.tenantID": "", + } + } +} +``` + ## Example Usage Scenarios Here is a minimal example that clones an Azure DevOps repository. This would also require @@ -54,6 +66,23 @@ If a user configures a Codespaces User Secret named `ADO_SECRET` and assigns thi Codespace, then the value of that secret will be used as a PAT for authentication. If the secret is not defined by the user it will fallback to the browser login. +### Interactive authentication only (avoids PAT token) +The advantage of using a PAT token is the ability to clone the repository during the devContainer creation (onCreateCommand). You can avoid to configure any secret by requiring the authentication once the Codespace load it means that the repository will be cloned when the Codespaces UI initielizes completely. Following a configuration example for this scenario: +```json +{ +"image": "mcr.microsoft.com/devcontainers/universal:ubuntu", +"features": { + "ghcr.io/microsoft/codespace-features/external-repository:latest": { + "cloneUrl": "https://dev.azure.com/contoso/_git/reposname", + "folder": "/workspaces/ado-repos" + } +}, +"workspaceFolder": "/workspaces/ado-repos", +"initializeCommand": "mkdir -p ${localWorkspaceFolder}/../ado-repos", +"postStartCommand": "external-git clone && external-git config" +} +``` + ## Multiple Repository Support As of version 3, you can clone multiple repositories by separating the URL's with a comma. In this From 5d07cbe950e73a59b346b9e07b69bbea0c76d6e0 Mon Sep 17 00:00:00 2001 From: Mark Phippard Date: Thu, 22 Feb 2024 09:33:19 -0500 Subject: [PATCH 2/5] Update NOTES.md Fix typos and clean up wording a bit --- src/external-repository/NOTES.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/src/external-repository/NOTES.md b/src/external-repository/NOTES.md index 0e0f242..4eca693 100644 --- a/src/external-repository/NOTES.md +++ b/src/external-repository/NOTES.md @@ -16,7 +16,12 @@ It is always possible to provide a token via the `userSecret` and this is what w other Git hosting providers. #### Microsoft Entra ID Tenant Configuration -The authentication happens on the common tenant. If the user is present on multiple tenant and the Azure DevOps organization for the reposiotory belongs to a specific one the repo opearations may fail (unauthorized). You can configure the tenant for the authenthication by providing it as setting customization to the the underlying extension, following an example: + +The authentication to Azure DevOps happens on the default tenant. If the user is present on +multiple tenants, and the Azure DevOps organization for the reposiotory belongs to a specific +one, the repository operations may fail (unauthorized). You can configure the tenant for +the authentication by providing it as setting to the the underlying extension in your devcontainer.json: + ```json "customizations": { "vscode":{ @@ -67,7 +72,11 @@ Codespace, then the value of that secret will be used as a PAT for authenticatio is not defined by the user it will fallback to the browser login. ### Interactive authentication only (avoids PAT token) -The advantage of using a PAT token is the ability to clone the repository during the devContainer creation (onCreateCommand). You can avoid to configure any secret by requiring the authentication once the Codespace load it means that the repository will be cloned when the Codespaces UI initielizes completely. Following a configuration example for this scenario: + +The advantage of using a PAT token is the ability to clone the repository during the devContainer creation +(onCreateCommand). You can avoid the need to configure a secret by requiring the authentication once the +Codespace loads. This means the repository will be cloned only after the Codespaces UI initializes completely: + ```json { "image": "mcr.microsoft.com/devcontainers/universal:ubuntu", From 58f40144bb491b28e1ae60562a6e33b4edc64dc9 Mon Sep 17 00:00:00 2001 From: Mark Phippard Date: Thu, 22 Feb 2024 09:35:52 -0500 Subject: [PATCH 3/5] Update NOTES.md Fixed a couple more spelling errors --- src/external-repository/NOTES.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/external-repository/NOTES.md b/src/external-repository/NOTES.md index 4eca693..69b1d6b 100644 --- a/src/external-repository/NOTES.md +++ b/src/external-repository/NOTES.md @@ -1,4 +1,4 @@ -This feature standardizes and simplifies the proces of setting up a Codespace +This feature standardizes and simplifies the process of setting up a Codespace to work with an external repository -- meaning a Git repository other than the one that defines your Codespace. This is being primarily developed to support Azure DevOps repositories but it ought to work with any Git repository. @@ -18,7 +18,7 @@ other Git hosting providers. #### Microsoft Entra ID Tenant Configuration The authentication to Azure DevOps happens on the default tenant. If the user is present on -multiple tenants, and the Azure DevOps organization for the reposiotory belongs to a specific +multiple tenants, and the Azure DevOps organization for the repository belongs to a specific one, the repository operations may fail (unauthorized). You can configure the tenant for the authentication by providing it as setting to the the underlying extension in your devcontainer.json: @@ -56,7 +56,7 @@ that the token only have this scope. } ``` -This would clone the repository to `/workspaces/ado-repos` during the Prebuild process +This would clone the repository to `/workspaces/ado-repos` during the Prebuild s using the PAT stored in a Codespaces secret. At runtime, when a user opens the Codespace the `workspaceFolder` feature would open VS Code to this folder automatically and it would be configured to prompt the user to login to Azure DevOps when they open the Codespace. @@ -103,12 +103,12 @@ last part of the clone URL so this value has to be unique for each repository sp When `external-git config` is executed it will check the branch name of the Codespaces bridge repository and if it begins with "azdo/" then it will treat the rest of the branch name as an AzDO branch name to checkout on the external repository. The idea here is that a utility could be created in AzDO that -would let you open a Pull Request in a Codespace. The process would create a new branch in the bridge +would let you open a Pull Request in a Codespace. The s would create a new branch in the bridge repository named "azdo/branch/name" and then create the Codespace on that branch name. When the Codespace opens and clones the AzDO repository default branch it will then detect the need to fetch and checkout the requested branch. -If a different process is desired for determining the branch name, then an environment variabled named +If a different s is desired for determining the branch name, then an environment variabled named `AZDO_BRANCH` can be created with the name of the branch that should be checked out. When the `external-git config` command runs it will also detect that this envvar is set and checkout that From 19605f6c24f2bfefb6a488173466322790d9d2c6 Mon Sep 17 00:00:00 2001 From: Mark Phippard Date: Thu, 22 Feb 2024 09:36:40 -0500 Subject: [PATCH 4/5] Update NOTES.md --- src/external-repository/NOTES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/external-repository/NOTES.md b/src/external-repository/NOTES.md index 69b1d6b..732d8c2 100644 --- a/src/external-repository/NOTES.md +++ b/src/external-repository/NOTES.md @@ -56,7 +56,7 @@ that the token only have this scope. } ``` -This would clone the repository to `/workspaces/ado-repos` during the Prebuild s +This would clone the repository to `/workspaces/ado-repos` during the Prebuild process using the PAT stored in a Codespaces secret. At runtime, when a user opens the Codespace the `workspaceFolder` feature would open VS Code to this folder automatically and it would be configured to prompt the user to login to Azure DevOps when they open the Codespace. From 26723585a13e68f3b9832d37c037a1f6b1c35780 Mon Sep 17 00:00:00 2001 From: Mark Phippard Date: Thu, 22 Feb 2024 09:37:21 -0500 Subject: [PATCH 5/5] Update NOTES.md --- src/external-repository/NOTES.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/external-repository/NOTES.md b/src/external-repository/NOTES.md index 732d8c2..4bfbb29 100644 --- a/src/external-repository/NOTES.md +++ b/src/external-repository/NOTES.md @@ -103,12 +103,12 @@ last part of the clone URL so this value has to be unique for each repository sp When `external-git config` is executed it will check the branch name of the Codespaces bridge repository and if it begins with "azdo/" then it will treat the rest of the branch name as an AzDO branch name to checkout on the external repository. The idea here is that a utility could be created in AzDO that -would let you open a Pull Request in a Codespace. The s would create a new branch in the bridge +would let you open a Pull Request in a Codespace. The process would create a new branch in the bridge repository named "azdo/branch/name" and then create the Codespace on that branch name. When the Codespace opens and clones the AzDO repository default branch it will then detect the need to fetch and checkout the requested branch. -If a different s is desired for determining the branch name, then an environment variabled named +If a different process is desired for determining the branch name, then an environment variabled named `AZDO_BRANCH` can be created with the name of the branch that should be checked out. When the `external-git config` command runs it will also detect that this envvar is set and checkout that