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 Packages 不适用于使用旧版按仓库计划的帐户所拥有的私有仓库。 此外,使用旧版按存储库计划的帐户无法访问支持精细权限的注册表,因为这些帐户按存储库计费。 有关支持精细权限的注册表的列表,请参阅“关于 GitHub Packages 的权限”。 有关详细信息,请参阅“GitHub 的计划”。

向 GitHub Packages 验证

GitHub Packages 仅支持使用 personal access token (classic) 进行身份验证。 有关详细信息,请参阅“管理个人访问令牌”。

需要访问令牌才能发布、安装和删除专用、内部和公共包。

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

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

  • GITHUB_TOKEN 发布与工作流存储库相关联的包。
  • 范围至少为 read:packages 的 personal access token (classic),用于安装与其他专用存储库(GITHUB_TOKEN 无法访问)关联的包。

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

使用 personal access token

进行身份验证

必须使用具有适当范围的 personal access token (classic) 才可在 GitHub Packages 中发布和安装包。 有关详细信息,请参阅“GitHub Packages 简介”。

通过编辑 ~/.m2/settings.xml 文件以包含 personal access token (classic),可以使用 Apache Maven 向 GitHub Packages 进行身份验证。 如果 ~/.m2/settings.xml 文件不存在,请新建该文件。

servers 标记中,添加一个带有 id 的子 server 标记,将“USERNAME”替换为 GitHub 用户名,并将“TOKEN”替换为 personal access token。

repositories 标记中,通过将存储库的 id 映射到在包含凭据的 server 标记中添加的 id 来对该存储库进行配置。 将 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.pkg.github.com/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 元素,将 OWNER 替换为拥有该存储库的个人帐户或组织的名称,并将 REPOSITORY 替换为包含项目的存储库的名称。

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

    mvn deploy
    

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

安装包

要从 GitHub Packages 安装 Apache Maven 包,请编辑 pom.xml 文件以包含该包作为依赖项。 如果要从指定存储库所有者的任何存储库安装包,请使用存储库 URL,例如 https://maven.pkg.github.com/OWNER/*。 有关在项目中使用 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
    

延伸阅读