Forge
How-to guides

Package the project sources

Declare what zipSources packages, and the two guards it enforces.

A delivery sometimes includes the sources the resource was built from. zipSources packages them into build/distributions/<resource-archive-name>-sources.zip, from a list you declare. Sending the archive stays your act: Forge writes it and never delivers it.

Declare what the archive holds

Add a sources block to the forge extension in build.gradle.kts:

forge {
    sources {
        include(
            "settings.gradle.kts", "build.gradle.kts", "gradle.properties",
            "gradlew", "gradlew.bat", "gradle/**", "src/**",
        )
    }
}

include takes Ant-style patterns relative to the project directory. The list above produces an archive a recipient can unzip and build with ./gradlew build.

A project that declares no block, or a block naming no include, produces no archive. zipSources reports SKIPPED and assemble succeeds. Tasks records the task's lifecycle edge and the inherited Zip methods to leave alone.

Keep the list current

Forge contributes no default patterns, so nothing ships unless you named it. Adding a file the build needs, without adding it here, produces an archive that does not build. Re-read this block when you add a build file, and when you upgrade Forge.

Remove something inside an included tree

src/** takes the whole source tree, including an assembly folder that may hold a client's model. exclude carves it back out:

forge {
    sources {
        include("build.gradle.kts", "src/**")
        exclude("src/main/assembly/samples/acme-nda/**")
    }
}

Two guards

Credentials. zipSources fails when your project's gradle.properties carries com.mbseconsulting.forge.credentials.username or .password and that file is in the archive:

> Task :zipSources FAILED

gradle.properties carries credentials that would ship in the source archive:
  com.mbseconsulting.forge.credentials.password

Move the keys to ~/.gradle/gradle.properties, which Forge merges under your project file anyway. To package the file as it stands, declare allowCredentials() in the same block.

The guard knows those two keys, and it reads the applying project's own gradle.properties alone — the root project's only in a single-project build. A subproject's own file, packaged by a pattern such as include("sub/**"), is never scanned, so keep credentials out of every module. A signing key or a .env matched by a broad pattern raises nothing either, so keep the include list narrow.

Build output. A pattern that is not rooted at a directory you named — include("**") — fails, naming a path it found under the build directory. The build directory itself is not the problem: an unrooted pattern reaches every path Gradle visits while resolving it, and the build directory is only the one instance the guard can see land there. The guard reads the resolved tree, and the build directory is part of that tree whether or not it holds a file yet, so a pattern rooted at ** fails on a clean checkout the same way it fails on a rebuilt one.

Root every pattern at a directory you name, and it keeps the filter you meant:

// Before: unrooted, and rejected
include("**/*.kt")

// After: rooted at src/, and equivalent
include("src/**/*.kt")

src/** is not a substitute for src/**/*.kt — the first takes the whole source tree, the second takes only Kotlin files under it. Keep the extension filter and add the directory it belongs to: **/*.mdzip becomes src/**/*.mdzip, not src/**.

Where the archive goes

build/distributions/, beside the resource zip, the plugin zip, the API-docs zip and the report:

build/distributions/
  acme-profile-1.4.0-2024x.zip
  com.acme.profile-1.4.0-2024x.zip
  acme-profile-1.4.0-2024x-sources.zip
  acme-profile-1.4.0-2024x-apidocs.zip
  acme-profile-1.4.0-2024x-report.html
  acme-profile-1.4.0-2024x-report.json

The base name comes from com.mbseconsulting.forge.resource.name and com.mbseconsulting.forge.resource.humanVersion, the same two keys that name the resource zip; see Properties. Missing either, zipSources fails naming the key rather than writing a delivery under an invented name.

Handing that folder over hands over the sources, so removing the archive is the deliberate act.

The archive reaches no Maven repository. Publication reads publication-index.json, which names each artifact explicitly, and zipSources writes no entry there. The index sits in build/publication/, outside the release set; see Build outputs.

What the archive does not claim

Running zipSources does not record that a client received the archive. Building it and sending it stay two separate acts, and only the second one is yours to track.

Declare the second act yourself. com.mbseconsulting.forge.legal.sourceProvided takes Provided or Not provided, and ARTIFACT-INFO carries the answer in its Source field for every artifact except a Product. Forge reads that key and nothing else: it never infers the declaration from whether zipSources ran, from the sources block, or from the archive sitting in build/distributions/. A project may build the archive and withhold it, or hand over source it never packaged this way.

The key carries no default. Under an MBSE Consulting licence a Deliverable that omits it fails the build; elsewhere ARTIFACT-INFO renders Not provided, so a delivery that did include source under-claims until someone declares it. See Properties.

On this page