Hedgehog Documentation

Pipelines in Hedgehog

  • Last Modified: 2019-07-18

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 project- or global-level. Because projects are hierarchical, it is recommended to store pipelines at the appropriate project level.

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 (or any accessible to parent projects) when creating or editing a deployment set.

Pipeline Stages

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

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 deployment set for a particular stage, 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 deployment set wasn't already deployed to the target stage, and the deployment set is still active.

Deployment Targets

A target defines where and how a deployment set 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 project-level plan, a parent project's plan, or global plan. Plan names should be referenced by simple names, but may also be accessed via normal raft resolution rules.

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 deployment sets have been deployed to which environments

Server Targeting

You can target servers 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

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.

Package Targeting

You can target server packages as well. At deployment time, the Pipeline Stage Deployment Execution will run the specified deployment plan with each targeted package in context. If the deployment set does not contain a package with that name, the plan will not be executed.

Note: Package targeting does not apply to attachments.

Multiple Package Targeting Note: When you target multiple packages, the same deployment plan will be executed once for each package that's in the deployment set, against all targeted servers. This means that, if you target three packages that are in the set, the deployment plan will be executed against each server at least three times.

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, deployment sets 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.

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 Pre- and Post-Deployment Steps

Although you can certainly do "anything" in a pre- or 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 ce197caa on master