Connecter Azure Boards à GitHub (cloud)

  • Article

Azure DevOps Services

Utilisez les référentiels GitHub.com pour le développement de logiciels et le projet Azure Boards pour planifier et suivre le travail. Connectez le projet et le référentiel pour que vos commits GitHub et vos demandes de tirage (pull requests) soient liés à vos éléments de travail dans Azure Boards.

Remarque

Azure Boards et Azure DevOps Services prennent en charge l’intégration aux dépôts GitHub.com et GitHub Enterprise Server. Si vous souhaitez vous connecter à partir d’une instance Azure DevOps Server locale, consultez Connecter Azure DevOps Server à GitHub Enterprise Server.

Prérequis

  • Vous devez avoir un projet Azure Boards ou Azure DevOps. Si vous n’avez pas encore de projet, créez-en un.
  • Vous devez être membre du groupe Administrateurs du projet. Si vous avez créé le projet, vous disposez d’autorisations.
  • Vous devez être administrateur ou propriétaire du référentiel GitHub auquel vous allez vous connecter. Vous pouvez vous connecter à plusieurs référentiels GitHub tant que vous êtes administrateur de ces référentiels.

Options d’authentification

Les options d’authentification suivantes sont prises en charge en fonction de la plateforme GitHub à laquelle vous souhaitez vous connecter.

GitHub.com

GitHub Enterprise Server

Notes

Si vous choisissez de vous connecter à GitHub avec un jeton d’accès personnel, veillez à configurer l’authentification unique (SSO) pour le jeton d’accès personnel sur votre compte GitHub. Il est nécessaire de pouvoir obtenir la liste des dépôts d’une organisation avec l’authentification unique SAML (Security Assertion Markup Language) configurée.

Connectez Azure Boards à un référentiel GitHub.

  1. Connectez-vous à votre projet Azure DevOps.

  2. Sélectionnez Paramètres du projet>Connections GitHub.

    Screenshot of open Project Settings>GitHub connections.

  3. Si c’est la première fois que vous établissez une connexion à partir du projet, choisissez Connecter votre compte GitHub pour utiliser les informations d’identification de votre compte GitHub.

    Screenshot of first time connecting with GitHub credentials.

    Sinon, choisissez Nouvelle connexion, puis sélectionnez votre méthode d’authentification dans la boîte de dialogue Nouvelle connexion.

    Lorsque vous vous connectez à l’aide de votre compte GitHub, utilisez les informations d’identification de votre compte GitHub pour vous authentifier. Pour utiliser PAT, consultez la section Ajouter une connexion GitHub à l’aide de PAT. Pour vous connecter à un serveur GitHub Enterprise Server, consultez Inscrire Azure DevOps dans GitHub en tant qu’application OAuth.

Ajouter une connexion GitHub avec des informations d’identification GitHub

Vous pouvez connecter jusqu’à 500 référentiels GitHub à un projet Azure Boards.

  1. Si vous vous connectez à GitHub pour la première fois à partir d’Azure Boards, vous serez invité à vous connecter à l’aide de vos identifiants GitHub. Choisissez un compte pour lequel vous êtes un administrateur de référentiels.

  2. Choisissez le compte GitHub ou l’organisation que vous souhaitez connecter. Seules les organisations dont vous êtes administrateur ou dont vous êtes propriétaire sont répertoriées.

    Si tous les référentiels d’une organisation ont déjà été connectés à Azure Boards, le message suivant s’affiche.

    Screenshot of message where no more repositories exist to connect.

  3. Saisissez vos informations d’identification GitHub. Si vous avez activé l’authentification à 2 facteurs, saisissez le code d’authentification que GitHub vous a envoyé, puis choisissez Vérifier. Dans le cas contraire, le système reconnaît automatiquement votre organisation GitHub en tant que compte GitHub associé à votre compte Azure DevOps Services.

Choisir les dépôts

Une fois que vous avez été authentifié, vous pouvez sélectionner les référentiels que vous souhaitez connecter.

  1. La boîte de dialogue Ajouter des dépôts GitHub s’affiche automatiquement et sélectionne tous les dépôts GitHub.com pour lesquels vous êtes administrateur de l’organisation sélectionnée. Désélectionnez tous les dépôts que vous ne souhaitez pas faire participer à l’intégration.

    Screenshot showing GitHub repos.

    Conseil

    Nous vous recommandons de connecter un dépôt GitHub uniquement aux projets définis dans une même organisation Azure DevOps. La connexion du même dépôt GitHub à des projets définis dans deux organisations Azure DevOps ou plus peut entraîner une liaison de mention AB# inattendue. Pour plus d’informations, consultez Résoudre les problèmes d’intégration GitHub et Azure Boards.

    Si tous les référentiels ont déjà été connectés à l’organisation actuelle ou une autre, le message suivant s’affiche.

    Screenshot of message where no more repositories exist to connect.

  2. Quand vous avez terminé, sélectionnez Enregistrer.

