Adicionar e configurar um catálogo do GitHub ou do Azure Repos

Este guia explica como adicionar e configurar um catálogo no centro de desenvolvimento dos Ambientes de Implantação Azure. Um catálogo é um repositório hospedado no GitHub ou no Azure DevOps.

Você pode usar um catálogo para fornecer às suas equipes de desenvolvimento um conjunto de modelos de infraestrutura como código (IaC) selecionados chamados de definições de ambiente.

Os Ambientes de Implantação dão suporte a catálogos hospedados no Azure Repos (o serviço de repositório no Azure, comumente conhecido como Azure DevOps) e catálogos hospedados no GitHub. O Azure Repos dá suporte à autenticação atribuindo permissões a uma identidade gerenciada. O Azure Repos e o GitHub dão suporte ao uso de um token de acesso pessoal (PAT) para autenticação. Para proteger ainda mais os seus modelos, o catálogo é criptografado; os Ambientes de Implantação Azure dão suporte à criptografia em repouso com chaves de criptografia gerenciadas pela plataforma, gerenciadas pela Microsoft para Serviços do Azure.

• Para saber como hospedar um repositório no GitHub, confira Introdução ao GitHub.
• Para saber como hospedar um repositório do Git em um projeto do Azure Repos, confira Azure Repos.

A Microsoft oferece um catálogo de início rápido que você pode adicionar ao centro de desenvolvimento e um catálogo de exemplo que você pode usar como o seu repositório. Você também pode usar seu próprio repositório privado ou pode bifurcar e personalizar as definições de ambiente no catálogo de exemplo.

Configurar uma identidade gerenciada para o centro de desenvolvimento

Depois de criar um centro de desenvolvimento, antes de anexar um catálogo, você deve configurar uma identidade gerenciada, também chamada de MSI (identidade de serviço gerenciado), para o centro de desenvolvimento. Você pode anexar uma identidade gerenciada atribuída pelo sistema (MSI atribuída pelo sistema) ou uma identidade gerenciada atribuída pelo usuário (MSI atribuída pelo usuário). Em seguida, você atribui funções à identidade gerenciada para permitir que o centro de desenvolvimento crie tipos de ambiente em sua assinatura e leia o projeto do Azure Repos que contém o repositório de catálogo.

Se o centro de desenvolvimento não tiver uma MSI anexada, siga as etapas em Configurar uma identidade gerenciada para criar uma e atribuir funções para a identidade gerenciada do centro de desenvolvimento.

Para saber mais sobre identidades gerenciadas, confira O que são identidades gerenciadas para recursos do Azure?

Adicionar um catálogo

Você pode adicionar um catálogo de um repositório do Azure Repos ou de um repositório do GitHub. Você pode optar por autenticar-se atribuindo permissões a uma MSI ou usando um PAT, que você armazena em um cofre de chaves.

Selecione a guia para o tipo de repositório e autenticação que você deseja usar.

Repositório do Azure Repos com MSI

Para adicionar um catálogo, conclua as seguintes tarefas:

• Atribua permissões no Azure Repos para a identidade gerenciada do centro de desenvolvimento.
• Adicione o repositório como um catálogo.

Atribuir permissões no Azure Repos para a identidade gerenciada do centro de desenvolvimento

Você deve conceder permissões à identidade gerenciada do centro de desenvolvimento ao repositório no Azure Repos.

1. Entre na sua organização do Azure DevOps.

   Observação

   Sua organização do Azure DevOps deve estar no mesmo diretório que a assinatura do Azure que contém o centro de desenvolvimento.

2. Selecione Configurações da organização.

   

3. Na página Visão Geral, selecione Usuários.

   

4. Na página Usuários, selecione Adicionar usuários.

   

