Conectar o Azure Boards ao GitHub (nuvem)

Artigo
07/20/2023

Azure DevOps Services

Use os repositórios do GitHub.com para seu desenvolvimento de software e seu projeto do Azure Boards para planejar e acompanhar seu trabalho. Conecte seu projeto e repositório para que seus commits e pull requests do GitHub sejam vinculados aos seus itens de trabalho no Azure Boards.

Observação

O Azure Boards e o Azure DevOps Services dão suporte à integração com GitHub.com e repositórios do GitHub Enterprise Server. Se você quiser se conectar de um Azure DevOps Server local, confira Conectar o Servidor do Azure DevOps ao GitHub Enterprise Server.

Pré-requisitos

Você deve ter um projeto do Azure Boards ou do Azure DevOps. Se você não tiver um projeto ainda, crie um.
Você deve ser membro do grupo Administradores de Projeto. Se você criou o projeto, tem permissões.
Você deve ser um administrador ou proprietário do repositório GitHub ao qual se conectará. Você pode se conectar a vários repositórios do GitHub desde que seja administrador desses repositórios.

Opções de autenticação

As opções de autenticação a seguir têm suporte com base na plataforma GitHub à qual você deseja se conectar.

GitHub.com

GitHub Enterprise Server

GitHub.com conta de usuário (Recomendado)
PAT (Token de acesso pessoal)

OAuth (preferencial, registro necessário)
PAT
Nome de usuário mais senha

Observação

Se você optar por conectar o Github ao PAT, configure o SSO (logon único) para o PAT em sua conta do GitHub. Isso é necessário para obter uma lista de repositórios de uma organização com a autenticação de SSO do SAML (Security Assertion Markup Language) configurada.

Conecte o Azure Boards a um repositório do GitHub.

Entre em seu projeto do Azure DevOps.
Selecione Configurações do projeto>Conexões do GitHub.
Se for a primeira vez que faz uma conexão com o projeto, escolha Conectar sua conta do GitHub para usar suas credenciais de conta do GitHub.

Caso contrário, escolha Nova conexão e selecione o método de autenticação na caixa de diálogo Nova Conexão.

Ao se conectar usando sua conta do GitHub, use suas credenciais de conta do GitHub para se autenticar. Para usar o PAT, consulte Adicionar uma conexão do GitHub usando PAT. Se estiver se conectando a um GitHub Enterprise Server, confira Registrar o Azure DevOps no GitHub como um aplicativo OAuth.

Adicionar uma conexão do GitHub com as credenciais do GitHub

Você pode conectar até 500 repositórios GitHub a um projeto do Azure Boards.

Se for a primeira vez que se conectar ao GitHub do Azure Boards, você será solicitado a entrar usando suas credenciais do GitHub. Escolha uma conta da qual você seja administrador do repositório.
Escolha a conta ou organização do GitHub que você deseja conectar. Somente as organizações que você possui ou é administrador estão listadas.

Se todos os repositórios de uma organização já tiverem sido conectados ao Azure Boards, você verá a mensagem a seguir.
Insira suas credenciais do GitHub. Se você tiver a autenticação de dois fatores habilitada, insira o código de autenticação que o GitHub enviou e escolha Verificar. Caso contrário, o sistema reconhecerá automaticamente sua organização do GitHub, pois sua conta do GitHub foi associada anteriormente à sua conta Azure DevOps Services.

Escolher os repositórios

Depois de uma nova autenticação, você pode selecionar os repositórios que deseja conectar.

A caixa de diálogo Adicionar Repositórios do GitHub é exibida automaticamente e seleciona todos os repositórios GitHub.com para os quais você é administrador da organização selecionada. Desmarque todos os repositórios que você não deseja que participem da integração.

Dica

Por esse motivo, recomendamos que você conecte apenas um repositório GitHub a projetos definidos em uma única organização do Azure DevOps. Conectar o mesmo repositório GitHub a projetos definidos em duas ou mais organizações do Azure DevOps, poderá levar a uma vinculação de menção inesperada AB#. Para obter mais informações, consulte Solução de problemas de integração do GitHub e Azure Boards.

Se todos os repositórios já estiverem conectados à organização atual ou a outra organização, a mensagem a seguir será exibida.
Quando terminar, selecione Salvar.

Confirmar a conexão