Confirmer la connexion

  1. Passez en revue la page GitHub qui s’affiche, puis choisissez Approuver, Installer et Autoriser.

    Screenshot showing confirming GitHub repositories.

  2. Indiquez votre mot de passe GitHub pour confirmer.

  3. Lorsque vous avez terminé, vous devriez voir la nouvelle connexion avec les référentiels sélectionnés répertoriés.

Screenshot of list of connected repositories.

Pour modifier la configuration ou gérer l’application Azure Boards pour GitHub, consultez Modifier l’accès du dépôt à Azure Boards.

Ajouter une connexion GitHub à l’aide d’un jeton d’accès personnel

Nous vous recommandons d’utiliser les informations d’identification de votre compte GitHub pour vous connecter à votre dépôt GitHub. Toutefois, si vous avez besoin d’utiliser un jeton d’accès personnel, procédez comme suit.

Conseil

Lorsque vous créez votre PAT GitHub, assurez-vous d’inclure ces portées : repo, read:user, user:email, admin:repo_hook.

  1. Choisissez Jeton d’accès personnels.

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

    Pour créer un PAT GitHub, accédez à Paramètres du développeur GitHub> Jetons d’accès personnels.

  2. Entrez le jeton d’accès personnel et choisissez Se connecter.

    Screenshot showing entered PAT.

  3. Choisissez les dépôts que vous souhaitez connecter au projet en suivant les procédures décrites dans Choisir les dépôts plus haut dans cet article.

  4. S’il s’agit de la première connexion à un compte GitHub ou à une organisation à partir d’Azure Boards, vous allez également installer l’application Azure Boards pour GitHub. Confirmez la connexion précédemment évoquée dans cet article.

Inscrire Azure DevOps dans GitHub en tant qu’application OAuth

Si vous envisagez d’utiliser OAuth pour vous connecter à Azure DevOps avec GitHub Enterprise Server, vous devez d’abord inscrire l’application en tant qu’application OAuth. Pour plus d’informations, consultez Créer une application OAuth.

Inscrire Azure DevOps Services

  1. Connectez-vous au portail web pour votre serveur GitHub Enterprise.

    Screenshot of sign in for GitHub Enterprise server.

  2. Ouvrez Paramètres>Paramètres de développeur>Applications Oauth>Nouvelle application OAuth.

    Screenshot showing sequence for New OAuth App.

  3. Saisissez les informations nécessaires à l’enregistrement de votre application.

    Pour URL de la page d’accueil, spécifiez l’URL d’organisation de votre organisation.
    Pour URL de rappel d’autorisation, utilisez le modèle suivant pour construire l’URL.

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

    Par exemple :

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

    Screenshot showing app to register.

  4. Sélectionnez Register application (Inscrire l’application).

  5. L’ID client et la clé secrète client pour votre application OAuth inscrite s’affichent.

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

Inscrire votre configuration OAuth dans Azure DevOps Services

  1. Connectez-vous au portail web pour Azure DevOps Services.

  2. Ajoutez la configuration Oauth de GitHub Enterprise à votre organisation.

  3. Dans les paramètres de l’organisation, sélectionnez Configurations Oauth>Ajouter une configuration Oauth.

    Screenshot of Open Organization Settings, OAuth configurations.

  4. Saisissez vos informations, puis sélectionnez Créer.

    OAuth configurations dialog.

Connecter Azure DevOps Services à GitHub Enterprise Server

Important

Pour connecter Azure DevOps Services à GitHub Enterprise Server, votre serveur GitHub Enterprise Server doit être suffisamment accessible à partir d’Internet. Assurez-vous qu’Azure DNS peut résoudre le nom de votre serveur GitHub Enterprise et que votre pare-feu autorise l’accès à partir des adresses IP du centre de données Azure. Pour déterminer la plage d’adresses IP, consultez Plages d’adresses IP du centre de données Microsoft Azure. Un message d’erreur courant rencontré en cas de problèmes de connectivité est le suivant :

Impossible de résoudre le nom distant : « github-enterprise-server.contoso.com »