5. Conclua Adicionar novos usuários inserindo ou selecionando as seguintes informações e, em seguida, selecione Adicionar:

   Nome	Valor
   Usuários ou entidades de serviço	Insira o nome do centro de desenvolvimento. Quando você usa uma MSI atribuída pelo sistema, especifique o nome do centro de desenvolvimento, não a ID do objeto da conta gerenciada. Ao usar uma MSI atribuída pelo usuário, use o nome da conta gerenciada.
   Nível de acesso	Selecione Basic.
   Adicionar aos projetos	Selecione o projeto que contém o repositório.
   Grupos de DevOps do Azure	Selecione Leitores de projeto.
   Enviar convites por email (somente para usuários)	Desmarque a caixa de seleção.

   

Adicionar o repositório como um catálogo

Os Ambientes de Implantação Azure dão suporte à anexação de repositórios do Azure Repos e de repositórios do GitHub. Você pode armazenar um conjunto de modelos de IaC coletados em um repositório. A anexação do repositório a um centro de desenvolvimento como um catálogo fornece às equipes de desenvolvimento acesso aos modelos e permite que elas criem ambientes consistentes com agilidade.

As etapas a seguir permitem anexar um repositório do Azure Repos.

1. No portal do Azure, navegue até o centro de desenvolvimento.

2. No menu esquerdo, em Configuração do ambiente, selecione Catálogos e, em seguida, selecione Adicionar.

   

3. No painel Adicionar catálogo, insira as informações a seguir e clique em Adicionar:

   Campo	Valor
   Nome	Insira um nome para o catálogo.
   Localização do catálogo	Escolha Azure DevOps.
   Tipo de autenticação	Selecione Identidade Gerenciada.
   Organização	Selecione sua organização do Azure DevOps.
   Projeto	Na lista de projetos, selecione o projeto que armazena o repositório.
   Repo	Na lista de repositórios, selecione o repositório que você deseja adicionar.
   Branch	Selecione o branch.
   Caminho da pasta	O Computador de desenvolvimento recupera uma lista de pastas em seu branch. Selecione a pasta que armazena seus modelos de IaC.

   

4. Verifique se o catálogo aparece em Catálogos no centro de desenvolvimento. Quando a conexão é bem-sucedida, o Status exibe Sincronização bem-sucedida. Conectar a um catálogo pode levar alguns minutos na primeira vez.

Repositório do Azure Repos com PAT

Para adicionar um catálogo, conclua as seguintes tarefas:

• Obtenha a URL de clonagem para o seu repositório do Azure Repos.
• Crie um token de acesso pessoal (PAT).
• Armazene o PAT como um segredo do cofre de chaves no Azure Key Vault.
• Adicione o repositório como um catálogo.

Obter a URL de clonagem para o seu repositório do Azure Repos

