Channels Walkthrough

Published on: 26 Oct 2015 by: Michael Noonan

In this walkthrough we will ship releases of a sample application using Octopus Deploy 3.2 modeled on how we build, test and ship releases of Octopus Deploy itself. We will cover all of the scenarios discussed in the Octopus 3.2 post.

Getting started with Channels in Octopus Deploy 3.2

In this walkthrough

Prerequisites

  • You meet the prerequisites to install Octopus Server.
  • A machine where you can install a new instance of Octopus Deploy 3.2.

The following are optional, if you want to run the deployments (recommended).

Sample project

To simulate this real-life scenario we are going to use git-flow as a guideline for our branching strategy, and GitVersion to provide a predictable versioning strategy based on our source repository. If these concepts or tools are new to you, please stop and take a few minutes to familiarize yourself before moving on with this walkthrough.

We have created a sample ASP.NET Web Application that simulates each of the scenarios in the walkthrough.

github https://github.com/OctopusDeploy/Channels.Sample

The following image shows the sample repository using the git-flow branch and tag conventions and an estimation of the versions that will be calculated by GitVersion. Notice the branches and tags control how GitVersion calculates the version for our packages.

Sample repository graph

Sample deployment process

As a starting point, we have built a Process that deploys the Channels.OrderService as an Azure Web App using the Octopus 3.1 support for Azure Steps, and notifies the right Slack channel when the deployment is complete.

Starting Process

Why so many steps to deploy a simple ASP.NET Application to Azure? In these scenarios we will be introducing several new Web App instances leveraging the dynamic capabilities of Octopus 3.1 Azure Steps - especially feature branches! We want this walkthrough to focus on the Channels features, but feel free to take a deeper look at the sample to see how it works.

Scenario 0: Getting started

  1. Check the prerequisites
  2. Download the latest Octopus 3.2 pre-release.
  3. Do a standard install of Octopus Server.
  4. Download the Channels.Sample.Packages.zip (66.8 MB) and extract it into the folder for your built-in Package Feed - [OctopusRoot]\Packages by default. When the Octopus Server restarts it will automatically add these NuGet packages to the built-in feed. Otherwise you can upload the packages manually through the user interface.

    Packages Folder

  5. Download the Octopus Configuration Channels.Sample.Configuration-scenario-0.zip (17 KB), extract it to a temporary folder, and use the Octopus Manager to import it into your Octopus Server instance using the password Password01!. Beware: Long paths may cause the import to fail.

    Channels.Sample.Configuration-scenario-0

    Octopus Manager Import

  6. Install and configure a single Tentacle on the Octopus Server machine with the Role Octopus Server and add it to all of the Environments.

    Add Octopus Server Tentacle

  7. Create the two Azure Subscription Accounts ChannelsSample-Test and ChannelsSample-Production to simulate Subscription-segregated Azure environments - this is a common method to provide a clear distinction between Test and Production Environments in Azure.

    Only have one Azure Subscription? No problem. In this sample you can make both Azure Subscription Accounts target the same Azure Subscription for the sake of convenience, but in a real-life scenario you should target different Azure Subscriptions to provide any real security benefit.

    Don't forget to upload the Management Certificates to your Azure Subscription if you actually want to run the deployments!

    Production Azure Account

    Test Azure Account

  8. Set the SlackWebHookUrl Variable in the Slack Variable Set to your Incoming Web Hook URL for your Slack account.

    Don't have a Slack account? You can create a personal Slack team as a testing sandbox free of charge.

  9. Create the following channels in your Slack team: testing, pulse which will become #testing and #pulse respectively. Alternatively you can post messages to other Slack channels by modifying the Slack Library Variable Set you just imported.

    Create Slack Channels

  10. Configure your SMTP settings for Scenario 4: Early access programs to send email to "Beta Customers". smtp4dev is a really handy tool for testing email without needing a real SMTP Server and email addresses.

Scenario 1: Standard release promotion

Matthew is enhancing and fixing bugs on the latest release of his Company's flagship product. He wants to push his code changes and have them automatically deployed to a Dev environment, and then let his test team promote releases through a Test environment, and finally to deploy releases to Production when they are ready. He also wants to build pre-release packages, but wants to prevent those from being accidentally deployed to Production.

The basic Release Promotion scenario is supported out of the box by Octopus Deploy without the need for Channels. But in this case we want to prevent pre-release packages from being accidentally deployed to Production. Let's modify our Default Channel to prevent creating Releases that would deploy pre-release packages.

Step 1: Prevent pre-release packages from being deployed to Production

Select the Channels tab and click on the Default Channel to edit it.

Where did the Default Channel come from? When we introduced Lifecycles we created a Default Lifecycle that was backwards compatible, and in the case of Channels we have done the same thing by creating a Default Channel that inherits the Project Lifecycle.

Open Default Channel

Add a Version Rule for the Deploy Web App step defining a regular expression ^$ to exclude any packages that have any kind of pre-release tag, and save your changes to the Default Channel. These Version Rules can be daunting at first glance, so we've built a designer that makes it easy to tune and test your rules. Take a moment and experiment with the Version Rule designer.

Note: Version Rules will work best when you follow Semantic Versioning (SemVer) for your versioning strategy.

Add Version Rule

Version Rules Designer - Non-pre-release

Step 2: Look at the results

Now when you create a Release, the Package for each Step will be selected using the rules you've defined.

Create Release Scenario 1

Similarly we will filter the Package Search screen to the Channel you've selected for the Release. You can un-check Only this channel to manually override the rules you've defined if necessary.

Package Search Filtering

And if somebody tries to create a Release using packages that don't match the Version Rules they will need to explicitly force Octopus Deploy to create the Release.

Force Release with non-matching Packages

Take a few moments to experiment yourself and understand the implications this has when creating Releases.

Step 3: Deploy!

Create a Release using the 0.1.0 package and watch it deploy through to the Dev Environment. If there are any problems take a few minutes to diagnose it, otherwise drop a comment on this post.

Now promote that Release through to the Test Environment and check your Slack channel. You should have a nice notification informing you of the new release complete with a URL you can click to test your application.

Continue and promote the Release through to both of the Production environments. Now you should have fully deployed 0.1.0 to all Environments. Feel free to do the same with 1.0.0 and experiment with this deployment process, and then move on to Scenario 2 when ready.

Scenario 2: Supporting multiple versions (evolving deployment design)

Version 1.x has just shipped, and Andrew is starting work on 2.x. As part of 2.x Andrew needs to introduce a new service which needs some new Steps and a handful of new Variables. He would like to start shipping pre-releases as soon as he can. In the meantime Stephanie is enhancing and fixing bugs on Version 1.x, and wants deployments of 1.x to work the same as they always have.

In this scenario we will use Channels to ensure deployments of Version 1.x remain unaffected by our work on Version 2.x deployments. We are going to create a new Channel called 2.x Unstable, and scope the new Steps and Variables to the 2.x Unstable Channel so they only get included in deployments of 2.x. We will also configure Version Rules to make it easier, and safer, to create Releases of either 1.x or 2.x making sure compatible packages are included. Let's get to it!

Step 1: Protecting deployments of 1.x releases

Rename the Default Channel to 1.x Normal and set it as the Default Channel for creating Releases. This will make sure when we create a Release of the Channels.Sample Project the 1.x Normal Channel will be used by default, ensuring our changes are backwards compatible.

Set Default Channel

Update the Version Range for the 1.x Normal Channel to [1.0,2.0). This will make sure we don't accidentally create a Release in the 1.x Normal Channel using 2.x packages.

1.x Only Version Rules

Step 2: Preparing to deploy 2.x releases

Create a new Lifecycle called Limited to Dev with a single Phase to the Dev environment - need help with this? This will make sure we don't accidentally promote a 2.x Unstable Release to any other Environments.

Limited to Dev Lifecycle

Create a new Channel called 2.x Unstable linked to the Limited to Dev Lifecycle with a Version Rule for the Deploy Web App Step of 2.0 and ^unstable\d+$. This will make sure we don't accidentally create Releases in the 2.x Unstable Channel using 1.x packages.

Why "Unstable"? When you are using git-flow you typically do most of your new development work in a branch called develop, and GitVersion will add a pre-release tag on your behalf with a numbered suffix that increments on every commit, like so: Channels.OrderService.2.0.0-unstable0001 -> Channels.OrderService.2.0.0-unstable0002 -> etc.

Breaking change in 3.4: In Octopus 3.4, we fixed an issue where pre-release versions were considered newer than normal versions. In 3.4 and newer, you will need to use a Version Range of [2.0.0-unstable,2.0.0) instead of 2.0.

2.x Unstable Channel

Step 3: Adding the WebJob deployment step for 2.x releases

Create a new Azure Web App Step to deploy the Channels.InventoryJob Web Job into the same Web App:

  • Name: Deploy InventoryJob
  • NuGet Package ID: Channels.InventoryJob
  • Account: #{AzureAccount}
  • Web App: #{Octopus.Action[Ensure Web App].Output.WebAppName}
  • Physical Path: app_data/jobs/triggered/InventoryJob
  • Remove additional files: Yes
  • Preserve App_Data: Yes
  • Channels: 2.x Unstable

Channel Scoping Step

Re-order your steps to make sure the Deploy InventoryJob Step is directly after the Deploy WebApp Step.

2.x Unstable Process

Modify the 2.x Unstable Channel to include the new Step in the existing Version Rule. This will make sure the Version Rule we created earlier will also be applied to this new Step.

Updated 2.x Unstable Version Rule

Step 4: Look at the results

Now when you create a Release the Steps are displayed, according to the Channel you've selected, with the latest Packages that match the Channel Version Rules selected by default.

Create Release 1.x Normal and 2.x Unstable

With this configuration the team can continue deploying 1.x and start deploying 2.x without cloning the Project nor compromising their deployment process!

Step 5: Deploy!

Create a Release using the 2.0.0-unstable0006 packages and let it deploy through to the Dev Environment.

Scenario 3: Hotfix deployments

Stephanie has just received an alert that the checkout process in Version 1.x is failing in Production due to a problem with a 3rd party integration. The remedy is a simple code change to the Order Processor service and she wants to deploy an emergency hotfix release to Production without delay.

In this scenario we will configure a 1.x Hotfix Channel that uses a new Lifecycle allowing Releases to be deployed directly to Production, and then back filled into the Dev and Test Environments.

Step 1: Configure the Hotfix Lifecycle

Create a new Lifecycle called Hotfix with two Phases, first to the two Production Environments, and secondly to the Test and Dev Environments.

Hotfix Lifecycle

Step 2: Configure the Hotfix Channel

Add a new Channel called 1.x Hotfix linked to the Hotfix Lifecycle you just created, specifying the same Version Rules as 1.x Normal for the Deploy Web App Step, [1.0,2.0) and ^$.

1.x Hotfix Channel

Step 3: Deploy!

Create a Release in the 1.x Hotfix Channel using the 1.0.1 package, add some Release Notes using Markdown, and deploy it into both Production environments, one at a time or in parallel - it's up to you. If everything has worked you should see a nice notification in the #general Slack Channel informing you of the hot fix release. Now back fill the Release into the Dev and Test Environments.

Scenario 4: Early access programs

Andrew is ready to start sharing early builds of 2.x with a specific group of trusted Beta Customers. He would like to deploy specific pre-release builds to a Beta Environment and notify these Customers of the new pre-release.

In this scenario we will configure a 2.x Beta Channel using another new Lifecycle which deploys Releases directly to a new Beta Environment. We will also configure an Email step and a Variable for the Beta Customer email addresses that is scoped to the 2.x Beta Channel.

We will also make use of the Release Branch concept in git-flow and GitVersion. When we build from source on the release/2.0.0-beta.1 branch we will get packages with the version 2.0.0-beta0001. We will use the well-known beta tag to discriminate which packages should be used to create Releases in the 2.x Beta Channel.

Step 1: Configure the Beta Environment

Create a new Environment called Beta, and then add the Octopus Server Tentacle to the Beta Environment.

Beta Environment

Add the Beta Environment to the ChannelsSample-Test Azure Account.

Beta Environment Scope

Step 2: Configure the Beta Lifecycle

Create a new Lifecycle called Directly to Beta with a single Phase to the Beta Environment you just created. This will restrict Releases to the Beta Environment, making sure they never deploy to Production.

Directly to Beta Lifecycle

Step 3: Configure the Beta Channel

Add a new Channel called 2.x Beta linked to the Directly to Beta Lifecycle you just created, specifying this Version Rule for the Deploy Web App and Deploy InventoryJob Steps, 2.0 and ^beta\d+$. This will match packages that were built from git-flow style release branches, with versions like 2.0.0-beta0001 and 2.0.0-beta0002.

2.x Beta Channel

Step 4: Include the Deploy InventoryJob Step in Beta Channel deployments

Update the Deploy InventoryJob Step to include the 2.x Beta Channel you just created. This will make sure the step is included in 2.x Unstable and 2.x Beta deployments.

Add Beta Channel to Deploy InventoryJob Step

Step 5: Configure the Variables

Create a new Variable called BetaCustomerEmailAddresses with the list of email addresses you'll use to simulate your Beta Customers (comma-separated), and set the Scope for this variable to the 2.x Beta Channel you've just created. This will ensure the variable is only available when deploying Releases in the 2.x Beta Channel.

