1.2 Creating a Plan

To create a new plan,

To copy an existing plan,

Screenshot 1. 'Plan Details' 

1. 'Plan Details': 

• Project — When you create a new plan, you can either add it to an existing project or create a new project. Either:
  • Select the appropriate project from the drop-down list;
    or:
  • Select 'New Project' and complete the following two fields:
    1. Project Name — Type a descriptive name (e.g. 'Issue Tracking Application') that will identify your project on the Dashboard and in reports. 
    2. Project Key — Type a logical contraction of the Project Name (e.g. 'ITA'). The Project Key will be included in the plan's Build Results keys (e.g. 'ITA-MAIN-179'), so you may want to make it no longer than 3 or 4 characters. The Project Key must be unique within your Bamboo system.
• Build Plan Name — Type a name that will identify the plan within its project (e.g. 'Main Build', 'Branch', 'Unit Tests', 'Acceptance Tests'). Note that the Build Plan Name, which is displayed throughout Bamboo, is always accompanied by its Project Name.
• Build Plan Key — Type a logical contraction of the Build Plan Name. The Build Plan Key (e.g. 'MAIN') will be included in the plan's Build Results keys (e.g. 'ITA-MAIN-179'), so you may want to make it no longer than 3 or 4 characters. Note that the Build Plan Key only has to be unique within the project, that is, you could have a 'MAIN' plan in lots of different projects.

Note that Project Name and Build Plan Name can be edited after the plan is created. A plan's Project Key and Build Plan Key are not editable, but can be changed as described in 1.5 Moving a Plan to a different Project.

Screenshot 2. 'Source Repository'

2. 'Source Repository':

