Gradle設定ファイルの基礎からCI/CD構築までを徹底解説

Gradleプロジェクトはどこでどう設定する？主要ファイルの役割を解説

Gradleの設定ファイルは主に4種類ある

Gradleプロジェクトでは設定ファイルが役割ごとに分かれている。中心となるのは、プロジェクト全体の構成を定義するsettings.gradle(.kts)と、ビルド処理そのものを記述するbuild.gradle(.kts)の2つだ。これに加えて、Gradle実行時のJVMオプションやキャッシュ設定を管理するgradle.properties、依存関係のバージョンを一元管理するgradle/libs.versions.tomlがある。ファイル名の.ktsはKotlin DSLを使用する場合の拡張子で、Groovy DSLとKotlin DSLのどちらかを選択できる。新規プロジェクトではKotlin DSLが推奨される傾向にあるが、既存資産との整合性も考慮して選ぶとよい。

settings.gradleとbuild.gradleの役割の違い

settingsファイルはプロジェクトの初期化時に評価される。ここではルートプロジェクト名の設定、マルチプロジェクト構成の登録（include(":モジュール名")）、プラグイン解決用リポジトリの設定（pluginManagement）、依存関係解決のリポジトリ定義（dependencyResolutionManagement）を行う。一方、build.gradleは各プロジェクトのビルド設定を記述する。適用するプラグイン、依存関係、カスタムタスクなどを定義する。重要なのは、settingsファイルが無い場所でGradleを実行すると、親ディレクトリにsettingsファイルを探しに行く点だ。見つかればマルチプロジェクト構成として扱われ、見つからなければ単一プロジェクトとしてビルドされる。

gradle.propertiesとバージョンカタログの活用

gradle.propertiesにはGradleデーモンのJVM引数やビルドの挙動を制御するプロパティを記述する。代表的なものとして、並列実行を有効にするorg.gradle.parallel=true、ビルドキャッシュを有効にするorg.gradle.caching=trueがある。また、Gradle 7.0以降ではバージョンカタログ（gradle/libs.versions.toml）を使って依存関係のバージョンを一元管理できる。[versions]セクションでバージョン変数を定義し、[libraries]でライブラリの座標とバージョンを紐付け、[plugins]でプラグインを定義する。これにより複数モジュール間でバージョンの一貫性を保ちやすくなる。

依存関係とプラグインのリポジトリ設定をsettingsファイルで一元管理する方法

pluginManagementブロックでプラグイン解決先を指定する

Gradleのプラグインは、デフォルトのリポジトリから自動で解決されない。そのためsettings.gradle(.kts)のpluginManagementブロックで、プラグインを取得するリポジトリを明示的に指定する必要がある。使用できるリポジトリには、Gradle公式のプラグインを配布するgradlePluginPortal()、Maven Central（mavenCentral()）、Google Mavenリポジトリ（google()）、ローカルのMavenキャッシュ（mavenLocal()）などがある。複数のリポジトリを宣言した場合は上から順に検索されるため、依存関係の取得元をコントロールしたい場合は順序にも注意が必要だ。

dependencyResolutionManagementで依存関係のリポジトリを集約する

Gradle 6.8以降では、dependencyResolutionManagementブロックを使ってプロジェクト全体の依存関係解決を一元的に管理できる。このブロック内でrepositoriesを宣言すると、すべてのサブプロジェクトに共通のリポジトリ設定が適用される。さらにrepositoriesModeを指定することで、プロジェクト側でのリポジトリ定義の扱いを制御できる。デフォルトのPREFER_PROJECTはプロジェクト側の定義を優先し、FAIL_ON_PROJECT_REPOSはプロジェクト側での定義を禁止してビルドエラーにする。リポジトリを厳密に一元管理したい場合は後者を選ぶとよい。

プライベートリポジトリの認証情報はコードに書かない

社内のNexusやArtifactoryなど、プライベートなMavenリポジトリを利用する場合は認証情報が必要になる。Gradleではmaven { url = uri("...") }ブロック内でcredentialsを指定して認証できるが、ユーザー名やパスワードをビルドスクリプトに直接記述するのは避けるべきだ。代わりにgradle.propertiesにプロパティとして定義するか、CI/CD環境では環境変数やGitHub ActionsのSecretsなどから注入する方法が安全である。また、全プロジェクト共通のリポジトリ設定を適用したい場合は、ユーザーのホームディレクトリに配置するInit Script（~/.gradle/init.gradle）を活用できる。

要点: プラグインと依存関係のリポジトリはsettingsファイルで一元管理できる。認証情報はスクリプトに直接書かず、プロパティや環境変数から注入する。

Gradle WrapperとJava Toolchainsの基本とバージョン互換性の考え方

Gradle WrapperはプロジェクトごとにGradleバージョンを固定する仕組み

Gradle Wrapperは、プロジェクトが使用するGradleバージョンを指定し、必要に応じて自動取得・実行する仕組みだ。代表的なファイルはgradlew（Linux/macOS用）、gradlew.bat（Windows用）、gradle/wrapper/gradle-wrapper.properties、gradle/wrapper/gradle-wrapper.jarである。システムにGradleを手動インストールする必要がなく、開発者全員やCI環境で同じバージョンを利用できるため、Gradle公式もWrapperの使用を推奨している。既存プロジェクトでは、まずgradlewの有無とgradle-wrapper.propertiesに記載されたバージョンを確認するのが基本だ。

Gradleを実行するJDKとJavaの互換性を理解する

Gradleを実行するにはJDK 17以上が必要だ。Java 17からJava 26までが実行環境としてサポートされている。ただし、JavaのバージョンとGradleのバージョンは別物であり、組み合わせには互換性がある。たとえばJava 21でGradleを実行するにはGradle 8.5以降が必要になる。古い記事にある「JDK 8があれば実行できる」という説明は現行版には当てはまらないため注意が必要だ。

