Clone a private repository by using a customization file

You can use secrets from your Azure key vault in your YAML customizations to clone private repositories, or with any custom task you author that requires an access token. In a team customization file, you can use a personal access token (PAT) stored in a key vault to access a private repository.

Use key vault secrets in team customization files

To clone a private repository, store your PAT as a key vault secret. See Grant the managed identity access to the key vault secret, and use it when you invoke the git-clone task in your customization.

To configure your key vault secrets for use in your YAML customizations:

1. Ensure that your dev center project's managed identity has the Key Vault Reader role and the Key Vault Secrets User role on your key vault.
2. Grant the Key Vault Secrets User role for the key vault secret to each user or user group that should be able to consume the secret during the customization of a dev box. The user or group granted the role must include the managed identity for the dev center, the admin's user account, and any user or group that needs the secret during dev box customization.

For more information, see:

• Configure a managed identity for a dev center
• Grant the managed identity access to the key vault secret

You can reference the secret in your YAML customization in the following format, which uses the git-clone task as an example:

$schema: "1.0"
tasks:
  - name: git-clone
    description: Clone this repository into C:\Workspaces
    parameters:
      repositoryUrl: https://myazdo.visualstudio.com/MyProject/_git/myrepo
      directory: C:\Workspaces
      pat: '{{KEY_VAULT_SECRET_URI}}'

Use key vault secrets in individual customization files

To clone a private Azure Repos repository from an individual customization file, you don't need to configure a secret in Azure Key Vault. If you want to clone a private Azure Repos repository from an individual customization file, you don't need to configure a secret in Azure Key Vault. Instead, you can use {{ado}} or {{ado://your-ado-organization-name}} as a parameter. This parameter fetches an access token on your behalf when you're creating a dev box. The access token has read-only permission to your repository.

The git-clone task in the quickstart catalog uses the access token to clone your repository. Here's an example:

tasks:
  - name: git-clone
    description: Clone this repository into C:\Workspaces
    parameters:
      repositoryUrl: https://myazdo.visualstudio.com/MyProject/_git/myrepo
      directory: C:\Workspaces
      pat: '{{ado://YOUR_ADO_ORG}}'

The dev center needs access to your key vault. Dev centers don't support service tags, so if your key vault is private, allow trusted Microsoft services to bypass the firewall.

Dev centers don't support service tags, so if the key vault is private, allow trusted Microsoft services to bypass the firewall.

To learn how to allow trusted Microsoft services to bypass the firewall, see Configure Azure Key Vault networking settings.

Share a customization file from a code repository

Make the customization file available to dev box pools by naming it imagedefinition.yaml and uploading it to the repository that hosts the catalog. When you create a dev box pool, you can select the customization file from the catalog to apply to the dev boxes in the pool.

Related content

• Microsoft Dev Box team customizations
• Configure imaging for Dev Box team customizations
• Add and configure a catalog from GitHub or Azure Repos