Bamboo - Create Build Job

Step 1

Log in to Bamboo and Click the "Create Plan" button.

You will be presented with an initial screen which should be filled out in a similar way to the following:

"Bitbucket" is the name for bitbucket.renalregistry.nhs.uk and you can then select from any of the repositories that you have access to.

Step 2

Ignore this screen for now and click "Create". Make sure that the plan is not enabled otherwise it will try to run and fail straight away.

Step 3 - Repositories

Go to the Repositories Screen and link in the "housekeeping" repository. This contains the build scripts that your job will use. Your project repository should be the default.

Step 4 - Triggers

This menu can be used to configure additional ways in which your job can be triggered - a common one would be linking the projects that your project depends on so it is rebuilt after they are updated.

This can be left as-is for a simple job.

Step 5 - Branches

This menu controls whether your job also applies to any branches of the default repository.

Typically this would be set to "When new branch in repository is created" so that when you are developing a change it is automatically tested. Bitbucket will automatically tidy up files that relate to branches that have become inactive.

Step 6 - Dependencies / Permissions

Leave all these as they are.

Step 7 Notifications

Add a Notification on the Event "Failed Builds and First Successful" and set it to notify the Responsible User(s). If the build breaks this will e-mail those who had last comitted to the repository until the build is fixed.

Step 8 - Variables

Leave this as it is.

(TODO: Check if we have any examples where we use this...)

Step 9 - Miscellaneous

Select "Use Clover to collect Code Coverage for this build."

Choose "Clover is already integrated into this build and a clover.xml file will be produced."

Enter "clover.xml".

The above steps assume you have pytest-clov and coverage2clover setup in your tox.ini.

When setup this will generate a report showing how the coverage changes from build to build.

TODO: Does this step mean that is is no longer neccesary to generate/publish the HTML coverage report as an Artifact?

Step 10 - Audit Log

Leave these as they are.

Step 10 - Job(s)

Select the Default Job from the left hand side of the page. All our build plans (so far) only use a single job.

Step 11 - Source Code Checkout

This step checks out your code to the build directory of the server, along with the housekeeping scripts that will be used by other steps.

• There should be a Task called "Source Code Checkout". Click on this and see that it is set to checkout the Default Repository which should be your project.
• Click on the "Add Repository" button at the bottom of the screen and choose the housekeeping repository. Enter housekeeping as the checkout folder.
• Click Save.

Step 12 - Script Task (Tox)

This step runs Tox which performs a number of tasks such as running unit tests and returning their output in a standard way. (TODO: Link to Tox documentation once written...)

• Click on the "Add Task" button and search for a "Script" task. Click OK.
• In the Task Description enter "Run Tox".
• LINUX: As this is a Linux task put "Shell" as the Interpreter.
• LINUX: For the script location Select "File" and put "housekeeping/scripts/linux/runtests.sh" as the script location.
• WINDOWS: TODO
• Click Save

Step 13 - Script Task (Build Wheel)

This is only required if you wish to package your code as a module to be distributed via Pip. This isn't needed for all repositories, such as those which contain a collection of scripts.

Before doing this step make sure that the changes in Preparing Python Code for Distribution via PIP have been made to the repository.

This step runs a script which builds the code and uploads it to the Dev pip repository. This then allows it to easily be installed on other computers.

• Click on the "Add Task" button and search for a "Script" task. Click "OK".
• In the Task Description enter "Build Wheel"
• LINUX: Again, as this is a Linux task put "Shell" as the Interpreter.
• LINUX: For the script location Select "File" and put "housekeeping/scripts/linux/build_wheel.sh" as the script location.
• WINDOWS: TODO
• In the Argument field put "dev my_package", where my_package is the name of the package to be built. Dev is the index to which it will be published.
• Click Save

Step 14 - Junit Parser Task

This step takes the XML output produced by any tests that have run and parses it into a format that Bamboo can understand.

• Click on the "Add Task" button and search for the "Junit Parser" task. Click OK.
• In the Task Description enter "Parse Reports"
• The custom results directory should already be set to "**/test-reports/*.xml" - if so leave as-is.
• Click Save
• Drag the "Junit Parser" Task down to the "Final Tasks" section. This is so that it runs even if there has been a problem with the previous steps.

Step 15 - Requirements

• Click on the "Requirements" Tab.
• As this is a Linux job choose "Linux Python3.6" and "exists", then "Add". This should change the "Number of Agents this job can build on" from 2 to 1 as you have restricted it to running on the Linux server.

Step 16 - Artifacts

Artifacts are files that have been produced as part of the build process that you wish to make available via the Bamboo website. This may include code coverage reports or zipped builds of the code.

The locations will vary but if you have used the Build Wheel script above you should find a wheel file in a dist subdirectory of wherever your code was checked out to.

Step 17 - Miscellaneous

You should be able to leave this as-is. Setting it to clean the build directory is sometimes useful if you are having issues with your Python virtualenv containing incorrect package versions but it will noticably slow down the build process.