Agile Central Build Connector for Bamboo

Overview

The Agile Central Build Connector for Bamboo posts information about Bamboo Plan Builds to Agile Central. The CA Agile Central Build Connector is classified as a one-way and one-time mechanism. Information in Bamboo is never altered. The AC Build Connector consists of software that you run on your platform according to your desired schedule. The configuration of the connector is policy-based, meaning that you do not need to provide configuration information in Bamboo for each plan for which you want the connector to operate. While you can configure specific plans with this connector, you can also configure by views and folders with the option to use shell regex syntax to include plans or exclude plans. The policy-based nature allows you to add Bamboo Plans per Bamboo Project without altering the configuration in order to get the builds for those plans posted to Agile Central.

This guide includes:

Requirements

  • Bamboo 6.0.3 and 6.1. We expect the connector to work with the 6.x evolution as long as any Bamboo API changes are backwards compatible.
  • Python 3.5.x or 3.6.x (if the platform you are using is Windows, we recommend using the 64-bit version). You can retrieve the installer package from www.python.org.
  • Windows-only additional requirements: The pywin32 package must be downloaded and installed subsequent to Python 3.5 or 3.6 installation.

Connector Download

To download the connector, follow the steps here.

Installation

  1. pip3 install requests==2.12.5
  2. pip3 install pyral==1.3.1
  3. pip3 install PyYAML==3.12
  4. Unpack bldeif-1.1.2.zip
  5. Change your working directory (cd) to a directory where you want to install the connector
  6. Unzip bldeif-1.1.2.zip (or use a suitable program that can unzip a .zip file)
  7. bldeif-1.1.2
  8. ls -laR # observe the unpacked contents, or use dir on Windows

Sample contents:

bldeif             # bldeif module root directory
ac_build_connector # connector initiation script that you will run
config             # holds any configuration files used with this connector
sample_bamboo.yml  # a sample configuration to use as a base reference
README_BAMBOO.txt  # this file

Setup

General recommendations:

  1. Start simple. Specify Bamboo Plans under their respective Bamboo Project.

  2. Locate the configuration subdirectory.

  3. Copy the sample_bamboo.yml file to a file named suitably for your environment, for example

    cp sample_bamboo.yml your_config.yml
  4. Edit your_config.yml file. Change the sample values for credentials, workspace , projects, plans to values that are relevant and valid for your environment.

       *See Appendix A on configuration file syntax.

Operation

Manual

Using a terminal window or console: cd to the installation root directory eg. /opt/local/sw/bldeif-1.1.2 and run the following command, replacing your_config.yml with the name of your .yml file:

 

python3 ac_build_connector your_config.yml

This software requires that the configuration file reside in the configuration subdirectory. You specify the name of the file on the command line (don't specify the subdirectory in the command line argument).

Scheduled

Use either cron, launchctl, or Windows Task Scheduler. Make sure the environment in effect when running this software has an appropriate environment set so that you can run:

python3 $BLDEIF/ac_build_connector your_config.yml

where $BLDEIF is the reference to an environment variable containing the fully qualified path to the directory where the software is installed. As an example: If you unzipped the package in /opt/local/sw, then your BLDEIF would be set like this:

export BLDEIF=/opt/local/sw/bldeif-1.1.2

Time File

In normal operation, the connector writes a time file in the log directory whose name is based on the configuration file name.

Example: If the configuration file name is your_config.yml then the associated time file name would be product_x_time.file. The content of the time file is a single line containing a human readable date and time stamp value in the format YYYY-MM-DD hh:mm:ss Z. The value represents the timestamp of the last Bamboo plans considered (after some negative value adjustment to ensure no Bamboo plans are ever overlooked). When the connector is run a subsequent time, it consults the time file to determine which plans need to be considered for the current run by only processing the builds whose start time is greater than or equal than the time file value. It is possible to set the time file value artificially (but in the correct format) so that you can revert to builds from some arbitrary point in the past. The connector does not duplicate build records so you do not have to worry about duplicated information getting posted to Agile Central.

Troubleshooting

The connector always writes a log file name based on the configuration file name. The log file is written into the log subdirectory under the base installation directory. Within the configuration file, you can set the LogLevel which determines the amount of logging information written to the log file. When you set the LogLevel to DEBUG, you will get the full range of logging messages that can be very helpful in pinpointing where a problem occurred and what information was being processed at the time of the anomaly.

It can be helpful to run the connector in Preview mode when setting things up for the first time. This allows you to get the connections to Agile Central and Bamboo to initialize and validate correctly without posting any build information. This mode also can show you what Bamboo plans would actually be considered without actually posting any build information to Agile Central.

Known size limitation on plan names

Within AgileCentral there is an entity called a BuildDefinition which for the purposes of the Build Connector for Bamboo is named after the Bamboo plan. The AC BuildDefinition Name attribute is limited to 256 bytes.

VCS Support

Currently the connector will not process changesets related to builds. In order to see builds related to changesets, run a VCS connector prior to the Build Connector.

Appendix A - Configuration file editing

The CA Agile Central build connector for Bamboo uses a text file in the YAML format. For complete information, consult the web page at www.yaml.org/start.html.

For brevity, this document mentions several of the most relevant syntax items and covers the three sections of a valid YAML configuration that can be used with the connector:

  • Use a text editor (not MS Word or Google Doc) to edit the file.
  • Never use a tab character in the file. YAML does not allow or recognize tab characters.
  • Save the file in UTF-8 format.
  • Use a monospace font.
  • Be consistent with the number of spaces you use to indent.
  • On a line, the first occurrence of a non-quoted # character indicates a comment, the # character and all characters to the right are ignored in processing.
  • Keep the sections in the same order as is present in the sample.yml file.
  • Be aware that the colon character : is significant, it separates a key from the value.
  • Be aware that the dash character - is significant, it denotes the start of a list which may have one or more key value pairs that constitute the list item.
  • You usually do not have to quote values if they have spaces in them; you will have to quote the value if it contains an embedded # character.


Skeleton of the Sample_config.yml 

BambooBuildConnector:
        AgileCentral:
                ...  # several key value pairs are relevant for this section
        Bamboo:
                ...  # several key value pairs are relevant for this section
        Service:
                ...  # a few key value pairs relevant for the overall operation of the connector appear in this section

The Agile Central section specifies values to use to obtain a connection with Agile Central. The Bamboo section specifies values to use to obtain a connection with Bamboo and specify the policies governing what plans in Bamboo get processed to result in posting of build information to Agile Central. The Service section controls some aspects of the connector behavior on an overall basis.

A sample file with some explanatory notations:

 ---------------------------------------------
BambooBuildConnector:

    AgileCentral:
        Server        :  rally1.rallydev.com     # R
        #Username     : [email protected]  # R  if an API_Key entry is used, then this isn't needed
        #Password     : 2MuchAngst1415           # R  if an API_Key entry is used, then this isn't needed
        APIKey        :  _abc123                 # O  can use this instead of a Username and Password
        Workspace     :  My AC Workspace         # R  name of the Agile Central Workspace used for connection and project containment
        ProxyServer   : wu-tank.smooth.org       # O  only specify this if you intend to use a proxy server to communicate with Agile Central
        ProxyUser     : jessonbrone              # O  ditto and only if you are using an authenticating proxy
        ProxyPassword : S-e-c*r*EtT321!789       # 0  ditto and only if you are using an authenticating proxy

    Bamboo:
        Protocol  :  http                        # R  defaults to http  use https for SSL connections
        Server    :  mybamboo.mydomain.com       # R  the fully qualified hostname for your Bamboo server (or the Bamboo cloud server)
        Port      :  8085                        # R  port number used by Bamboo for REST API communication
        Username  :  apiuser                     # R  your Bamboo user name
        Password  :  secret                      # R  your Bamboo password
        AgileCentral_DefaultBuildProject :  AC Top Project # R

        Projects:
            - Project: Bamboo Project 1          # R
              AgileCentral_Project: AC Project 1 # O
              Plans:                             # O  you don't have to list individual plans, but if you don't all Plans of the Project will be included
                  - include: ^Quick*
                  - exclude: ^Quicksand*
                  - Plan: Bamboleo

            - Project: Bamboo Project 2
              Plans:
                  - include: ^DonCamillo*,^Return*
                  - include: ^Modi*,^VanG*,^Deg*,^Toulouse*,^Bon*

            - Project: Bamboo Project 3
              AgileCentral_Project: AC Project 3

    Service:
        Preview       : False   # O
        LogLevel      : DEBUG   # O  defaults to INFO
        MaxBuilds     : 50      # O  maximum builds for an individual plan to post to AC per one connector run
        SecurityLevel : Encrypt # O
------  end of the file ---------------------------------------

Appendix B: Bamboo Plan specification

In the sample configuration file above for Bamboo Project 1 and Bamboo Project 2, note that the list of exclusions denoted with exclude entry is applied only to the list of inclusions denoted with include entry, as long as include entry is present.

Do not list any plans in the exclusions list that otherwise do not match the include pattern. Per this configuration file, all plans under Bamboo Project 1 where the name starts with Quick will be processed, except those plans where name starts with Quicksand. For example, plans Quicksilver and Quickstep will be processed, along with the explicitly specified plan Bamboleo, but a plan Quicksand by Caro will be excluded.

Next, plans under Bamboo Project 2 will be processed as long as they match patterns on the inclusions list. You may have a single include entry that consists of comma-separated list of patterns, or multiple include entries if you prefer to organize them so for the ease of reading when the list is too long. Finally, all plans under Bamboo Project 3 will be processed since there are no explicit plan names and inclusion or exclusion patterns are listed under it.

Appendix C: AgileCentral Project specification

 

The connector reflects Bamboo Plan and Build objects by creating respective BuildDefinition and Build objects in AgileCentral projects. For more granularity, specify the destination AgileCentral project in AgileCentral_Project entry under Project section. When this entry is omitted, as in the Project: Bamboo Project 2 section of the sample configuration file above, the Agile Central destination project defaults to Agile Central project specified in AgileCentral_DefaultBuildProject entry in Bamboo section (in this example, AC Top Project)

In AgileCentral, project names do not have to be unique. The connector provides a mechanism of distinguishing projects with the same name.

For example, if a fragment of a project tree looks like this:

   |__ AC Project 1
        |__ Salamandra
        |__ Corral
            |__ Salamandra

We recommend that in order for the build definitions to be assigned to the intended projects in AC the following syntax should be used:

Example configuration file snippet:

       Bamboo:
           ...
           AgileCentral_DefaultBuildProject :  AC Top Project

           Projects:
               - Project: Bamboo Project 1
                 AgileCentral_Project: AC Project 1 // Salamandra
               - Project: Bamboo Project 1
                 AgileCentral_Project: AC Project 1 // Corral // Salamandra


Appendix D: Protecting credentials

The connector configuration file has three settings for SecurityLevel entry in the Service section:

  • Encrypt
  • Encode
  • Cleartext

SecurityLevel entry in the configuration file is optional. The default setting is Encrypt.

Revision History

  • 1.1.3-Master --- 20-Oct-2017
    • Fixes:
      • Updated timestamp function issue
  • 1.1.2-master --- 8-August-2017
    • Initial release - Supports Bamboo 6.0.3 and 6.1

Feedback

Need more help? The CA Agile Central Community is your one-stop shop for self-service and support. To submit feedback or cases to CA Agile Central Support, find answers, and collaborate with others, please join us in the CA Agile Central Community.