GradleとGitHub・GitLabを連携する方法とCI/CDパイプライン構築のポイント

GradleとGitを組み合わせる際に知っておきたい基本（gradle.properties、gitignore、Wrapper）

GradleプロジェクトをGitで管理する際は、Gradle Wrapperのファイルをリポジトリに含めることが最も重要です。Wrapperがあれば、開発者やCI環境ごとにGradleを手動インストールする必要がなく、プロジェクト固有のGradleバージョンを全員が同じように使用できます。

Gradle WrapperをGit管理する理由と必須ファイル

Gradle Wrapperとは、プロジェクトが使用するGradleバージョンを固定し、必要に応じて自動取得する仕組みです。公式もGradle本体を手動インストールするよりWrapperの使用を推奨しています。

リポジトリにコミットすべきWrapper関連ファイルは以下のとおりです。

• gradlew：Linux/macOS用の実行スクリプト
• gradlew.bat：Windows用の実行スクリプト
• gradle/wrapper/gradle-wrapper.properties：Gradleバージョンの指定ファイル
• gradle/wrapper/gradle-wrapper.jar：Wrapperの実行に必要なJARファイル

これらのファイルをコミットしておくことで、クローンした直後から./gradlew buildのように同じバージョンでビルドできます。（出典：Gradle「Gradle Wrapper Basics」）

gradle.propertiesの役割とGit管理の考え方

gradle.propertiesは、Gradleのビルド設定をプロジェクト単位で記述するファイルです。JVMのメモリ設定やGradleデーモンの挙動、プロジェクト固有のプロパティなどを定義できます。

このファイルは基本的にGitで管理します。理由は、ビルドに必要な設定をチーム全体で共有する必要があるためです。ただし、APIキーやパスワードなどの機密情報を直接書くことは避けてください。機密情報は環境変数やCIのシークレット機能を使い、gradle.propertiesには環境変数を参照する形だけを記述するのが安全です。

.gitignoreの基本設定で余計なファイルを除外する

Gradleプロジェクトでは、ビルドのたびに生成されるファイルやディレクトリをGitの管理対象から除外する必要があります。代表的な除外対象は以下のとおりです。

• .gradle/：Gradleが生成する一時ファイルやキャッシュ
• build/：コンパイル済みクラスやJARなどの成果物

Gradleの公式ドキュメントやGitHubのテンプレートリポジトリでは、.gitignoreに.gradle/とbuild/を記載するのが一般的です。これにより、不要なファイルがコミットされるのを防ぎ、リポジトリを清潔に保てます。

GitHub ActionsでGradleビルドを実行する公式アクションの使い方

GitHub ActionsでGradleビルドを実行するには、gradle/actions/setup-gradleアクションを使うのが公式推奨です。このアクションはGradle User Homeのキャッシュ復元・保存、Wrapper検証、Build Scanリンクのキャプチャなどを自動で行います。旧アクションgradle/gradle-build-actionはアーカイブ済みのため、新規プロジェクトでは使用しないでください。

setup-gradleアクションの基本的な使い方

最小限のワークフローでは、actions/checkoutでコードを取得し、actions/setup-javaでJDKをインストールしてから、gradle/actions/setup-gradleを実行します。最後に./gradlew buildでビルドします。

name: Build
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 21
      - uses: gradle/actions/setup-gradle@v6
      - run: ./gradlew build

setup-gradleのgradle-version入力を省略するとwrapperがデフォルトとなり、リポジトリ内のWrapperを使用します。（出典：Gradle「Gradle on GitHub Actions」）

キャッシュ機能と注意点

setup-gradleはGradle User Home（~/.gradle）を自動的に保存・復元します。これにはGradle配布物、解決済み依存関係、ローカルビルドキャッシュが含まれます。デフォルトブランチへのpush時にキャッシュが書き込まれ、他のジョブは既存エントリから復元します。

注意点として、actions/setup-javaのcache: gradleオプションとsetup-gradleのキャッシュを併用しないでください。互いに干渉する可能性があります。キャッシュ管理はsetup-gradleに一本化しましょう。（出典：gradle/gradle-build-action README）

Build Scanの公開設定

Build ScanをGitHub Actions上で公開するには、setup-gradleに以下の入力を追加します。