Si vous rencontrez cette erreur, vérifiez que votre serveur est accessible. Pour plus d’informations, consultez Forum aux questions sur Azure DNS.

  1. Sélectionnez Paramètres de projet>Connexions GitHub>GitHub Enterprise Server s’il s’agit de votre première connexion.

    First connection, choose GitHub Enterprise Server.

    Ou, dans la boîte de dialogue Nouvelle connexion GitHub, choisissez GitHub Enterprise Server.

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

  2. Sélectionnez la méthode d'authentification.

    Screenshot showing authentication method dialog.

    Se connecter avec OAuth

    Choisissez la configuration que vous avez définie à l’étape 4 d’Inscrire votre configuration OAuth dans Azure DevOps Services, puis Se connecter.

    Screenshot of New GitHub Enterprise connection, OAuth connection dialog.

    Connexion avec un jeton d’accès personnel

    Entrez l’URL de votre serveur GitHub Enterprise et les informations d’identification de jeton d’accès personnel reconnues par ce serveur. Puis choisissez Se connecter.

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

    Se connecter avec le nom d’utilisateur et le mot de passe

    Entrez l’URL de votre serveur GitHub Enterprise et les informations d’identification du compte d’administrateur reconnues par ce serveur, puis choisissez Se connecter.

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

  3. La boîte de dialogue répertorie tous les dépôts pour lesquels vous disposez de droits d’administration GitHub. Vous pouvez basculer entre Les miens et Tous pour déterminer si d’autres personnes apparaissent, puis vérifier celles que vous souhaitez ajouter. Lorsque vous avez terminé, sélectionnez Enregistrer.

    Screenshot of repositories listed.

    Conseil

    Vous pouvez uniquement créer une connexion aux dépôts définis sous une organisation GitHub. Pour connecter un projet à d’autres dépôts définis dans une autre organisation GitHub, vous devez ajouter une autre connexion.

  4. Si c’est la première fois que vous vous connectez à un compte ou une organisation GitHub depuis Azure Boards, vous devez également installer l’application Azure Boards pour GitHub. Confirmez la connexion précédemment évoquée dans cet article.

Résoudre les problèmes de connexion

L’intégration d’Azure Boards-GitHub s’appuie sur différents protocoles d’authentification pour prendre en charge la connexion. Les modifications apportées à l’étendue d’autorisation ou aux informations d’authentification d’un utilisateur peuvent entraîner la révocation des dépôts GitHub connectés à Azure Boards.

Pour obtenir une vue d’ensemble de l’intégration prise en charge par l’application Azure Boards pour GitHub, consultez Intégration d’Azure Boards-GitHub.

Options d’authentification prises en charge

Les options d’authentification suivantes sont prises en charge en fonction de la plateforme GitHub à laquelle vous souhaitez vous connecter.

Plateforme

GitHub.com

GitHub Enterprise Server

Azure DevOps Services

  • Compte d’utilisateur GitHub.com
  • Un jeton d’accès personnel (PAT)
  • OAuth
  • Jeton d’accès personnel
  • Nom d’utilisateur plus mot de passe

Azure DevOps Server 2020

Non applicable

  • Jeton d’accès personnel
  • Nom d’utilisateur plus mot de passe

Azure DevOps Server 2019

Non applicable

  • OAuth
  • Jeton d’accès personnel
  • Nom d’utilisateur plus mot de passe

Notes

Avec l’application Azure Boards pour GitHub, Azure Boards et Azure DevOps Services prennent en charge l’intégration aux dépôts GitHub.com et GitHub Enterprise Server. Azure DevOps Server 2019 et versions ultérieures prennent en charge l’intégration aux référentiels GitHub Enterprise Server uniquement. L’intégration à d’autres référentiels Git n’est pas prise en charge.

Accorder l’accès à l’organisation Azure Boards

Si l’intégration entre Azure Boards et GitHub ne fonctionne pas comme prévu, vérifiez que vous avez accordé l’accès à l’organisation.

  1. À partir du portail web GitHub, ouvrez Paramètres dans le menu de votre profil.
    Screenshot of open profile, choose Settings.

  2. Sélectionnez Applications sous Intégrations>Applications OAuth autorisées>Azure Boards.

  3. Sous Accès de l’organisation, résolvez tous les problèmes qui peuvent apparaître. Choisissez Accorder pour accorder l’accès à toutes les organisations qui indiquent avoir une Demande d’accès en attente.

    Screenshot of Organization access with organizations without access.

Résoudre les problèmes d’accès

Lorsque la connexion Azure Boards à GitHub n’a plus accès, elle affiche un état d’alerte dans l’interface utilisateur avec un X rouge. Pointez sur l’alerte ; elle indique que les informations d’identification ne sont plus valides. Pour corriger le problème, supprimez la connexion et recréez une nouvelle connexion.

Screenshot of failed connection.

