BuildMaster Documentation

Builds & Continuous Integration

  • Last Modified: 2019-02-14

Note: between BuildMaster v5.0 and v6.1, a build was known as a "release package"

A build in BuildMaster is the fundamental unit of deployment under the context of a release that advances through a sequence of pipeline stages in order to effectively deploy a release. Its components may consist of any or all of the following:

Creating a Build

Builds may be created via the following methods:

In order a create a build, at least one release must exist for an application. When creating a build from UI, there are at minimum three initial options:

  • Release – the release that the build is associated with; this will inherit the pipeline and prompt for the appropriate release template variables upon creation
  • Build number - this is an integer that uniquely identifies a build within a release, the default value will sequentially follow the current latest build’s number
  • Automatically advance to first stage - when checked, the build will be automatically deployed to its first stage of the release pipeline; this is a common workflow in BuildMaster, as the first stage typically adds artifacts to the build. However, if there are deployment variables required, approvals, or deployment windows for the first stage, advancement must occur after the build is created

Deploying a Build

The release's pipeline determines where the build will be deployed, as well as what approvals are required before deploying to each stage.

Clicking on one of the stages in the build's pipeline status will present one of the following dialogs:

  • Deploy Build - if a build was successfully deployed to the previous stage and meets all approval requirements, you can deploy the build to that stage
  • Force Build - if a build was not successfully deployed to the previous stage, or if it doesn't have the requisite approvals, you can force the build to that stage
  • Re-deploy Build - if a build has already been successfully deployed to that stage, you can redeploy it at any time; this is how you perform a rollback of a build

You can use Security and Access Controls to determine which users can perform these actions for which environments.

Status and Lifecycles

A build has three possible statuses:

  • Active - progressing through its pipeline with the possibility of being deployed to the final stage
  • Deployed - successfully deployed to the final stage of its pipeline
  • Rejected - not deployed to its final stage, and instead determined to be inadequate or otherwise inappropriate for the final stage

When a build is successfully deployed to the final stage of its pipeline, both the release and build status is automatically changed to Deployed. This is controlled by the pipeline, and can be configured to behave differently.

Users may manually reject builds and, depending on pipeline configuration, builds may automatically be rejected if another build enters the same stage. Administrators may also change build status at any time, however, this should only be done in exceptional situations such as to "unreject" an accidentally-rejected build or correct other mistakes.

Configuring Continuous Integration

Continuous Integration (CI) is the concept of automatically creating a build immediately following a commit to a source control system. BuildMaster supports 3 methods to achieve a fully-automated CI workflow:

  • Repository monitors – supports polling a generic repository for changes
  • Repository hooks - supports immediate build creation from GitHub or GitLab, but may require support for incoming push notification requests from the internet
  • Release & Build API - the most general method to create builds from a third-party system, whether TeamCity, Jenkins, TFS, or others

Repository Monitors

Repository monitors are an extensible component that can be configured to poll a source control repository at a custom interval, capturing and comparing the latest commit to determine whether a new build should be created, or a custom OtterScript plan should run.

BuildMaster supports a repository monitor for Git repositories. Install the Git extension (v1.1 or later) to use it. Visit the Git extension Wiki for more information.

Configuring a Repository Monitor

A repository monitor may be created from the Administration > Repository Hooks & Monitors page, or from the Builds submenu in the context of an application. The following fields apply to all monitors:

  • Name – a friendly name to identify the monitor in the UI
  • Run for application/group – the application filter of the monitor
  • Plan – the deployment plan to run when a new commit is detected. When no plan is assigned to the monitor, a new build is created for the latest release. See Custom Plans below for more information.
  • Active – determines whether the monitor is enabled
  • Schedule - This cron expression determines the frequency that the repository will be checked for changes. See the Quartz Documentation for information about this format as well as examples. The default configuration of '0 0/4 * * * ?' performs a check every 4 minutes.
  • Run on server - When specified, the repository monitor will use this server to connect to the remote repository, otherwise the polling is performed from the BuildMaster server.

