Octopus Deploy Documentation

Deploy an ASP.NET Core application to Azure websites using Octopus and GitHub Actions

In this tutorial, we show you how to build a fully-functional continuous delivery pipeline for a simple ASP.NET Core web application and deploy it to Azure websites. We use GitHub Actions to build the code and run tests, and we use Octopus Deploy to deploy and promote releases.

To get up and running quickly, the TestDrive VMs provide preconfigured environments demonstrating various continuous delivery pipelines documented in these guides.

Introduction

The application we'll deploy is called Random Quotes, which is a simple web application that randomly displays a famous quote each time the page loads. It consists of a web front end and a database that contains the quotes. We'll build a complete Continuous Integration/Continuous Delivery (CI/CD) pipeline with automated builds, deployments to a dev environment, and sign offs for production deployments.

Deployment pipeline

For this tutorial, we assume you use Git for version controlling changes to your source code and GitHub Actions to compile code and run unit tests. Octopus Deploy will take care of the deployment. Here is what the full continuous integration and delivery pipeline will look like when we are finished:

Git C# C# C# TeamCity Artifactory create release DEV TEST PRODUCTION Release 1.1

The development team's workflow is:

  1. Developers commit code changes to Git.
  2. GitHub Actions detects the change and performs the continuous integration build, this includes resolving any dependencies and running unit tests.
  3. When the GitHub Actions build completes, the change will be deployed to the Dev environment.
  4. When one of your team members (perhaps a tester) wants to see what's in a particular release, they can use Octopus to manually deploy a release to the Test environment.
  5. When the team is satisfied with the quality of the release and they are ready for it to go to production, they use Octopus to promote the release from the Test environment to the Production environment.

Since Octopus is designed to be used by teams, in this tutorial we also set up some simple rules:

  • Anyone can deploy to the dev or test environments.
  • Only specific people can deploy to production.
  • Production deployments require sign off from someone in our project stakeholders group.
  • We'll send an email to the team after any test or production deployment has succeeded or failed.

This tutorial makes use of the following tools:

Octopus is an extremely powerful deployment automation tool, and there are numerous ways to model a development team's workflow in Octopus Deploy, but this tends to be the most common for small teams. If you're not sure how to configure Octopus, we recommend following this guide to learn the basics. You'll then know how to adjust Octopus to suit your team's workflow.

This tutorial takes about an hour to complete. That sounds like a long time, but keep in mind, at the end of the tutorial, you'll have a fully-functional CI/CD environment for your entire team, and you'll be ready to deploy to production at the click of a button. It's worth the effort!

Build vs. deployment

For any non-trivial application, you're going to deploy the software to multiple environments. For this tutorial, we're using the environments Dev, Test, and Prod. This means you need to choose between building your application once or building it before each deployment? To reduce the risk of a failed production deployment, Octopus strongly encourages the practice of building once, and deploying multiple times.

The following activities are a build time concern, so they will happen in GitHub Actions after any change to code is committed to Git:

  1. Check out the latest changes from Git.
  2. Resolve and install any dependencies from NuGet.
  3. Run unit tests.
  4. Package the application by bundling all the files it needs to run into a ZIP file.

This results in a green CI build and a file that contains the application and everything it needs to run. Any configuration files will have their default values, but they won't know anything about dev vs. production settings just yet.

Lastly, it's very important that we give this artifact a unique version number. We will produce a new artifact file every time our CI build runs, and we don't want to accidentally deploy a previous version of the artifact.

An example of a package that is ready to be deployed is:

RandomQuotes.1.0.0.zip

At this point, we have a single artifact that contains all the files our application needs to run, ready to be deployed. We can deploy it over and over, using the same artifact in each environment. If we deploy a bad release, we can go and find the older version of the artifact and re-deploy it.

The following activities happen at deployment time by Octopus Deploy:

  1. Changing any configuration files to include settings appropriate for the environment, e.g., database connection strings, API keys, etc.
  2. Running tasks that need to be performed during the deployment such as database migrations or taking the application temporarily offline.

Prerequisites

There are a number of tools you need to install to implement a complete CI/CD workflow. These include the GitHub Actions and Octopus servers, some command-line tools, and Azure websites to host the final deployment.

Git

The source code for the sample application is hosted on GitHub. To access the code, you need the Git client. The Git documentation has instructions to download and install the Git client.

GitHub Actions

GitHub Actions are available for free on public GitHub repsoitories and with paid options for private repositories.

.NET Core SDK

The .NET Core SDK version 2.2 or above is required to compile and run the ASP.NET Core sample application. The SDK can be downloaded from the Microsoft .NET website.

