Skip to main content

使用 Apache Maven 注册表

您可以配置 Apache Maven 以将包发布到 GitHub Packages 并将存储在 GitHub Packages 上的包用作 Java 项目中的依赖项。

GitHub Packages 适用于 GitHub Free、GitHub Pro、面向组织的 GitHub Free、GitHub Team, GitHub Enterprise Cloud, GitHub Enterprise Server 3.0 或更高版本以及 GitHub AE。 有关升级 GitHub Enterprise Server 实例更多信息,请参阅“关于升级至新版本”和 升级助手以从你当前的发布版本中查找升级路径。

注意:这种包类型可能不适用于你的实例,因为站点管理员可以启用或禁用每种支持的包类型。 有关详细信息,请参阅“为企业配置包支持”。

向 GitHub Packages 验证

需要访问令牌才能发布、安装和删除包。

可使用个人访问令牌 (PAT) 向 GitHub Packages 或 GitHub Enterprise Server API 进行身份验证。 创建个人访问令牌时,可根据需要为令牌分配不同的作用域。 有关 PAT 的包相关范围的详细信息,请参阅“关于 GitHub Packages 的权限”。

要在 GitHub Actions 工作流程内向 GitHub Packages 注册表验证,您可以使用:

  • GITHUB_TOKEN 发布与工作流存储库相关联的包。
  • PAT 来安装与其他专用存储库(GITHUB_TOKEN 无法访问)相关联的包。

有关 GitHub Actions 工作流中使用的 GITHUB_TOKEN 的详细信息,请参阅“工作流中的身份验证”。

使用个人访问令牌进行身份验证

您必须使用具有适当范围的个人访问令牌才可在 GitHub Packages 中发布和安装。 有关详细信息,请参阅“关于 GitHub Packages”。

通过编辑 ~/.m2/settings.xml 文件以包含个人访问令牌,可以使用 Apache Maven 向 GitHub Packages 进行身份验证。 如果 ~/.m2/settings.xml 文件不存在,请新建该文件。

servers 标记中,添加一个带有 id 的子 server 标记,将“USERNAME”替换为 GitHub 用户名,并将“TOKEN”替换为个人访问令牌。

repositories 标记中,通过将存储库的 id 映射到在包含凭据的 server 标记中添加的 id 来对该存储库进行配置。 将 HOSTNAME 替换为 your GitHub Enterprise Server instance 的主机名,并将 OWNER 替换为拥有该存储库的用户或组织帐户的名称。 由于不支持大写字母,因此,即使您的 GitHub 用户或组织名称中包含大写字母,也必须对仓库所有者使用小写字母。

如果要与多个存储库交互,可以将每个存储库添加到 repositories 标记中独立的子 repository,将每个存储库的 id 映射到 servers 标记中的凭据。

GitHub Packages 支持 Apache Maven 的 SNAPSHOT 版本。 要使用 GitHub Packages 存储库下载 SNAPSHOT 工件,请在所用项目的 POM 或 ~/.m2/settings.xml 文件中启用 SNAPSHOTS。

如果实例启用了子域隔离:

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

如果实例禁用了子域隔离:

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

发布包

默认情况下,GitHub 将包发布到名称与包相同的现有仓库中。 例如,GitHub 会将名为 com.example:test 的包发布到名为 OWNER/test 的存储库中。

如果要将多个包发布到同一存储库,可以在 pom.xml 文件的 <distributionManagement> 元素中包含该存储库的 URL。 GitHub 将根据该字段匹配仓库。 由于存储库名称也是 distributionManagement 元素的一部分,因此将多个包发布到同一存储库无需额外步骤。

有关创建包的详细信息,请参阅 maven.apache.org 文档

  1. 编辑位于包目录中的 pom.xml 文件的 distributionManagement 元素,将 HOSTNAME 替换为 your GitHub Enterprise Server instance 的主机名,将 OWNER 替换为拥有该存储库的用户或组织帐户的名称,并将 REPOSITORY 替换为包含项目的存储库的名称。

    如果您的实例启用了子域隔离功能:

    <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

在发布包后,您可以在 GitHub 上查看该包。 有关详细信息,请参阅“查看包”。

安装包

要从 GitHub Packages 安装 Apache Maven 包,请编辑 pom.xml 文件以包含该包作为依赖项。 如果要从多个存储库安装包,请为每个存储库添加 repository 标记。 有关在项目中使用 pom.xml 文件的详细信息,请参阅 Apache Maven 文档中的“POM 简介”。

  1. 向 GitHub Packages 验证。 有关详细信息,请参阅“向 GitHub Packages 进行身份验证”。

  2. 将包依赖项添加到项目 pom.xml 文件的 dependencies 元素,将 com.example:test 替换为包。

    <dependencies>
      <dependency>
        <groupId>com.example</groupId>
        <artifactId>test</artifactId>
        <version>1.0.0-SNAPSHOT</version>
      </dependency>
    </dependencies>
    
  3. 安装此包。

    $ mvn install

延伸阅读