BuildMaster Documentation

Pipelines

  • Last Modified: 2019-07-18

Pipelines let you build a repeatable release process by defining the servers and environments that your builds 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. Builds created for that release will then follow the process you defined in the pipeline.

Pipeline Stages

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

Deployment Targets

A target defines where and how a build 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 build. 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 builds 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, builds 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 build must follow the defined stage sequence (requiring a Force to override); otherwise, a build 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 build 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 build 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:

Is this documentation incorrect or incomplete? Help us by contributing!

This documentation is licensed under CC-BY-SA-4.0 and stored in GitHub.

Generated from commit 2fde8bec on master