Pour résoudre ce problème, procédez comme suit :

  • Si la connexion utilise OAuth :

    • L’accès à l’application Azure Boards a été refusé pour l’un des dépôts.

    • GitHub peut être indisponible/inaccessible. Cette indisponibilité peut être due à une panne dans le service ou à un problème d’infrastructure/de réseau local. Vous pouvez vérifier l’état du service à partir des liens suivants :

      Supprimez et recréez la connexion au référentiel GitHub. Cette connexion recréée amène GitHub à demander une nouvelle autorisation pour Azure Boards.

  • Si la connexion utilise un jeton d’accès personnel :

    • Le jeton d’accès personnel a peut-être été révoqué ou les étendues d’autorisation requises ont été modifiées et sont insuffisantes.

    • L’utilisateur a peut-être perdu les autorisations d’administrateur sur le dépôt GitHub.

      Recréez le PAT et assurez-vous que la portée du jeton inclut les autorisations requises : repo, read:user, user:email, admin:repo_hook.

Résoudre une connexion GitHub Enterprise Server rompue

Si vous avez migré d’Azure DevOps Server vers Azure DevOps Services avec une connexion GitHub Enterprise Server existante, votre connexion existante ne fonctionnera pas comme prévu. Les mentions d’éléments de travail dans GitHub peuvent être retardées ou ne jamais s’afficher dans Azure DevOps Services. Ce problème se produit car l’URL de rappel associée à GitHub n’est plus valide.

Tenez compte des résolutions suivantes :

  • Supprimer et recréer la connexion : supprimez et recréez la connexion au dépôt GitHub Enterprise Server. Suivez la séquence d’étapes fournie dans Se connecter à partir d’Azure Boards documentation.

  • Corriger l’URL du webhook : accédez à la page des paramètres du dépôt GitHub et modifiez l’URL du webhook pour pointer vers l’URL de l’organisation Azure DevOps Services migrée : https://dev.azure.com/{OrganizationName}/_apis/work/events?api-version=5.2-preview

Connexion à plusieurs organisations Azure DevOps

Si vous connectez votre dépôt GitHub à deux projets ou plus définis dans plusieurs organisations Azure DevOps, comme dev.azure.com/Contoso et dev.azure.com/Fabrikam, vous pouvez obtenir des résultats inattendus lors de l’utilisation de mentions AB# pour lier des éléments de travail. Ce problème se produit car les ID d’élément de travail ne sont pas uniques dans les organisations Azure DevOps. Par conséquent, AB#12 peut faire référence à un élément de travail dans l’organisation Contoso ou Fabrikam. Par conséquent, lorsqu’un élément de travail est mentionné dans un message de validation ou une demande de tirage, les deux organisations tentent de créer un lien vers un élément de travail avec un ID correspondant (le cas échéant).

En général, un utilisateur a l’intention qu’une mention AB# soit liée à un seul élément de travail dans l’un des projets. Toutefois, si un élément de travail du même ID existe dans les deux comptes, des liens sont créés pour les deux éléments de travail, ce qui va probablement entraîner une confusion.

Actuellement, il n’existe aucun moyen de contourner ce problème. Nous vous recommandons donc de connecter un dépôt GitHub unique à une seule organisation Azure DevOps.

Remarque

Lorsque vous créez la connexion à l’aide de l’application Azure Boards pour GitHub, l’application vous empêche de vous connecter à deux organisations différentes. Si un référentiel GitHub est par erreur connecté à la mauvaise organisation Azure DevOps, vous devez contacter le propriétaire de cette organisation pour supprimer la connexion avant de pouvoir ajouter le référentiel à l’organisation Azure DevOps appropriée.

Mettre à jour les définitions XML pour certains types d’éléments de travail

Si votre organisation utilise le modèle de processus XML hébergé ou local pour personnaliser l’expérience de suivi des travaux et que vous souhaitez lier et afficher les types de liens GitHub à partir de la section Développement dans les formulaires d’éléments de travail, vous devez mettre à jour les définitions XML des types d’éléments de travail.

Par exemple, si vous souhaitez lier des récits utilisateur et des bogues aux validations et aux demandes de tirage GitHub à partir de la section Développement, vous devez mettre à jour les définitions XML pour les récits utilisateur et les bogues.

Suivez la séquence de tâches fournie dans Modèle de processus XML hébergé pour mettre à jour les définitions XML. Pour chaque type d’élément de travail, recherchez la section Group Label="Development" et ajoutez les deux lignes suivantes dans la syntaxe de code suivante pour prendre en charge les types de liens externes : Validation GitHub et Demande de tirage GitHub.

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

Lorsqu’elle est mise à jour, la section doit apparaître comme suit.

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

Étapes suivantes

Lier les validations et les demandes de tirage (pull requests) GitHub aux éléments de travail