Examine a página do GitHub exibida e escolha Aprovar, Instalar e autorizar.
Forneça sua senha do GitHub para confirmar.
Quando terminar, você deverá ver a nova conexão com os repositórios selecionados listados.

Screenshot of list of connected repositories.

Para alterar a configuração ou gerenciar o aplicativo Azure Boards para GitHub, confira Alterar o acesso do repositório ao Azure Boards.

Adicionar uma conexão do GitHub usando PAT

Recomendamos que você use suas credenciais de conta do GitHub para se conectar ao repositório GitHub. No entanto, se você precisar usar um PAT, faça isso seguindo esses procedimentos.

Dica

Ao criar seu PAT do GitHub, inclua estes escopos: repo, read:user, user:email, admin:repo_hook.

Escolha Token de acesso pessoal.

Para criar um PAT do GitHub, acesse Configurações de Desenvolvedor do GitHub > tokens de acesso pessoal.
Insira o PAT e escolha Conectar.
Escolha os repositórios que você deseja conectar ao projeto seguindo os procedimentos descritos anteriormente neste artigo em Escolher os repositórios.
Se for a primeira vez que se conectar a uma conta do GitHub ou a uma organização do Azure Boards, você também instalará o aplicativo Azure Boards para GitHub. Confirme a conexão anteriormente neste artigo.

Registrar o Azure DevOps no GitHub como um aplicativo OAuth

Se você planeja usar o OAuth para conectar o Azure DevOps com o GitHub Enterprise Server, primeiro precisa registrar o aplicativo como um aplicativo OAuth. Para obter mais informações, consulte Criar um Aplicativo OAuth.

Registrar o Azure DevOps Services

Entre no portal da Web para o servidor GitHub Enterprise.
Abra Configurações>Configurações do desenvolvedor>Aplicativos OAuth>Novo aplicativo OAuth.
Insira as informações para registrar seu aplicativo.

Para a de URL da página inicial, especifique o URL da Organização de sua organização.
Para a URL de retorno de chamada de autorização, use o padrão a seguir para construir a URL.

{Azure DevOps Services Organization URL}/_admin/oauth2/callback

Por exemplo:

https://dev.azure.com/fabrikam/_admin/oauth2/callback
Selecione Registrar aplicativo.
O ID do Cliente e Segredo do Cliente para seu aplicativo OAuth registrado.

Registrar sua configuração do OAuth no Azure DevOps Services

Entre no portal da Web para o Azure DevOps Services.
Adicione a configuração do GitHub Enterprise Oauth à sua organização.
Em Configurações da organização, selecione Configurações do Oauth>Adicionar configuração Oauth.
Insira as informações, selecione Criar.

Conectar o Azure DevOps Services ao GitHub Enterprise Server

Importante

Para conectar o Azure DevOps Services ao GitHub Enterprise Server, o GitHub Enterprise Server deve estar suficientemente acessível pela Internet. Verifique se o DNS do Azure pode resolver o nome do GitHub Enterprise Server e se o firewall permite o acesso de endereços IP do Data Center do Azure. Para determinar o intervalo de endereços IP, confira Intervalos de IP do Datacenter do Microsoft Azure. Uma mensagem de erro comum encontrada quando há problemas de conectividade é:

O nome remoto não pôde ser resolvido: 'github-enterprise-server.contoso.com'

Se você encontrar esse erro, verifique se o servidor está acessível. Para obter mais informações, confira Perguntas Frequentes sobre o DNS do Azure.

Selecione Configurações do projeto>Conexões GitHub>GitHub Enterprise Server para uma conexão pela primeira vez.

Ou, na caixa de diálogo Nova Conexão do GitHub, selecione GitHub Enterprise Server.
Selecione o método de autenticação.

Conectar-se ao OAuth

Escolha a configuração que você configurou na Etapa 4 de Registrar sua configuração do OAuth no Azure DevOps Servicese escolha Conectar.

Conectar-se por meio de um Token de Acesso Pessoal

Insira a URL do servidor GitHub Enterprise e as credenciais de token de acesso pessoal reconhecidas por esse servidor. Escolha Conectar.

Conectar com nome de usuário e senha

Insira a URL do servidor GitHub Enterprise e as credenciais de conta de administrador reconhecidas por esse servidor e selecione Conectar.
A caixa de diálogo lista todos os repositórios para os quais você tem direitos de administração do GitHub. Você pode alternar entre Meu e Todos para determinar se outras pessoas aparecem e, em seguida, marcar as que deseja adicionar. Selecione Salvar ao terminar.

Dica

Você só pode fazer uma conexão com repositórios definidos em uma organização do GitHub. Para conectar um projeto a outros repositórios definidos em outra organização do GitHub, você deve adicionar outra conexão.
Se for a primeira vez que se conectar a uma conta ou organização do GitHub do Azure Boards, você também instalará o aplicativo Azure Boards para GitHub. Confirme a conexão anteriormente neste artigo.

Resolver problemas de conexão

A integração do Azure Boards-GitHub depende de vários protocolos de autenticação para dar suporte à conexão. Alterações no escopo de permissão ou credenciais de autenticação de um usuário podem causar revogação dos repositórios do GitHub conectados ao Azure Boards.

Para obter uma visão geral da integração compatível com o aplicativo Azure Boards para GitHub, confira Integração do Azure Boards-GitHub.

Opções de autenticação com suporte

As opções de autenticação a seguir têm suporte com base na plataforma GitHub à qual você deseja se conectar.

Plataforma

GitHub.com

GitHub Enterprise Server

Azure DevOps Services

GitHub.com conta de usuário
PAT (token de acesso pessoal)

OAuth
PAT
Nome de usuário mais senha

Azure DevOps Server 2020

Não aplicável

PAT
Nome de usuário mais senha

Azure DevOps Server 2019

Não aplicável

OAuth
PAT
Nome de usuário mais senha

Observação

Com o aplicativo Azure Boards para GitHub, o Azure Boards e o Azure DevOps Services dão suporte à integração com repositórios do GitHub.com e do GitHub Enterprise Server. O Azure DevOps Servers 2019 e versões posteriores dão suporte apenas à integração com repositórios do GitHub Enterprise Server. Não há suporte para a integração com outros repositórios Git.

Conceder acesso à organização Azure Boards

Se a integração entre o Azure Boards e o GitHub não estiver funcionando conforme o esperado, verifique se você concedeu acesso à organização.

No portal da Web do GitHub, abra Configurações no menu de perfil.
Selecione Aplicativos em Integrações>Aplicativos OAuth Autorizados>Azure Boards.
Em Acesso à organização, resolva todos os problemas que possam aparecer. Selecione Conceder para conceder acesso a todas as organizações que aparecem com uma solicitação de Acesso pendente.

Resolver problemas de acesso

Quando a conexão do Azure Boards com o GitHub não tem mais acesso, ela mostra um status de alerta na interface do usuário com um X vermelho. Passar o mouse sobre o alerta e indica que as credenciais não são mais válidas. Para corrigir o problema, remova a conexão e recrie uma nova conexão.

Screenshot of failed connection.

Para resolver esse problema, considere os itens a seguir:

Se a conexão estiver usando o OAuth:
- O aplicativo Azure Boards teve seu acesso negado para um dos repositórios.
- O GitHub pode estar indisponível/inacessível. Essa indisponibilidade pode ser devido a uma interrupção no serviço ou em um problema de infraestrutura/rede local. Você pode verificar o status do serviço nos seguintes links:
  - GitHub
  - Azure DevOps
  Exclua e recrie a conexão com o repositório GitHub. Essa conexão recriada faz com que o GitHub solicite a reautorização do Azure Boards.
Se a conexão estiver usando um PAT:
- O PAT pode ter sido revogado ou os escopos de permissão necessários foram alterados e são insuficientes.
- O usuário pode ter perdido permissões de administrador no repositório GitHub.
  
  Recrie o PAT e verifique se o escopo do token inclui as permissões necessárias: repo, read:user, user:email, admin:repo_hook.

Resolver a conexão do GitHub Enterprise Server interrompida

Se você tiver migrado do Azure DevOps Server para o Azure DevOps Services com uma conexão existente do GitHub Enterprise Server, sua conexão existente não funcionará conforme o esperado. As menções de item de trabalho no GitHub podem ser atrasadas ou nunca aparecer no Azure DevOps Services. Esse problema ocorre porque a URL de retorno de chamada associada ao GitHub não é mais válida.

Considere as seguintes resoluções:

Remova e recrie a conexão: remova e recrie a conexão com o repositório do GitHub Enterprise Server. Siga a sequência de etapas fornecidas na documentaçãoConectar pelo Azure Boards.
Corrija a URL do webhook: vá para a página de configurações do repositório do GitHub e edite a URL do webhook para apontar para a URL da organização do Azure DevOps Services migrada: https://dev.azure.com/{OrganizationName}/_apis/work/events?api-version=5.2-preview

Conectar-se a várias organizações do Azure DevOps

Se você conectar seu repositório GitHub a dois ou mais projetos definidos em mais de uma organização do Azure DevOps, como dev.azure.com/Contoso e dev.azure.com/Fabrikam, poderá obter resultados inesperados ao usar menções AB# para vincular a itens de trabalho. Esse problema ocorre porque as IDs de item de trabalho não são exclusivas em organizações do Azure DevOps, portanto, AB#12 podem se referir a um item de trabalho na organização Contoso ou Fabrikam. Portanto, quando um item de trabalho é mencionado em uma mensagem de confirmação ou solicitação de pull, ambas as organizações tentam criar um link para um item de trabalho com uma ID correspondente (se houver).

Em geral, um usuário pretende uma menção AB# é vinculada a um único item de trabalho em um dos projetos. Porém, se houver um item de trabalho da mesma ID em ambas as contas, os links serão criados para ambos os itens de trabalho, provavelmente causando confusão.

Atualmente, não há como resolver esse problema, portanto, recomendamos que você conecte um único repositório do GitHub a apenas uma organização do Azure DevOps.

Observação

Ao fazer a conexão usando o aplicativo Azure Boards para GitHub, o aplicativo impede que você se conecte a duas organizações diferentes. Se um repositório GitHub estiver conectado incorretamente à organização errada do Azure DevOps, você precisará entrar em contato com o proprietário dessa organização para remover a conexão antes de poder adicionar o repositório à organização correta do Azure DevOps.

Atualizar definições XML para selecionar tipos de item de trabalho

Se a sua organização usar o modelo de processo XML hospedado ou XML local para personalizar a experiência de acompanhamento de trabalho e você quiser vincular e exibir os tipos de link do GitHub da seção Desenvolvimento nos formulários do item de trabalho, você precisará atualizar as definições XML para os tipos de item de trabalho.

Por exemplo, se você quiser vincular histórias de usuário e bugs às solicitações de confirmação e pull do GitHub da seção Desenvolvimento, será necessário atualizar as definições XML para histórias de usuário e bugs.

Siga a sequência de tarefas fornecidas em modelo de processo XML hospedado para atualizar as definições XML. Para cada tipo de item de trabalho, localize a seção Group Label="Development" e adicione as duas linhas a seguir na seguinte sintaxe de código para dar suporte aos tipos de links externos: Confirmação do GitHub e Solicitação de Pull do GitHub.

             <ExternalLinkFilter Type="GitHub Pull Request" />  
             <ExternalLinkFilter Type="GitHub Commit" />

Quando for atualizada, a seção deverá aparecer da seguinte maneira.

<Group Label="Development">  
   <Control Type="LinksControl" Name="Development">  
      <LinksControlOptions ViewMode="Dynamic" ZeroDataExperience="Development" ShowCallToAction="true">  
         <ListViewOptions GroupLinks="false">   
         </ListViewOptions>  
         <LinkFilters>  
             <ExternalLinkFilter Type="Build" />  
             <ExternalLinkFilter Type="Integrated in build" />  
             <ExternalLinkFilter Type="Pull Request" />  
             <ExternalLinkFilter Type="Branch" />  
             <ExternalLinkFilter Type="Fixed in Commit" />  
             <ExternalLinkFilter Type="Fixed in Changeset" />  
             <ExternalLinkFilter Type="Source Code File" />  
             <ExternalLinkFilter Type="Found in build" />  
             <ExternalLinkFilter Type="GitHub Pull Request" />  
             <ExternalLinkFilter Type="GitHub Commit" />  
         </LinkFilters>  
      </LinksControlOptions>  
   </Control>  
</Group>

Próximas etapas

Vincular solicitações de pull e commit do GitHub para itens de trabalho

Conectar o Azure Boards ao GitHub (nuvem)

Pré-requisitos

Opções de autenticação

Conecte o Azure Boards a um repositório do GitHub.