Also, add the Beta Environment to the AzureAccount and AzureLocation Variables. This will make sure Releases deployed to the Beta Environment are also provisioned in SoutheastAsia.

Variable Scoped to 2.x Beta Channel

Notice you can scope Variables and Steps to Channels just like you can Environments. Sometimes they will align (like this example), sometimes Environment will be the sensible choice, sometimes Channel will be the sensible choice - it's up to you!

Step 6: Create the scoped Email Step

Create a new Email Step called Notify Beta Customers of new Pre-Release:

  • To: #{BetaCustomerEmailAddresses}
  • Subject: #{Octopus.Project.Name} pre-release #{Octopus.Release.Number} is ready for you to try out!
  • Body: Go try out the latest #{Octopus.Project.Name} pre-release: <a href="#{Octopus.Action[Ensure Web App].Output.WebAppUrl}">#{Octopus.Action[Ensure Web App].Output.WebAppUrl}</a>
  • Body is HTML: Yes
  • Channels: 2.x Beta

Beta Email Step

Step 7: Look at the results

Now when Releases are created with the special beta pre-release version tag they will be deployed to the Beta Environment and the Beta Customers will be sent a special email invitation to test the new pre-release of 2.x.

Create Beta Release

Step 8: Deploy!

Create a Release using the 2.0.0-beta0001 packages and deploy it to the Beta Environment. If you've configured your SMTP Server settings and some real email addresses you should receive an announcement of the new Beta release.

Scenario 5: Feature branch deployments

Sarah is starting work on a new feature for Version 2.x called Multitenancy and she wants to make sure people can test her work as soon as possible without interrupting other work going on in Version 1.x and 2.x.

We will base this scenario on the Feature Branch concept in git-flow and GitVersion. When we build from source on the feature-multitenancy branch we will get packages with the version 2.0.0-multitenancy0001. Since we already use the well-known unstable and beta Tag, we will consider anything else as a feature branch.

We will configure a 2.x Feature Branch Channel using the Limited to Dev Lifecycle we created earlier. The interesting part of this scenario is the amazing development experience we've built using the Octopus 3.1 Azure Steps:

  • when anyone pushes a new feature branch they will get a notification a few minutes later with the URL to the test environment for their feature that was just provisioned and deployed by Octopus Deploy, and
  • when anyone pushes new code to an existing feature branch, their existing environment will be updated with the new code
  • at any time you could delete the hosting environment and provision it again by deploying a Release

Step 1: Configure the Feature Branch Channel

Add a new Channel called 2.x Feature Branch linked to the Limited to Dev Lifecycle, specifying this Version Rule for the Deploy Web App and Deploy InventoryJob Steps, 2.0 and ^(?!beta|unstable).+$. This will match packages that are pre-releases that aren't beta nor unstable.

2.x Feature Branch Channel

Step 2: Include the Deploy InventoryJob Step in Feature Branch Channel deployments

Update the Deploy InventoryJob Step to include the 2.x Feature Branch Channel you just created. This will make sure the step is included in 2.x Unstable and 2.x Beta and 2.x Feature Branch deployments.

Add Feature Branch Channel to Deploy InventoryJob Step

Step 3: Add the Slack Notification Step

Create a new Slack - Post Message Step called Slack - Notify #pulse of new Feature Branch build:

  • Webhook URL: #{SlackWebHookUrl}
  • Channel: #{SlackChannel}
  • Title: Feature Branch #{Octopus.Action[Determine App Instance Name].Output.AppInstanceName} #{Octopus.Release.Number} deployed
  • Value: The Feature Branch #{Octopus.Action[Determine App Instance Name].Output.AppInstanceName} #{Octopus.Release.Number} is available at #{Octopus.Action[Ensure Web App].Output.WebAppUrl}
  • Fallback: Feature Branch #{Octopus.Action[Determine App Instance Name].Output.AppInstanceName} #{Octopus.Release.Number} deployed
  • Channels: 2.x Feature Branch

Feature Branch Slack Notification Step

Step 4: Look at the results

Now we can automatically deploy feature branch releases without interrupting 1.x/2.x deployments.

Create Feature Branch Release

Step 5: Deploy!

Create a Release using the 2.0.0-multitenancy0001 packages and deploy it to the Dev Environment. If everything works you should see a nice announcement in the #testing Slack channel with the details to start early testing on the new multitenancy feature.


Octopus Deploy is used by thousands of developers across the globe, from small companies to large enterprises. Find out if it meets your deployment automation needs by taking advantage of our free 30-day trial. You can spin up an instance with just a few clicks!