The .NET Core SDK must be installed locally for development and also on the GitHub Actions server or any agents that will compile the application code.

Octopus Deploy

The installation file used to install Octopus Server on-premises can be downloaded from the Octopus website.

Octopus requires a Microsoft SQL Server to host the database. Microsoft SQL Server Express can be downloaded for free from the Microsoft website.

Complete the following steps to install Octopus:

  1. Start the Octopus Installer, click Next, accept the Terms in the License Agreement and click Next.
  2. Accept the default Destination Folder or choose a different location and click Next.
  3. Click Install, and give the app permission to make changes to your device.
  4. Click Finish to exit the installation wizard and launch the Getting started wizard to configure your Octopus Server.
  5. Click Get started... and either enter your details to start a free trial of Octopus Deploy or enter your license key and click Next.
  6. Accept the default Home Directory or enter a location of your choice and click Next.
  7. Decide whether to use a Local System Account or a Custom Domain Account.

Learn more about the permissions required for the Octopus Windows Service or using a Managed Service Account.

  1. On the Database page, click the dropdown arrow in the Server Name field to detect the SQL Server database. Octopus will create the database for you which is the recommended process; however, you can also create your own database.
  2. Enter a name for the database, and click Next and OK to create the database.

Be careful not to use the name of an existing database as the setup process will install Octopus into that pre-existing database.

  1. Accept the default port and directory or enter your own. This guide assumes Octopus is listening on port 80. Click Next.
  2. If you’re using a username and passwords stored in Octopus authentication mode, enter the username and password that will be used for the Octopus administrator. If you are using active directory, enter the active directory user details.
  3. Click Install.
  4. When the installation has completed, click Finish to launch the Octopus Manager.

Azure websites

Deploying to Azure requires an Azure Service Principal Account. Documentation on how to create this account can be found here.

In order to deploy to Azure an App Service implementing the ASP.NET V4.7 runtime stack needs to be created for each Octopus environment. App Services are documented here.

Clone source code

The source code for the random quotes application is hosted in GitHub. The code can be cloned from https://github.com/OctopusSamples/RandomQuotes.git with the command:

git clone https://github.com/OctopusSamples/RandomQuotes.git

The RandomQuotes application can be run locally with the command:

cd RandomQuotes/RandomQuotes
dotnet run

Octopus API key

In order to allow GitHub Actions to communicate with Octopus, we need to generate an API key. This is done in the Octopus web portal. The web portal can be opened from the Browse link in the Octopus Manager:

Screenshot of the Octopus Manager

From the Octopus Deploy web portal, sign in, and view your profile:

Screenshot of the Octopus profile drop down menu

Go to the API keys tab. This lists any previous API keys that you have created. Click on New API key:

Screenshot of the Octopus profile API keys page

Give the API key a name so that you remember what the key is for, and click Generate New:

Screenshot of the new API key dialog

Copy the new API key to your clipboard:

Screenshot of new API key

Continuous integration

GitHub Actions supports Node.js, Python, Java, Ruby, PHP, Go, Rust, .NET, and more. Build, test, and deploy applications in your language of choice. In this tutorial, we rely on GitHub Actions to do the following:

  • Clone the code from Git.
  • Resolve and install any dependencies from NuGet.
  • Run unit tests.
  • Package the application by bundling all the files it needs to run into a ZIP file.
  • Push the package to the Octopus (built-in) package repository.

At a high level, GitHub Actions workflows are YAML documents committed to a GitHub repsository that define the runner that the steps are executed on, the triggers that execute the workflow, and the steps to be run.