• 'Repository' — Select the type of repository from which Bamboo will check-out and build this plan's source-code. The following fields will vary depending on what type of repository you select:
  • CVS:
    • 'CVS Root' — Type the full path to your CVS repository root (e.g. ':pserver:me@cvs.atlassian.com:/cvsroot/atlassian'). Bamboo supports pserver, ext (ssh) and local repository access methods.
    • 'Authentication Type' — Select either 'Password' or 'SSH'.
      • If you select 'Password', the following fields will appear:
        'Password' — (Optional) Type the password for your CVS repository.
        'Change Password' --- (Will only appear after you have saved the plan) Select this check-box if you want to change the password that is used to access the CVS repository.
      • If you select 'SSH', the following fields will appear:
        'Private Key' — Type the absolute path of your SSH private key.
        'Passphrase' — Type the passphrase for your SSH private key.
        'Change Passphrase' --- (Will only appear after you have saved the plan) Select this check-box if you want to change the password for your SSH private key.
    • 'Quiet Period' — This setting is used to avoid starting a build while someone is in mid-checkin. Bamboo will only initiate a build for this plan when no more changes are detected within the Quiet Period following the last known change. Type the number of seconds Bamboo should wait.
    • 'Module' — Type the name of the CVS module that contains the source-code.
    • 'Version of Module' — Select either 'HEAD' or 'Branch/Tag'. If you select 'Branch/Tag', the following field will appear:
      • 'Branch name' — Type the relevant branch name or tag.
  • Subversion:
    • 'Repository URL' — The location of subversion repository (e.g. http://svn.collab.net/repos/svn/trunk).
    • 'Username' — (Optional) The Subversion username (if any) required to access the repository.
    • 'Authentication Type' — Select either 'Password' or 'SSH'.
      • If you select 'Password', the following field will appear:
        'Password' — (Optional) Type the password required by the Subversion username (if applicable).
        'Change Password' --- (Will only appear after you have saved the plan) Select this check-box if you want to change the password that is used to access the Subversion repository.
      • If you select 'SSH', the following fields will appear:
        'Private Key' — Type the absolute path of your SSH private key.
        'Passphrase' — Type the passphrase for your SSH private key.
        'Change Passphrase' --- (Will only appear after you have saved the plan) Select this check-box if you want to change the password for your SSH private key.
    • 'Use Externals?' — (Optional) Select this check-box if your Subversion repository uses svn:externals to link to other repositories. Please note that you only need to select this check box if you require Bamboo to detect changes in the externals. If your externals references a particular (static) revision, you do not need to check this box.
  • Perforce:
    • 'Perforce P4 client' — The location (on the Bamboo server) of the Perforce P4 client application. On UNIX systems this is typically /usr/local/bin/p4.
    • 'Port' — Type either the port to which the Perforce client will connect, or the Perforce server itself. This is the Perforce P4PORT environment variable that tells Bamboo which p4d (Perforce server) to use.
    • 'Client (Workspace)' — The name of the Perforce Client Workspace which Bamboo will use. The Client Workspace determines which portions of the depot are visible in your Workspace Tree and where local copies of depot files are stored in your workspace.
       If you wish to have several plans pointing to the same Perforce depot, you will need to set up a different client for each.
    • 'Depot View' — The client view of the depot that contains the source-code files for this plan. This is typically in the form //<clientname>/<workspace_mapping>/... For details please see the Perforce User's Guide.
    • 'Username': (Optional) The Perforce username that Bamboo will use when it accesses the server ('Port'). Leave this field blank if you want Bamboo to use the default Perforce user (i.e. the OS username).
      Please set the P4PASSWD environment variable to the Perforce password of the Username that Bamboo will use when it accesses Perforce. The P4 client will look up the environmental variable every time it needs to verify the user's identity for any Perforce client command.
    • 'Web Repository URL' — (Optional) You can specify the URL of the plan's browsable repository. If you specify a Web Repository URL, then links to relevant files will be displayed in the 'Code Changes' section of a build result.
• 'Include/Exclude Files' — (Optional) You can specify a particular inclusion or exclusion pattern for file changes to be detected.
• 'File Pattern' — (Optional) The regular expression for file changes for which you wish to include/exclude.
• 'Web Repository Module' — (Optional) The plan's repository name, if the above Web Repository URL points to multiple repositories.
• 'Build Strategy' — The default value, 'Poll the repository for changes', is a convenient option that requires no additional configuration. A number of other options are available; for details, please see 03. Triggering a Build. You can change the Build Strategy over time as required. The rest of the fields on this tab will vary depending on which Build Strategy you select.
  

Screenshot 3. 'Builder Configuration' 

3. 'Builder Configuration':

To define a new Builder, please see 2.1 Configuring a new Builder.

• 'Builder' — From the list of available Builders, select the one which Bamboo will use to build this plan. The following fields will vary depending on what type of Builder you select:
  • Ant:
    • 'Build File' — (Optional) Type the relevant filename (e.g. build.xml)
    • 'Target' — Specify the Ant target you want Bamboo to execute each time the source code changes. For example: test (this will run the Ant target 'test'). You can also use '-D' to define one or more system properties, e.g.: -Djava.awt.headless=true (this will pass the parameter 'java.awt.headless' to with a value of 'true').
  • Maven:
    • 'Goal' — Specify the Maven goal you want Bamboo to execute each time the source code changes. For example: clean test (this will run the Maven goal 'clean' followed by the Maven goal 'test'). You can also use '-D' to define one or more system properties, e.g.: -Djava.awt.headless=true (this will pass the parameter 'java.awt.headless' to with a value of 'true').
  • Custom command:
    • 'Argument' — Specify the relevant argument to pass to the command. Note that arguments which contain spaces must be quoted.
  • Script:
    • 'Script' — Specify the location of the script file. This can be either relative to the repository root of the plan, or absolute.
    • 'Argument' — Specify the relevant argument to pass to the script. Note that arguments which contain spaces must be quoted.
  • With each of the above fields, you can specify variables by using the following format: ${bamboo.<your_variable>}. These variables will be evaluated during build time. To configure global variable values, please see 2.3 Configuring Global Variables.
• 'Build JDK' — If you selected an Ant or Maven builder above, you will need to choose a JDK from the list.
  To define a new JDK in your Bamboo system, please see 2.2 Configuring a new JDK.
• 'System Environment Variables' — (Optional) Specify any operating system environment variables you want to pass to your build. Note that 'System Environment Variables' are specific to this particular build. 
• 'Working Sub Directory' — (Optional) If you leave this field blank, Bamboo will look for the build files in the build root directory (which is assumed to be the build's Working Directory). You can override this option by specifying an alternative working directory (which must be a subdirectory of the root directory). For example, if your plan has a build script in a subdirectory, and the script needs to be run from within that subdirectory, you would type the name of that subdirectory in the 'Working Sub Directory' field.
• 'The build has tests' — Select this check-box if you want Bamboo to gather test results data for each build result. Choose one of the following:
  • 'Test Results Directory' — Select this option if Bamboo should look in the Builder's standard test results directory.
  • 'Specify custom results directories' — Select this option if the Builder will place generated test results in an alternative directory:
    • 'Specify custom results directories' — Type the name of the test results directory (or multiple directories, separated by commas). You can also use Ant-style patterns such as */test-reports/.xml.
• 'Clover output will be produced' — Select this check-box if you are running Cenqua Clover and want to view its code-coverage data from within Bamboo. The following field will be displayed:
  • 'Clover XML Directory' — Specify the name of the directory (including path) where Bamboo will look for the XML report output file from Clover. Please note that the Clover coverage analysis will only run for successful builds.

Screenshot 4. 'Build Artifacts'

4. 'Build Artifacts':

Here you can specify the plan's artifacts, e.g. JAR files which you wish to keep after each build. Artifacts can be any reports, websites or files. Artifacts are copied to a subdirectory (/PROJECT_NAME/download_data) under your 'Projects Data' folder (see 8.1 Locating Important Directories and Files).

• 'Artifact Label' — Specify the name which Bamboo will use to describe the artifact.
• 'Artifact Copy Pattern' — Specify the name (or Regular Expression pattern) of the artifact(s) you want to keep.
• 'Source Directory' — Specify the directory (including path) where Bamboo will look for your artifact.

For example, if you want to keep the latest version of a JAR you have built, you could specify Artifact Copy Pattern to be '*/.jar' and the Source Directory to be 'target'.

Screenshot 5. 'Notifications' 

5. 'Notifications':

• Here you can specify who will receive notifications about this plan's build results, and under what circumstances. For details please see 6.1 Enabling or disabling Notifications for a Plan.
  

Screenshot 6. 'Post Actions' 

6. 'Post Actions':

• 'Regex Pattern' — The regular expression for which to match the log files on. Labels will be applied to the build if the regular expression finds a match. You can leave this blank to label every build.
• 'Labels' — Type the labels (if any) which you want to automatically apply to the plan's build results. See 1.4 Specifying Labels for a Plan's Build Results.
  

RELATED TOPICS

• 1.1 About Projects, Plans and Builds
• 1.2 Creating a Plan
  • 1.2.1 Using Custom Variables
• 1.3 Editing a Plan
• 1.4 Specifying Labels for a Plan's Build Results
• 1.5 Moving a Plan to a different Project
• 1.6 Disabling or deleting a Plan
  • 1.6.1 Deleting a Build Result