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.
Before you begin
Make sure you have the following installed:
- JDK 8 or higher
- Maven 3.2 or higher
- Eclipse or IntelliJ IDEA IDE
Note: You may use a different IDE, but tutorial provides examples for the two above
- Bamboo 6.0 or higher
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=minimalwhere:
| Property | Description |
|---|---|
| Maven uses a set of identifiers to uniquely identify a project and specify how the project artifact should be packaged:
|
| Your Project identifiers:
|
| Prefix of the Java package that you want to use for the project. |
| 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-specsStep 2: Import the project into IDE
You can now import the project into your integrated development environment (IDE).
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:
| PlanSpec | The name of the class. You can use any class name. |
| BambooSpec | The file is annotated. The annotation is used by the spec-runner Maven plugin to find classes containing Bamboo plans. |
| main | With the main method you can run the project as any other Java application. |
| BambooServer | The 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
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)"); }- Type "." and let your IDE show you available options:
- 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).
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"))); }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!")))); }
You can always open a JavaDoc dialog to learn more about given method or class:
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.
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 / Name | A path to an invalid element |
| Expected and actual value |
PlanSpec.java:42 | The 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
.credentialsfile located in the root directory of the project.
When you're sending a plan, Bamboo validates it.
The console output looks like this:
Publishing plan PLANKEY
Result OK: http://localhost:8085/browse/PRJ-PLANKEYFor more verbose logging, add -Dbamboo.specs.log.level=DEBUG program argument when running Bamboo Specs.
Step 6: Check the results
- Go to your Bamboo instance.
- Open the plan that you created.
- Go to Actions > Configure plan.
- Check whether the stage contains a job with the Hello world Script task.
- Select Run > Run plan to execute the build.
- 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:
- Create a Bamboo Specs project using Maven Archetype
- Exporting existing plan configurations to Bamboo Specs
- Creating deployment projects in Bamboo Specs
- Bamboo Specs reference
- Bamboo Specs API reference