Bamboo API Changes for 5.10

See also

• Bamboo 5.10 upgrade guidelines

Stash rebranding information

We've renamed Stash to Bitbucket Server and Bitbucket to Bitbucket Cloud in the Bamboo GUI to maintain consistency with Stash/Bitbucket rebranding.

The changes in the UI don't affect the internal use of APIs.

Platform upgrades

We're introducing the following changes:

Security improvements: class serialization

Now you can control the Java classes that are serialized in Bamboo and that are required specifically for Bamboo agent-server communication. 

If you have access to the Bamboo home directory, you can edit the whitelist file in the Bamboo configuration directory (<config-dir>/serialization-whitelist.list), which is usually placed in the <bamboo-home>/xml-data/configuration directory*.*

Plugin vendors can implement a new plugin module to list additional whitelisted classes used by their plugin:

Example of a configuration directory file

serialization-whitelist.list

1
2
com.atlassian.bamboo.configuration.StorageLimits
com.atlassian.bamboo.configuration.SystemInfo
com.atlassian.bamboo.plan.PlanKey
com.atlassian.bamboo.plan.PlanResultKey
java.lang.Boolean
java.lang.Double
java.util.UUID

Example of plugin module usage

• atlassian-plugin.xml

1
2
<atlassian-plugin>
  ...
  <serializableClassWhitelistProvider key="serializable.class.whitelist.git" class="com.atlassian.bamboo.plugins.git.GitSerializableClassWhitelistProvider" />
  ...
</atlassian-plugin>

• GitSerializableClassWhitelistProvider.java

1
2
public class GitSerializableClassWhitelistProvider implements SerializableClassWhitelistProvider
{
    ...
    @Override
    public Iterable<String> getWhitelistedClasses()
    {
        return ...;
    }
}

Other API changes

com.atlassian.bamboo.plan.Plan

The following methods were removed without replacement as plugins shouldn't modify the values:

1
2
void setFirstBuildNumber(int firstBuildNumber);

void setLastBuildNumber(int lastBuildNumber);

void setNextBuildNumber(int nextBuildNumber);

com.atlassian.bamboo.plan.ImmutablePlan

Accessing next build number has been deprecated.

1
2
/**
 * The next build number represents the number of the next build result that's to be executed
 * @return a build number, starting with 1
 * @deprecated 5.10 this is a piece of internal data and should not be used
 */
@Deprecated
int getNextBuildNumber();

com.atlassian.bamboo.deployments.execution.DeploymentContext

Return type change. The method incorrectly returned Map<String, Artifact> instead of Multimap<String,Artifact>

1
2
@NotNull
Multimap<String, Artifact> getVersionArtifacts();

com.atlassian.bamboo.build.artifact.ArtifactHandler

This method has been removed.

1
2
/**
 * Retrieve plan artifact. Artifact is found by label (taken from artifactSubscription) and planResultKey.
 * @param planResultKey identifier of source plan
 * @param clientKey identifier of plan or deployment doing the download
 * @param artifactSubscription download details (e.g. target path, copy pattern)
 * @param artifactRetrievalConfig handler specific configuration
 */
@NotNull
ArtifactRetrievalStatus retrieve(@NotNull final PlanResultKey planResultKey,
                                 @NotNull final ResultKey clientKey,
                                 @NotNull final ArtifactSubscriptionContext artifactSubscription,
                                 @NotNull final ArtifactRetrievalConfig artifactRetrievalConfig) throws Exception;

com.atlassian.bamboo.build.artifact.ArtifactManager

Method signature changes.

1
2
/**
 * Retrieves a plan artifact from artifact storage.
 *
 * @param buildLogger           to use
 * @param planResultKey         the plan result that contains the artifact
 * @param artifactSubscription  the artifact subscription used to identify artifact
 * @param buildWorkingDirectory working directory of current build
 * @param availableArtifacts    artifacts found in source result
 * @return true if retrieval was successful, false otherwise
 */
boolean retrieve(@Nullable final BuildLogger buildLogger,
                 @NotNull final PlanResultKey planResultKey,
                 @NotNull final ArtifactSubscriptionContext artifactSubscription,
                 @NotNull final Map<String, String> artifactHandlerConfiguration,
                 @NotNull final File buildWorkingDirectory,
                 @NotNull final Multimap<String, Artifact> availableArtifacts);

/**
 * Retrieves an artifact from artifact storage. The important difference for that method is, that NO subscription
 * information is updated. Useful for retrieving artifacts in non standard way (cross-plan for example)
 *
 * If versionArtifacts parameter is specified, the method will first try to match requested artifact with the content of the map.
 * If match is found, information in {@link Artifact} object will be used to find artifact in the storage.
 *
 * @param buildLogger
 * @param planResultKey
 * @param clientKey
 * @param artifactDefinitionContext
 * @param destinationPath
 * @param artifactHandlersConfiguration
 * @param buildWorkingDirectory
 * @param availableArtifacts
 *
 * @return
 */
boolean retrieve(@Nullable BuildLogger buildLogger,
                 @NotNull PlanResultKey planResultKey,
                 @NotNull ResultKey clientKey,
                 @NotNull ArtifactDefinitionContext artifactDefinitionContext,
                 @NotNull String destinationPath,
                 @NotNull Map<String, String> artifactHandlersConfiguration,
                 @NotNull File buildWorkingDirectory,
                 @NotNull final Multimap<String, Artifact> availableArtifacts);   

com.atlassian.bamboo.task.CommonTaskContext

This method has been added. It returns runtime data that complements static task configuration.

1
2
@Nullable
Map<String, Serializable> getRuntimeTaskData();

Plan directory information REST API

Future changes to on-disk directory layout

A future release of Bamboo will make changes to the layout of the on-disk directory structure for artifacts and logs. These changes are necessary to make functionality more robust. If you are relying on scripts or other tools that examine data in the Bamboo home directory, you will need to update them to ensure that they continue to work.

To make this easier, we have added a resource to the Bamboo REST API to retrieve information about where on disk log files and artifacts will be stored in 5.9 so that you can prepare for the changes.

For more information, see Plan directory information REST API.