• build-scan-publish: true
• build-scan-terms-of-use-url: "https://gradle.com/terms-of-service"
• build-scan-terms-of-use-agree: "yes"

これを設定すると、ジョブ内の全Gradle実行のBuild Scanが公開され、ビルドの問題分析やパフォーマンス確認がしやすくなります。GitHub Actionsは環境変数CI=trueを自動設定するため、Gradle側でCIを検知してBuild Scanを公開する条件分岐も可能です。（出典：Gradle「Gradle on GitHub Actions」）

要点：GitHub Actionsではgradle/actions/setup-gradle@v6を使い、JDKはsetup-javaで用意します。キャッシュはsetup-gradleに任せ、setup-javaのcache: gradleとは併用しません。

GitLab CI/CDでGradleパイプラインを構築するテンプレートの活用方法

GitLab CI/CDでGradleビルドを行うには、公式テンプレートGradle.gitlab-ci.ymlを出発点にするのが効率的です。ただし、テンプレートはそのまま使うのではなく、JDKバージョンの固定やGradle Wrapperの使用、キャッシュ設定をプロジェクトに合わせて調整することが推奨されます。

公式テンプレートの基本構成

GitLabの公式Gradle CIテンプレートは、以下のようにinclude文で読み込みます。

include:
  - template: Gradle.gitlab-ci.yml

このテンプレートはbuild、test、deployの3ステージを定義し、gradle:alpineイメージを使用します。多くのプロジェクトでは、特定のJDKを含むイメージに上書きし、Gradle Wrapperを使ってビルドする形にカスタマイズします。（出典：Gradle「Gradle on GitLab CI」）

最小限のパイプライン設定例

実用的なパイプラインでは、JDK入りのイメージを指定し、Gradleデーモンを無効化します。以下はeclipse-temurin:21イメージを使用する例です。

image: eclipse-temurin:21

variables:
  GRADLE_USER_HOME: "$CI_PROJECT_DIR/.gradle"
  GRADLE_OPTS: "-Dorg.gradle.daemon=false"

build:
  stage: build
  script:
    - ./gradlew --no-daemon build
  artifacts:
    when: always
    reports:
      junit: "**/build/test-results/test/TEST-*.xml"
    paths:
      - "**/build/reports"
    expire_in: 1 week

GRADLE_USER_HOMEを$CI_PROJECT_DIR内に置くことで、GitLabのキャッシュ可能・アップロード可能エリアに含まれます。また、reports: junitを指定すると、テスト結果がMRやパイプライン画面に直接表示されます。（出典：Gradle「Gradle on GitLab CI」）

キャッシュ戦略とBuild Scan公開

GitLab CIではキャッシュをキーで管理します。SaaS共有ランナーではWrapperのみのキャッシュ（gradle-wrapper.propertiesをキーにする）が推奨されます。大規模なキャッシュアーカイブのアップロードが節約効果を上回る場合があるためです。専用ランナーやセルフホスト環境では、完全なGradle User Homeキャッシュも選択肢になります。

Build Scanを公開するには、settings.gradleまたはsettings.gradle.ktsにDevelocityプラグインを適用し、CI実行時に利用規約に同意する設定を追加します。GitLab CIはCI=trueを自動設定するため、この環境変数でCI検出ができます。（出典：Gradle「Gradle on GitLab CI」）

要点：GitLab CIでは公式テンプレートを参考に、JDK入りイメージとGradle Wrapperを組み合わせます。デーモンを無効化し、SaaS共有ランナーではWrapperのみのキャッシュが推奨されます。

GitHub PackagesとGitLab Package RegistryへのGradle成果物の公開手順

Gradleの成果物を公開する方法は、GitHubとGitLabで異なります。GitHub PackagesはMavenリポジトリ形式で公開し、GitLab Package RegistryもMaven形式で公開します。どちらもmaven-publishプラグインを使いますが、リポジトリURLと認証方法が異なります。

GitHub Packagesへの公開手順

GitHub Packagesへ公開するには、maven-publishプラグインをbuild.gradleに適用し、公開リポジトリをhttps://maven.pkg.github.com/OWNER/REPOSITORYに設定します。

認証にはGitHub Actionsの環境変数を使用します。

• ユーザー名：GITHUB_ACTOR環境変数
• トークン：GITHUB_TOKENシークレット

公開コマンドは./gradlew publishです。GitHub Packagesはパブリックパッケージのストレージ・転送が無料で、プライベートパッケージの利用はプランに含まれます。なお、従来のper-repositoryプランを持つプライベートリポジトリではGitHub Packagesを利用できません。（出典：GitHub Docs「Publishing Java packages with Gradle」）

GitLab Package Registryへの公開手順

GitLab Package Registryへの公開は、プロジェクトレベルでのみ可能です。グループ・インスタンスレベルでは公開できません。認証トークンには以下が使えます。

• パーソナルアクセストークン（2FA使用時はapiスコープが必要）
• Deployトークン
• CI/CDジョブトークン（CI_JOB_TOKEN）

CI/CDパイプラインで公開する場合は、CI_JOB_TOKENを使うのが最も安全です。Gradleのリポジトリ設定で、ヘッダー認証としてJob-TokenをCI_JOB_TOKENの値で送信します。エンドポイントはhttps://gitlab.example.com/api/v4/projects/<project_id>/packages/mavenの形式です。（出典：GitLab Docs「Maven packages in the Package Registry」）

公開時の注意点と比較

GitLab Package Registryでは、同一の名前・バージョンのパッケージを公開すると、既存パッケージにファイルが追加されます。上書きではなく追加される点に注意が必要です。また、Maven Centralへのリクエスト転送機能はデフォルトでは無効です。

要点：GitHub PackagesはGITHUB_TOKENで認証し、GitLab Package RegistryはCI_JOB_TOKENで認証します。GitLabはプロジェクトレベル限定の公開で、重複公開時はファイルが追加される点に注意が必要です。

GradleをGitで管理するためのgitignore設定とGradleバージョン指定の作法

GradleプロジェクトをGitで適切に管理するには、.gitignoreで生成物を除外し、GradleバージョンはWrapperのgradle-wrapper.propertiesで明示的に固定することが基本です。これにより、チーム内やCI環境でのビルド再現性が確保されます。

.gitignoreに記載すべきGradle関連の除外項目

GradleプロジェクトでGit管理から除外すべき主な項目は以下のとおりです。

• .gradle/：Gradleがプロジェクト内に生成するキャッシュや一時ファイル
• build/：コンパイル済みクラス、JAR、テストレポートなどのビルド成果物

これらのディレクトリは./gradlew buildなどの実行で自動的に再生成されるため、コミットする必要はありません。除外することでリポジトリサイズを抑え、不要な差分を防げます。

Gradleバージョン指定はgradle-wrapper.propertiesで行う

Gradleバージョンの指定は、gradle/wrapper/gradle-wrapper.propertiesファイルのdistributionUrlプロパティで行います。このファイルをGitで管理することで、すべての開発者とCI環境が同じGradleバージョンを使用します。

バージョンを変更する場合は、このファイルを直接編集するか、./gradlew wrapper --gradle-version 9.6.1のようなコマンドを実行します。システムにインストールしたGradleのバージョンに依存せず、プロジェクトごとに独立してバージョンを管理できるのがWrapperの利点です。（出典：Gradle「Gradle Wrapper Basics」）

JDKバージョンとGradleバージョンの互換性確認

Gradleを実行するにはJDK 17以上が必要です。また、Gradleを実行するJDKバージョンとGradleバージョンには互換性があります。例えば、Java 26でGradleを実行するにはGradle 9.4.0以降が必要です。

注意すべきは、「Gradleを実行するJDK」と「プロジェクトをコンパイルするJavaバージョン」は別物という点です。GradleにはJava Toolchainsという機能があり、Gradleを実行するJDKと、コンパイル・テストに使用するJava環境を分離できます。プロジェクトのJavaバージョン要件とCI環境のJDKを混同しないようにしましょう。（出典：Gradle「Compatibility Matrix」）

要点：Git管理では.gradle/とbuild/を除外し、Gradleバージョンはgradle-wrapper.propertiesで固定します。Gradle実行用JDKは17以上が必要で、コンパイル対象のJavaバージョンとは区別して管理します。