Secure Artifact Registry Configuration

This guide explains how to configure your local development environments, Gradle build systems, and CI/CD pipelines to securely resolve and pull Milesoft SDKs and foundation libraries from our Google Cloud Artifact Registry.

1. Registry Architecture

The Milesoft package repository contains all software development kits, platform extensions, and core base libraries. Developers are granted read-only Identity and Access Management (IAM) access to this registry.

  • Repository URL: artifactregistry://us-west2-maven.pkg.dev/milesoft-repo/repo-maven
  • Artifact Categories:
    • SDKs (-sdk packages): Software Development Kits used to integrate with Milesoft services (e.g., liquid-sdk, contacts-sdk, accounts-sdk).
    • Extensions (-ext packages): Feature and utility extensions (e.g., storage-ext, task-queue-ext, twilio-ext, cloudinary-ext).
    • Foundations: Core base frameworks and libraries (e.g., primitives, commons, clients, app-stack).

2. Setting Up IAM & Local Authentication

Milesoft manages package repository authentication using native Google Cloud IAM. We never distribute long-lived, high-risk passwords or service account JSON key files for local development.

2.1 Install the Google Cloud CLI

You must have the Google Cloud CLI (gcloud) installed on your workstation. If you do not have it, refer to the official installation instructions.

2.2 Authenticate your CLI Environment

To authorize your local Gradle package manager to retrieve artifacts, log in using your authorized company Google account or Google Workspace email:

# Log in with your primary developer identity
gcloud auth login

# Set up Application Default Credentials (ADC)
# This step is critical; it generates the local JSON credentials that Gradle plugins read
gcloud auth application-default login

Once completed, Google's Client Libraries and Artifact Registry plugins will automatically fetch temporary, short-lived OAuth2 access tokens to authenticate outgoing repository requests.

3. Gradle Integration (Java / Kotlin)

To natively resolve dependencies from our registry using Gradle, you must integrate the official Google Cloud Artifact Registry Gradle Plugin. This plugin handles the artifactregistry:// protocol and automatically injects authentication headers from your active local gcloud session.

3.1 Declare the Gradle Plugin

In your project's build.gradle (or settings.gradle for repository settings), include the Artifact Registry plugin:

plugins {
    id "java"
    id "org.springframework.boot" version "3.5.15"
    // Declare the GCP Artifact Registry Plugin
    id "com.google.cloud.artifactregistry.gradle-plugin" version "2.2.5"
}

3.2 Add the Milesoft Repository

Define the repositories block to include the milesoft-repo secure URL. Note that you must use the artifactregistry:// scheme instead of standard https://:

repositories {
    mavenLocal()
    mavenCentral()
    maven {
        // Use the secure artifactregistry protocol
        url "artifactregistry://us-west2-maven.pkg.dev/milesoft-repo/repo-maven"
    }
}

3.3 Declare Milesoft SDK Dependencies

You can now import any client-facing Milesoft SDKs, foundation libraries, or platform extensions directly in your dependencies section using actual, stable production versions:

dependencies {
    // Ingest the base application runtime stack (contains abstract configurations and auth filters)
    implementation "io.milesoft:app-stack:2.2.0"
    
    // Ingest specific platform service SDKs
    implementation "io.milesoft:liquid-sdk:2.1.0"
    implementation "io.milesoft:contacts-sdk:2.0.1"
    
    // Ingest useful utility extensions
    implementation "io.milesoft:storage-ext:2.0.1"
    implementation "io.milesoft:task-queue-ext:2.0.1"
    implementation "io.milesoft:vertex-ext:2.0.1"
}

3.4 Mandatory Plugin & Evaluation Order Mandate

Downstream client applications must declare and apply the com.google.cloud.artifactregistry.gradle-plugin within their standard plugins {} block.

  • Evaluation Order: Gradle evaluates the plugins {} block before the repositories {} block. If the Artifact Registry plugin is missing or applied incorrectly, Gradle will fail to compile, reporting Unknown protocol: artifactregistry.
  • Standard Resolution: Always verify that the plugin id and version are correctly specified at the top of your build.gradle or settings.gradle.

4. CI/CD Pipeline Authentication (Google Cloud Build)

In non-interactive CI/CD runtimes, you do not have an active browser to execute gcloud auth login. Instead, authentication is managed using Service Accounts.

If you are running builds within Google Cloud Build, authentication is entirely automatic. The default Cloud Build service account already possesses read access to Artifact Registry repositories in the same or permitted adjacent projects. Simply run your Gradle commands directly:

steps:
  - name: 'gcr.io/cloud-builders/gradle'
    args: ['build']

5. Common Troubleshooting

5.1 Repository resolution failed: 401 Unauthorized

  • Root Cause: Gradle is trying to access the repository without finding valid credentials.
  • Resolution: Re-run gcloud auth application-default login on your terminal. Ensure that the terminal instance where you are running ./gradlew build is in the same subshell environment and inherits the global environment pointers.

5.2 Unknown protocol: artifactregistry

  • Root Cause: The Google Cloud Artifact Registry build plugin or extension was not declared or applied correctly.
  • Resolution: Double-check that your build.gradle contains id "com.google.cloud.artifactregistry.gradle-plugin" version "2.2.5" and that the plugins are fully evaluated before the repositories block.