GitHub Maven 插件使用技术文档

1. 安装指南

GitHub Maven 插件是用于与 GitHub API 集成的插件集合。这些插件基于 GitHub API v3 以及 GitHub Java 库构建。

要使用这些插件，您需要首先确保您的环境中已经安装了 Maven。可以从 Maven 官方网站下载最新版本的 Maven，并按照官方文档进行安装。

安装完成后，您可以从 Maven Central 仓库获取已发布的插件构建版本。

2. 项目使用说明

GitHub Maven 插件支持多种配置选项，这些选项可以在您的项目 POM 文件或 settings.xml 文件中设置。具体设置取决于您是想全局配置还是针对每个项目单独配置。

所有 GitHub Maven 插件都支持以下核心配置元素：

• host (github.global.host): GitHub API 调用的域名，默认为 api.github.com
• oauth2Token (github.global.oauth2Token): API 认证的 OAuth2 访问令牌
• userName (github.global.userName): API 认证的 GitHub 用户名
• password (github.global.password): API 认证的 GitHub 密码
• server (github.global.server): settings.xml 中 server 元素的 ID
• repositoryName: 仓库名称
• repositoryOwner: 仓库拥有者

repositoryOwner 属性和 repositoryName 是可选的，如果没有指定，将会从以下属性推断：

• project.scm.url
• project.scm.connection
• project.scm.developerConnection
• project.url

认证示例

settings.xml 配置

使用用户名和密码：

<servers>
  <server>
    <id>github</id>
    <username>GitHubLogin</username>
    <password>GitHubPassw0rd</password>
  </server>
</servers>

使用 OAuth2 令牌：

<servers>
  <server>
    <id>github</id>
    <password>OAUTH2TOKEN</password>
  </server>
</servers>

pom.xml 配置

<properties>
  <github.global.server>github</github.global.server>
</properties>

3. 项目 API 使用文档

GitHub Maven 插件提供了多种插件，以下是一个具体插件的使用示例：Site 插件。

Site 插件

该插件用于将生成的文件提交到 GitHub 仓库的特定分支。此插件可以用来部署创建的 Maven 站点到 gh-pages 分支，以便作为 GitHub 项目页面静态服务。

配置

• branch: 将更新的分支引用
• message: 提交信息
• outputDirectory: 包含包含和排除模式的目录
• includes: 包含的模式
• excludes: 排除的模式
• path: 所有 blob 相对于仓库根目录的路径
• force (github.site.force): 是否强制更新引用
• merge (github.site.merge): 是否与当前树合并
• dryRun: 是否仅记录操作而不实际执行
• noJekyll: 是否创建 .nojekyll 文件

示例

在 pom.xml 文件中配置插件：

<build>
  <plugins>
    <plugin>
      <groupId>com.github.github</groupId>
      <artifactId>site-maven-plugin</artifactId>
      <version>0.12</version>
      <configuration>
        <message>Creating site for ${project.version}</message>
      </configuration>
      <executions>
        <execution>
          <goals>
            <goal>site</goal>
          </goals>
          <phase>site</phase>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

运行以下命令以提交创建的站点：

$ mvn site

4. 项目安装方式

GitHub Maven 插件的安装方式与常规 Maven 插件相同。您只需将插件添加到项目的 pom.xml 文件中即可。然后通过 Maven 的命令行工具执行相关命令，以使用插件的各项功能。确保在执行命令前已经正确配置了项目的依赖和插件。