GitHub Actions workflows have access to encrypted secrets. Two secrets are defined called:

  • OCTOPUS_SERVER_URL, which defines the URL of the Octopus server (for example, https://myserver.octopus.app for hosted Octopus instances)
  • OCTOPUS_API_TOKEN, which defines the API key used to access the Octopus instance.

The YAML document below is saved to a file called .github/workflows/build.yaml. It is configured to be triggered on a git push and defines steps to build, test, package, and publish the sample application:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
      with:
        fetch-depth: '0'
    - name: Set up DotNET Core
      uses: actions/setup-dotnet@v3
      with:
        dotnet-version: 3.1.402
    - name: Install GitVersion
      uses: gittools/actions/gitversion/setup@v0.9.14
      with:
        versionSpec: 5.x
    - id: determine_version
      name: Determine Version
      uses: gittools/actions/gitversion/execute@v0.9.14
      with:
        additionalArguments: /overrideconfig mode=Mainline
    - name: Install Octopus Deploy CLI
      uses: OctopusDeploy/install-octopus-cli-action@v1
      with:
        version: latest
    - name: Install Dependencies
      run: dotnet restore
      shell: bash
    - name: Test
      run: dotnet test -l:trx
      shell: bash
    - if: always()
      name: Report
      uses: dorny/test-reporter@v1
      with:
        name: DotNET Tests
        path: '**/*.trx'
        reporter: dotnet-trx
        fail-on-error: 'false'
    - name: Publish
      run: dotnet publish --configuration Release /p:AssemblyVersion=${{ steps.determine_version.outputs.assemblySemVer }}
    - id: package
      name: Package
      run: |
        # Find the publish directories
        shopt -s globstar
        paths=()
        for i in **/publish/*.dll; do
          dir=${i%/*}
          echo ${dir}
          paths=(${paths[@]} ${dir})
        done
        eval uniquepaths=($(printf "%s\n" "${paths[@]}" | sort -u))
        for i in "${uniquepaths[@]}"; do
          echo $i
        done
        # For each publish dir, create a package
        packages=()
        versions=()
        for path in "${uniquepaths[@]}"; do
          # Get the directory name four deep, which is typically the project folder.
          # The directory name is used to name the package.
          dir=${path}/../../../..
          parentdir=$(builtin cd $dir; pwd)
          projectname=${parentdir##*/}
          # Package the published files
          octo pack \
          --basePath ${path} \
          --id ${projectname} \
          --version ${{ steps.determine_version.outputs.semVer }} \
          --format zip \
          --overwrite
          packages=(${packages[@]} "${projectname}.${{ steps.determine_version.outputs.semVer }}.zip")
          versions=(${versions[@]} "${projectname}:${{ steps.determine_version.outputs.semVer }}")
        done
        # Join the array with commas
        printf -v joined "%s," "${packages[@]}"
        # Save the list of packages as an output variable
        echo "::set-output name=artifacts::${joined%,}"
        # Do the same again, but use new lines as the separator
        # https://trstringer.com/github-actions-multiline-strings/
        # Multiline strings require some care in a workflow
        printf -v versionsjoinednewline "%s\n" "${versions[@]}"
        versionsjoinednewline="${versionsjoinednewline//'%'/'%25'}"
        versionsjoinednewline="${versionsjoinednewline//$'\n'/'%0A'}"
        versionsjoinednewline="${versionsjoinednewline//$'\r'/'%0D'}"
        # Save the list of packages newline separated as an output variable
        echo "::set-output name=versions_new_line::${versionsjoinednewline%\n}"
    - name: Push packages to Octopus Deploy πŸ™
      uses: OctopusDeploy/push-package-action@v2
      env:
        OCTOPUS_API_KEY: ${{ secrets.OCTOPUS_API_TOKEN }}
        OCTOPUS_HOST: ${{ secrets.OCTOPUS_SERVER_URL }}
      with:
        overwrite_mode: OverwriteExisting
        packages: ${{ steps.package.outputs.artifacts }}
name: DotNET Core Build
'on':
  workflow_dispatch: {}
  push: {}
    

There is a lot of work being performed by this workflow, so let's break it down.

The job called build is run on an Ubuntu runner:

jobs:
  build:
    runs-on: ubuntu-latest
    

The first step checks out the source code from the git repository. Setting the fetch-depth option to 0 means all the history for all branches and tags is fetched. This is required by the GitVersion action used in later steps:

    steps:
    - uses: actions/checkout@v3
      with:
        fetch-depth: '0'

This step sets up DotNET Core 3 which is used to build the application source code:

    - name: Set up DotNET Core
      uses: actions/setup-dotnet@v3
      with:
        dotnet-version: 3.1.402

GitVersion builds meaningful version strings based on the commits to git.

This step installs GitVersion:

    - name: Install GitVersion
      uses: gittools/actions/gitversion/setup@v0.9.14
      with:
        versionSpec: 5.x

This step calls GitVersion which outputs many different variables representing different parts of a SemVer version string generated from the commits to the git repository. Later steps use these output values as the version of the package generated by this workflow:

    - id: determine_version
      name: Determine Version
      uses: gittools/actions/gitversion/execute@v0.9.14
      with:
        additionalArguments: /overrideconfig mode=Mainline

This step installs the Octopus CLI, which is used by the subsequent Octopus GitHub Actions:

    - name: Install Octopus Deploy CLI
      uses: OctopusDeploy/install-octopus-cli-action@v1
      with:
        version: latest

This step installs the application's dependencies:

    - name: Install Dependencies
      run: dotnet restore
      shell: bash

This step runs the unit tests:

    - name: Test
      run: dotnet test -l:trx
      shell: bash

This step publishes the results of the test against the workflow run. The if parameter is set to always() to ensure that the results are published even if the tests fail:

      - if: always()
        name: Report
        uses: dorny/test-reporter@v1
        with:
          name: DotNET Tests
          path: '**/*.trx'
          reporter: dotnet-trx
          fail-on-error: 'false'

This step publishes the application's executable files. The version of the assemblies is set to the assemblySemVer output generated by GitVersion:

    - name: Publish
      run: dotnet publish --configuration Release /p:AssemblyVersion=${{ steps.determine_version.outputs.assemblySemVer }}

This step packages the application's published executable files into a self contained artifact:

    - id: package
      name: Package
      run: |

The bash script defined in this step relies on the conventions used by the dotnet publish command to determine the location of the published executable files.

By default, the dotnet publish command saves files to the directory [project_file_folder]/bin/[configuration]/[framework]/publish/ .

This kind of generalized logic is perhaps overkill for the Random Quotes sample application, because there is only one project being built and we know exactly where the published files will be found. However, more complex DotNET applications can have several projects referenced by a single solution, in which case multiple projects are built and published. The logic presented here accomodates these more complex projects.

The first part of the bash script finds dll files located under a directory called publish and saves the directory to a variable called paths:

        # Find the publish directories
        shopt -s globstar
        paths=()
        for i in **/publish/*.dll; do
          dir=${i%/*}
          echo ${dir}
          paths=(${paths[@]} ${dir})
        done

There are likely many dll files, meaning the paths variable contains many duplicate entries. The variable uniquepaths is created containing the unique values found in the paths variable:

        eval uniquepaths=($(printf "%s\n" "${paths[@]}" | sort -u))

Each of the unique paths is printed to the console for debugging:

        for i in "${uniquepaths[@]}"; do
          echo $i
        done

We then define two arrays that hold the paths to packages artifacts and the versions:

        packages=()
        versions=()

We loop over the directories containing the published files:

        for path in "${uniquepaths[@]}"; do

The package ID is determined by the directory containing the project file. Remember that the packaged files are saved to the directory [project_file_folder]/bin/[configuration]/[framework]/publish/ by default. This means the project directory is found four levels up from the published files in the directory structure:

          # Get the directory name four deep, which is typically the project folder.
          # The directory name is used to name the package.
          dir=${path}/../../../..
          parentdir=$(builtin cd $dir; pwd)
          projectname=${parentdir##*/}

The published files are packaged as a Zip archive with the ID determined from the project directory name and with the version contained in the output variable semVer generated by GitVersion:

          # Package the published files
          octo pack \
          --basePath ${path} \
          --id ${projectname} \
          --version ${{ steps.determine_version.outputs.semVer }} \
          --format zip \
          --overwrite

The location of the zip file is added to the packages variable, and the version of the package is added to the versions variable:

          packages=(${packages[@]} "${projectname}.${{ steps.determine_version.outputs.semVer }}.zip")
          versions=(${versions[@]} "${projectname}:${{ steps.determine_version.outputs.semVer }}")

Actions use lists in a few different ways. Some actions require lists to be comma separated, while others use newline separated lists.

The list of packages is exported a comma separated list called artifacts:

        # Join the array with commas
        printf -v joined "%s," "${packages[@]}"
        # Save the list of packages as an output variable
        echo "::set-output name=artifacts::${joined%,}"

The list of package versions is exported as a newline separated list called versions_new_line.

In order to create a newline separated list that can be consumed in a later step, we must take care to escape special characters like the percent sign and line breaks:

        # Do the same again, but use new lines as the separator
        # https://trstringer.com/github-actions-multiline-strings/
        # Multiline strings require some care in a workflow
        printf -v versionsjoinednewline "%s\n" "${versions[@]}"
        versionsjoinednewline="${versionsjoinednewline//'%'/'%25'}"
        versionsjoinednewline="${versionsjoinednewline//$'\n'/'%0A'}"
        versionsjoinednewline="${versionsjoinednewline//$'\r'/'%0D'}"
        # Save the list of packages newline separated as an output variable
        echo "::set-output name=versions_new_line::${versionsjoinednewline%\n}"

The package files are then pushed to Octopus:

    - name: Push packages to Octopus Deploy
      uses: OctopusDeploy/push-package-action@v2
      env:
        OCTOPUS_API_KEY: ${{ secrets.OCTOPUS_API_TOKEN }}
        OCTOPUS_HOST: ${{ secrets.OCTOPUS_SERVER_URL }}
      with:
        overwrite_mode: OverwriteExisting
        packages: ${{ steps.package.outputs.artifacts }}

The workflow is triggered on each push to the git repository. The workflow can also be triggered manually with the workflow_dispatch event:

name: DotNET Core Build
'on':
  workflow_dispatch: {}
  push: {}

Commit the file and push it to the GitHub repository with the command:

git add .; git commit -m "Added workflow file"; git push

GitHub Actions then runs the workflow.

Deploying with Octopus Deploy

Now that GitHub Actions has successfully built the application, we need to configure Octopus to deploy it into our environments.

Create the environments

Environments represent the stages that a deployment must move through as part of the deployment pipeline. We'll create three environments: Dev, Test, and Prod.

Log into Octopus, and click the Infrastructure link, then the Environments link, and click ADD ENVIRONMENT:

A screenshot of the Octopus environments page

Enter Dev as the New environment name, and click SAVE:

A screenshot of the new environment dialog creating an environment called Dev

Repeat the process for the Test and Prod environments:

A screenshot of the new environment dialog creating an environment called Test A screenshot of the new environment dialog creating an environment called Prod

Create the Azure Account

In order to interact with Azure, we need to define the details of an Azure account that will grant us access to perform the deployment.

Click the Infrastructure link:

Click the Accounts link:

Click ADD ACCOUNT, and click the Azure Subscription option:

Enter Azure as the account name:

Enter the Subscription ID:

Enter the Tenant ID:

Enter the Application ID:

Enter the Application Password / Key, and click Save:

Create the Azure WebApp Target

Azure App Services are represented as targets in Octopus. We will create a new target for each environment.

Click the Infrastructure link:

Click the Deployment Targets link:

Click ADD DEPLOYMENT TARGET:

Click Azure, and click Add on the Azure Web App tile:

Enter Azure web app - Dev as the Display Name:

Select Dev as the Environment:

Enter azurewebapp as the Target Role:

Select the Azure account that was created in the previous section:

Select the App Service created in Azure that this target will deploy to. We won't be using slots, so click SAVE:

Repeat this process to create targets scoped to the Test and Prod environments, with each target referencing a unique Azure App Service.

Create the Octopus deployment project

With the environments defined and a target created, we now need to create a deployment project in Octopus.

Log into Octopus, click the Projects link, and click ADD PROJECT:

A screenshot of the ADD PROJECT button

Enter Random Quotes for the project name, and click SAVE:

A screenshot of the Add New Project dialog

We start by defining the variables that we will consume as part of the deployment. Click the Variables link, and then select the Project option:

A screenshot of the Variables link

The first variable we'll define is called AppSettings:EnvironmentName. This matches the name of a key in the appsettings.json file:

{
       ...
       "AppSettings": {
         ...
         "EnvironmentName": "DEV"
       }
     }
We set the value of this variable to match the name of the environment that Octopus is deploying the application into by setting its value to #{Octopus.Environment.Name}. This variable, in conjunction with the Structured Configuration Variables feature, means that the config file will be updated during deployment to reflect the current environment. This is how we can have a single, environment agnostic package, and customize it for any environment it is deployed into.

Then click SAVE to save the changes:

A screenshot of the project variables

We will now define the deployment process. Click Deployments link, then the Overview link, and then click DEFINE YOUR DEPLOYMENT PROCESS:

A screenshot of the CREATE PROCESS button

Click ADD STEP:

A screenshot of the ADD STEP button

Enter Azure Web App into the search box:

A screenshot of the step sreach field

Click ADD on the Deploy an Azure Web App tile.

A screenshot of the step ADD button

We want to take advantage of a feature in Octopus that replaces settings in the web.config file based on our variables. Specifically, we're replacing the AppSettings:EnvironmentName variable that was defined earlier. To do this we enable the Structured Configuration Variables feature.

Click CONFIGURATION FEATURES:

A screenshot of the CONFIGURATION FEATURES button

Enable the Structured Configuration Variables option, and click OK:

A screenshot of the Structured Configuration Variables option

In the Structured Configuration Variables section, enter appsettings.json as the Target files value.

A screenshot of the Structured Configuration Variables section

Enter Deploy an Azure Web App as the step name:

A screenshot of the step name field

Enter azurewebapp as the On Behalf Of option:

A screenshot of the On Behalf Of option

