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 a manual approval they've given, provided that the release package wasn't already deployed to the target stage.

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.

Command Line Executes a program via command line on the BuildMaster server.
File In Artifact Verifies that a file exists in an Artifact before a promotion to the pipeline stage.
Issues Closed Verifies that all issues are closed before a promotion to the pipeline stage.
Issues in Status Verifies that issues are in a certain status before a promotion to the pipeline stage.
Pipeline Stage Complete Ensures a pipeline stage of another application has been completed.
Change Controls Performed Verifies that change controls have been performed.
Change Scripts Run Verifies that all required change scripts have been run successfully.
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've configured a Issues Closed automatic approval to verify that issues in a particular JIRA project are closed prior to promoting to a stage, BuildMaster won't be notified of a status change.

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.

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 after a release has been deployed by incrementing the final part of the deployed release number (e.g. 3.4.3 to 3.4.4) .
  • Deploy Release: mark the release and package as deployed once it reaches the final stage.

Best Practices

Start Simple

This level of flexibility can make it feel overwhelming to design the "right" pipeline. You can always "add more" to it later, and adopt your deployment process as you learn how to improve it.

Keep Pipelines Reusable

Pipelines are designed to be used for all the deployment sets in a project, and they represent a repeatable process. Don't treat them like a "release checklist" for a single release, and then start again on the next release.

Stages vs Targets vs Plans

You could, in theory, have a single deployment plan that deploys a package from one server to another, all the way through production. On the other hand, you could have a pipeline with a thousand stages, each running a micro-step in deploying to a particular environment… not to mention targets.

To find the best middle ground, consider the design intent of each of the elements:

  • Stages are designed to visualize deployment sets as they make their way to production. Too many stages, and it becomes cluttered and almost useless. Come up with a sequence of stages that shows how others may visualize this progress over the course of days and weeks.
  • Targets are used to help keep your deployment plans reusable, and let you define servers and roles outside of the deployment plan; they are also visualized as a separate execution which may make identifying which parts of the deployment were successful, warned, or failed.
  • Plans have a lot of flexibility, but they should generally be reusable and not server- or role-specific; but sometimes they are, and that's ok too.

Don't Use and Abuse Post-Deployment Steps

Although you can certainly do "anything" in a post-deployment step, in general these steps should be reserved for:

  • Auditing purposes
  • Sending notifications

More on this topic: