Conexión de Azure Boards a GitHub (nube)

  • Artículo

Azure DevOps Services

Use los repositorios de GitHub.com para el desarrollo de software y Azure Boards para planear su trabajo y realizar el seguimiento. Conecte su proyecto y repositorio para vincular las confirmaciones y solicitudes de cambios de GitHub a los elementos de trabajo de Azure Boards.

Nota:

Azure Boards y Azure DevOps Services admiten la integración con repositorios de GitHub.com y GitHub Enterprise Server. Si desea conectarse desde una instancia local de Azure DevOps Server, consulte Conexión de Azure DevOps Server a GitHub Enterprise Server.

Requisitos previos

  • Debe tener un proyecto de Azure Boards o Azure DevOps. Si todavía no tiene un proyecto, cree uno.
  • Debe ser miembro del grupo Administradores de proyectos. Si ha creado el proyecto, tener permisos.
  • Debe ser administrador o propietario del repositorio de GitHub al que se conectará. Puede conectarse a varios repositorios de GitHub siempre que sea administrador para esos repositorios.

Opciones de autenticación

Las siguientes opciones de autenticación se admiten en función de la plataforma de GitHub a la que desea conectarse.

GitHub.com

Servidor de GitHub Enterprise

Nota

Si decide conectarse a Github con PAT, asegúrese de configurar el inicio de sesión único (SSO) para el PAT en la cuenta de GitHub. Esto es necesario para poder obtener una lista de repositorios de una organización con la autenticación SSO del lenguaje de marcado de aserción de seguridad (SAML) configurada.

Conexión de Azure Boards a un repositorio de GitHub.

  1. Inicie sesión en el proyecto de Azure DevOps.

  2. Seleccione Configuración del proyecto>Conexiones de GitHub.

    Screenshot of open Project Settings>GitHub connections.

  3. Si es la primera vez que realiza una conexión desde el proyecto, elija Conectar con la cuenta de GitHub para usar las credenciales de la cuenta de GitHub.

    Screenshot of first time connecting with GitHub credentials.

    De lo contrario, elija Nueva conexión y seleccione el método de autenticación en el cuadro de diálogo Nueva conexión.

    Al conectarse mediante la cuenta de GitHub, use las credenciales de la cuenta de GitHub para autenticarse. Para usar PAT, consulte Adición de una conexión de GitHub mediante PAT. Para conectarse a un servidor de GitHub Enterprise, consulte Registro de Azure DevOps en GitHub como una aplicación de OAuth.

Adición de una conexión de GitHub con credenciales de GitHub

Puede conectar hasta 500 repositorios de GitHub a un proyecto de Azure Boards.

  1. Si es la primera vez que se conecta a GitHub desde Azure Boards, se le pedirá que inicie sesión con sus credenciales de GitHub. Elija una cuenta en la que sea administrador del repositorio.

  2. Elija la cuenta u organización de GitHub que desea conectar. Solo se muestran las organizaciones que posee o de las que es administrador.

    Si todos los repositorios de una organización ya se han conectado a Azure Boards, verá el siguiente mensaje.

    Screenshot of message where no more repositories exist to connect.

  3. Escriba las credenciales de GitHub. Si ha habilitado la autenticación en dos fases, escriba el código de autenticación que GitHub le envió y elija Comprobar. De lo contrario, el sistema reconoce automáticamente la organización de GitHub, ya que la cuenta de GitHub se ha asociado anteriormente a la cuenta de Azure DevOps Services.

Elección de los repositorios

Una vez que se haya autenticado, puede seleccionar los repositorios a los que se quiere conectar.

  1. El cuadro de diálogo Agregar repositorios de GitHub aparece automáticamente y selecciona todos los repositorios de GitHub.com de los que es administrador en la organización seleccionada. Anule la selección de los repositorios que no quiera que se integren.

    Screenshot showing GitHub repos.

    Sugerencia

    Se recomienda conectar solo un repositorio de GitHub a los proyectos definidos en una sola organización de Azure DevOps. La conexión del mismo repositorio de GitHub a proyectos definidos en dos o más organizaciones de Azure DevOps puede dar lugar a una vinculación de menciones AB# inesperada. Para obtener más información, consulte Solución de problemas de la integración entre GitHub y Azure Boards.

    Si todos los repositorios ya se han conectado a la organización actual o a otra organización, aparecerá el siguiente mensaje.

    Screenshot of message where no more repositories exist to connect.

  2. Cuando finalice, seleccione Guardar.

Confirmación de la conexión

  1. Revise la página de GitHub que se muestra y, a continuación seleccione Aprobar, instalar y autorizar.

    Screenshot showing confirming GitHub repositories.

  2. Proporcione la contraseña de GitHub para confirmar.

  3. Cuando haya terminado, debería ver la nueva conexión con los repositorios seleccionados.

Screenshot of list of connected repositories.

Para cambiar la configuración o administrar la aplicación Azure Boards para GitHub, consulte Cambio del acceso de los repositorios a Azure Boards.

Adición de una conexión de GitHub mediante PAT

Se recomienda usar las credenciales de la cuenta de GitHub para conectarse al repositorio de GitHub. Sin embargo, si necesita usar un PAT, hágalo siguiendo estos procedimientos.

Sugerencia

Al crear el PAT de GitHub, asegúrese de que incluye estos ámbitos: repo, read:user, user:email, admin:repo_hook.

  1. Seleccione Token de acceso personal.

    Screenshot of New GitHub connection dialog, choosing Personal Access Token.

    Para crear un PAT de GitHub, vaya a Configuración de desarrollador de GitHub > Tokens de acceso personal.

  2. Especifique el PAT y elija Conectar.

    Screenshot showing entered PAT.

  3. Seleccione los repositorios que desea conectar al proyecto siguiendo los procedimientos descritos en Elección de los repositorios anteriormente en este artículo.

  4. Si es la primera vez que se conecta a una cuenta u organización de GitHub desde Azure Boards, también debe instalar la aplicación Azure Boards para GitHub. Confirme la conexión anteriormente en este artículo.

Registro de Azure DevOps en GitHub como una aplicación de OAuth

Si tiene previsto usar OAuth para conectar Azure DevOps con GitHub Enterprise Server, primero debe registrar la aplicación como una aplicación de OAuth. Para más información, consulte Creación de una aplicación de OAuth.

Registro de Azure DevOps Services

  1. Inicie sesión en el portal web del servidor de GitHub Enterprise.

    Screenshot of sign in for GitHub Enterprise server.

  2. Abra Configuración>Configuración del desarrollador>Aplicaciones de Oauth>Nueva aplicación de OAuth.

    Screenshot showing sequence for New OAuth App.

  3. Introduzca la información para registrar la aplicación.

    En la dirección URL de la página principal, especifique la dirección URL de la organización.
    En la dirección URL de devolución de llamada de autorización, use el siguiente patrón para construir la dirección URL.

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

    Por ejemplo:

    https://dev.azure.com/fabrikam/_admin/oauth2/callback

    Screenshot showing app to register.

  4. Seleccione Register application (Registrar aplicación).

  5. Aparecerán el Id. de cliente y el secreto de cliente de la aplicación de OAuth registrada.

    Screenshot of Client ID and Client Secret for the registered OAuth application.

Registro de la configuración de OAuth en Azure DevOps Services

  1. Inicie sesión en el portal web de Azure DevOps Services.

  2. Agregue la configuración de Oauth de GitHub Enterprise a su organización.

  3. En Configuración de la organización, seleccione Configuraciones de OAuth>Agregar configuración de Oauth.

    Screenshot of Open Organization Settings, OAuth configurations.

  4. Introduzca la información y, a continuación, seleccione Crear.

    OAuth configurations dialog.

Conexión de Azure DevOps Services a GitHub Enterprise Server

Importante

Para conectar Azure DevOps Services a GitHub Enterprise Server, este último debe ser suficientemente accesible desde Internet. Asegúrese de que Azure DNS puede resolver el nombre del servidor de GitHub Enterprise Server y que el firewall permite el acceso desde direcciones IP del centro de datos de Azure. Para determinar el intervalo de direcciones IP, consulte Intervalos de direcciones IP del centro de datos de Microsoft Azure. Se detecta un mensaje de error común cuando existen problemas de conectividad:

No se pudo resolver el nombre remoto: "github-enterprise-server.contoso.com"

Si experimenta este error, compruebe que el servidor es accesible. Para más información, consulte Preguntas más frecuentes sobre Azure DNS.

  1. Seleccione Configuración del proyecto>Conexiones de GitHub>GitHub Enterprise Server si se conecta por primera vez.

    First connection, choose GitHub Enterprise Server.

    O bien, en el cuadro de diálogo Nueva conexión de GitHub, seleccione GitHub Enterprise Server.

    Screenshot of New GitHub connection dialog, choose GitHub Enterprise Server.

  2. Seleccione el método de autenticación.

    Screenshot showing authentication method dialog.

    Conectar con OAuth

    Elija la configuración que configuró en el paso 4 de Registro de la configuración de OAuth en Azure DevOps Services y, a continuación, elija Conectar.

    Screenshot of New GitHub Enterprise connection, OAuth connection dialog.

    Conectarse con un token de acceso personal.

    Escriba la dirección URL del servidor de GitHub Enterprise y las credenciales del token de acceso personal reconocidas por ese servidor. A continuación, seleccione Conectar.

    Screenshot of New GitHub Enterprise connection, Personal access token connection dialog.

    Conectarse con nombre de usuario y contraseña

    Escriba la dirección URL del servidor de GitHub Enterprise y las credenciales de la cuenta de administrador reconocidas por ese servidor y, a continuación, seleccione Conectar.

    Screenshot of New GitHub Enterprise connection screen, User Name connection dialog.

  3. En el cuadro de diálogo se enumeran todos los repositorios para los que tiene derechos de administración de GitHub. Puede alternar entre Míos y Todos para determinar si aparecen otros y, a continuación, comprobar los que desea agregar. Cuando haya terminado, haga clic en Guardar.

    Screenshot of repositories listed.

    Sugerencia

    Solo puede establecer una conexión a repositorios definidos en una organización de GitHub. Para conectar un proyecto a otros repositorios definidos en otra organización de GitHub, debe agregar otra conexión.

  4. Si es la primera vez que se conecta a una cuenta u organización de GitHub desde Azure Boards, también debe instalar la aplicación Azure Boards para GitHub. Confirme la conexión anteriormente en este artículo.

Solución de problemas de conexión

La integración de Azure Boards y GitHub se basa en varios protocolos de autenticación para admitir la conexión. Los cambios en el ámbito de permisos o las credenciales de autenticación de un usuario pueden provocar la revocación de los repositorios de GitHub conectados a Azure Boards.

Para información general sobre la integración que admite la aplicación Azure Boards para GitHub, consulte Integración de Azure Boards con GitHub.

Opciones de autenticación admitidas

Las siguientes opciones de autenticación se admiten en función de la plataforma de GitHub a la que desea conectarse.

Plataforma

GitHub.com

Servidor de GitHub Enterprise

Azure DevOps Services

  • Cuenta de usuario de GitHub.com
  • Un token de acceso personal (PAT)
  • OAuth
  • PAT
  • Nombre de usuario más contraseña

Azure DevOps Server 2020

No aplicable

  • PAT
  • Nombre de usuario más contraseña

Azure DevOps Server 2019

No aplicable

  • OAuth
  • PAT
  • Nombre de usuario más contraseña

Nota:

Con la aplicación Azure Boards para GitHub, Azure Boards y Azure DevOps Services admiten la integración con repositorios de GitHub.com y GitHub Enterprise Server. Azure DevOps Servers 2019 y versiones posteriores solo admiten la integración con repositorios de GitHub Enterprise Server. No se admite la integración con otros repositorios de Git.

Concesión de acceso a la organización de Azure Boards

Si la integración entre Azure Boards y GitHub no funciona según lo previsto, compruebe que ha concedido acceso a la organización.

  1. En el portal web de GitHub, abra Configuración en el menú del perfil.
    Screenshot of open profile, choose Settings.

  2. Seleccione Aplicaciones en Integraciones>Aplicaciones de OAuth autorizadas>Azure Boards.

  3. En Acceso a la organización, resuelva los problemas que puedan aparecer. Seleccione Conceder para conceder acceso a las organizaciones que se muestran con una Solicitud de acceso pendiente.

    Screenshot of Organization access with organizations without access.

Resolución de problemas de acceso

Cuando la conexión de Azure Boards a GitHub ya no tiene acceso, muestra un estado de alerta en la interfaz de usuario con una X roja. Mantenga el puntero sobre la alerta e indicará que las credenciales ya no son válidas. Para corregir el problema, quite la conexión y vuelva a crear una nueva.

Screenshot of failed connection.

Considere estos puntos para resolver el problema:

  • Si la conexión usa OAuth:

    • La aplicación Azure Boards tenía denegado su acceso para uno de los repositorios.

    • GitHub podría no estar disponible o no accesible. Esta falta de disponibilidad podría deberse a una interrupción en el servicio o un problema de infraestructura o red en el entorno local. Puede comprobar el estado del servicio en los vínculos siguientes:

      Elimine la conexión con el repositorio de GitHub y vuélvala a crear. Esta conexión recién creada hace que GitHub pida que vuelva a autorizar Azure Boards.

  • Si la conexión usa un PAT:

    • Es posible que el PAT se haya revocado o que los ámbitos de permisos necesarios hayan cambiado y no sean suficientes.

    • Es posible que el usuario haya perdido los permisos de administrador en el repositorio de GitHub.

      Vuelva a crear el PAT y asegúrese de que el ámbito del token incluye los permisos necesarios: repo, read:user, user:email, admin:repo_hook.

Resolución de una conexión interrumpida con GitHub Enterprise Server

Si ha migrado de Azure DevOps Server a Azure DevOps Services con una conexión existente de GitHub Enterprise Server, la conexión existente no funcionará según lo previsto. Las menciones de elementos de trabajo en GitHub pueden retrasarse o no aparecer nunca en Azure DevOps Services. Este problema se produce porque la dirección URL de devolución de llamada asociada a GitHub ya no es válida.

Considere las siguientes soluciones:

  • Eliminar y volver a crear la conexión: elimine y vuelva a crear la conexión al repositorio de GitHub Enterprise Server. Siga la secuencia de pasos que se indica en la documentación Conexión desde Azure Boards.

  • Corrección de la dirección URL del webhook: vaya a la página de configuración del repositorio de GitHub y edite la dirección URL del webhook para que apunte a la dirección URL de la organización de Azure DevOps Services migrada: https://dev.azure.com/{OrganizationName}/_apis/work/events?api-version=5.2-preview

Conectarse a varias organizaciones de Azure DevOps

Si conecta el repositorio de GitHub a dos o más proyectos definidos en más de una organización de Azure DevOps, como dev.azure.com/Contoso y dev.azure.com/Fabrikam, puede que obtenga resultados inesperados al usar menciones de AB# para vincular a elementos de trabajo. Este problema se produce porque los identificadores de elemento de trabajo no son únicos en las organizaciones de Azure DevOps, por lo que AB#12 puede hacer referencia a un elemento de trabajo de la organización Contoso o Fabrikam. Por lo tanto, cuando se menciona un elemento de trabajo en un mensaje de confirmación o una solicitud de incorporación de cambios, ambas organizaciones intentan crear un vínculo a un elemento de trabajo con un identificador coincidente (si existe alguno).

En general, un usuario pretende que una mención ab# se vincule a un único elemento de trabajo de uno de los proyectos. Sin embargo, si existe un elemento de trabajo con el mismo identificador en ambas cuentas, los vínculos se crean para ambos elementos de trabajo, lo que probablemente provocará confusión.

Actualmente, no hay ninguna manera de solucionar este problema, por lo que se recomienda conectar un único repositorio de GitHub solo a una sola organización de Azure DevOps.

Nota:

Al establecer la conexión mediante la aplicación Azure Boards para GitHub, la aplicación impide que se conecte a dos organizaciones diferentes. Si un repositorio de GitHub está conectado incorrectamente a la organización de Azure DevOps equivocada, debe ponerse en contacto con el propietario de esa organización para eliminar la conexión antes de poder agregar el repositorio a la organización de Azure DevOps correcta.

Actualización de las definiciones XML para tipos de elementos de trabajo elegidos

Si su organización usa el modelo de proceso XML hospedado o XML local para personalizar la experiencia de seguimiento del trabajo y desea vincular y ver los tipos de vínculo de GitHub en la sección Desarrollo de los formularios de elementos de trabajo, deberá actualizar las definiciones XML de los tipos de elementos de trabajo.

Por ejemplo, si desea vincular casos de usuario y errores a confirmaciones de GitHub y solicitudes de incorporación de cambios en la sección Desarrollo, debe actualizar las definiciones XML de los casos de usuario y los errores.

Siga la secuencia de tareas proporcionadas en el modelo de proceso XML hospedado para actualizar las definiciones XML. Para cada tipo de elemento de trabajo, busque la sección Group Label="Development" y agregue las dos líneas siguientes en la sintaxis del código siguiente para admitir los tipos de vínculos externos: Confirmación de GitHub y Solicitud de incorporación de cambios de GitHub.

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

Cuando se actualice, la sección debe aparecer como se muestra a continuación.

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

Pasos siguientes

Vínculo de confirmaciones y solicitudes de incorporación de cambios de GitHub a los elementos de trabajo