What's Changed

• chore: migrate issue templates to forms by @skhokhlov in #680
• build(deps): bump gradle/actions from 4.4.2 to 4.4.3 by @dependabot[bot] in #678
• build(deps): bump org.cyclonedx.bom from 2.3.1 to 2.4.0 by @dependabot[bot] in #684
• build(deps): bump com.uber.nullaway:nullaway from 0.12.9 to 0.12.10 by @dependabot[bot] in #685
• build(deps): bump com.gradle.plugin-publish from 1.3.1 to 2.0.0 by @dependabot[bot] in #677
• build: upgrade gradle to 9.1.0 by @skhokhlov in #687
• Java 25 by @skhokhlov in #688
• build(deps): bump org.cyclonedx.bom from 2.4.0 to 2.4.1 by @dependabot[bot] in #693
• build: use jdk 21 as default by @skhokhlov in #695
• fix: register direct bom task once by @skhokhlov in #694
• build(deps): bump org.cyclonedx:cyclonedx-core-java from 10.2.1 to 11.0.0 by @dependabot[bot] in #698
• build(deps): bump gradle/actions from 4.4.3 to 4.4.4 by @dependabot[bot] in #697
• build: prepare version 3.0.0-alpha-2 by @skhokhlov in #699

Full Changelog: cyclonedx-gradle-plugin-3.0.0-alpha-1...cyclonedx-gradle-plugin-3.0.0-alpha-2

CycloneDX Gradle Plugin Migration Guide: 2.4.1 → 3.0.0-alpha-2

This guide covers the breaking changes and migration steps required when upgrading from CycloneDX Gradle Plugin version 2.4.1 to 3.0.0-alpha-2.

Task Behavior and Naming Changes

Version 2.4.1: Single Task Model

# Single task for all scenarios
gradle cyclonedxBom

Version 3.0.0: Dual Task Model

# Generate per-project SBOMs (individual projects)
gradle cyclonedxDirectBom

# Generate aggregated SBOM (multi-project builds)
gradle cyclonedxBom

Task Behavior Changes

Configuration Method Changes

❌ Version 2.4.1: Single task configuration

// OLD - No longer supported
tasks.cyclonedxBom {
    setIncludeConfigs(["runtimeClasspath"])
    setDestination(file("build/reports"))
    setOutputName("bom")
    setOutputFormat("json")
}

✅ Version 3.0.0: Project-scoped task configuration

// NEW
tasks.cyclonedxDirectBom {
    includeConfigs = ["runtimeClasspath"]
    jsonOutput = file("build/reports/sbom/bom.json")
    xmlOutput = file("build/reports/sbom/bom.xml")
}
tasks.cyclonedxBom {
    jsonOutput = file("build/reports/sbom/bom.json")
    xmlOutput = file("build/reports/sbom/bom.xml")
}

Plugin Application Recommendations

Version 2.4.1: Multiple Application Strategies

// Applied to individual projects OR used init scripts
plugins {
    id 'org.cyclonedx.bom' version '2.4.1'
}

Version 3.0.0: Root Project Application

// ROOT PROJECT build.gradle - RECOMMENDED
plugins {
    id 'org.cyclonedx.bom' version '3.0.0'
}

cyclonedxBom {
    // Configuration applies to both direct and aggregate tasks
}

Output Configuration Changes

Version 2.4.1: Combined Output Properties (deprecated since 2.4.0)

cyclonedxBom {
    destination = file("build/reports")          // Directory
    outputName = "bom"                           // Base filename
    outputFormat = "json"                        // Format: xml, json, all
}

Version 3.0.0: Explicit File Properties

tasks.cyclonedxBom {
    // Explicit file paths for each format
    jsonOutput = file("build/reports/sbom/bom.json")
    xmlOutput = file("build/reports/sbom/bom.xml")
}

// Or disable specific formats
tasks.withType<CyclonedxDirectTask> {
    xmlOutput.unsetConvention()  // Generate JSON only
}

Migration Example

// OLD (2.4.1)
cyclonedxBom {
    destination = file("build/custom")
    outputName = "my-sbom"
    outputFormat = "json"
}

// NEW (3.0.0)
tasks.cyclonedxBom {
    jsonOutput = file("build/custom/my-sbom.json")
    // xmlOutput omitted = only JSON generated
}

Schema Version Configuration Changes

Version 2.4.1: String-Based (deprecated since 2.4.0)

cyclonedxBom {
    schemaVersion = "1.6"
}

Version 3.0.0: Enum-Based

import org.cyclonedx.model.schema.SchemaVersion

tasks.cyclonedxBom {
    schemaVersion = SchemaVersion.VERSION_16
}
tasks.cyclonedxDirectBom {
    schemaVersion = SchemaVersion.VERSION_16
}

Organizational Entity Configuration

Version 2.4.1: Closure-Based Configuration (deprecated since 2.4.0)

cyclonedxBom {
    // Closure-based approach
    organizationalEntity { oe ->
        oe.name = 'Test Company'
        oe.url = ['www.test1.com', 'www.test2.com']
        oe.addContact(organizationalContact)
    }
}

Version 3.0.0: Direct Object Assignment

import org.cyclonedx.model.*

tasks.cyclonedxBom {
    // Direct object assignment
    organizationalEntity = OrganizationalEntity().apply {
        name = "ACME Corporation"
        urls = listOf("https://www.acme.com", "https://security.acme.com")
        addContact(OrganizationalContact().apply {
            name = "Security Team"
            email = "security@acme.com"
            phone = "+1-555-SECURITY"
        })
    }
}

License Choice Configuration

Version 2.4.1: Closure-Based Configuration (deprecated since 2.4.0)

cyclonedxBom {
    // Closure-based approach
    licenseChoice { lc ->
        License license = new License()
        license.setName("Apache-2.0")
        license.setUrl("https://www.apache.org/licenses/LICENSE-2.0.txt")
        lc.addLicense(license)
    }
}

Version 3.0.0: Direct Object Assignment

import org.cyclonedx.model.*

tasks.cyclonedxBom {
    // Direct object assignment
    licenseChoice = LicenseChoice().apply {
        addLicense(License().apply {
            name = "Apache-2.0"
            url = "https://www.apache.org/licenses/LICENSE-2.0.txt"
        })
    }
}

External References Configuration

Version 2.4.1: VCS Git Configuration (deprecated since 2.4.0)

cyclonedxBom {
    // VCS-specific configuration
    setVCSGit { vcs ->
        vcs.url = "https://github.com/example/repo.git"
        vcs.comment = "Source repository"
    }
}

Version 3.0.0: Generic External References

import org.cyclonedx.model.*

tasks.cyclonedxBom {
    // Generic external references
    externalReferences = listOf(
        ExternalReference().apply {
            url = "https://github.com/example/repo.git"
            type = ExternalReference.Type.VCS
        },
        ExternalReference().apply {
            url = "https://example.com/docs"
            type = ExternalReference.Type.DOCUMENTATION
        }
    )
}

Multi-Project Setup Changes

# Generate per-project SBOMs for all projects
./gradlew cyclonedxDirectBom

# Generate single aggregated SBOM
./gradlew cyclonedxBom

Breaking Changes Summary

🚨 Critical Breaking Changes

1. Task configuration syntax changes
2. Output property names changed - destination/outputName/outputFormat (deprecated since 2.4.0) → jsonOutput/xmlOutput
3. Metadata configuration syntax changed - Closures (deprecated since 2.4.0) → Object assignment

⚠️ Behavioral Changes

1. New task structure - Two tasks instead of one
2. Different default output locations
3. Plugin should be applied to root project for aggregation

Step-by-Step Migration Process

1. Update Plugin Version

plugins {
    id("org.cyclonedx.bom") version "3.0.0"
}

2. Update Output Configuration

// OLD
cyclonedxBom {
    destination = file("build/reports")
    outputName = "sbom"
    outputFormat = "json"
}

// NEW
tasks.cyclonedxBom {
    jsonOutput = file("build/reports/sbom.json")
    xmlOutput.unsetConvention()
}

3. Update Schema Version

import org.cyclonedx.model.schema.SchemaVersion

tasks.cyclonedxBom {
    schemaVersion = SchemaVersion.VERSION_16
}

4. Migrate Metadata Configuration

import org.cyclonedx.model.*

tasks.cyclonedxBom {
    // Convert closure-based to object assignment
    organizationalEntity = OrganizationalEntity().apply {
        // configuration
    }
    
    licenseChoice = LicenseChoice().apply {
        // configuration
    }
    
    externalReferences = listOf(
        ExternalReference().apply {
            // configuration
        }
    )
}

5. Update Task Execution

# For per-project SBOMs
./gradlew cyclonedxDirectBom

# For aggregated SBOM (multi-project)
./gradlew cyclonedxBom

6. Verify Output Locations

Check that your SBOM files are generated in the expected locations:

• Direct: build/reports/cyclonedx-direct/
• Aggregated: build/reports/cyclonedx/

Common Migration Issues and Solutions

Issue: "Task configuration not found"

Problem: Using tasks.cyclonedxBom { } syntax
Solution: Use cyclonedxBom { } extension configuration

Issue: "Output files not found"

Problem: Looking in old output location
Solution: Check new default locations or configure explicit paths

Issue: "Schema version error"

Problem: Using string schema version
Solution: Import and use SchemaVersion enum

Issue: "Multi-project aggregation not working"

Problem: Plugin not applied to root project
Solution: Apply plugin to root project and use cyclonedxBom task

Testing Your Migration

1. Clean build directory: ./gradlew clean
2. Test per-project generation: ./gradlew cyclonedxDirectBom --info
3. Test aggregation (if applicable): ./gradlew cyclonedxBom --info
4. Verify output files exist in expected locations
5. Validate SBOM content matches expectations

This migration guide should help you successfully upgrade from CycloneDX Gradle Plugin 2.4.1 to 3.0.0. The new version provides better separation of concerns with dedicated tasks and improved configuration flexibility.