Add and configure a catalog
Learn how to add and configure a catalog in your Azure Deployment Environments Preview dev center. You can use a catalog to provide your development teams with a curated set of infrastructure as code (IaC) templates called catalog items.
For more information about catalog items, see Add and configure a catalog item.
A catalog is a repository that's hosted in GitHub or Azure DevOps.
- To learn how to host a repository in GitHub, see Get started with GitHub.
- To learn how to host a Git repository in an Azure DevOps project, see Azure Repos.
We offer a sample catalog that you can use as your repository. You also can use your own private repository, or you can fork and customize the catalog items in the sample catalog.
In this article, you learn how to:
- Add a catalog.
- Update a catalog.
- Delete a catalog.
Important
Azure Deployment Environments currently is in preview. For legal terms that apply to Azure features that are in beta, in preview, or otherwise are not yet released into general availability, see the Supplemental Terms of Use for Microsoft Azure Previews.
Add a catalog
To add a catalog, you complete these tasks:
- Get the clone URL for your repository.
- Create a personal access token.
- Store the personal access token as a key vault secret in Azure Key Vault.
- Add your repository as a catalog.
Get the clone URL for your repository
You can choose from two types of repositories:
- A GitHub repository
- An Azure DevOps repository
Get the clone URL of a GitHub repository
- Go to the home page of the GitHub repository that contains the template definitions.
- Get the GitHub repo clone URL.
- Copy and save the URL. You use it later.
Get the clone URL of an Azure DevOps repository
- Go to the home page of your team collection (for example,
https://contoso-web-team.visualstudio.com
), and then select your project. - Get the Git repo clone URL.
- Copy and save the URL. You use it later.
Create a personal access token
Next, create a personal access token. Depending on the type of repository you use, create a personal access token either in GitHub or in Azure DevOps.
Create a personal access token in GitHub
- Go to the home page of the GitHub repository that contains the template definitions.
- In the upper-right corner of GitHub, select the profile image, and then select Settings.
- On the left sidebar, select Developer settings > Personal access tokens.
- Select Generate new token.
- On New personal access token, in Note, enter a description for your token.
- In the Expiration dropdown, select an expiration for your token.
- For a private repository, under Select scopes, select the repo scope.
- Select Generate token.
- Save the generated token. You use the token later.
Create a personal access token in Azure DevOps
- Go to the home page of your team collection (for example,
https://contoso-web-team.visualstudio.com
) and select your project. - Create a personal access token.
- Save the generated token. You use the token later.
Store the personal access token as a key vault secret
To store the personal access token that you generated as a key vault secret and copy the secret identifier:
- Create a key vault.
- Add the personal access token as a secret to the key vault.
- Open the secret and copy the secret identifier.
Add your repository as a catalog
In the Azure portal, go to your dev center.
Ensure that the identity that's attached to the dev center has access to the key vault secret where your personal access token is stored.
On the left menu under Environment configuration, select Catalogs, and then select Add.
On Add catalog, enter the following information, and then select Add:
Field Value Name Enter a name for the catalog. Git clone URI Enter or paste the clone URL for either your GitHub repository or your Azure DevOps repository.
Sample catalog example:https://github.com/Azure/deployment-environments.git
Branch Enter the repository branch to connect to.
Sample catalog example:main
Folder path Enter the folder path relative to the clone URI that contains subfolders that hold your catalog items.
This folder path should be the path to the folder that contains the subfolders that have the catalog item manifests, and not the path to the folder that has the catalog item manifest itself.
Sample catalog example:/Environments
The folder path can begin with or without a forward slash (/
).Secret identifier Enter the secret identifier that contains your personal access token for the repository.
When you copy a secret identifier, the connection string includes a version identifier at the end, like in this example:https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat/9376b432b72441a1b9e795695708ea5a
.
Removing the version identifier ensures that Deployment Environments fetches the latest version of the secret from the key vault. If your personal access token expires, only the key vault needs to be updated.
Example secret identifier:https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat
On Catalogs for the dev center, verify that your catalog appears. If the connection is successful, Status is Connected.
Update a catalog
If you update the Azure Resource Manager template (ARM template) contents or definition in the attached repository, you can provide the latest set of catalog items to your development teams by syncing the catalog.
To sync an updated catalog:
- On the left menu for your dev center, under Environment configuration, select Catalogs,
- Select the specific catalog, and then select Sync. The service scans through the repository and makes the latest list of catalog items available to all the associated projects in the dev center.
Delete a catalog
You can delete a catalog to remove it from the dev center. Templates in a deleted catalog aren't available to development teams when they deploy new environments. Update the catalog item reference for any existing environments that were created by using the catalog items in the deleted catalog. If the reference isn't updated and the environment is redeployed, the deployment fails.
To delete a catalog:
- On the left menu for your dev center, under Environment configuration, select Catalogs.
- Select the specific catalog, and then select Delete.
- In the Delete catalog dialog, select Continue to delete the catalog.
Catalog sync errors
When you add or sync a catalog, you might encounter a sync error. A sync error indicates that some or all the catalog items have errors. Use the Azure CLI or the REST API to GET the catalog. The GET response shows you the type of errors:
- Ignored catalog items that were detected to be duplicates.
- Invalid catalog items that failed due to schema, reference, or validation errors.
Resolve ignored catalog item errors
An ignored catalog item error occurs if you add two or more catalog items that have the same name. You can resolve this issue by renaming catalog items so that each catalog item has a unique name within the catalog.
Resolve invalid catalog item errors
An invalid catalog item error might occur for various reasons:
Manifest schema errors. Ensure that your catalog item manifest matches the required schema.
Validation errors. Check the following items to resolve validation errors:
- Ensure that the manifest's engine type is correctly configured as
ARM
. - Ensure that the catalog item name is between 3 and 63 characters.
- Ensure that the catalog item name includes only characters that are valid for a URL, which are alphanumeric characters and these symbols:
~
!
,
.
'
;
:
=
-
_
+
(
)
*
&
$
@
- Ensure that the manifest's engine type is correctly configured as
Reference errors. Ensure that the template path that the manifest references is a valid relative path to a file in the repository.
Next steps
- Learn how to create and configure a project.
- Learn how to create and configure a project environment type.
Feedback
Submit and view feedback for