Java Toolchainsで実行環境とビルド対象を分離する

GradleにはJava Toolchainsという、Gradleを実行するJDKとプロジェクトのコンパイル・テストに使うJava環境を分離する機能がある。これにより、Gradle自体はJava 17で実行しつつ、プロジェクトのコンパイル対象としてJava 21を使用する、といった構成が可能になる。「Java 21をコンパイル対象にすること」と「Java 21でGradle自体を実行すること」は混同しやすいが、別の問題だ。Toolchainsを使えば、開発環境のJDKバージョンに縛られずにプロジェクトごとに適切なJavaバージョンを指定できる。

要点: Gradle本体の実行にはJDK 17以上が必要。Wrapperでバージョンを固定し、Toolchainsでビルド対象のJavaバージョンを柔軟に指定する。

GitHub ActionsでGradleビルドを実行するCI/CD構築手順とポイント

GitHub Actionsのワークフローは3つのステップが基本

GitHub ActionsでGradleビルドを実行する場合、基本的なワークフローは3つのステップで構成される。まずactions/checkoutでソースコードを取得し、次にactions/setup-javaでJDKを設定する。最後にGradleのビルドを実行するが、このときシステムにインストールされたGradleではなく、Gradle Wrapper（./gradlew）を使うのが公式推奨だ。GitHubホストランナーにはJDKとGradleが事前インストールされているが、Wrapperを使うことでCI環境でもローカルと同じGradleバージョンを利用でき、再現性が高まる。

setup-gradleアクションとwrapper検証を活用する

Gradle公式はGitHub Actions向けにgradle/actions/setup-gradleというアクションを提供している。これはワークフロー実行間のキャッシュ状態を管理し、Gradle実行のサマリーを提供するものだ。セットアップ手順としては以下の通りになる。

1. actions/checkoutでコードを取得する
2. actions/setup-javaでJDKを設定する（例：java-version: '17'、distribution: 'temurin'）
3. gradle/actions/setup-gradleでGradle環境を準備する
4. ./gradlew buildでビルドを実行する

また、リポジトリ内のgradle-wrapper.jarのチェックサム検証を行うwrapper-validation-actionを組み合わせると、Wrapperの改ざんを防ぐセキュリティ対策になる。サードパーティ製アクションはコミットSHAでバージョンを固定することが推奨されている。

エフェメラルCI環境ではキャッシュ対策が重要

GitHub Actionsのような使い捨て（エフェメラル）環境では、Gradle User Home（.gradleディレクトリ）が毎回消去される。これにより、Gradleディストリビューションの再ダウンロードや初回初期化コストが毎回発生する。対策として、CI向けにはgradle.propertiesにorg.gradle.daemon=false（デーモン無効化）、org.gradle.parallel=true（並列実行）、org.gradle.caching=true（キャッシュ有効化）を設定するのが一般的だ。さらにDockerイメージにGradleのキャッシュを事前に埋め込む「プリミング」や、リモートビルドキャッシュの活用も有効な手段として挙げられる。

要点: GitHub ActionsではWrapperを使い、setup-gradleアクションとwrapper検証でCIの信頼性とセキュリティを高める。エフェメラル環境ではキャッシュ対策がビルド時間短縮の鍵となる。

依存関係の改ざんを防ぐGradleのセキュリティ対策（検証・証明書・タイムアウト）

Dependency Verificationでチェックサムと署名を検証する

Gradleには依存関係の改ざんや中間者攻撃を防ぐためのDependency Verification（依存関係検証）機能がある。ダウンロードしたライブラリのSHA-256などのチェックサムと、PGP署名を検証する仕組みだ。設定はgradle/verification-metadata.xmlに記述する。導入は、./gradlew --write-verification-metadata pgp,sha256 --export-keys helpコマンドを実行して初期メタデータを生成し、生成されたverification-metadata.xmlとPGP公開鍵ファイルをGitにコミットする流れになる。依存関係をアップグレードするたびにチェックサムが変わるため、メタデータの更新が必要になる点に注意したい。

Dependency Lockingで解決結果を固定する

動的バージョン（バージョン範囲）を使用しているプロジェクトでは、Dependency Locking（依存関係ロック）を使って解決結果をgradle.lockfileに固定できる。これにより、ビルドごとに異なるバージョンが解決されることを防ぎ、再現性を高められる。ただし、固定バージョンのみを指定しているプロジェクトでは、ロックを追加する価値は低い。動的バージョンや推移的依存関係のバージョンが頻繁に変わる状況で有効な対策だ。ロックファイルもバージョン管理に含めて、チーム全体で共有する運用が推奨される。

リポジトリのフィルタリングと認証で取得元を制御する

セキュリティ対策として、リポジトリごとにcontent {}ブロックで取得できるグループやモジュールを制限する方法がある。たとえばMaven Centralは全体に許可し、特定のライブラリのみJitPackから取得する、といった制御が可能だ。また、プライベートリポジトリの認証情報は環境変数やSecretsから注入し、ビルドスクリプトに平文で書かないことが基本である。さらに、署名検証時にキーサーバーへのアクセスを無効化し、ローカルキーリングのみを使用する設定も可能で、CI環境での外部通信を減らすセキュリティ強化策として有効だ。これらの対策を組み合わせることで、依存関係の取得経路を信頼できる範囲に限定できる。

要点: Dependency Verificationでチェックサムと署名を検証し、リポジトリのフィルタリングで取得元を制限する。認証情報はスクリプトに書かず、Secretsや環境変数から注入する。