Edit

Add and configure a catalog from GitHub or Azure DevOps

  • Article

Learn how to add and configure a catalog in your Azure Deployment Environments dev center. You can use a catalog to provide your development teams with a curated set of infrastructure as code (IaC) templates called environment definitions. Your catalog is encrypted; Azure Deployment Environments supports encryption at rest with platform-managed encryption keys, which are managed by Microsoft for Azure Services.

For more information about environment definitions, see Add and configure an environment definition.

A catalog is a repository that's hosted in GitHub or Azure DevOps.

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 environment definitions in the sample catalog.

In this article, you learn how to:

  • Add a catalog.
  • Update a catalog.
  • Delete a catalog.

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

  1. Go to the home page of the GitHub repository that contains the template definitions.
  2. Get the GitHub repo clone URL.
  3. Copy and save the URL. You use it later.

Get the clone URL of an Azure DevOps repository

  1. Go to the home page of your team collection (for example, https://contoso-web-team.visualstudio.com), and then select your project.
  2. Get the Git repo clone URL.
  3. 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

  1. Go to the home page of the GitHub repository that contains the template definitions.

  2. In the upper-right corner of GitHub, select the profile image, and then select Settings.

  3. On the left sidebar, select Developer settings > Personal access tokens > Fine-grained tokens.

  4. Select Generate new token.

  5. On the New fine-grained personal access token page, provide the following information:

    Name Value
    Token name Enter a descriptive name for the token.
    Expiration Select the token expiration period in days.
    Description Enter a description for the token.
    Repository access Select Public Repositories (read-only).

    Leave the other options at their defaults.

  6. Select Generate token.

  7. Save the generated token. You use the token later.

Create a personal access token in Azure DevOps

  1. Go to the home page of your team collection (for example, https://contoso-web-team.visualstudio.com) and select your project.
  2. Create a personal access token.
  3. Save the generated token. You use the token later.

Store the personal access token as a key vault secret

Store the personal access token that you generated as a key vault secret and copy the secret identifier:

Create a Key Vault

You need an Azure Key Vault to store the GitHub personal access token (PAT) that is used to grant Azure access to your GitHub repository. Key Vaults can control access with either access policies or role-based access control (RBAC). If you have an existing key vault, you can use it, but you should check whether it uses access policies or RBAC assignments to control access. For help with configuring an access policy for a key vault, see Assign a Key Vault access policy.

Use the following steps to create an RBAC key vault:

  1. Sign in to the Azure portal.

  2. In the Search box, enter Key Vault.

  3. From the results list, select Key Vault.

  4. On the Key Vault page, select Create.

  5. On the Create key vault tab, provide the following information:

    Name Value
    Name Enter a name for the key vault.
    Subscription Select the subscription in which you want to create the key vault.
    Resource group Either use an existing resource group or select Create new and enter a name for the resource group.
    Location Select the location or region where you want to create the key vault.

    Leave the other options at their defaults.

  6. On the Access policy tab, select Azure role-based access control, and then select Review + create.

  7. On the Review + create tab, select Create.

Store the personal access token in the key vault

  1. In the Key Vault, on the left menu, select Secrets.
  2. On the Secrets page, select Generate/Import.
  3. On the Create a secret page:
    • In the Name box, enter a descriptive name for your secret.
    • In the Secret value box, paste the GitHub secret.
    • Select Create.

Get the secret identifier

Get the path to the secret you created in the key vault.

  1. In the Azure portal, navigate to your key vault.
  2. On the key vault page, from the left menu, select Secrets.
  3. On the Secrets page, select the secret you created earlier.
  4. On the versions page, select the CURRENT VERSION.
  5. On the current version page, for the Secret identifier, select copy.

Add your repository as a catalog

  1. In the Azure portal, go to your dev center.

  2. 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.

  3. In the left menu under Environment configuration, select Catalogs, and then select Add.

  4. In 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 environment definitions.
    The folder path is for the folder with subfolders containing environment definition manifests, not for the folder with the environment definition manifest itself. The following image shows the sample catalog folder structure.
    Sample catalog example: /Environments
    Screenshot showing Environments sample folder in GitHub. 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

    Screenshot that shows how to add a catalog to a dev center.

  5. In 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 environment definitions to your development teams by syncing the catalog.

To sync an updated catalog:

  1. On the left menu for your dev center, under Environment configuration, select Catalogs,
  2. Select the specific catalog, and then select Sync. The service scans through the repository and makes the latest list of environment definitions 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 environment definition reference for any existing environments that were created by using the environment definitions in the deleted catalog. If the reference isn't updated and the environment is redeployed, the deployment fails.

To delete a catalog:

  1. On the left menu for your dev center, under Environment configuration, select Catalogs.
  2. Select the specific catalog, and then select Delete.
  3. 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 environment definitions have errors. Use the Azure CLI or the REST API to GET the catalog. The GET response shows you the type of errors:

  • Ignored environment definitions that were detected to be duplicates.
  • Invalid environment definitions that failed due to schema, reference, or validation errors.

Resolve ignored environment definition errors

An ignored environment definition error occurs if you add two or more environment definitions that have the same name. You can resolve this issue by renaming environment definitions so that each environment definition has a unique name within the catalog.

Resolve invalid environment definition errors

An invalid environment definition error might occur for various reasons:

  • Manifest schema errors. Ensure that your environment definition 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 environment definition name is between 3 and 63 characters.
    • Ensure that the environment definition name includes only characters that are valid for a URL, which are alphanumeric characters and these symbols: ~ ! , . ' ; : = - _ + ( ) * & $ @

  • Reference errors. Ensure that the template path that the manifest references is a valid relative path to a file in the repository.

Next steps