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:

  1. Create a Repository: Set up a Maven-type repository in the CloudRepo Admin Portal (Gradle uses Maven repository format)

  2. 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)

Groovy DSL - Repository Configuration
 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_PASSWORD")
 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)

Kotlin DSL - Repository Configuration
 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_PASSWORD")
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):

gradle.properties - Credential Storage
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:

Setting Environment Variables
1export CLOUDREPO_USERNAME="your-email@example.com"
2export CLOUDREPO_PASSWORD="your-repository-user-password"

Method 3: System Properties

Pass credentials as system properties when running Gradle:

Using System Properties
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)

Groovy DSL - Publishing Configuration
 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_PASSWORD")
52            }
53        }
54    }
55}

Kotlin DSL (build.gradle.kts)

Kotlin DSL - Publishing Configuration
 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_PASSWORD")
54            }
55        }
56    }
57}

Publishing Commands

To publish your artifacts to CloudRepo:

Publishing Artifacts
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 that can be overwritten. Append -SNAPSHOT to your version:

version = '1.0.0-SNAPSHOT'
Release Versions

Immutable versions that cannot be overwritten:

version = '1.0.0'

Note

CloudRepo enforces immutability for release versions. Once published, a release version cannot be overwritten.

Multi-Module Projects

For multi-module Gradle projects, configure publishing in each module that produces artifacts:

Root Project (build.gradle)

Root Project Configuration
 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

Submodule build.gradle
 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

Consuming Published Artifacts
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:

Dynamic Version Examples
 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:

Caching Configuration
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:

Gradle Wrapper Setup
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:

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:

settings.gradle - Composite Build Configuration
 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:

settings.gradle - Build Cache Configuration
 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:

Plugin Publishing Configuration
 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

settings.gradle - Plugin Repository Configuration
 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_PASSWORD")
 8            }
 9        }
10        gradlePluginPortal()
11    }
12}
build.gradle - Apply Custom Plugin
1plugins {
2    id 'com.yourcompany.myplugin' version '1.0.0'
3}

Repository Mirroring

Configure CloudRepo as a mirror for public repositories:

Mirror Configuration
 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

.github/workflows/build.yml
 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_PASSWORD: ${{ secrets.CLOUDREPO_PASSWORD }}
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_PASSWORD: ${{ secrets.CLOUDREPO_PASSWORD }}
36      run: ./gradlew publish

Jenkins Pipeline

Jenkinsfile
 1pipeline {
 2    agent any
 3
 4    environment {
 5        CLOUDREPO_USERNAME = credentials('cloudrepo-username')
 6        CLOUDREPO_PASSWORD = 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

.gitlab-ci.yml
 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_PASSWORD: $CLOUDREPO_PASSWORD
30  only:
31    - main

Troubleshooting

Common Issues and Solutions

Authentication Failures

Problem: 401 Unauthorized errors when accessing CloudRepo

Solution:

  1. Verify credentials are correct:

    # Test authentication with curl
curl -u "your-email@example.com:your-password" \
     https://your-org.mycloudrepo.io/repositories/your-repo

  2. Check credential precedence:

    // Debug credential sources
task checkCredentials {
     doLast {
         println "Username from property: ${project.findProperty("cloudrepoUsername")}"
         println "Username from env: ${System.getenv("CLOUDREPO_USERNAME")}"
     }
}

  3. Ensure you’re using a repository user, not an admin user

Dependency Resolution Issues

Problem: Gradle cannot find dependencies published to CloudRepo

Solution:

  1. Verify the artifact was published successfully:

    # List published artifacts
gradle tasks --all | grep publish

  2. Check repository ordering:

    repositories {
     // CloudRepo should be listed before public repositories
     maven {
         url "https://your-org.mycloudrepo.io/repositories/your-repo"
         credentials { /* ... */ }
     }
     mavenCentral()
}

  3. 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:

  1. Update Java certificates:

    # Update CA certificates
update-ca-certificates

  2. For testing only (not recommended for production):

    // Temporary workaround - DO NOT USE IN PRODUCTION
repositories {
     maven {
         url "https://your-org.mycloudrepo.io/repositories/your-repo"
         allowInsecureProtocol = false  // Keep HTTPS
         credentials { /* ... */ }
     }
}

Publishing Failures

Problem: Artifacts fail to publish

Solution:

  1. Check version conflicts:

    # Attempting to overwrite a release version will fail
# Change version or use SNAPSHOT for development

  2. Verify publication configuration:

    # List all publications
./gradlew tasks --group=publishing

  3. Enable debug logging:

    # Run with debug output
./gradlew publish --debug

# Or info level
./gradlew publish --info

Performance Issues

Problem: Slow dependency downloads

Solution:

  1. Configure parallel downloads:

    # gradle.properties
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.configureondemand=true

  2. 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

Gradle Debug Commands
 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

Verification Tasks
 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

  1. Never commit credentials: Always use environment variables or secure credential stores

  2. Use dedicated CI/CD users: Create specific users for automated processes with minimal permissions

  3. Rotate credentials regularly: Update passwords periodically

  4. Use HTTPS only: Never use HTTP for repository access

  5. Implement token-based authentication: When available, prefer tokens over passwords

Performance

  1. Cache dependencies locally: Use Gradle’s build cache effectively

  2. Use specific versions in production: Avoid dynamic versions for reproducible builds

  3. Parallelize builds: Enable parallel execution for multi-module projects

  4. Optimize repository ordering: Place frequently-used repositories first

  5. Use repository content filtering: Reduce unnecessary repository queries

Version Management

  1. Semantic Versioning: Follow SemVer principles

  2. SNAPSHOT for development: Use SNAPSHOT versions during development

  3. Tag releases: Create Git tags for all production releases

  4. Document breaking changes: Maintain a CHANGELOG for version history

  5. Automate version bumping: Use plugins to manage version increments

Project Organization

  1. Centralize configuration: Use convention plugins for common settings

  2. Modularize large projects: Break monoliths into smaller, focused modules

  3. Standardize naming: Use consistent artifact and module naming

  4. Document dependencies: Explain why each dependency is needed

  5. 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