Skip to main content

Gradle configuration cache

Abstract

Gradle configuration cache reduces build times by caching the result of a Gradle project's configuration phase and reusing it in subsequent builds. For details, read Gradle's official documentation. The Bitrise Build Cache supports this feature for Gradle 8.6 and later versions.

Gradle configuration cache reduces build times by caching the result of a Gradle project's configuration phase and reusing it in subsequent builds. For details, read Gradle's official documentation. The Bitrise Build Cache supports this feature for Gradle 8.6 and later versions.

Setting up the configuration cache

To set up the configuration cache:

  1. Make sure you have a subscription or a trial for the Bitrise Build Cache.

  2. Run a build locally with the --configuration-cache flag.

    This ensures that your Gradle project supports configuration caching. To enable configuration caching in the Gradle settings, refer to Gradle's official guide.

  3. Generate a Bitrise personal access token and add it as a Secret with the BITRISE_BUILD_CACHE_AUTH_TOKEN key.

    Token consistency

    For the configuration cache to function correctly, the authentication token used by the Gradle plugins must remain consistent across builds.

  4. Generate a Gradle encryption key:

    openssl rand -base64 16

  5. Save the key as a Secret named GRADLE_ENCRYPTION_KEY in your Bitrise project.

    This ensures that the encrypted value of the configuration cache remains the same across different builds. Using a fixed encryption key is supported from Gradle version 8.6 or later. Bitrise doesn't support Gradle configuration cache for earlier Gradle versions.

  6. Set your Bitrise workspace slug as an Environment Variable named BITRISE_BUILD_CACHE_WORKSPACE_ID.

  7. Add the Build Cache for Gradle Step to your Workflow.

    The Step must be of version 2.7.7 or later. Any subsequent updates to the Step will cause a one-off invalidation of the configuration cache. If this happens, do a rebuild to fix the issue.

  8. Add the Restore Gradle configuration cache and the Restore Gradle Cache Steps before your Gradle invocation in the Workflow.

    The Steps retrieve cached configuration data and enable the configuration cache to access artifacts it references.

    Configuration cache directory

    The Restore Gradle configuration cache Step saves data in the ./.gradle/configuration-cache directory. You can override this by changing the Configuration cache directory input.

    For example, if you use Android Build to build your Gradle project, these two Steps must come before it in the Workflow.

  9. Add the Save Gradle configuration cache and the Save Gradle Cache Steps after your Gradle invocation in the Workflow.

    The Steps save the configuration data to the cache and save artifacts referenced by the configuration cache.

  10. Enable the Save transforms input of the Save Gradle Cache Step. You need Step version 1.4.1 or later.

Saving the Gradle configuration cache log

Gradle's build logs might contain information about why it didn't reuse the configuration cache. You can save the log to the Artifacts page of your build:

  1. Enable the --info log level in Gradle.

  2. Add the Deploy to Bitrise.io Step to your Workflow.

  3. Set the Deploy directory or file path input to what Gradle outputs as the file path.

You can check the deployed file on the Artifacts page: open Bitrise CI, select your project and then the build, and select the Artifacts tab.

Troubleshooting the configuration cache

If your build doesn't reuse the configuration cache, you can check a number of potential problems.

General troubleshooting

  • Make sure to add the Save/Restore Gradle cache Steps to utilize dependency caching. Gradle configuration cache references artifacts that must be present.

  • It may take multiple runs before the configuration cache is fully applied and reused.

  • Check the Gradle logs to find out why Gradle didn't reuse the configuration cache. You can save the gradle configuration cache log to your build artifacts.

  • Updates to the Build Cache for Gradle Step will cause a one-off invalidation of the configuration cache. Just run another build to fix the problem.

Failed to instrument class error

Your build could fail with the following error:

org.gradle.internal.operations.BuildOperationInvocationException: Failed to instrument class io/bitrise/gradle/cache/BitriseBuildCache in ClassLoaderScopeIdentifier.Id{coreAndPlugins:init-file:/root/.gradle/init.d/bitrise-build-cache.init.gradle.kts(export)}

To fix this issue:

  1. In the Save Gradle cache Step, set the Save transforms input to true.

    Version requirement

    The input is only available from version 1.4.1 or later.

  2. Force a save by running a build without the Restore Gradle cache Step.

In this section: