使用 Gradle 构建和测试 Java

你可以在 GitHub Actions 中创建持续集成 (CI) 工作流程，以使用 Gradle 构建和测试 Java 项目。

本文内容

Note

GitHub Enterprise Server 目前不支持 GitHub 托管的运行器。 可以在 GitHub public roadmap 上查看有关未来支持计划的更多信息。

简介

本指南介绍如何使用 Gradle 构建系统为 Java 项目创建执行持续集成 (CI) 的工作流程。 你创建的工作流程将允许你查看拉取请求提交何时会在默认分支上导致构建或测试失败； 这个方法可帮助确保你的代码始终是健康的。 可以扩展 CI 工作流以缓存文件并从工作流运行中上传项目。

GitHub 托管的运行器具有预安装了软件的工具缓存，包括 Java 开发工具包 (JDK) 和 Gradle。 有关 JDK 和 Gradle 的软件和预安装版本列表，请参阅“使用 GitHub 托管的运行器”。

先决条件

你应该熟悉 YAML 和 GitHub Actions 的语法。 有关详细信息，请参阅：

建议你对 Java 和 Gradle 框架有个基本的了解。 有关详细信息，请参阅 Gradle 用户手册。

在 GitHub Enterprise Server 上使用自托管的运行器

在包含自承载运行器的 GitHub Enterprise Server 上使用设置操作（例如 actions/setup-LANGUAGE）时，可能需要在无法访问 Internet 的运行器上设置工具缓存。 有关详细信息，请参阅“在未接入互联网的自托管运行器上设置工具缓存”。

使用 Gradle 工作流模板

若要快速开始使用，请将工作流模板添加到存储库的 .github/workflows 目录。

GitHub 为 Gradle 提供了一个工作流模板，适用于大多数带有 Gradle 的 Java 项目。 本指南的后续部分提供了如何自定义此工作流模板的示例。

  1. 在 GitHub 上，导航到存储库的主页面。

  2. 在存储库名称下，单击 “操作”。

    “github/docs”存储库的选项卡的屏幕截图。 “操作”选项卡以橙色边框突出显示。

  3. 如果存储库中已有工作流，请单击“新建工作流”。

  4. “选择工作流”页面显示一系列推荐的工作流模板。 搜索“Java with Gradle”。

  5. 在“Java 与 Gradle”工作流上，单击“配置”。

    如果未找到“基于 Gradle 的 Java”工作流模板，请将以下工作流代码复制到存储库的 .github/workflows 目录中名为 gradle.yml 的新文件。

    YAML
    name: Java CI with Gradle

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Set up JDK 17
      uses: actions/setup-java@v4
      with:
        java-version: '17'
        distribution: 'temurin'

    - name: Setup Gradle
      uses: gradle/actions/setup-gradle@af1da67850ed9a4cedd57bfd976089dd991e2582 # v4.0.0

    - name: Build with Gradle
      run: ./gradlew build

此工作流程执行以下步骤：

  1. 检出项目仓库的副本。

  2. 设置 Java JDK。

  3. 设置 Gradle 环境。 gradle/actions/setup-gradle 操作负责工作流运行之间的缓存状态，并提供所有 Gradle 执行的详细摘要。

  4. “使用 Gradle 进行生成”步骤使用 Gradle 包装器执行 build 任务。

  5. 根据需要编辑工作流。 例如更改 Java 版本。

    Note

    • 此工作流模板包含未通过 GitHub 认证的操作。 第三方提供的操作受单独的服务条款、隐私政策和支持文档管辖。
    • 如果使用来自第三方的操作，则应使用提交 SHA 指定的版本。 如果操作已被修改，并且需要使用较新版本，则需要更新 SHA。 可以通过引用标记或分支来指定版本，但操作可能会在没有事先警告的情况下更改。 有关详细信息，请参阅“GitHub Actions 的安全强化”。

  6. 单击“提交更改”。

指定 Java 版本和体系结构

工作流模板将 PATH 设置为包含 OpenJDK 8，用于 x64 平台。 如果要使用不同的 Java 版本或面向不同的体系结构（x64 或 x86），可以使用 setup-java 操作选择不同的 Java 运行时环境。

例如，要使用由 Adoptium 提供的 11 版本的 JDK，用于 x64 平台，可以使用 setup-java 操作并将 java-version、distribution 和 architecture 参数配置为 '11'、'temurin' 和 x64。

YAML
steps:
  - uses: actions/checkout@v4
  - name: Set up JDK 11 for x64
    uses: actions/setup-java@v4
    with:
      java-version: '11'
      distribution: 'temurin'
      architecture: x64

有关详细信息，请参阅 setup-java 操作。

构建和测试代码

你可以使用与本地相同的命令来构建和测试代码。

默认情况下，工作流模板将运行 build 任务。 在默认的 Gradle 配置中，此命令将下载依赖项、构建类别、运行测试并将类别打包为可分发格式，如 JAR 文件。

如果使用不同的命令来构建项目，或者想要使用不同的任务，则可以指定这些命令。 例如，你可能想要运行在 ci.gradle 文件中配置的 package 任务。

YAML
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-java@v4
    with:
      java-version: '17'
      distribution: 'temurin'

  - name: Setup Gradle
    uses: gradle/actions/setup-gradle@af1da67850ed9a4cedd57bfd976089dd991e2582 # v4.0.0

  - name: Build with Gradle
    run: ./gradlew -b ci.gradle package

缓存依赖项

可以缓存生成依赖项以加快工作流运行。 成功运行后，gradle/actions/setup-gradle 会缓存 Gradle 用户主目录的重要部分。 在将来的作业中，将还原缓存，这样就不需要重新编译构建脚本，也不需要从远程包存储库下载依赖项。

使用 gradle/actions/setup-gradle 操作时，默认启用缓存。 有关详细信息，请参阅 gradle/actions/setup-gradle。

将工作流数据打包为构件

构建成功且测试通过后，你可能想要上传生成的 Java 包作为构件。 这会将构建的包存储为工作流程运行的一部分，并允许你下载它们。 构件可帮助你在拉取请求合并之前在本地环境中测试并调试它们。 有关详细信息，请参阅“从工作流存储和共享数据”。

Gradle 通常会在 build/libs 目录中创建 JAR、EAR 或 WAR 等输出文件。 可以使用 upload-artifact 操作上传该目录的内容。

YAML
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-java@v4
    with:
      java-version: '17'
      distribution: 'temurin'

  - name: Setup Gradle
    uses: gradle/actions/setup-gradle@af1da67850ed9a4cedd57bfd976089dd991e2582 # v4.0.0

  - name: Build with Gradle
    run: ./gradlew build

  - name: Upload build artifacts
    uses: actions/upload-artifact@v3
    with:
      name: Package
      path: build/libs