Gradle Repositories
This section provides comprehensive documentation for configuring and using Gradle-based repositories with CloudRepo.
Overview
Gradle is a powerful build automation tool used primarily for Java, Kotlin, Groovy, and Scala projects, though it supports many other languages through plugins. Gradle uses a flexible DSL based on Groovy or Kotlin and provides advanced dependency management capabilities.
Why Private Gradle Repositories?
While public repositories like Maven Central and JCenter provide access to open-source libraries, many organizations need private Gradle repositories to:
Protect Intellectual Property: Keep proprietary code and libraries secure within your organization
Control Dependencies: Manage which versions of libraries are approved for use
Improve Build Performance: Cache dependencies closer to your build infrastructure
Ensure Availability: Guarantee access to critical dependencies regardless of external service availability
Compliance and Governance: Track and audit dependency usage across projects
CloudRepo provides fully managed, cloud-based Gradle repositories that eliminate the need to maintain your own repository infrastructure while providing enterprise-grade security and reliability.
Prerequisites
Before configuring Gradle to work with CloudRepo, you’ll need to:
Create a Repository: Set up a Maven-type repository in the CloudRepo Admin Portal (Gradle uses Maven repository format)
Create a Repository User: Create a dedicated user for accessing the repository
If you haven’t completed these steps, please refer to:
Important
For security reasons, admin users cannot directly access repositories. Always create dedicated repository users for artifact access.
Note
CloudRepo repositories use the following URL format:
https://[organization-id].mycloudrepo.io/repositories/[repository-id]
Gradle Configuration
Gradle supports two DSL (Domain Specific Language) options: Groovy DSL (build.gradle) and Kotlin DSL (build.gradle.kts). We’ll provide examples for both.
Basic Repository Configuration
Groovy DSL (build.gradle)
1repositories {
2 // CloudRepo private repository
3 maven {
4 url "https://your-org.mycloudrepo.io/repositories/your-repo"
5 credentials {
6 username = project.findProperty("cloudrepoUsername") ?: System.getenv("CLOUDREPO_USERNAME")
7 password = project.findProperty("cloudrepoPassword") ?: System.getenv("CLOUDREPO_API_TOKEN")
8 }
9 }
10
11 // Include Maven Central for public dependencies
12 mavenCentral()
13}
14
15dependencies {
16 implementation 'com.yourcompany:your-library:1.0.0'
17 implementation 'org.springframework.boot:spring-boot-starter-web:3.1.0'
18}
Kotlin DSL (build.gradle.kts)
1repositories {
2 // CloudRepo private repository
3 maven {
4 url = uri("https://your-org.mycloudrepo.io/repositories/your-repo")
5 credentials {
6 username = project.findProperty("cloudrepoUsername") as String?
7 ?: System.getenv("CLOUDREPO_USERNAME")
8 password = project.findProperty("cloudrepoPassword") as String?
9 ?: System.getenv("CLOUDREPO_API_TOKEN")
10 }
11 }
12
13 // Include Maven Central for public dependencies
14 mavenCentral()
15}
16
17dependencies {
18 implementation("com.yourcompany:your-library:1.0.0")
19 implementation("org.springframework.boot:spring-boot-starter-web:3.1.0")
20}
Authentication Setup
Store your CloudRepo credentials securely using one of these methods:
Method 1: gradle.properties
Create or edit ~/.gradle/gradle.properties (user-level) or gradle.properties (project-level):
1cloudrepoUsername=your-email@example.com
2cloudrepoPassword=your-repository-user-password
Warning
Never commit gradle.properties files containing credentials to version control. Add them to .gitignore.
Method 2: Environment Variables
Set environment variables in your shell or CI/CD environment:
1export CLOUDREPO_USERNAME="your-email@example.com"
2export CLOUDREPO_API_TOKEN="your-repository-user-password"
Method 3: System Properties
Pass credentials as system properties when running Gradle:
1./gradlew build \
2 -PcloudrepoUsername=your-email@example.com \
3 -PcloudrepoPassword=your-repository-user-password
Publishing Artifacts
To publish artifacts to CloudRepo, configure the maven-publish plugin:
Basic Publishing Configuration
Groovy DSL (build.gradle)
1plugins {
2 id 'java-library'
3 id 'maven-publish'
4}
5
6group = 'com.yourcompany'
7version = '1.0.0'
8
9java {
10 toolchain {
11 languageVersion = JavaLanguageVersion.of(17)
12 }
13 withJavadocJar()
14 withSourcesJar()
15}
16
17publishing {
18 publications {
19 maven(MavenPublication) {
20 from components.java
21
22 pom {
23 name = 'Your Library Name'
24 description = 'A description of your library'
25 url = 'https://github.com/yourcompany/your-library'
26
27 licenses {
28 license {
29 name = 'The Apache License, Version 2.0'
30 url = 'http://www.apache.org/licenses/LICENSE-2.0.txt'
31 }
32 }
33
34 developers {
35 developer {
36 id = 'johndoe'
37 name = 'John Doe'
38 email = 'john.doe@yourcompany.com'
39 }
40 }
41 }
42 }
43 }
44
45 repositories {
46 maven {
47 name = 'CloudRepo'
48 url = "https://your-org.mycloudrepo.io/repositories/your-repo"
49 credentials {
50 username = project.findProperty("cloudrepoUsername") ?: System.getenv("CLOUDREPO_USERNAME")
51 password = project.findProperty("cloudrepoPassword") ?: System.getenv("CLOUDREPO_API_TOKEN")
52 }
53 }
54 }
55}
Kotlin DSL (build.gradle.kts)
1plugins {
2 `java-library`
3 `maven-publish`
4}
5
6group = "com.yourcompany"
7version = "1.0.0"
8
9java {
10 toolchain {
11 languageVersion.set(JavaLanguageVersion.of(17))
12 }
13 withJavadocJar()
14 withSourcesJar()
15}
16
17publishing {
18 publications {
19 create<MavenPublication>("maven") {
20 from(components["java"])
21
22 pom {
23 name.set("Your Library Name")
24 description.set("A description of your library")
25 url.set("https://github.com/yourcompany/your-library")
26
27 licenses {
28 license {
29 name.set("The Apache License, Version 2.0")
30 url.set("http://www.apache.org/licenses/LICENSE-2.0.txt")
31 }
32 }
33
34 developers {
35 developer {
36 id.set("johndoe")
37 name.set("John Doe")
38 email.set("john.doe@yourcompany.com")
39 }
40 }
41 }
42 }
43 }
44
45 repositories {
46 maven {
47 name = "CloudRepo"
48 url = uri("https://your-org.mycloudrepo.io/repositories/your-repo")
49 credentials {
50 username = project.findProperty("cloudrepoUsername") as String?
51 ?: System.getenv("CLOUDREPO_USERNAME")
52 password = project.findProperty("cloudrepoPassword") as String?
53 ?: System.getenv("CLOUDREPO_API_TOKEN")
54 }
55 }
56 }
57}
Publishing Commands
To publish your artifacts to CloudRepo:
1# Publish all publications to all repositories
2./gradlew publish
3
4# Publish to CloudRepo specifically
5./gradlew publishMavenPublicationToCloudRepoRepository
6
7# Publish to local Maven repository (for testing)
8./gradlew publishToMavenLocal
SNAPSHOT vs Release Versions
CloudRepo supports both SNAPSHOT and release versions:
- SNAPSHOT Versions
Development versions, republished as often as you like. Append
-SNAPSHOTto your version:version = '1.0.0-SNAPSHOT'
- Release Versions
Versions intended to stay fixed once published:
version = '1.0.0'
Note
CloudRepo repositories have Overwrite Protection
enabled by default. With it enabled, republishing a release version that
already exists is refused with 409 Conflict and the published artifact is
left as it is; -SNAPSHOT versions and maven-metadata.xml are exempt
and can always be republished.
Overwrite Protection is a per-repository setting. If it is switched off for a repository, that repository will accept a release overwrite.
Note
Nothing in the Maven specification forbids republishing a release version. Treating releases as fixed is a publishing policy (Maven Central refuses redeployment outright) and a strong ecosystem convention that most repository managers default to. CloudRepo defaults to it as well, and lets you turn it off per repository.
Multi-Module Projects
For multi-module Gradle projects, configure publishing in each module that produces artifacts:
Root Project (build.gradle)
1subprojects {
2 apply plugin: 'java-library'
3 apply plugin: 'maven-publish'
4
5 group = 'com.yourcompany'
6 version = '1.0.0'
7
8 repositories {
9 maven {
10 url "https://your-org.mycloudrepo.io/repositories/your-repo"
11 credentials {
12 username = rootProject.findProperty("cloudrepoUsername")
13 password = rootProject.findProperty("cloudrepoPassword")
14 }
15 }
16 mavenCentral()
17 }
18
19 publishing {
20 repositories {
21 maven {
22 name = 'CloudRepo'
23 url = "https://your-org.mycloudrepo.io/repositories/your-repo"
24 credentials {
25 username = rootProject.findProperty("cloudrepoUsername")
26 password = rootProject.findProperty("cloudrepoPassword")
27 }
28 }
29 }
30 }
31}
Submodule Configuration
1// Each submodule can have its own specific configuration
2publishing {
3 publications {
4 maven(MavenPublication) {
5 from components.java
6
7 artifactId = 'specific-module-name'
8
9 pom {
10 name = 'Module Specific Name'
11 description = 'Module specific description'
12 }
13 }
14 }
15}
Consuming Dependencies
Once artifacts are published to CloudRepo, other projects can consume them:
Simple Dependency Declaration
1dependencies {
2 implementation 'com.yourcompany:your-library:1.0.0'
3 implementation 'com.yourcompany:another-library:2.1.0'
4
5 // Using specific configurations
6 compileOnly 'com.yourcompany:annotations:1.0.0'
7 testImplementation 'com.yourcompany:test-utils:1.0.0'
8}
Dynamic Version Strategies
Gradle supports various dynamic version strategies:
1dependencies {
2 // Latest release version
3 implementation 'com.yourcompany:your-library:+'
4
5 // Latest 1.x version
6 implementation 'com.yourcompany:your-library:1.+'
7
8 // Version range
9 implementation 'com.yourcompany:your-library:[1.0,2.0)'
10
11 // Latest SNAPSHOT
12 implementation 'com.yourcompany:your-library:1.0.0-SNAPSHOT'
13}
Warning
Use dynamic versions cautiously in production as they can lead to non-reproducible builds.
Dependency Caching
Configure Gradle’s dependency caching for CloudRepo:
1configurations.all {
2 resolutionStrategy {
3 // Cache dynamic versions for 10 minutes
4 cacheDynamicVersionsFor 10, 'minutes'
5
6 // Cache changing modules (SNAPSHOTs) for 0 seconds (always check)
7 cacheChangingModulesFor 0, 'seconds'
8 }
9}
Advanced Topics
Gradle Wrapper Configuration
Configure the Gradle Wrapper to ensure consistent builds across environments:
1# Generate wrapper with specific version
2gradle wrapper --gradle-version 8.5
3
4# Configure distribution type
5gradle wrapper --gradle-version 8.5 --distribution-type all
Update gradle/wrapper/gradle-wrapper.properties:
1distributionBase=GRADLE_USER_HOME
2distributionPath=wrapper/dists
3distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-all.zip
4networkTimeout=10000
5validateDistributionUrl=true
6zipStoreBase=GRADLE_USER_HOME
7zipStorePath=wrapper/dists
Composite Builds
Use composite builds to work with multiple related projects:
1rootProject.name = 'main-project'
2
3// Include local development versions of dependencies
4if (file('../library-project').exists()) {
5 includeBuild('../library-project') {
6 dependencySubstitution {
7 substitute module('com.yourcompany:library') using project(':')
8 }
9 }
10}
This allows you to work on a library and its consumer simultaneously without publishing intermediate versions.
Build Cache Configuration
Configure Gradle’s build cache for improved performance:
1buildCache {
2 local {
3 enabled = true
4 directory = new File(rootDir, '.gradle/build-cache')
5 removeUnusedEntriesAfterDays = 30
6 }
7
8 // Optional: Configure remote build cache
9 remote(HttpBuildCache) {
10 url = 'https://your-org.mycloudrepo.io/repositories/build-cache'
11 credentials {
12 username = 'build-cache-user'
13 password = 'build-cache-password'
14 }
15 push = System.getenv("CI") == "true"
16 }
17}
Plugin Publishing
Publish Gradle plugins to CloudRepo:
1plugins {
2 id 'java-gradle-plugin'
3 id 'maven-publish'
4}
5
6gradlePlugin {
7 plugins {
8 myPlugin {
9 id = 'com.yourcompany.myplugin'
10 implementationClass = 'com.yourcompany.MyPlugin'
11 displayName = 'My Custom Plugin'
12 description = 'A custom Gradle plugin'
13 }
14 }
15}
16
17publishing {
18 publications {
19 pluginMaven(MavenPublication) {
20 artifactId = 'my-gradle-plugin'
21 }
22 }
23
24 repositories {
25 maven {
26 name = 'CloudRepo'
27 url = "https://your-org.mycloudrepo.io/repositories/gradle-plugins"
28 credentials {
29 username = project.findProperty("cloudrepoUsername")
30 password = project.findProperty("cloudrepoPassword")
31 }
32 }
33 }
34}
Using Published Plugins
1pluginManagement {
2 repositories {
3 maven {
4 url "https://your-org.mycloudrepo.io/repositories/gradle-plugins"
5 credentials {
6 username = System.getenv("CLOUDREPO_USERNAME")
7 password = System.getenv("CLOUDREPO_API_TOKEN")
8 }
9 }
10 gradlePluginPortal()
11 }
12}
1plugins {
2 id 'com.yourcompany.myplugin' version '1.0.0'
3}
Repository Mirroring
Configure CloudRepo as a mirror for public repositories:
1repositories {
2 // CloudRepo as exclusive repository (proxies to Maven Central)
3 exclusiveContent {
4 forRepository {
5 maven {
6 url "https://your-org.mycloudrepo.io/repositories/maven-proxy"
7 credentials {
8 username = project.findProperty("cloudrepoUsername")
9 password = project.findProperty("cloudrepoPassword")
10 }
11 }
12 }
13 filter {
14 includeGroupByRegex ".*"
15 }
16 }
17}
CI/CD Integration
Basic CI/CD configuration examples for common platforms:
GitHub Actions
1name: Build and Publish
2
3on:
4 push:
5 branches: [ main ]
6 pull_request:
7 branches: [ main ]
8
9jobs:
10 build:
11 runs-on: ubuntu-latest
12
13 steps:
14 - uses: actions/checkout@v3
15
16 - name: Set up JDK 17
17 uses: actions/setup-java@v3
18 with:
19 java-version: '17'
20 distribution: 'temurin'
21
22 - name: Grant execute permission for gradlew
23 run: chmod +x gradlew
24
25 - name: Build with Gradle
26 env:
27 CLOUDREPO_USERNAME: ${{ secrets.CLOUDREPO_USERNAME }}
28 CLOUDREPO_API_TOKEN: ${{ secrets.CLOUDREPO_API_TOKEN }}
29 run: ./gradlew build
30
31 - name: Publish to CloudRepo
32 if: github.ref == 'refs/heads/main'
33 env:
34 CLOUDREPO_USERNAME: ${{ secrets.CLOUDREPO_USERNAME }}
35 CLOUDREPO_API_TOKEN: ${{ secrets.CLOUDREPO_API_TOKEN }}
36 run: ./gradlew publish
Jenkins Pipeline
1pipeline {
2 agent any
3
4 environment {
5 CLOUDREPO_USERNAME = credentials('cloudrepo-username')
6 CLOUDREPO_API_TOKEN = credentials('cloudrepo-password')
7 }
8
9 stages {
10 stage('Build') {
11 steps {
12 sh './gradlew clean build'
13 }
14 }
15
16 stage('Test') {
17 steps {
18 sh './gradlew test'
19 }
20 }
21
22 stage('Publish') {
23 when {
24 branch 'main'
25 }
26 steps {
27 sh './gradlew publish'
28 }
29 }
30 }
31}
GitLab CI
1image: gradle:8.5-jdk17
2
3variables:
4 GRADLE_OPTS: "-Dorg.gradle.daemon=false"
5
6before_script:
7 - export GRADLE_USER_HOME=`pwd`/.gradle
8
9cache:
10 paths:
11 - .gradle/wrapper
12 - .gradle/caches
13
14build:
15 stage: build
16 script:
17 - gradle build
18 artifacts:
19 paths:
20 - build/libs/*.jar
21 expire_in: 1 week
22
23publish:
24 stage: deploy
25 script:
26 - gradle publish
27 variables:
28 CLOUDREPO_USERNAME: $CLOUDREPO_USERNAME
29 CLOUDREPO_API_TOKEN: $CLOUDREPO_API_TOKEN
30 only:
31 - main
Troubleshooting
Common Issues and Solutions
Authentication Failures
Problem: 401 Unauthorized errors when accessing CloudRepo
Solution:
Verify credentials are correct:
# Test authentication with curl curl -u "your-email@example.com:YOUR_API_TOKEN" \ https://your-org.mycloudrepo.io/repositories/your-repo
Check credential precedence:
// Debug credential sources task checkCredentials { doLast { println "Username from property: ${project.findProperty("cloudrepoUsername")}" println "Username from env: ${System.getenv("CLOUDREPO_USERNAME")}" } }
Ensure you’re using a repository user, not an admin user
Dependency Resolution Issues
Problem: Gradle cannot find dependencies published to CloudRepo
Solution:
Verify the artifact was published successfully:
# List published artifacts gradle tasks --all | grep publish
Check repository ordering:
repositories { // CloudRepo should be listed before public repositories maven { url "https://your-org.mycloudrepo.io/repositories/your-repo" credentials { /* ... */ } } mavenCentral() }
Clear Gradle cache:
# Clear specific dependency rm -rf ~/.gradle/caches/modules-2/files-2.1/com.yourcompany/ # Or refresh dependencies ./gradlew build --refresh-dependencies
SSL/TLS Certificate Issues
Problem: SSL handshake failures
Solution:
Update Java certificates. Gradle runs on the JVM, which normally reads its OWN truststore, so
update-ca-certificatesalone is usually not enough. (On Debian/Ubuntu with a distro OpenJDK theca-certificates-javapackage does link the two, but a tarball JDK (Adoptium, Temurin, most CI images) is not linked, and that is where this fails.) Do both:# System trust store update-ca-certificates # JVM truststore -- this is the one Gradle reads # Resolve the truststore BEFORE importing. Two things bite here: # * Java 8 keeps it at $JAVA_HOME/jre/lib/security/cacerts, Java 9+ at lib/security. # * keytool CREATES the file if the path is wrong, prints "Certificate was added to # keystore" and exits 0 -- so a wrong path is a silent no-op wearing a success # message, and a `keytool -list` against that same wrong path agrees with it. CACERTS="$JAVA_HOME/lib/security/cacerts" [ -f "$CACERTS" ] || CACERTS="$JAVA_HOME/jre/lib/security/cacerts" [ -f "$CACERTS" ] || { echo "No cacerts under $JAVA_HOME - is it the JDK your build uses?"; exit 1; } keytool -importcert -keystore "$CACERTS" -storepass changeit -noprompt \ -alias corporate-proxy-ca -file corporate-ca.crt # Verify against the RESOLVED path, not an asserted one. keytool -list -keystore "$CACERTS" -storepass changeit -alias corporate-proxy-ca
Keep HTTPS on. The repository URL must stay
https://:repositories { maven { url "https://your-org.mycloudrepo.io/repositories/your-repo" allowInsecureProtocol = false // Keep HTTPS credentials { /* ... */ } } }
Publishing Failures
Problem: Artifacts fail to publish
Solution:
Check version conflicts. CloudRepo refuses a republished release version with
409 Conflict, because Overwrite Protection is enabled by default. A409on a publish almost always means exactly that.The same refusal reaches the Maven client as nothing but its status line, which is worth recognising if you also publish with
mvn deploy:status code: 409, reason phrase: Conflict
Three ways forward: publish a new version (usually the right answer), switch to a
-SNAPSHOTversion while iterating (SNAPSHOT coordinates are exempt and may be republished freely), or turn Overwrite Protection off for that repository if it is genuinely meant to accept republished releases. See Publish Refused: status code: 409, reason phrase: Conflict for the full walkthrough and what turning it off costs you.Verify publication configuration:
# List all publications ./gradlew tasks --group=publishing
Enable debug logging:
# Run with debug output ./gradlew publish --debug # Or info level ./gradlew publish --info
Performance Issues
Problem: Slow dependency downloads
Solution:
Configure parallel downloads:
# gradle.properties org.gradle.parallel=true org.gradle.caching=true org.gradle.configureondemand=true
Increase network timeout:
repositories { maven { url "https://your-org.mycloudrepo.io/repositories/your-repo" credentials { /* ... */ } metadataSources { mavenPom() artifact() } timeout { connection = 30000 // 30 seconds read = 60000 // 60 seconds } } }
Debugging Tips
Enable Detailed Logging
1# Show dependency tree
2./gradlew dependencies
3
4# Show dependency insights
5./gradlew dependencyInsight --dependency your-library
6
7# Debug repository access
8./gradlew build --debug 2>&1 | grep -i cloudrepo
9
10# Show effective POM
11./gradlew generatePomFileForMavenPublication
Check Published Artifacts
1task verifyPublication {
2 doLast {
3 publishing.publications.each { publication ->
4 println "Publication: ${publication.name}"
5 println " Artifacts: ${publication.artifacts.collect { it.file.name }}"
6 println " Group: ${publication.groupId}"
7 println " Artifact: ${publication.artifactId}"
8 println " Version: ${publication.version}"
9 }
10 }
11}
Best Practices
Security
Never commit credentials: Always use environment variables or secure credential stores
Use dedicated CI/CD users: Create specific users for automated processes with minimal permissions
Rotate credentials regularly: Update passwords periodically
Use HTTPS only: Never use HTTP for repository access
Implement token-based authentication: When available, prefer tokens over passwords
Performance
Cache dependencies locally: Use Gradle’s build cache effectively
Use specific versions in production: Avoid dynamic versions for reproducible builds
Parallelize builds: Enable parallel execution for multi-module projects
Optimize repository ordering: Place frequently-used repositories first
Use repository content filtering: Reduce unnecessary repository queries
Version Management
Semantic Versioning: Follow SemVer principles
SNAPSHOT for development: Use SNAPSHOT versions during development
Tag releases: Create Git tags for all production releases
Document breaking changes: Maintain a CHANGELOG for version history
Automate version bumping: Use plugins to manage version increments
Project Organization
Centralize configuration: Use convention plugins for common settings
Modularize large projects: Break monoliths into smaller, focused modules
Standardize naming: Use consistent artifact and module naming
Document dependencies: Explain why each dependency is needed
Regular dependency updates: Keep dependencies current for security and performance
Summary
This guide covered comprehensive Gradle configuration for CloudRepo, including:
Repository setup and authentication
Publishing artifacts with sources and documentation
Consuming dependencies from CloudRepo
Multi-module project configuration
Advanced features like composite builds and build caching
CI/CD integration patterns
Troubleshooting common issues
CloudRepo provides a robust, secure, and cost-effective solution for hosting your private Gradle artifacts, with no egress fees and included support for all users.
For additional assistance, please contact CloudRepo Support. Our team typically responds within a few business hours.
See Also
Maven Repositories - Maven-specific configuration
Repository Management - Managing repositories in CloudRepo
Continuous Integration and Deployment - Detailed CI/CD integration guides
Gradle Documentation - Official Gradle documentation
CloudRepo Admin Portal - Manage your repositories and users