Skip to main content

Utilisation du registre Apache Maven

Vous pouvez configurer Apache Maven pour qu’il publie des packages dans GitHub Packages et utilise les packages stockés dans GitHub Packages comme dépendances dans un projet Java.

GitHub Packages est disponible avec GitHub Free, GitHub Pro, GitHub Free pour les organisations, GitHub Team, GitHub Enterprise Cloud, GitHub Enterprise Server 3.0 ou version ultérieure et GitHub AE. Pour plus d’information sur la mise à niveau de votre instance GitHub Enterprise Server, consultez « À propos des mises à niveau vers de nouvelles versions » et reportez-vous à l’Upgrade assistant pour trouver le chemin de mise à niveau à partir de votre version actuelle.

Remarque : Ce type de package peut ne pas être disponible pour votre instance, car les administrateurs de site peuvent activer ou désactiver chaque type de package pris en charge. Pour plus d’informations, consultez « Configuration de la prise en charge des packages pour votre entreprise ».

Authentification auprès de GitHub Packages

Vous avez besoin d’un jeton d’accès pour publier, installer et supprimer des packages privés, internes et publics.

Vous pouvez utiliser un personal access token pour vous authentifier sur GitHub Packages ou l’API GitHub Enterprise Server. Quand vous créez un personal access token, vous pouvez l’attribuer à différentes étendues selon vos besoins. Pour plus d’informations sur les étendues liées aux packages pour un personal access token, consultez « À propos des autorisations pour les packages GitHub ».

Pour vous authentifier sur un registre GitHub Packages dans un workflow GitHub Actions, vous pouvez utiliser :

  • GITHUB_TOKEN pour publier des packages associés au dépôt du workflow.
  • un personal access token avec au moins l’étendue read:packages pour installer des packages associés à d’autres dépôts privés (auxquels GITHUB_TOKEN ne peut pas accéder).

Pour plus d’informations sur le GITHUB_TOKEN utilisé dans les workflows GitHub Actions, consultez « Authentification dans un workflow ».

Authentification avec un personal access token

Vous devez utiliser un personal access token avec les étendues appropriées pour publier et installer des packages dans GitHub Packages. Pour plus d’informations, consultez « À propos de GitHub Packages ».

Vous pouvez vous authentifier auprès de GitHub Packages avec Apache Maven en modifiant votre fichier ~/.m2/settings.xml pour y inclure votre personal access token. Créez un fichier ~/.m2/settings.xml s’il n’existe pas encore.

Dans l’étiquette servers, ajoutez une étiquette server enfant avec un id, en remplaçant USERNAME par votre nom d’utilisateur GitHub et TOKEN par votre personal access token.

Dans la balise repositories, configurez un dépôt en mappant l’id du dépôt à l’id que vous avez ajouté dans la balise server contenant vos informations d’identification. Remplacez HOSTNAME par le nom d’hôte de your GitHub Enterprise Server instance et OWNER par le nom de l’utilisateur ou du compte d’organisation qui est propriétaire du dépôt. Étant donné que les lettres majuscules ne sont pas prises en charge, vous devez utiliser des lettres minuscules pour le propriétaire du dépôt, même si le nom d’utilisateur ou d’organisation GitHub contient des lettres majuscules.

Si vous voulez interagir avec plusieurs dépôts, vous pouvez ajouter chaque dépôt à des enfants repository distincts dans la balise repositories, en mappant l’id de chacun des dépôts aux informations d’identification dans la balise servers.

GitHub Packages prend en charge les versions SNAPSHOT d’Apache Maven. Pour utiliser le dépôt GitHub Packages afin de télécharger les artefacts SNAPSHOT, activez SNAPSHOTS dans le POM du projet consommateur ou de votre fichier ~/.m2/settings.xml.

Si l’isolation de sous-domaine est activée pour votre instance :

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">

  <activeProfiles>
    <activeProfile>github</activeProfile>
  </activeProfiles>

  <profiles>
    <profile>
      <id>github</id>
      <repositories>
        <repository>
          <id>central</id>
          <url>https://repo1.maven.org/maven2</url>
        </repository>
        <repository>
          <id>github</id>
          <url>https://maven.HOSTNAME/OWNER/REPOSITORY</url>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </repository>
      </repositories>
    </profile>
  </profiles>

  <servers>
    <server>
      <id>github</id>
      <username>USERNAME</username>
      <password>TOKEN</password>
    </server>
  </servers>
</settings>

Si l’isolation de sous-domaine est désactivée pour votre instance :

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">

  <activeProfiles>
    <activeProfile>github</activeProfile>
  </activeProfiles>

  <profiles>
    <profile>
      <id>github</id>
      <repositories>
        <repository>
          <id>central</id>
          <url>https://repo1.maven.org/maven2</url>
        </repository>
        <repository>
          <id>github</id>
          <url>HOSTNAME/_registry/maven/OWNER/REPOSITORY</url>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </repository>
      </repositories>
    </profile>
  </profiles>

  <servers>
    <server>
      <id>github</id>
      <username>USERNAME</username>
      <password>TOKEN</password>
    </server>
  </servers>
</settings>

Publication d’un package

Par défaut, GitHub publie le package dans un dépôt existant portant le même nom que le package. Par exemple, GitHub va publier un package nommé com.example:test dans un dépôt appelé OWNER/test.

Si vous souhaitez publier plusieurs packages sur le même dépôt, vous pouvez inclure l’URL du dépôt dans l’élément <distributionManagement> du fichier pom.xml. GitHub va établir la correspondance avec le dépôt en fonction de ce champ. Comme le nom du dépôt fait également partie de l’élément distributionManagement, il n’y a pas d’autre étape pour publier plusieurs packages sur le même dépôt.

Pour plus d’informations sur la création d’un package, consultez la documentation maven.apache.org.

  1. Modifiez l’élément distributionManagement du fichier pom.xml qui se trouve dans votre répertoire de packages, en remplaçant HOSTNAME par le nom d’hôte de your GitHub Enterprise Server instance, OWNER par le nom de l’utilisateur ou du compte d’organisation propriétaire du dépôt et REPOSITORY par le nom du dépôt contenant votre projet.

    Si l’isolation de sous-domaine est activée pour votre instance :

    <distributionManagement>
       <repository>
         <id>github</id>
         <name>GitHub OWNER Apache Maven Packages</name>
         <url>https://maven.HOSTNAME/OWNER/REPOSITORY</url>
       </repository>
    </distributionManagement>
    

    If your instance has subdomain isolation disabled:

    <distributionManagement>
       <repository>
         <id>github</id>
         <name>GitHub OWNER Apache Maven Packages</name>
         <url>https://HOSTNAME/_registry/maven/OWNER/REPOSITORY</url>
       </repository>
    </distributionManagement>
    
  2. Publish the package.

    $ mvn deploy

Après avoir publié un package, vous pouvez l’afficher sur GitHub. Pour plus d’informations, consultez « Affichage de packages ».

Installation d’un package

Pour installer un package Apache Maven à partir de GitHub Packages, modifiez le fichier pom.xml pour y inclure le package en tant que dépendance. Si vous voulez installer des packages à partir de plusieurs dépôts, ajoutez une balise repository pour chacun d’eux. Pour plus d’informations sur l’utilisation d’un fichier pom.xml dans votre projet, consultez « Présentation du POM » dans la documentation Apache Maven.

  1. Authentifiez-vous sur GitHub Packages. Pour plus d’informations, consultez « Authentification auprès de GitHub Packages ».

  2. Ajoutez les dépendances de package à l’élément dependencies du fichier pom.xml de votre projet, en remplaçant com.example:test par votre package.

    <dependencies>
      <dependency>
        <groupId>com.example</groupId>
        <artifactId>test</artifactId>
        <version>1.0.0-SNAPSHOT</version>
      </dependency>
    </dependencies>
    
  3. Installez le package.

    $ mvn install

Pour aller plus loin