BuildMaster Documentation

Pipelines in BuildMaster

Pipelines let you build a repeatable release process by defining the servers and environments that your release packages will be deployed to, as well as the manual and automatic approvals required at each stage of the process.

A basic web application might use a pipeline with only two stages (testing and production), and simply deploy to a different folder on the same server. Another application may require a dozen stages, each with multiple targets that go to different environments, and all sorts of automatic and human approvals to meet compliance requirements.

Creating Pipelines

You can create a pipeline at the application- or global-level. Global pipelines behave in the same manner, with the exception that global pipelines may only reference global deployment plans.

A pipeline has three properties that help distinguish it: name, description, and a color. While the description is primarily used to guide users on which pipeline to use, the name and color are used to visualize the releases that are utilizing that pipeline.

Once a pipeline is created, you can select it when creating or editing a release. Packages created for that release will then follow the process you defined in the pipeline.

Pipeline Stages

Pipelines contain a sequence of stages that release packages will pass through on their way to production. Each stage defines the requirements for stage entry, where and how release package will be deployed, and what to do after they are deployed.

Deployment Windows

Deployment windows allow you to restrict the days and times that release packages may be deployed. They can be used in conjunction with manual deployments to enforce existing policies, or as part of a continuous delivery pipeline to ensure deployments occur within known times. Like approvals, a release package may be forced into a stage even if it's not within the specified window. However, this requires a special action and a specific permission.

Configuring Deployment Windows

A deployment window consists of day of the week, as well as a start and end time.

Config Deploying Windows

When the end time is earlier than the start time, then the window will "crossover" into the following day. For example, specifying "Sundays after 11:00pm and before 2:00am" will create a three-hour window from Sunday at 11:00pm until Monday at 2:00am.

You can specify deployment windows on the edit pipeline page.

Deploying Windows set

When there are multiple deployment windows specified, they are treated like an "or" condition; that is, as long as one of the deployment windows is valid, then a deployment may proceed.

Manual and Automatic Approvals

As a release package progresses through a pipeline, both people and automatic processes can add an "approval" to indicate that a package is eligible to be deployed to a particular stage. The approvals required for that stage are defined in the pipeline, and the actual approvals received becomes part of the release package's history and metadata.

Like deployment windows, a release package may be forced into a stage even if its approvals were not met. However, this requires a special action and a specific permission.

Manual Approvals

There are two types of manual approvals: user and group. A user-based approval can only be entered by the specified user, whereas a group-based approval can be entered by any members of the specified group. You can also specify that more than one member of a particular group must approve a release package before deploying to a stage.

In either case, when a user approves a release package, the following is recorded:

  • User's Name
  • Group name (if group-based)
  • Stage name
  • Approval Description
  • User Comments
  • Date/Time

Users may revoke an approval they've given, provided that the release package wasn't already deployed to the target stage, and the release package is still active.

Automatic Approvals

You can also define automatic checks that must be met before a release package may be deployed to a stage. These are an extensible feature, and there are several built in to BuildMaster.

Pipeline Stage Complete Ensures a pipeline stage of another application has been completed.
File In Artifact Verifies that a file exists in an Artifact before a promotion to the pipeline stage.
Change Controls Performed Verifies that change controls have been performed.
Change Scripts Run Verifies that all required change scripts have been run successfully.
Command Line Executes a program via command line on the BuildMaster server.
Issues Resolved Verifies that issues are in a certain status before a promotion to the pipeline stage.
United Tests Passed Verifies that unit tests have passed in the last execution.
Variable Ensures a specified variable value before promotion to the pipeline stage.
Drift Status Verifies that a specified Otter server or role is in a specified drift status.

These automatic approvals are verified periodically, as they can change over time.

For example, if you set the status of an issue in your Jira instance, BuildMaster won't know about it until the next time the approval is run.

When an automatic approval is verified, the following information is recorded:

  • State (Met, Not Met, Not Required)- for example, if there are no issues associated with the release, then the requirement would be Not Met, whereas the requirement would be Met only if all issues associated with the release were Resolved
  • Description - a text description of the approval conditions; for example, "3/8 issues are resolved"
  • Date/Time - a timestamp of when the approval was run

Deployment Targets

A target defines where and how a release package will be deployed. It's comprised of a deployment plan, an environment name, and a list of servers or roles.

Deployment Plan

This is the actual OtterScript that will be run in order to deploy the release package. It can reference an application-level plan or a global plan. Global plans names are prefixed with GLOBAL::.

Note: depending on how server targeting is configured, the deployment plan may be run multiple times across different servers.

Environment Targeting

Deployments can be targeted to an environment, which affect it in a few ways:

  • Permissions: users must have permission to deploy to that environment in order to deploy to that stage
  • Role Selection Filtering: if you also target by role, then the server must be in that environment to be included
  • Runtime Server Protection: a server must be in the target environment, or a runtime error will occur
  • Visualization: this help you see which release packages have been deployed to which environments

Server Targeting

You Can Target servers in four different manners:

  • No default server context; this means you will need to explicitly specify which servers to deploy to in the deployment plan itself
  • All servers in target environment ;this will run the deployment plan against all servers in the targeted environment
  • Specific servers; the plan will be run against the list of servers specified
  • Specific server roles; the plan will be run against servers with the specified roles and that are associated with the targeted environment

Multiple Role Targeting Note: When you target multiple role names, the same deployment plan will be executed once for each role selected, against all servers with that role and in the target environment. This means that, if you target two roles – and one server happens to have both of those roles – the deployment plan will be executed against that server at least twice.

Post Deployment Events

Once all deployments to all targets have completed (whether successfully, or unsuccessfully), you can execute one or more event listeners. These are an extensible feature, and there are several built-in to BuildMaster:

  • Email Notification: Deployment Execution Completed
  • Execute Command Line
  • Publish Event Details (HTTP)

Auto-deploying Pipelines

You can configure a stage to automatically deploy into the next stage by checking the "Auto deploy" checkbox in the stage properties. When checked, release packages will automatically be deployed to the next stage upon a successful deployment, as soon as all requirements for following stage are met.

This feature can be particularly useful to build an automated deployment pipeline.

Pipeline Variables

You can define key/value pairs on pipelines and stages. These behave just like configuration variables, in that you can use these variables within deployment plans that are executed through the plan.

However, pipeline variables are not actually configuration variables: you can't create multi-scoped variables, or modify them through the variables API.

BuildMaster does not support using variable expressions for targeting.

For example, you cannot target servers in role $SomeVariable. Hedgehog's pipelines, however, do support this.

Advanced Features and Properties

Pipelines also have the following options:

  • Enforce stage sequence; when set, a release package must follow the defined stage sequence (requiring a Force to override); otherwise, a release package may be deployed to any stage at any time
  • Cancel Release; cancel earlier (lower-sequenced) releases that are still active and have not yet been deployed.
  • Create Release: creates a new release by incrementing the final part after a release has been deployed.
  • Deploy Release: mark the release and package as deployed once it reaches the final stage.