Select the RandomQuotes package ID. This is the package that GitHub Actions pushed to the built-in feed. The remaining values can be left at their defaults, so click SAVE:

A screenshot of the package ID selection field

Deploy!

We now have a deployment project in Octopus ready to deploy our ASP.NET Core application to our Dev, Test, and Prod environments. The next step is to create and deploy a release.

Click CREATE RELEASE.

The release creation screen provides an opportunity to review the packages that will be included and to add any release notes. By default, the latest package is selected automatically. Click SAVE:

A screenshot of the release creation screen

This screen allows you to select the environment that will be deployed into. Lifecycles can be used to customize the progression of deployments through environments (this is demonstrated later in the guide), however, we will accept the default option to deploy to the Dev environment by clicking DEPLOY TO DEV...:

A screenshot of the DEPLOY TO DEV button

Click DEPLOY to deploy the application into the Dev environment:

A screenshot of the DEPLOY button

The application is then deployed:

A screenshot of the deployment

Congratulations! You have now built and deployed your first application. Visit the URL of the Azure web application to view a random quote.

A screenshot of the application deployed to an Azure Web App

Continuous deployments

The process of deploying a successful build to the Dev environment is currently a manual one; GitHub Actions pushes the file to Octopus, and we must trigger the initial deployment to the Dev environment from within Octopus. Typically though, deployments to the Dev environment will be performed automatically if a build and all of its tests succeed.

To trigger the initial deployment to the Dev environment after a successful build, we will go back to the project we created in GitHub Actions and add an additional step to create an Octopus release and then deploy it to the Dev environment.

When added to the workflow file, the YAML below creates a new release in Octopus with each build and deploys it to the development environment.

Note that the package versions are explicitly defined via the output variable called versions_new_line generated in previous steps:

    - name: Create Octopus Release
      uses: OctopusDeploy/create-release-action@v1.1.1
      with:
        api_key: ${{ secrets.OCTOPUS_API_TOKEN }}
        project: Random Quotes
        server: ${{ secrets.OCTOPUS_SERVER_URL }}
        deploy_to: Dev
        packages: ${{ steps.package.outputs.versions_new_line }}

Additional configuration

Now we will explore some of the more advanced features of Octopus that allow us to customize the deployment progression through environments, secure deployments to production environments, add deployment sign offs, view the audit logs, and add notifications.

Lifecycles

Our project currently uses the default lifecycle, which defines a progression through all the environments in the order they were created.

A custom lifecycle allows the progression of a deployment to be further refined, by defining only a subset of environments that can be deployed to, allowing some environments to be skipped entirely, or requiring that a minimum number of environments are successfully deployed to before moving onto the next environment.

Here we will create a custom lifecycle that makes deployments to the Dev environment optional. This means that initial deployments can be made to the Dev or Test environments, but a successful deployment must be made to the Test environment before it can be progressed to the Prod environment.

Skipping the Dev environment like this may be useful for promoting a release candidate build directly to the Test environment for product owners or testers to review.

Click the Library link, click the Lifecycles link, and click ADD LIFECYCLE:

A screenshot showing the Octopus lifecycles page

Set the lifecycle name to Dev, Test, and Prod, and the description to Progression from the Dev to the Prod environments:

A screenshot showing the new lifecycle name and description

Phases are used to group environments that can accept a deployment. Simple lifecycles, such as the lifecycle we are creating, have a one-to-one relationship between phases and environments.

Click ADD PHASE:

A screenshot showing the ADD PHASE button

Enter Dev as the phase name, and select the Optional phase option. This means that deployments can skip this phase and any environments defined in it, and deploy directly to the next phase.

Because we are mapping each environment to its own phase, the name of the phase matches the name of the environment:

A screenshot showing the new lifecycle phase

Click ADD ENVIRONMENT:

A screenshot showing the ADD ENVIRONMENT button

Click the dropdown arrow, select the Dev environment, and click OK:

A screenshot showing the selection of the Dev environment

Repeat the process to add a new phase for the Test and Prod environments, leaving the default All must complete option selected:

A screenshot showing the selection of the Test environment A screenshot showing the selection of the Prod environment

Click SAVE:

A screenshot showing the SAVE button

Now, we need to switch the deployment project from the Default Lifecycle to the newly created lifecycle.

Click the Projects link, and click the Random Quotes project tile:

A screenshot showing the Random Quotes project

Click the Process link, and click CHANGE:

A screenshot showing the lifecycle CHANGE button in the project's process screen

Select the Dev, Test, and Prod lifecycle. Notice the Dev environment is shown as optional.

Click SAVE:

A screenshot showing the lifecycle selection dialog

Click CREATE RELEASE, and click SAVE to save the new release:

A screenshot showing the release creation screen

Because the Dev environment has been configured as optional, the initial release can be made to either the Dev or Test environments. We'll skip the Dev environment and deploy straight to Test.

Click DEPLOY TO..., and select the Test environment:

A screenshot showing the Test environment selected to deploy to

Click DEPLOY to deploy the application to the Test environment:

A screenshot of the DEPLOY button

The deployment is then performed directly in the Test environment, skipping the Dev environment:

A screenshot of the deployment being performed to the Test environment

Opening https://appservicename.azurewebsites.net displays the copy of the Random Quotes application deployed to the Test environment. Note the URL matches the name of the Azure App Service that was defined in the target scoped to the Test environment and will be unique for each Azure App Service.

Also see the footer text that says running in Test. This is the result of the Structured Configuration Variables feature and the AppSettings:EnvironmentName variable replacing the initial value of DEV in the appsettings.json file with Test. This is an example of a single, environment agnostic package being customized for the environment it is being deployed into:

Approvals

It's a common business requirement to have testers or product owners manually verify that a particular build meets the requirements before a deployment can be considered successful.

Octopus supports this workflow through the use of manual intervention steps. We'll add a manual intervention step to the end of the deployment process, which requires a responsible party to verify the build meets the requirements.

Open the Random Quotes project, click the Process link, and click the ADD STEP button:

A screenshot of the Random Quotes process page

Search for the Manual Intervention Required step, and add it to the process:

A screenshot of the Manual Intervention Required step

Enter Deployment Sign Off for the Step Name:

A screenshot of the new step name field

Enter the following for the Instructions:

Open the application and confirm it meets all the requirements.
A screenshot of the instructions field

Because every build is automatically deployed to the Dev environment, it doesn't make sense to force someone to manually approve all those deployments. To accommodate this, we do not enable the manual intervention step for deployments to the Dev environment.

Expand the Environments section under the Conditions heading, select the Skip specific environments option, and select the Dev environment.

Click SAVE to save the step:

A screenshot of the step environment conditions and SAVE button

When this application is deployed to the Test or Prod environments, a prompt will be displayed requiring manual sign off. Click ASSIGN TO ME to assign the task to yourself:

A screenshot of the ASSIGN TO ME button

Add a note in the provided text box, and click PROCEED to complete the deployment:

A screenshot of the manual intervention message and PROCEED button

The deployment will then complete successfully:

A screenshot of the deployment process

Email notifications

Octopus has native support for sending email notifications as part of the deployment process. We will add a step to the deployment process to let people know when a release has been deployed to an environment.

To start, we need to configure an SMTP server to send our emails. For this guide, we'll use the free SMTP server provided by Google.

Click the Configuration link:

A screenshot of the Configuration link

Click the SMTP link:

A screenshot of the SMTP link
  • Enter smtp.gmail.com as the SMTP Host.
  • Enter 587 as the SMTP Port.
  • Enable the Use SSL/TLS option.
  • Enter your Gmail address as the From Address.
  • Enter your Gmail address and password in the credentials.

You will enable the Less secure apps option on your Google account for Octopus to send emails via the Google SMTP server.

A screenshot of the SMTP configuration

Open the Random Quotes project, click the Process link, and click ADD STEP:

A screenshot of the ADD STEP button

Search for the Send an Email step, and add it to the process:

A screenshot of the Send an Email step

Enter Random quotes deployment status for the Step Name:

A screenshot of the Step Name field

Enter the email address to receive the notification in the To field:

A screenshot of the email To field

Enter Random quotes deployment status as the Subject:

A screenshot of the email Subject field

Enter the following as the Body:

Deployment to #{Octopus.Environment.Name}
#{each step in Octopus.Step}
StepName: #{step}
Status: #{step.Status.Code}
#{/each}

Here we use the #{Octopus.Environment.Name} variable provided by Octopus to add the name of the environment that was deployed to, and then loop over the status codes in the #{Octopus.Step} variable to return the status of each individual step.

The complete list of system variables can be found in the Octopus documentation.

A screenshot of the email Body field

We want to be notified of the status of this deployment regardless of whether the deployment succeeded or failed. Click the Run Conditions section to expand it.

Select the Always run option, which ensures the notification email is sent even when the deployment or the manual intervention fail:

A screenshot of the Run Condition options

Given every change to the source code will result in a deployment to the Dev environment, we do not want to generate reports for deployments to this environment.