1. Acesse a página inicial de sua coleção de equipe (por exemplo, https://contoso-web-team.visualstudio.com) e selecione o projeto.

2. Obtenha a URL de clone do repositório Git do Azure Repos.

3. Copie e salve a URL.

Criar um token de acesso pessoal no Azure Repos

1. Acesse a página inicial da coleção da equipe (por exemplo, https://contoso-web-team.visualstudio.com) e selecione o projeto.

2. Crie um PAT.

3. Copie e salve o token gerado para usá-lo posteriormente.

Criar um cofre de chaves

Você precisa de um Azure Key Vault para armazenar o PAT usado para conceder acesso ao seu repositório para o Azure. Os cofres de chaves podem controlar o acesso com políticas de acesso ou controle de acesso baseado em função (RBAC). Se você tiver um cofre de chaves existente, poderá usá-lo, mas deverá verificar se ele usa políticas de acesso ou atribuições RBAC para controlar o acesso. Para obter ajuda sobre como configurar uma política de acesso para um cofre de chaves, consulte Atribuir uma política de acesso ao Cofre de Chaves.

Use as seguintes etapas para criar um cofre de chaves RBAC:

1. Entre no portal do Azure.

2. Digite Key Vault na caixa Pesquisar.

3. Na lista de resultados, selecione Key Vault.

4. Na página Key Vault, selecione Criar.

5. Na guia Criar cofre de chaves, forneça as seguintes informações:

   Nome	Valor
   Nome	Insira um nome para o cofre de chaves.
   Assinatura	Selecione a assinatura na qual deseja criar o cofre de chaves.
   Grupo de recursos	Use um grupo de recursos existente ou selecione Criar e insira um nome para o grupo de recursos.
   Localidade	Escolha a localização ou a região em que deseja criar o cofre de chaves.

   Mantenha as outras opções com os respectivos padrões.

6. Na guia Política de acesso, selecione Controle de acesso baseado em função do Azure e selecione Examinar + criar.

7. Na guia Revisar + criar, selecione Criar.

Armazenar token de acesso pessoal no cofre de chaves

1. No Key Vault, no menu à esquerda, selecione Segredos.

2. Na página Segredos, selecione Gerar/Importar.

3. Na página Criar um segredo:

   • Na caixa Nome, insira um nome descritivo para o segredo.
   • Na caixa de Valor do segredo, cole o PAT que você copiou anteriormente.
   • Selecione Criar.

Obter identificador do segredo

Obtenha o caminho para o segredo criado no cofre de chaves.

1. No portal do Azure, navegue até o cofre de chaves.

2. Na página do cofre de chaves, no menu à esquerda, selecione Segredos.

3. Na página Segredos, selecione o segredo que você criou anteriormente.

4. Na página de versões, selecione a VERSÃO ATUAL.

5. Na página da versão atual, em Identificador de segredo, selecione Copiar.

Adicionar o repositório como um catálogo

1. No portal do Azure, acesse o centro de desenvolvimento.

2. Certifique-se de que a identidade anexada ao centro de desenvolvimento tenha acesso ao segredo do cofre de chaves em que o token de acesso pessoal está armazenado.

3. No menu esquerdo, em Configuração do ambiente, selecione Catálogos e, em seguida, selecione Adicionar.

4. No painel Adicionar catálogo, insira as informações a seguir e clique em Adicionar:

   Campo	Valor
   Nome	Insira um nome para o catálogo.
   Localização do catálogo	Escolha Azure DevOps.
   Tipo de autenticação	Selecione Token de acesso pessoal.
   Organização	Selecione a organização que hospeda o repositório de catálogo.
   Projeto	Selecione o projeto que armazena o repositório de catálogo.
   Rep	Selecione o repositório que armazena o catálogo.
   Caminho da pasta	Selecione a pasta que contém seus modelos de IaC.
   Identificador do segredo	Insira o identificador de segredo que contém o seu PAT para o repositório. Ao copiar um identificador secreto, a cadeia de conexão incluirá um identificador de versão no final, como neste exemplo: https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat/9376b432b72441a1b9e795695708ea5a. A remoção do identificador de versão faz com que os Ambientes de Implantação busquem a versão mais recente do segredo do cofre de chaves. Se o PAT expirar, apenas o cofre de chaves precisará ser atualizado. Exemplo de identificador secreto:https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat

   

5. Verifique se o catálogo aparece em Catálogos no centro de desenvolvimento. Se a conexão for bem-sucedida, o Status será Conectado.

Repositório do GitHub no aplicativo do DevCenter

Para adicionar um catálogo, conclua as seguintes tarefas:

1. Instalar e configurar o aplicativo do Centro de Desenvolvimento da Microsoft
2. Atribua permissões no GitHub para os repositórios.
3. Adicione o repositório como um catálogo.

Instalar o aplicativo do Centro de Desenvolvimento da Microsoft

1. Entre no portal do Azure.

2. Navegue até o centro de desenvolvimento.

3. No menu esquerdo, em Configuração do ambiente, selecione Catálogos e, em seguida, selecione Adicionar.

4. No painel Adicionar catálogo, insira ou selecione o seguinte:

   Campo	Valor
   Nome	Insira um nome para o catálogo.
   Origem do catálogo	Selecione GitHub.
   Tipo de autenticação	Selecione o aplicativo GitHub.

5. Para instalar o aplicativo do Centro de Desenvolvimento da Microsoft, selecione configurar seus repositórios.

   

6. Se for solicitado que você se autentique no GitHub, faça isso.

7. Na página Microsoft DevCenter, selecione Configurar.

   

8. Selecione a organização do GitHub que contém o repositório que você deseja adicionar como um catálogo. Você deve ser um proprietário da organização para instalar este aplicativo.

   

9. Na página Instalar o Microsoft DevCenter, selecione Somente selecionar repositórios, selecionar o repositório que você deseja adicionar como um catálogo e, em seguida, selecione Instalar.

   

   Você pode selecionar vários repositórios para adicionar como catálogos. Você deve adicionar cada repositório como um catálogo separado, conforme descrito em Adicionar seu repositório como um catálogo.

10. Na página O Microsoft DevCenter da Microsoft deseja permissão para:, examine as permissões necessárias e selecione Autorizar o DevCenter da Microsoft.

    

Adicionar o repositório como um catálogo

1. Alterne novamente para o portal do Azure.

2. No painel Adicionar catálogo, insira as informações a seguir e clique em Adicionar:

   Campo	Valor
   Repo	Selecione o repositório que você deseja adicionar como um catálogo.
   Branch	Selecione o branch.
   Caminho da pasta	Selecione a pasta que contém subpastas que contêm suas definições de ambiente.

   

3. Verifique se o catálogo aparece em Catálogos no centro de desenvolvimento. Quando a conexão é bem-sucedida, o Status exibe Sincronização bem-sucedida.

   

Repositório do GitHub com PAT

Para adicionar um catálogo, conclua as seguintes tarefas:

• Obtenha a URL de clone do repositório do GitHub.
• Crie um token de acesso pessoal (PAT) no GitHub.
• Armazene o PAT como um segredo do cofre de chaves no Azure Key Vault.
• Adicione o repositório como um catálogo.

Obter a URL de clone do repositório do GitHub

1. Acesse a home page do repositório do GitHub que contém as definições de modelo.

2. Obtenha a URL de clone do repositório do GitHub.

3. Copie e salve a URL.

Criar um token de acesso pessoal no GitHub

Os Ambientes de Implantação Azure dão suporte à autenticação em repositórios do GitHub usando tokens clássicos ou tokens refinados. Neste exemplo, você cria um token refinado.

1. Acesse a home page do repositório do GitHub que contém as definições de modelo.

2. Selecione a imagem de perfil no canto superior direito do GitHub e, em seguida, selecione Configurações.

3. Na barra lateral esquerda, selecione Configurações do desenvolvedor>Tokens de acesso pessoal >Tokens refinados.

4. Selecione Gerar novo token.

5. Na página Novo token de acesso pessoal refinado, forneça as seguintes informações:

   Nome	Valor
   Nome do Token	Insira um nome descritivo para o token.
   Validade	Selecione o período de expiração do token em dias.
   Descrição	Insira uma descrição para o token.
   Proprietário do recurso	Selecione o proprietário do repositório.
   Acesso ao repositório	Selecione Selecionar apenas repositórios.
   Selecionar repositórios	Selecione o repositório que contém as definições de ambiente.
   Permissões do repositório	Expanda as permissões do Repositório e, para Conteúdo, na lista de Acesso, selecione Leitura de código.

   

6. Selecione Gerar token.

7. Copie e salve o token gerado para usá-lo posteriormente.

Importante

Ao trabalhar com um repositório privado armazenado em uma organização do GitHub, você deve garantir que o PAT do GitHub esteja configurado para dar acesso à organização correta e aos repositórios dentro dela.

• Os tokens clássicos dentro da organização devem ser autorizados para SSO para a organização específica depois de serem criados.
• Tokens refinados devem ter o proprietário do token definido como a própria organização a ser autorizada.

PATs configuradas incorretamente podem resultar em um erro de Repositório não encontrado.

Criar um cofre de chaves

Você precisa de um Azure Key Vault para armazenar o PAT usado para conceder acesso ao Azure ao seu repositório. Os cofres de chaves podem controlar o acesso com políticas de acesso ou controle de acesso baseado em função (RBAC). Se você tiver um cofre de chaves existente, poderá usá-lo, mas deverá verificar se ele usa políticas de acesso ou atribuições RBAC para controlar o acesso. Para obter ajuda com a configuração de uma política de acesso para um cofre de chaves, confira Atribuir uma política de acesso do cofre de chaves.

Use as seguintes etapas para criar um cofre de chaves RBAC:

1. Entre no portal do Azure.

2. Na caixa de pesquisa, digite Key Vault.

3. Na lista de resultados, selecione Key Vault.

4. Na página Key Vault, selecione Criar.

5. Na guia Criar cofre de chaves, forneça as seguintes informações:

   Nome	Valor
   Nome	Insira um nome para o cofre de chaves.
   Assinatura	Selecione a assinatura na qual deseja criar o cofre de chaves.
   Grupo de recursos	Use um grupo de recursos existente ou selecione Criar e insira um nome para o grupo de recursos.
   Localidade	Escolha a localização ou a região em que deseja criar o cofre de chaves.

   Mantenha as outras opções com os respectivos padrões.

6. Na guia Política de acesso, selecione Controle de acesso baseado em função do Azure e selecione Examinar + criar.

7. Na guia Revisar + criar, selecione Criar.

Armazenar token de acesso pessoal no cofre de chaves

1. No Key Vault, no menu à esquerda, selecione Segredos.

2. Na página Segredos, selecione Gerar/Importar.

3. Na página Criar um segredo:

   • Na caixa Nome, insira um nome descritivo para o segredo.
   • Na caixa Valor do segredo, cole o seu PAT.
   • Selecione Criar.

Obter identificador do segredo

Obtenha o caminho para o segredo criado no cofre de chaves.

1. No portal do Azure, navegue até o cofre de chaves.

2. Na página do cofre de chaves, no menu à esquerda, selecione Segredos.

3. Na página Segredos, selecione o segredo que você criou anteriormente.

4. Na página de versões, selecione a VERSÃO ATUAL.

5. Na página da versão atual, em Identificador de segredo, selecione Copiar.

Adicionar o repositório como um catálogo

1. No portal do Azure, acesse o centro de desenvolvimento.

2. Certifique-se de que a identidade gerenciada anexada ao centro de desenvolvimento tenha acesso ao segredo do cofre de chaves em que o token de acesso pessoal está armazenado.

3. No menu esquerdo, em Configuração do ambiente, selecione Catálogos e, em seguida, selecione Adicionar.

4. Em Adicionar catálogo, insira as informações a seguir e selecione Adicionar.

   Campo	Valor
   Nome	Insira um nome para o catálogo.
   Localização do catálogo	Selecione GitHub.
   Repo	Insira ou cole a URL de clonagem do seu repositório do GitHub ou do Azure Repos. Exemplo de catálogo de amostra:https://github.com/Azure/deployment-environments.git
   Branch	Insira o branch do repositório ao qual se conectar. Exemplo de catálogo de amostra:main
   Caminho da pasta	Insira o caminho da pasta relativo ao URI do clone que contém as subpastas que contêm as definições do ambiente. O caminho da pasta é para a pasta com subpastas que contêm arquivos de ambiente de definição de ambiente, não para a pasta com o próprio arquivo de ambiente de definição de ambiente. A imagem a seguir mostra a estrutura de pastas do catálogo de amostra. Exemplo de catálogo de amostra:/Environments O caminho da pasta pode começar com ou sem uma barra (/).
   Identificador do segredo	Insira o identificador de segredo que contém o seu PAT para o repositório. Ao copiar um identificador secreto, a cadeia de conexão incluirá um identificador de versão no final, como neste exemplo: https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat/9376b432b72441a1b9e795695708ea5a. A remoção do identificador de versão garante que os Ambientes de Implantação busquem a versão mais recente do segredo do cofre de chaves. Se o PAT expirar, apenas o cofre de chaves precisará ser atualizado. Exemplo de identificador secreto:https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat

   

5. Verifique se o catálogo aparece em Catálogos no centro de desenvolvimento. Quando a conexão é bem-sucedida, o Status exibe Sincronização bem-sucedida.

Atualizar um catálogo

Se você atualizar o conteúdo ou a definição do modelo do Azure Resource Manager (modelo do ARM) no repositório anexado, você poderá fornecer o conjunto mais recente de definições de ambiente para suas equipes de desenvolvimento sincronizando o catálogo.

Para sincronizar um catálogo atualizado nos Ambientes de Implantação Azure:

1. No menu esquerdo do centro de desenvolvimento, em Configuração do ambiente, selecione Catálogos.

2. Selecione o catálogo específico e selecione Sincronizar. O serviço examina o repositório e disponibiliza a lista mais recente de definições de ambiente para todos os projetos associados no centro de desenvolvimento.

Excluir um catálogo

Você pode excluir um catálogo para removê-lo do centro de desenvolvimento dos Ambientes de Implantação Azure. Os modelos em um catálogo excluído não estarão disponíveis para as equipes de desenvolvimento quando novos ambientes forem implantados. Atualize a referência de definição de ambiente para todos os ambientes existentes que foram criados usando as definições de ambiente no catálogo excluído. Se a referência não for atualizada e o ambiente for reimplantado, a implantação falhará.

Para excluir um catálogo:

1. No menu esquerdo do centro de desenvolvimento, em Configuração do ambiente, selecione Catálogos.

2. Selecione o catálogo específico e clique em Excluir.

3. Na caixa de diálogo Excluir catálogo, selecione Continuar para excluir o catálogo.

Erros de sincronização de catálogo

Ao adicionar ou sincronizar um catálogo, é possível encontrar um erro de sincronização. Um erro de sincronização indica que algumas ou todas as definições de ambiente têm erros. Use a CLI do Azure ou a API REST para obter (GET) o catálogo. A resposta GET mostra o tipo de erro:

• Definições de ambiente ignoradas que foram detectadas como duplicatas.
• Definições de ambiente inválidas que falharam devido a erros de esquema, referência ou validação.

Resolver erros de definição de ambiente ignorados

Um erro de definição de ambiente ignorado ocorrerá se você adicionar duas ou mais definições de ambiente com o mesmo nome. Você pode resolver esse problema renomeando as definições de ambiente para que cada definição de ambiente tenha um nome exclusivo dentro do catálogo.

Resolver erros de definição de ambiente inválidos

Um erro de definição de ambiente inválido pode ocorrer por vários motivos:

• Erros no esquema de manifesto. Certifique-se de que o arquivo de ambiente de definição do ambiente corresponda ao esquema necessário.

• Erros de validação. Verifique os seguintes itens para resolver erros de validação:

  • Certifique-se de que o tipo de mecanismo do arquivo de ambiente esteja configurado corretamente como ARM.
  • Certifique-se de que o nome de definição do ambiente esteja entre 3 e 63 caracteres.
  • Certifique-se de que o nome da definição do ambiente inclua apenas caracteres válidos para uma URL, que são caracteres alfanuméricos e os símbolos a seguir: ~!,.';:=-_+()*&$@

• Erros de referência. Certifique-se de que o caminho do modelo a que o arquivo de ambiente faz referência seja um caminho relativo válido para um arquivo no repositório.

Conteúdo relacionado

• Configurar tipos de ambiente para um centro de desenvolvimento
• Criar e configurar um projeto usando a CLI do Azure
• Configurar tipos de ambiente de projeto