Tutorial: Create a simple plan with Bamboo Java Specs

This guide will help you understand how to create plans with Bamboo Java Specs. You'll create a simple project and execute it to create a plan in Bamboo.




On this page





Before you begin

Make sure you have the following installed:

Note: You may use a different IDE, but tutorial provides examples for the two above


Step 1: Create a project base with Maven

To create a base of the project, execute the following Maven archetype:

mvn archetype:generate -B \
    -DarchetypeGroupId=com.atlassian.bamboo -DarchetypeArtifactId=bamboo-specs-archetype \
	-DarchetypeVersion=6.2.1 \
    -DgroupId=com.atlassian.bamboo -DartifactId=bamboo-specs -Dversion=1.0.0-SNAPSHOT \
    -Dpackage=tutorial -Dtemplate=minimal

where:

PropertyDescription
  • archetypeGroupId
  • archetypeArtifactId
  • archetypeVersion

Maven uses a set of identifiers to uniquely identify a project and specify how the project artifact should be packaged:

  • archetypeGroupId - Bamboo Specs archetype’s groupId. Must be set to com.atlassian.bamboo
  • archetypeArtifactId - Bamboo Specs archetype’s artifactId. Must be set to bamboo-specs-archetype
  • archetypeVersion - Bamboo Specs archetype’s version. It should match the version of Bamboo you’re using.
  • groupId
  • artifactId
  • version

Your Project identifiers:

  • groupId - ID of the project’s group (eg. base name of your company); it can have an arbitrary value;
  • artifactId - ID of the project’s artifact; it should be set to bamboo-specs, so the project will be created in the bamboo-specs directory; you can change this value, but then you must manually rename the output directory to bamboo-specs;
  • version - version of your project; it can have an arbitrary value.
  • package
Prefix of the Java package that you want to use for the project.
  • template
Type of code in which the project is generated. For the purpose of this tutorial we're using minimal.


The project is created in the bamboo-specs directory:

cd bamboo-specs

Step 2: Import the project into IDE

You can now import the project into your integrated development environment (IDE).


How to import into Eclipse
  1. Run Eclipse.
  2. In the main menu, go to File > Import.
  3. In the Import dialog, select Maven > Existing Maven Projects.
  4. Select Next.
  5. Select Browse.
  6. Select the bamboo-specs-tutorial directory, and select Open.
  7. Select Finish.


Eclipse will create a new project and download necessary dependencies (it may take a while).

How to import into IntelliJ IDEA
  1. Run IntelliJ IDEA.
  2. In the main menu, go to File > Open.
  3. Select the pom.xml file.
  4. Select Open as project.

IntelliJ IDEA will create a new project and download necessary dependencies, which might take a while.


If you want to see how PlanSpec.java files is structured, go to src/main/java/tutorial/PlanSpec.java. Your file should have the following structure:

PlanSpecThe name of the class. You can use any class name.
BambooSpecThe file is annotated. The annotation is used by the spec-runner Maven plugin to find classes containing Bamboo plans.
mainWith the main method you can run the project as any other Java application.
BambooServerThe project uses the BambooServer class to publish plans with password authentication. The username and password are read from the .credentials file which is located in the current working directory.

Step 3: Define a job with a script task

  1. In the createPlan method put a cursor after the description method call:

    private Plan createPlan() {
        return new Plan(
                project(),
                "Plan Name", "PLANKEY")
                .description("Plan created from (enter repository url of your plan)");
    }
  2. Type "." and let your IDE show you available options:
  3. Select the stages method and add the new Stage ("Stage 1") constructor call inside the method's argument (you need to add the import statement for Stage class).
  4. Add a job to the stage using the jobs method and new J o b() constructor (add the import statement too). Name the job Build & run and use RUN for a key:

    private Plan createPlan() {
        return new Plan(
                project(),
                "Plan Name", "PLANKEY")
                .description("Plan created from (enter repository url of your plan)")
                .stages(
                        new Stage("Stage 1")
                                .jobs(new Job("Build & run", "RUN")));
    }
  5. Let's add a task to the job. Type .tasks() and declare a new ScriptTask() inside as shown below (add the import statement too). Call .inlineBody on the ScriptTask().

    private Plan createPlan() {
        return new Plan(
                project(),
                "Plan Name", "PLANKEY")
                .description("Plan created from (enter repository url of your plan)")
                .stages(
                        new Stage("Stage 1")
                                .jobs(new Job("Build & run", "RUN")
                                        .tasks(
                                                new ScriptTask().inlineBody("echo Hello world!"))));
    }


tip/resting Created with Sketch.

You can always open a JavaDoc dialog to learn more about given method or class:

How to show JavaDoc in Eclipse

To download JavaDocs, hold the Ctrl/Cmd key, place the mouse cursor over a method or class name, and select open declaration.

It opens a source editor with a decompiled class file. Eclipse immediately starts downloading sources and JavaDoc JARs in the background and updates editor as soon as it completes.

To display JavaDocs place the mouse cursor over a class or method name.

How to show JavaDoc in IntelliJ IDEA

To download JavaDocs hold the Ctrl/Cmd key and select the method or class name.

It opens a source editor with the decompiled class file. Select the Download sources link. IDEA will download sources and JavaDoc JARs.

To display JavaDocs place the cursor over a method or class name and press Ctrl+J to open a quick documentation pop-up.




Step 4: Validate Bamboo Specs offline

You can perform offline validation before deploying a plan to Bamboo. Let's try it out by running a unit test.


How to run from Eclipse
  1. In the Package Explorer view, right-click on src/test/java/tutorial/PlanSpecTest.java.
  2. Select Run as > JUnit test.
How to run from IntelliJ IDEA
  1. In the Project view, right-click on the src/test/java/tutorial/PlanSpecTest class.
  2. Select Run 'PlanSpecTest' .


Test fails with the following stack trace:

com.atlassian.bamboo.specs.api.exceptions.PropertiesValidationException: 
Plan or job / Name: can not contain any of those characters: [", &, ', <, >, \] but it is 'Build & run'
    at com.atlassian.bamboo.specs.api.validators.common.ImporterUtils.checkNoErrors(ImporterUtils.java:44)
    ...
    at tutorial.PlanSpec.createPlan(PlanSpec.java:42)
    at tutorial.PlanSpecTest.checkYourPlanOffline(PlanSpecTest.java:12)	

where:

Plan or job / NameA path to an invalid element

can not contain ...

but it is ...

Expected and actual value
PlanSpec.java:42The source line containing the error


As you can see, the validation fails because the name of the job contains an invalid & character. Let's remove it. Your code should look like this now:

private Plan createPlan() {
    return new Plan(
            project(),
            "Plan Name", "PLANKEY")
            .description("Plan created from (enter repository url of your plan)")
            .stages(
                    new Stage("Stage 1")
                            .jobs(new Job("Run", "RUN")
                                    .tasks(
                                            new ScriptTask().inlineBody("echo Hello world!"))));
}


Run the test again to make sure that it passes this time.

Step 5: Publish Bamboo Specs to the Bamboo server

  • Make sure that your Bamboo instance is up and running.
  • If you're not running Bamboo on your local machine ( http://localhost:8085 ), change the bambooUrl variable in the main method.
  • We're assuming that you have an administrator account with username admin and password admin. If you want to use other credentials, you need to update the .credentials file located in the root directory of the project.


When you're sending a plan, Bamboo validates it. 


How to run from Maven

The pom.xml contains the publish-specs profile which executes the spec-runner Maven plugin. So just type:

mvn -Ppublish-specs
How to run from Eclipse
  1. In the Package Explorer view, right-click on the PlanSpec class.
  2. Select Run as > Java application.
How to run from IntelliJ IDEA
  1. In the Project view, right-click on the PlanSpec class.
  2. Select Run 'PlanSpec.main()'.


The console output looks like this:

Publishing plan PLANKEY
Result OK: http://localhost:8085/browse/PRJ-PLANKEY

For more verbose logging, add -Dbamboo.specs.log.level=DEBUG program argument when running Bamboo Specs.

Step 6: Check the results

  1. Go to your Bamboo instance.
  2. Open the plan that you created.
  3. Go to Actions > Configure plan.
  4. Check whether the stage contains a job with the Hello world Script task.
  5. Select Run > Run plan to execute the build.
  6. Find the "Hello World!" message in the logs.  


Having configuration written as code using Bamboo Specs you can very easily manage all your build plans in Bamboo.

This is a very convenient method of managing large Bamboo instances with huge number of plans, publishing plans on Bamboo test instances before promoting changes to production, and tracking configuration changes in version control system.

Read What is Configuration as Code? to learn more about the benefits of using Bamboo Specs.


Next steps

 Here are some resources that can help you with writing your own Bamboo Specs:


Last modified on Mar 29, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.