Click the Environments section to expand it. Select the Skip specific environments option, and select the Dev environment to skip it.

This is the last piece of configuration for the step, so click SAVE to save the changes:

A screenshot of the Conditions Environments options and SAVE button

Deploy the project to the Test or Prod environments. When the deployment succeeds, the notification email will be sent:

A screenshot of the sample email

Permissions

One of the strengths of Octopus is that it models environments as first-class entities. This means the security layer can apply rules granting access only to specific environments. We'll take advantage of this ability to model and secure environments to create two users, an internal deployer who can deploy to the Dev and Test environments, and a production deployer who can deploy to the Prod environment.

We start by creating the users. Click the Configuration link:

A screenshot of the Configuration link

Click the Users link:

A screenshot of the Users link

Click ADD USER:

A screenshot of the ADD USER button

Enter internaldeployer as the Username:

A screenshot of the Username field

Enter Internal Deployer as the Display Name:

A screenshot of the Display Name field

Enter the user's email address. We have used a dummy address of internaldeployer@example.org here:

A screenshot of the Email Address field

Enter a password and confirm it. Then click SAVE to create the user:

A screenshot of the password field and SAVE button

Repeat the process for a user called productiondeployer. The summary for the productiondeployer user is shown below:

A screenshot of the user's details

The newly created users are not assigned to any teams and have no permissions to do anything. To grant them permissions, we must first create two teams. The internal deployment team will grant access to deploy to the Dev and Test environments, while the production deployment team will grant access to deploy to the Prod environment.

Click the Configuration link:

A screenshot of the Configuration link

Click the Teams link:

A screenshot of the Teams link

Click ADD TEAM:

A screenshot of the ADD TEAM button

Enter Internal Deployers for the New team name, and Grants access to perform a deployment to the internal environments for the Team description. Click SAVE to create the team:

A screenshot of the Add New Team dialog

We need to add the internaldeployer user to this team. Click ADD MEMBER:

A screenshot of the ADD MEMBER button

Select the Internal Deployer user from the dropdown list, and click ADD:

A screenshot of the Add Member dialog

The team does not grant any permissions yet. To add permissions click the USER ROLES tab, and click INCLUDE USER ROLE:

A screenshot of the INCLUDE USER ROLE button

Select the Deployment creator role from the dropdown list. As the name suggests, this role allows a user to create a deployment, which results in the deployment process being executed.

Click DEFINE SCOPE:

A screenshot of the Include User Role dialog

We only want to allow the internal deployer to deploy to the internal environments. Select the Dev and Test environments, and click APPLY:

A screenshot of the APPLY button

The permissions are then applied. We need a second permission to allow the internal deployer to view the projects dashboard. Click INCLUDE USER ROLE again:

A screenshot of the INCLUDE USER ROLE button

Select the Project viewer role. This role does not need to be scoped, so click the APPLY button:

A screenshot of the Include User Role dialog

Here are the final set of roles applied to the team:

A screenshot of the team's USER ROLES tab

Repeat the process to create a team called Production Deployers that includes the productiondeployer user, and grants the Deployment creator role scoped to the Prod environment:

A screenshot of the team's USER ROLES tab

When we log in as the internaldeployer user, we see that the Random Quotes project dashboard shows DEPLOY... buttons for the Dev and Test environments. Any deployments in the production environment will be visible, but they cannot be created by this user:

A screenshot of the Projects page

When we log in as the productiondeployer user, we see that the Random Quotes project dashboard shows DEPLOY... buttons only for the Prod environment. Also note that the lifecycle rules still apply, and only successful deployments to the Test environment are available to be promoted to the Prod environment:

A screenshot of the Projects page

Audit Log

Important interactions in Octopus are tracked in the audit log. This is useful for teams that have security or legislative requirements to track the changes and deployments made to their infrastructure.

To view the audit log, click the Configuration link:

A screenshot of the Configuration link

Click the Audit link:

A screenshot of the Audit link

A complete list of records are shown, with filtering available to help find specific events:

A screenshot of the Audit page

Conclusion

In this guide we ran through the process of building a complete CI/CD pipeline with:

  • GitHub Actions building and testing the source code and pushing the package to Octopus.
  • Octopus deploying the package to the Dev, Test, and Prod environments.
  • Email notifications generated when deployments succeed or fail.
  • Manual sign off for deployments to the Test and Prod environments.
  • Users with limited access to create releases in a subset of environments.

This is a solid starting point for any development team, but Octopus offers so much more! Below are more resources you can access to learn about the advanced functionality provided by Octopus:

Need support? We're here to help.