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.

    Capture d’écran de l’ouverture de Paramètres du projet>Connexions GitHub.

  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.

    Capture d’écran de la première connexion avec les informations d’identification GitHub.

    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 sont déjà connectés à Azure Boards, le message suivant s'affiche.

    Capture d’écran du message où il n’existe plus de dépôts auxquels se connecter.

  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 car votre compte GitHub est 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.

    Capture d'écran montrant les référentiels GitHub.

    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.

    Capture d’écran du message où il n’existe plus de dépôts auxquels se connecter.

  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.

    Capture d'écran montrant la confirmation des référentiels GitHub.

  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.

Capture d'écran de la liste des référentiels connectés.

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.

    Capture d'écran de la boîte de dialogue Nouvelle connexion GitHub, sélectionnant le jeton d'accès personnel.

    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.

    Capture d'écran montrant le PAT saisi.

  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.

    Capture d'écran de la connexion au serveur GitHub Enterprise.

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

    Capture d'écran montrant la séquence pour la nouvelle application OAuth.

  3. Entrez les informations d'enregistrement.

    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

    Capture d'écran montrant l'application à enregistrer.

  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.

    Capture d'écran de l'ID client et du secret client pour l'application OAuth enregistrée.

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.

    Capture d'écran des paramètres de l'organisation ouverte, configurations OAuth.

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

    Boîte de dialogue des configurations OAuth.

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.

    Tout d’abord, choisissez GitHub Enterprise Server.

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

    Capture d'écran de la boîte de dialogue Nouvelle connexion GitHub, choisissez GitHub Enterprise Server.

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

    Capture d'écran montrant la boîte de dialogue de la méthode d'authentification.

    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.

    Capture d'écran de la nouvelle connexion GitHub Enterprise, dialogue de connexion OAuth.

    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.

    Capture d'écran de la nouvelle connexion GitHub Enterprise, boîte de dialogue de connexion au jeton d'accès personnel.

    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.

    Capture d'écran de la connexion à New GitHub Enterprise, boîte de dialogue de connexion au nom d'utilisateur.

  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.

    Capture d'écran des référentiels listés.

    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é un accès à l'organisation.

  1. À partir du portail web GitHub, ouvrez Paramètres dans le menu de votre profil.
    Capture d’écran de l’ouverture du profil, choisissez Paramètres.

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

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

    Capture d’écran de l’accès de l’organisation avec des organisations sans accès.

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.

Capture d’écran de la connexion ayant échoué.

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 PAT pourrait être révoqué ou les portées de permission requises ont changé et sont insuffisantes.

    • L'utilisateur n'a peut-être pas les permissions d'administrateur sur le référentiel 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 existante à GitHub Enterprise Server, votre connexion existante ne fonctionne pas comme prévu. Les mentions d'éléments de travail dans GitHub peuvent être retardées ou ne jamais apparaître 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.

  • Corrigez l'URL du webhook : Accédez à la page des paramètres du référentiel de GitHub et modifiez l'URL du webhook, en pointant vers l'URL de l'organisation Azure DevOps migrée : https://dev.azure.com/{OrganizationName}/_apis/work/events?api-version=5.2-preview

Connexion à plusieurs organisations Azure DevOps

Si vous connectez votre référentiel GitHub à deux projets ou plus définis dans plusieurs organisations Azure DevOps, par exemple dev.azure.com/Contoso et dev.azure.com/Fabrikam, vous risquez d'obtenir des résultats inattendus lorsque vous utilisez les mentions AB# établissant un lien avec les é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. Lorsqu'un élément de travail est mentionné dans un message de livraison ou une requête pull, les deux organisations peuvent tenter de créer un lien vers un élément de travail avec un identifiant correspondant s'il existe.

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

Mettez à jour les définitions XML pour les 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 du travail et que vous souhaitez établir un lien vers les types de liens GitHub et les afficher à partir de la section Développement dans les formulaires 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" />

Une fois mise à jour, la section devrait 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>

FAQ (Foire aux questions)

Q : Certains de mes utilisateurs dans Azure DevOps ont des identités GitHub. Dois-je les ajouter en tant que nouveaux utilisateurs GitHub dans mon organisation ?

R : Non. Demandez à vos utilisateurs de se déconnecter, puis, à partir d'une nouvelle session de navigation, de se reconnecter à l'organisation avec leurs identifiants GitHub. Cette action permettra d'établir que les utilisateurs ont des identités GitHub valides.

Q : Je suis administrateur d'une organisation et j'ai activé la stratégie qui permet d'inviter des utilisateurs GitHub. Pourquoi ne puis-je pas inviter de nouveaux utilisateurs GitHub ?

R : Une fois le paramètre modifié, déconnectez-vous d'Azure DevOps, puis, à partir d'une nouvelle session de navigation, reconnectez-vous à l'organisation dev.azure.com/{organizationName} ou organizationName.visualstudio.com à l'aide de vos informations d'identification GitHub.

Q : Je me suis connecté avec mes identifiants GitHub, mais pourquoi ne puis-je pas inviter des utilisateurs GitHub ?

R : Seuls les administrateurs d'une organisation ou d'un projet peuvent inviter de nouveaux utilisateurs à rejoindre l'organisation. Il se peut que vous n'ayez pas la permission requise pour ajouter de nouveaux utilisateurs. Travaillez avec votre administrateur pour obtenir les bonnes permissions ou demandez-lui d'ajouter l'utilisateur pour vous.

Étapes suivantes

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