The following fields apply specifically to the Git monitor:

  • Branch – specifies the branch to be monitored, using regular expression syntax to match the branch name.
  • Credentials – the Resource Credentials used to connect to the Git repository
  • Repository URL – the URL of the Git repository. By default this uses the repository defined in the credentials, or anonymous if not supplied in the credentials either
  • Git executable path – By default, BuildMaster uses the LibGitSharp library for Git connections, but a path to Git client may be used instead for custom configurations (e.g. SSH connections, older versions of Git)

Text fields for a monitor support variable expansion, allowing for simpler configuration. For example, a single Git repository monitor with a Repository URL of https://github.com/inedo/inedo-$ToLower($ApplicationName) for the "Extensions" application group would allow all descendant applications named after the extensions to automatically have builds created for them on commit.

Custom Plans

When a custom plan is assigned to a repository monitor, then instead of automatic creation of a new build, that plan will be executed in the context of all applications matching the specified application filter. Because of this, plans may be application-level or system-level plans, and application-level plans take precendence if both exist. During execution, any additional context from the commit will be available via deployment variables to support more complex use-cases:

  • Automatically creating a release & build when a new branch is created by combining the Ensure-Release and Create-Build operations
  • Sending an email notification when a change is detected using the Send-Email operation
  • Create builds for multiple releases or spanning multiple applications

Repository Hooks

BuildMaster supports custom webhook events fired by GitHub and GitLab. Visit the Git extension Wiki for more information on the configuration required for each specific system.

Hook & Monitor Plans

Both Repository Monitors and Repository Hooks support common variables that can be used within the plan. The default variables include:

  • $Branch - the ref that a commit was pushed to without refs/heads/ at the beginning, e.g. master
  • $CommitHash - the ID, SHA, or hash associated with the commit, e.g. 525571720b56ca53d1d3229e774c7b7980d3ff2b

Note: these variables are only available when a custom plan is specified. If using the default setting (i.e. creating a build for the latest release), these variables are not available. This is primarily to support backwards compatibility of existing pipelines that rely on a configuration variable with the same name at a different scope.

To replicate the default no-plan behavior with these variables in context, you may reference a system-level plan defined simply as:

Create-Build
(
    Application: $ApplicationName,
    Variables: %(Branch: $Branch, CommitHash: $CommitHash)
);

Additional context may be available depending on the repository host. Visit the Git extension Wiki for more information.

Release & Build Deployment API

In addition to hooks and monitors, BuildMaster supports creating releases and builds from third-party systems via the Release & Build API documentation.

Other CI Integrations

Badge API

BuildMaster allows external tools to query build status in order to generate a "CI Badge", such as:

To access the CI Badge API, an API key must be added with access to the API. Then, the following URLs can be used to generate either the badge image or a link to the corresponding build/execution:

Image:

{buildmaster-host}/api/ci-badges/image?API_Key={yourApiKey}&$ApplicationName={appName}

Link:

{buildmaster-host}/api/ci-badges/link?API_Key={yourApiKey}&$ApplicationName={appName}

The badge specifiers are not limited to applications and may be further filtered based on commit IDs, branches, and more. For more information on how to configure and query a badge, visit the CI Badge API documentation.

Variable Value Renderers

Variable value renderers are useful in terms of CI mainly because they can transform captured important variable values into an image or link to a third-party system.

Examples:
  • ProGet Package
  • GitHub Commit
  • GitLab Branch
<a class="ci-icon proget" 
   href="{pg-host}/feeds/{feedName}/$ApplicationName/$UrlEncode($Value)">
$Value
</a>
<a class="ci-icon github" 
   href="https://github.com/{orgName}/$ApplicationName/commit/$Value">
$Substring($Value, 0, 7)
</a>
<a class="ci-icon gitlab" 
   href="https://gitlab.com/{orgName}/$CustomAppVariable/tree/$Value">
$Substring($Value, 0, 8)
</a>

Visit the Variable Value Renderers documentation for more information.

More on this topic:

Have a question? Try the Q&A Forum

Our documentation is now Open Source and on GitHub. We highly encourage our users to contribute and get involved! .