BuildMaster Documentation

Deployment Pipelines

  • Last Modified: 2020-02-10

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 multiple ways:

  • 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
  • Server Pool; the plan will run against one server from a specified role that will act as a pool. This will effectively put an Acquire-Server operation at the beginning of the plan.

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.

Pre- and Post-Deployment Steps

Before the pipeline stage's targets are evaluated, the Pipeline Stage Deployment Execution will run the pre-deployment steps associated with the stage.

Pre-deployment steps are executed in the sequence specified, and a failure in execution will cause the target evaluation to not be performed. Only the "run on fail" post-deployment steps will run when this happens.

Post-deployment steps work nearly the same way, except they are run after all of the targets have finished executing. Post-deployment steps denoted as "run on fail" will only be run if the execution has an error status, or if the pre-deployment steps failed.

Available Steps

The following steps may be selected as pre- and post-deployment steps:

  • Send Email: this sends an email to the specified addresses with the specified priority, subject, and body
  • Set Stage Variable Value: this creates or updates an ephemeral variable that is used throughout pipeline stage execution, and is made available to all plans as a configuration variable
  • Execute PowerShell Statement: this runs the specified text using PowerShell
  • Execute OtterScript Script: this runs the specified text using the OtterScript runtime

OtterScript and Steps

Each of the available steps are stored as separate OtterScript scripts, and executed by the OtterScript runtime. They are simply displayed in a more user-friendly manner in the UI.

The Send-Email and PSExec operations are used to perform the send email and PowerShell steps. You can use a "pseudo operation" called Set-PipelineStageVariableValue to set a variable value on the stage in the same manner. This operation has two required properties, Name and Value.

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/or stages. These behave just like configuration variables, in that you can use these variables within deployment plans that are executed through the plan.

However, unlike configuration variables, pipeline variables, cannot be multi-scoped, and cannot be modified through the variables API.

Advanced Features and Properties

When editing the details of a pipeline, the following additional options are available:

  • 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 50ab5958 on master