Octopus blog

DRY isn't just for application code

2026-10-28

In the first article of this series, I shared how we approached modernizing the build and deployment of our microsites at Octopus. One of the biggest sources of friction was how our GitHub Actions workflows were managed. Each of our microsites had its own repository, and each repository had its own copy of four workflows. That’s twenty workflow files, all meant to be identical, all maintained separately, and a problem that only got worse with every new microsite we provisioned.

From a technical perspective, it worked, but it didn’t age well, and the workflows were originally built before reusable workflows were available to us. Making a change like bumping the node version meant opening five pull requests across five repositories, getting each one reviewed, and merging them one by one. Small tweaks made in one repository didn’t always reach the others, and over time, it became trivial for the workflows to drift apart. It’s one of those classic things where each time someone made a change, they knew there was a better way, but the pain experienced for that one-off change wasn’t big enough to take action. However, nobody could say with confidence that every microsite was being built the same way.

Most developers learn “don’t repeat yourself” (DRY) early on as a principle for writing application code. Yet it’s surprisingly common to see the same pipeline copied across repository after repository, as if the rule stops at the edge of the source code. Our microsites were a textbook example.

The fix was to move the build logic into a single central repository and have each microsite call it, so a change made once applies everywhere. GitHub calls these reusable workflows, and getting them in place was one of the project’s quicker wins.

It wasn’t all smooth sailing, though. Reusable workflows solved the copy-paste problem, but they raised new questions about versioning, testing changes safely and without friction, and how much a platform team can see and control once other teams depend on what they’ve built.

A central home for shared workflows

The first step was deciding where the shared workflows would live. I knew there would likely be other shared elements for the project, so we created a central repository called microsite-deployment. Alongside the reusable workflows, it also holds the Terraform for the hosting infrastructure and the scripts used during deployment.

What makes a workflow reusable is a single trigger. Instead of running on a push or a pull request, it uses on: workflow_call, which tells GitHub it’s designed to be invoked by other workflows. It can then declare inputs, just like a function declares parameters, and the calling workflow supplies the values.

For each microsite, the result is refreshingly small. Here’s the entire calling workflow that runs when a pull request is opened against our blog:

name: Pull Request build and deploy

on:
  pull_request:
    branches:
      - main

jobs:
  branch_validation:
    uses: OctopusDeploy/microsite-deployment/.github/workflows/microsite-deployment-branch.yml@main
    with:
      octopus_project_name: "Blog Microsite"
      package_id: "BlogMicrosite"
    secrets: inherit

That’s it. The calling workflow decides when the build runs, and the called workflow decides how it runs. Each microsite provides two inputs: the name of its Octopus project and the package ID for the built site, so it knows which package to reference when GitHub triggers a release in Octopus. Installing dependencies, building and testing the site, packaging it, pushing it to Octopus, and creating a release all live in one place now.

Centralizing the workflows also means the trickier logic only needs to be solved once. Some of our microsite repositories are public and accept contributions from people outside of Octopus. Pull requests from forks don’t have access to the repository’s secrets, so a build from a fork can’t push anything to the Octopus instance that performs deployments. The reusable workflow handles this with a SHOULD_DEPLOY flag, which is set based on whether the Octopus server secret is available in the repo. If it isn’t, the site is still built, tested, and packaged, and the package is uploaded as a workflow artifact instead. Outside contributors still get a validated build, but it doesn’t try to deploy without the credentials to do it. That logic existed before this project, but now it lives in one place, and every public microsite gets it for free.

Adding a new microsite is now a very different experience. Instead of copying four complex workflow files from an existing repo and hoping you picked the latest version, a new repository needs a handful of stable short calling workflows like the one above, and it gets the same build process every other microsite uses from day one.

Bring improvements in small batches

When I started converting the workflows, there was a temptation to go all the way in one hit. Take everything, use Claude to consolidate it into as few files as possible, with whatever logic was needed to handle every incarnation, and be done with it. But moving five microsites onto shared workflows was already a meaningful change, and I didn’t want to stack a redesign of the build logic on top of it. We already know small batches are easier to author and review, easier to test, and much easier to roll back if something goes wrong.

The first step was a fairly direct translation. Each of the four workflows in the microsite repositories became a reusable workflow in the central repository, and each microsite swapped its copies for the short and stable calling workflows. The logic of the workflow stayed the same, but the benefit I was looking for with this change was to consolidate to one version of each workflow, giving us one place to make changes moving forward that would roll out to all callers.

The two build workflows are a good example of where I deliberately held back. One runs when a pull request is opened, and the other runs when changes are merged to main. Both build, test, and package the site, but what happens next is quite different. The main branch workflow is a single job that pushes the package to Octopus and creates a release. The pull request workflow is split into three jobs, deploys to an ephemeral environment, can be skipped with a label, and has a gate job that acts as the required status check for merging.

Could they be a single workflow? Yes. They might even become a single workflow in the future. You could check which event triggered the run, or pass in an input, and use conditions to determine which jobs run. But the two workflows differ in their structure, not just a step or two, and a single file full of conditionals can be harder to read and reason about. Keeping them separate means each one clearly does one job.

I can see what you’re thinking:

But Matt, we are trying to stop the duplication and the multiple changes!

Yes, true, but it doesn’t mean the duplication between them was entirely ignored. For example, workflows need to install the same versions of Node and pnpm, and specifying those versions in two places would have reintroduced the exact problem we were trying to escape, just inside the central repository instead of across the microsites.

So the versions for pnpm and Node are specified in a small composite action, which both workflows call:

- name: Retrieve versions
  uses: OctopusDeploy/microsite-deployment/.github/composite/versions@main
  id: versions

The composite action exposes the Node and pnpm versions as outputs, giving us one place to bump the toolchain for every workflow at once.

The flow from caller workflows, to called workflows, to the composite action

I’ll be honest, though: there’s still duplication. The steps to install dependencies, build, test, and package the site are nearly identical in both workflows, and that’s a natural next candidate for a composite action of its own. It’s a good reminder that copy-paste can creep back in even inside the platform that’s meant to eliminate it. But getting the microsites onto shared workflows first, and then improving those workflows from a single place, was a much safer path than trying to do everything at once. Any further consolidation is now a change to one repository, not five.

Versioning and testing changes

Once the microsites were calling shared workflows, a new question quickly arose. When I change a reusable workflow, which version should each microsite be running?

Choosing a reference

The calling workflow determines which version of a reusable workflow to uses via the reference after the @. There are three common options, each with a trade-off.

A branch, like @main. This is a floating reference. Whatever is on the main branch of the central repository is what every caller runs on its next build. For a platform team, that’s appealing, because a fix or improvement reaches every consumer immediately. For the consumer, it means a change can land in their build without them doing anything, and if that change breaks something, they find out when their pipeline fails. It’s a similar pattern to using latest with container images, which most of the industry has moved away from for good reason.

A tag, like @v1.2.0. Callers stay on a known version until they choose to update. That’s much more predictable, but git tags are mutable by default. Someone can move a tag to a different commit, accidentally or otherwise, and every caller pinned to it quietly starts running different code. GitHub’s immutable releases help here, as the tag attached to an immutable release can’t be changed after it’s published. The catch is that this doesn’t work for floating tags like @v1, which many teams use so consumers automatically get minor updates, because a floating tag has to move to be useful.

A commit SHA. This is the most stable option. A SHA always points to the exact same code, and GitHub’s own documentation recommends it as the safest choice for stability and security. The catch is that a 40-character hash tells you nothing at a glance, so the common convention is to add a comment with the version it represents.

We opted to use @main, effectively forcing every consumer onto the latest version at all times, and accepting that we’re on the hook if we break all the microsites at once. How a workflow is referenced is ultimately set in the calling repository, but the platform team decides which options exist and which one to recommend, so it’s a decision worth making together with your consumers. Think through the implications, and decide whether you’d rather keep everyone on the latest version, or end up with consumers using many versions and choosing when to update, with all the complications that may arise. As we’ll see, GitHub doesn’t have a neat way to notify people there’s a new version, or report on version use so you can track and encourage updates.

Keeping consumers up to date

If you do pin to tags or SHAs, the next problem is ensuring consumers move to newer versions when you publish. Pinned callers don’t automatically pick up changes, so the fix you’ve published might not be running anywhere.

Dependabot can help here. It can track reusable workflow references and raise pull requests when a new version is available, just as it does for marketplace actions. For workflows in private or internal repositories, which is the common case within an organization, they require a little extra setup, either by granting Dependabot access to the central repository in your organization settings or by configuring a Dependabot secret with a token that can read it. It’s also opt-in per calling repository. It makes updates easier to notice and act on, but the decision to update still sits with each consumer for any type of update, whether it be a patch, minor, or major change.

One tag for every workflow

Another paper cut I hit when exploring tagging for the reference approach, is that tags apply to the whole repository. A Git tag points to a commit, and that commit contains every workflow in the repository. If I change the pull request workflow and tag it v1.3.0, a consumer of the main branch workflow who moves to v1.3.0 picks up whatever state that workflow is in at the same commit, even if nothing changed for them. There’s no built-in way to version reusable workflows independently within one repository. You can work around it with prefixed tags, a repository per workflow, or community tools like the Workflow Independent Release Engine, but each adds its own overhead.

Testing changes

This is the part I found most awkward day-to-day. When I want to change a reusable workflow, I make the change on a branch in the central repository. I want to test it works as intended before I merge to main, but I don’t have anything that’s calling the version in my new branch. Currently to test, I create a branch in one of the microsite repositories, change its calling workflow to point at my branch instead of @main, and trigger it. Depending on the trigger, that can mean opening a throwaway pull request just to get the workflow to run.

This rarely happens, but it gets more awkward when the change also touches the composite action. The reusable workflow references the composite at @main, and that nested reference resolves on its own, regardless of which version of the reusable workflow the caller asked for. You might think a local path would solve this, but a local path inside a reusable workflow is resolved against the caller’s workspace, not the central repository. Before the composite action existed, I tried storing the versions in a JSON file in the central repository and reading it from the reusable workflow, but the workflow went looking for the file in the calling microsite repository instead. So testing a change that spans both files means re-pointing two references on my branch, and then remembering to point them back before merging, because I don’t want branch references promoted to main. Pinning to tags or SHAs doesn’t remove that awkwardness. It just moves it somewhere else.

This is an area of the project I haven’t put much thought into solving, as the pain is bearable, but it’s one I’d like to improve. I’ve seen other projects have similar concerns, and one way they’ve resolved this is to have a “test” calling repo - which, in our case, would be a basic microsite - which is primarily used to test changes to called workflows.

Visibility and governance for platform teams

Everything so far has mostly been from the perspective of the person writing and maintaining the shared workflows. But once other teams depend on what you’ve built, a different set of questions comes up. Who’s actually using this workflow? Which version are they on? And if I need everyone to move to a newer version, how do I make that happen?

Who’s consuming your workflows?

This is where GitHub gives a platform team surprisingly little. There’s no view from a reusable workflow that shows which repositories call it, or which reference each of the callers is using. On GitHub Enterprise Cloud, which Octopus uses, you can query the audit log through the REST API to see workflow use, but it’s not the best user experience. Outside of that, the options are to search for code across your organization or to write your own script to crawl repositories and parse their workflow files.

When you put this in the context of a platform team with hundreds of repositories calling many workflows, the questions get harder to answer. Is anyone still on an old version? Has a security fix been picked up everywhere? You’d reasonably expect a platform to tell you, and today on GitHub you mostly have to go and find out yourself.

Steering consumers to a new version

Imagine you’ve published a change that every team needs to pick up, maybe a security fix or a new organizational requirement baked into the build. If consumers reference @main, they get it on their next run. If they’ve pinned to a tag or SHA, as GitHub recommends, it’s up to each of them to update.

GitHub does give administrators some control here, through the allowed actions and reusable workflows policy. Administrators can block a specific action or reusable workflow version by adding it to the policy with a ! prefix, and blocks take priority over anything the policy would otherwise allow. So an administrator can block an old version of a reusable workflow across the organization.

The catch is that it’s a hard stop. There’s no warning phase, no grace period with a “please update by the end of the month” message that teams can see but keep working. The next time a caller on the blocked version runs, it simply fails. That makes sense when you look at why the controls exist. GitHub introduced them to reduce the risk of compromised action repositories, secrets, and malicious tag updates. They’re supply chain security tools, and they do that job well. What they weren’t designed for is managing the lifecycle of your own internal workflows, like guiding teams from one version to the next over a few weeks.

Dependabot, as I covered earlier, helps from the other direction. It can raise pull requests in calling repositories when a new version is available, but it’s configured per repository, and the consumer still decides when to merge. Between the two, a platform team can nudge from the consumer’s side or block from the organization’s side, with not much in between.

Wrapping up

Moving to reusable workflows was one of the quicker wins of this project. Twenty workflow files became a handful of short calling workflows; implementing a change is now one pull request instead of five, and I can say with confidence that every microsite is built the same way. They do come with tradeoffs, though, and if you’re a platform team sharing workflows across many repositories, it’s worth deciding early how consumers should reference your workflows, how you’ll test changes before they land, and how you’ll know who’s using which version, because those answers are much easier to design in than to retrofit.

Happy deployments!

Continuous Delivery Office Hours Ep.12: The platform adoption shock

2026-10-27

In the previous episode, we covered organizational culture, including why posters aren’t the way to change culture, crucial theoretical foundations from Douglas McGregor and Ron Westrum, the impact of arbitrary deadlines, and why feedback keeps organizations healthy.

This episode examines Platform Engineering and the persistent debate between mandatory and optional adoption strategies. The episode was inspired by data from our Future of Platform Engineering report.

Watch the episode

You can watch the episode below, or read on to find some of the key discussion points.

Watch Continuous Delivery Office Hours Ep.12

The rise of mandatory platforms

Mandatory platforms have been an issue in the past, with platform producers and consumers diverging dramatically on whether a platform is successful. Part of the perception gap comes down to platform teams losing the adoption signal: if everyone must use the platform, you’ve lost a way to discover gaps and flaws in what you provide.

Since then, platforms have become broader. Platforms now have almost 6x as many features as they did when the perception gap was present. As platforms take on tasks that developers truly appreciate, like security and compliance, the gap between producers and consumers has closed.

You might think of this like the difference between being forced to use a bicycle to travel both before and after the invention of the bicycle saddle. Riders are far happier to be forced to cycle when they have a cushioned seat.

Alongside the dissipation of perceptual differences, it turns out mandatory platforms outperform optional platforms in terms of goal attainment. However, there are many factors contributing to platform success, like monitoring developer satisfaction and regularly eliciting feedback to help improve the platform.

The other factors of platform success have more impact, and you should still consider optional adoption, but combined with mandatory policies. That means development teams have to meet the same standards they would meet if they adopted the platform, which makes platform adoption more appealing and less likely to cause conflict or friction.

Not just more features, but the right ones

The most common number of features baked into a platform was four, but that has grown to 24. Platforms are getting broader, and these wider platforms are more successful than the tiny ones of the past. Despite this link between platform breadth and goal attainment, it’s important to bear in mind that the volume of features alone is not a sufficient strategy, and that choosing to solve the right problems is the path to success.

Maintaining regular contact with developers, lightly assessing their satisfaction with the platform, and dedicating time to conversations that shape your platform’s direction are all part of the high-performance platform playbook. The usefulness comes from solving the right problems, and you need to focus on developer needs to make the right choices.

Platform teams are rediscovering many of the capabilities of the State of DevOps research and its associated model, like Lean Product Management, which prove useful in building platforms as internal products.

The invisible platform dilemma

Unsurprisingly, platforms that meet more goals have higher budget safety. They are showing a return on investment, so they can be confident in maintaining their funding over the long run. Platforms that fail to meet their goals are more likely to have their budgets redirected to other initiatives.

Platform teams need to show the value back to the organization in terms the organization understands and for measures it cares about. With AI initiatives soaking up money, some organizations will start reallocating funds and focus, leaving platforms underfunded or dropped.

Some of the best platforms will be invisible in daily use because developers don’t have to keep interacting with them. These boring, invisible platforms are the most valuable, but the least visible. Providing metrics and proof of value for these platforms will keep them funded.

Happy deployments!

Continuous Delivery Office Hours is a series of conversations about software delivery, with Tony Kelly, Bob Walker, and Steve Fenton.

You can find more episodes on YouTube, Apple Podcasts, and Pocket Casts.

From features to solutions

2026-10-26

Octopus Deploy ships dozens of features that are each useful on their own. But the real power comes from combining them. In this post, I will walk through bringing together a collection of smaller, often overlooked features into a practical solution: automatically notifying the responsible team members whenever a deployment hits a manual intervention. It’s a real-world example of how thinking in solutions, not just features, can unlock more value from the tools you already have.

In an application deployment process, a manual intervention step can help provide a checkpoint for sign-offs, or allow validation of the state of the deployment before it is switched over to a live site. Unfortunately, by default, manual interventions only show up in the Octopus user interface, so they’re easy to overlook and can block deployments from completing.

Let’s walk through a few different ways that we can solve this using old and new features of Octopus:

Subscriptions
Slack notifications
Webhook triggered runbooks

Slack notifications

In 2026.3, we added the ability to connect your Octopus Deploy instance to a Slack Workspace. At the time of writing, only one workspace is supported for the whole instance. Configuration is quite straightforward, so I won’t even go into details on how to configure it, just follow your nose from Configuration > Settings > Slack Integration, and the Slack docs on Creating apps with an app manifest.

Once you have a Slack Workspace configured, you can use a subscription to notify your Slack channel of a pending Manual Intervention being created in the Space the subscription is in. Subscriptions also allow you to narrow the projects that this applies to.

There is a rough edge worth calling out here: subscriptions are per space and it would be nice to have consistent behavior across many or all spaces. That’s where you can use some automation to create the exact same subscription setup.

Use the Octopus Deploy Terraform provider to create all your subscriptions across the required spaces:

terraform {
  required_providers {
    octopusdeploy = {
      source = "OctopusDeploy/octopusdeploy"
      version = "1.18.0"
    }
  }
}

variable "space_ids" {
  type = list(string)
  default = ["Spaces-142", "Spaces-1"]
  description = "List of Space IDs to create subscriptions in"
}

# Provider without space_id - space set per-resource
provider "octopusdeploy" {
  address = "https://example.octopus.app"
  api_key = "API-APIKEY12345"
}

resource "octopusdeploy_subscription" "per_space" {
  for_each = toset(var.space_ids)
  name = "Manual Intervention To Slack"
  space_id = each.value
  is_disabled = false

  event_notification_subscription = {
    # the id of your target channel
    slack_channel_ids = ["C0BG25D5DQV"]

    # the name of the channel, only required for display purposes
    slack_channel_names = ["manual-interventions"]

    # notify every minute
    slack_frequency_period = "00:01:00"

    filter = {
      event_categories = ["Created"]
      document_types = ["Interruptions"]
    }
  }
}

With this subscription in place, the #manual-interventions channel in your Slack workspace will receive a generic message with a link to the audit page in the Octopus instance.

Slack and email communications from a subscription will always be a batch of events covering the subscription frequency, and pressing the View all in Octopus button will take you to the audit page.

This works, but we can probably make it better.

Webhooks and runbooks

Another new feature available in 2026.3 is the ability to trigger a runbook from a webhook call. Octopus supports being both the webhook provider as well as a consumer for the purposes of executing a runbook via the Runbook Webhook Trigger.

In previous versions, if you wanted to take any action based on an event within Octopus you had two options: polling the event API, which can be expensive and requires somewhere to run the polling code, or standing up a webhook receiver either as a custom function/lambda or using an external SaaS service such as Zapier or Workato. Webhook Triggers let you use a runbook process as the execution location.

Let’s swap out the default behavior from the subscription’s Slack notification and provide our own custom message format that will notify the responsible users.

The attention-seeking project

The project that I am using as an example is very straightforward: it deploys to a staging deployment slot in Azure, uses a Manual Intervention step to get a human check, and performs the slot swap after it has been reviewed.

To build out this solution, I am going to touch on a number of Octopus features, some only made available recently in 2026.3, and others have been around for much longer:

Webhook triggers to Runbooks NEW
Slack integration and a built-in Slack step NEW
JSON path variables
Variable filter syntax
Octopus CLI
Read-only roles
Output variables
OIDC auth to Octopus with service accounts
Generic OIDC accounts
Library Variable Sets
Execution containers
Variable testing

Wiring up the webhook

The first thing we are going to need is a new runbook to receive the webhook trigger payload and a webhook trigger.

The trigger requires either a shared secret, supplied in the header X-Octopus-Webhook-Secret, or an API key, supplied in the header X-Octopus-ApiKey for an account that has permission to run the runbook. If you would prefer to have the executions tied to a specific account, for auditing purposes for example, use an API key.

Next, configure a subscription, or reuse the one we created earlier. You will need the endpoint URL for the trigger and the header and value to authenticate the webhook call.

In my case, I have opted for a shared secret:

Shape of the event payload

When a subscription fires a webhook, you get a pretty generous chunk of JSON. Here’s the shape of it, trimmed down to the bits we actually care about.

{
    "Timestamp": "2026-08-24T06:43:12.310+00:00",
    "EventType": "SubscriptionPayload",
    "Payload": {
        "ServerUri": "https://my.octopus.app",
        "ServerAuditUri": "https://my.octopus.app/app#/Spaces-142/configuration/audit?...",
        "Subscription": { ... },
        "Event": {
            "Id": "Events-772873",
            "RelatedDocumentIds": ["Interruptions-43"],
            "Category": "Created",
            "Message": "Interruption Check staging deployment was created",
            "ChangeDetails": {
                "DocumentContext": {
                    "Id": "Interruptions-43",
                    "Title": "Check staging deployment",
                    "Type": "ManualIntervention",
                    "Status": "Pending",
                    "RelatedDocumentIds": [
                        "Deployments-53208",
                        "ServerTasks-805184",
                        "Projects-941",
                        "Environments-423"
                    ],
                    "ResponsibleTeamIds": ["Teams-202"],
                    "SpaceId": "Spaces-142",
                    "ProjectId": "Projects-941",
                    "EnvironmentId": "Environments-423"
                }
            },
            "SpaceId": "Spaces-142"
        },
        "BatchId": "a634600f-0cd0-43f6-9412-14bb1a072fcd",
        "TotalEventsInBatch": 1,
        "EventNumberInBatch": 1
    }
}

The event details that we need are buried in Payload.Event.ChangeDetails.DocumentContext - that’s where we find the responsible team IDs, the related document IDs (handy for working out if this was a deployment or a runbook run), and the server task ID for linking people back to the Octopus web UI.

Note: The DocumentContext part shown here is specific to a Manual Intervention event. Other event types will have a different data shape.

The supporting cast

Before we get to the runbook itself, there are a few pieces of configuration that make the whole thing work.

Teams and users

The manual intervention step in our deployment process is configured with a responsible team, creatively named Manual Intervention. This team has all the people who can approve or reject the intervention: Annie Developer, Bob Tester, and yours truly. Crucially, these team IDs come through in the webhook event payload - that’s how our runbook figures out who to notify on Slack.

We also need a service account, readonly-svc, so the runbook can talk back to the Octopus API and look up who’s actually in those teams. This account lives in a new team called Read-only with only the Read only role assigned to it. The Read only built-in role is another feature added in 2026.3 to support read-only API keys and AI agents.

Generic OIDC account

Now here’s where it gets a little bit Inception-like: we need Octopus to authenticate with… itself.

Rather than stashing an API key somewhere (which always feels a bit icky), I’m using a Generic OIDC Account called “Octopus Loopback”. During the runbook run, the service account gets an OIDC token issued to it, and we use that to authenticate the CLI right back to the same instance.

There are two parts to set up.

Add an OIDC identity to the service account

On the readonly-svc account created earlier, add an OIDC identity with these settings:
- Issuer type: Other Issuer
- Issuer: the public HTTPS URL of your Octopus instance
- Subject: space:<space-slug>:runbook:<runbook-slug>
Slugs start out as the lowercase resource name with spaces replaced by hyphens. Renaming a resource doesn’t update its slug, so check the current value rather than working it out from the name.

Once it’s saved, take note of the audience shown on the OIDC identity. This is the service account’s ID, and it’s what the CLI needs to log in.
Create the Generic OIDC account

Create a new Generic OIDC account called “Octopus Loopback” with these settings:
- Deployments & Runbooks subject claim: Space and Runbook
- Audience: the audience value from the OIDC identity
The script uses Octopus.Web.ServerUri to log in and to build the link in the Slack message. Octopus Cloud always sets this. On a self-hosted instance, check that Configuration > Settings > Web Portal has an HTTPS server URI that’s accessible from the worker where the runbook runs, otherwise, the CLI login will fail.

Slack user mapping

We need a way to go from “Octopus user” to “Slack user” so we can @mention the right people. A library variable set called Slack Users does the trick - the variable names are email addresses and the values are Slack user IDs:

Variable Name (Email)	Value (Slack User ID)
`ben.pearce@octopus.com`	`U7PE3KF16`
`annie.developer@example.com`	`U0BT5BU5GS0`
`bob.tester@example.com`	`U0BT1LU7W5Q`

The script in the runbook will find each user’s email and then try to find a Slack User ID to add to the message, failing that it will just use the Display Name.

Project variables for extracting details

When the webhook trigger is fired, the request payload is available via the built-in variable Octopus.WebhookTrigger.RequestBody. From there, it’s a matter of fishing out what we need using JSON path notation and a sprinkle of Octostache filter syntax:

Variable	Value
`Event`	`#{Octopus.WebhookTrigger.RequestBody.Payload.Event}`
`SpaceId`	`#{Event.SpaceId}`
`DocumentContext`	`#{Event.ChangeDetails.DocumentContext}`
`ResponsibleTeams`	`#{DocumentContext.ResponsibleTeamIds}`
`RelatedDocumentIds`	`#{DocumentContext.RelatedDocumentIds}`
`DeploymentId`	`#{each item in RelatedDocumentIds}#{if item \| StartsWith Deployments-}#{item}#{/if}#{/each}`
`RunbookRunId`	`#{each item in RelatedDocumentIds}#{if item \| StartsWith RunbookRuns-}#{item}#{/if}#{/each}`
`ProjectId`	`#{each item in RelatedDocumentIds}#{if item \| StartsWith Projects-}#{item}#{/if}#{/each}`
`EnvironmentId`	`#{each item in RelatedDocumentIds}#{if item \| StartsWith Environments-}#{item}#{/if}#{/each}`
`ServerTaskId`	`#{each item in RelatedDocumentIds}#{if item \| StartsWith ServerTasks-}#{item}#{/if}#{/each}`
`IsDeployment`	`#{if DeploymentId}true#{else}false#{/if}`
`IsRunbook`	`#{if RunbookRunId}true#{else}false#{/if}`
`OctopusAccount`	Octopus Loopback (Generic OIDC Account type)

Those JSON paths are a mouthful! The DeploymentId and RunbookRunId variables are doing the heavy lifting - they loop over RelatedDocumentIds and use the StartsWith filter to sniff out whether this interruption came from a deployment or a runbook run. This lets the Slack message include the right context so people know what they’re clicking into.

If your project has a deployment process or other runbooks, each of these variables can be scoped to the runbook.

Runbook process

The runbook itself is fairly simple - just two real steps:

Step 1: Get Details - A script step that uses the Octopus CLI, authenticates back to the instance using our loopback account, and starts rummaging through team membership. For each responsible team, it grabs the members, looks up their Slack IDs, and stitches together the notification message. The result gets stashed as an output variable. See the Getting the Octopus CLI on the worker section to ensure the CLI is available for this step.

Step 2: Send a Slack Message - The built-in Slack step picks up the message via #{Octopus.Action[Get Details].Output.Message} and fires it off to the channel. No fuss, no custom integrations, just a step that does exactly what it says on the tin.

Bash

Introducing the pipeline explorer

2026-10-23

The first time you open an unfamiliar Octopus project (inheriting it, joining a new team, or exploring a corner of your own instance you haven’t touched before), you’re looking at someone else’s decisions with none of the context that went into making them. Real projects pick up channels, triggers, approvals, and a growing list of targets over time.

The pipeline explorer brings a project’s configuration together in one place. It helps you understand how an Octopus project works, on one page.

It’s built for anyone who’s new to a project: joining a team, inheriting ownership, or exploring an unfamiliar corner of their own instance.

It visualizes your deployment pipeline and deployment process as workflow diagrams, showing you how a release gets triggered and how it moves through your environments depending on the channel.

What the pipeline explorer does

1. Pipeline visualization

The pipeline explorer presents your project’s deployment pipeline and deployment process as workflow diagrams. Seeing them visually lets you understand how a release is triggered and how it moves through your environments, without piecing that together from separate tabs.

2. Process visualization

A project’s deployment process depends on settings that live outside its process, like lifecycles, deployment targets, credentials, and approvals. The pipeline explorer surfaces these connections directly, so you don’t need to already know where each one lives.

3. Configuration issues

The pipeline explorer flags conditions that could affect an upcoming deployment directly in the view where you’re already looking.

What it doesn’t do

The pipeline explorer doesn’t replace your existing process, variables, or settings pages. It’s a new view built on top of the same data, not a redesign of how you configure a project. Think of it as a project map.

Try it

Open any project and select Pipeline explorer from the navigation to see it for yourself. Next time you visit an unfamiliar project, this is where you’ll want to start.

Read the docs for more details.

Happy deployments!

Multi-node support for Polling Tentacles

2026-10-21

Polling Tentacles no longer need to poll every Octopus Server node in a self-hosted High Availability (HA) cluster. In the next GA release of 2026.4, Polling Tentacles can poll a single address instead.

Polling Tentacles connect out to Octopus Server, so you don’t need to open inbound firewall ports to reach them like you do for Listening Tentacles. That keeps your architecture simpler and more secure. However, if you run Octopus Server across multiple nodes and use Polling Tentacles, every Tentacle has to know about every node. Add a node, and you need to update every Tentacle. Remove a node, and you need to update them all again. With hundreds or thousands of Tentacles, that’s a lot of work just to resize your cluster.

Multi-node support for Polling Tentacles removes that restriction.

Why every Tentacle had to poll every node

A Polling Tentacle connects to Octopus Server and asks, “Do you have any work for me?”

In an HA cluster, any node can pick up a task. When a node runs a deployment that needs a Polling Tentacle, that node holds the work for that Tentacle. The Tentacle must poll that specific node to collect the work.

If the Tentacle is polling a different node, it never sees the work, and the deployment times out.

That’s why the guidance for Polling Tentacles with HA has previously been to configure each Tentacle to poll every HA node.

This would also prevent the use of a load balancer with Polling Tentacles. The load balancer could send the Tentacle to any node, which might not be the one holding its work.

What changed in Octopus Server 2026.4.6909

With multi-node support for Polling Tentacles, the nodes share a single queue of pending requests. The queue lives in Redis, a shared in-memory data store.

When a node needs a Polling Tentacle to perform an action, it puts the request in Redis. When the Tentacle polls a node for work, that node collects the Tentacle’s next request from Redis. The Tentacle’s response goes back through Redis to the node that originally queued the work.

Thus, it no longer matters which node a Tentacle connects to. Each Tentacle only needs to poll one address, and that address can be a load balancer that spreads Tentacles across all the nodes.

This feature has been in use in Octopus Cloud for some time. We’re now making it available for self-hosted customers.

A few details are worth knowing:

Octopus encrypts messages with your Master Key before storing them in Redis.
To keep Redis memory usage low, Octopus writes larger files, such as packages, to the cluster shared directory so every node can read them.
A Tentacle’s Connectivity page now shows communication logs from every active node, not just the node your browser is connected to.
This change doesn’t affect Listening Tentacles, which Octopus Server connects to directly.

What you need

To use multi-node support for Polling Tentacles, you need:

Octopus Server 2026.4.6909 or later installed on every node in the HA cluster
A Redis instance that every node can reach, set up as a short-lived queue rather than a database
A cluster shared directory that every node can read and write
A TCP load balancer (optional) in front of the Polling Tentacle port, so your Tentacles only need one address

To get early access before 2026.4 ships, contact support.

Getting started

You enable multi-node support for Polling Tentacles by giving each node the same Redis connection string. You can do this from the command line, with an environment variable in the Linux container, or with the Octopus Deploy Helm chart. The Helm chart can also run Redis and create the load balancer for you.

Once multi-node support for Polling Tentacles is turned on, you can configure Polling Tentacles to connect to one node, all nodes, or anything in between. You don’t have to reconfigure Tentacles straight away, and you can point your Tentacles at a load balancer at your own pace.

The docs for multi-node support for Polling Tentacles walk you through each step.

Conclusion

Now you can add or remove nodes in your HA cluster without reconfiguring every Tentacle.

If you’re thinking about moving to HA in the first place, read how one customer migrated to High Availability one safe step at a time.

Happy deployments!

Apache Ant Deployments with Octopus

2026-10-20

Apache Ant is a Java-based build tool that has been around for over 20 years. Despite its age, Ant is still actively developed and used in many enterprise deployments. Octopus can be used to deploy Ant applications with a few simple steps. This post will demonstrate how to deploy a sample Ant application using Octopus.

Prerequisites

Download the sample application from this GitHub repository. The releases provide ZIP files that can be uploaded to the Octopus built-in feed:

Preparing the Ant tooling

Ant was first released in 2000 and predates many popular DevOps tools like Docker by many years. While execution containers are a great solution for exposing Ant and its dependencies to your Octopus workers, we’ll make the assumption here that teams using Ant may not have implemented Docker in their deployment workflows.

Instead, Ant and its dependencies will be exposed to the Octopus workers by extracting portable versions of Ant and Java into the working directory as a step is executed.

Start by downloading a binary distribution of Ant from the Apache Ant website. At the time of writing, the file you will download is called apache-ant-1.10.18-bin.zip.

Octopus requires a strict filename structure for packages uploaded to the built-in feed. The filename must be in the format <package-name>.<version>.<extension>. For example, apache-ant.1.10.18.zip. So rename the file you downloaded to apache-ant.1.10.18.zip before uploading it to the built-in feed.

Ant requires a JDK to run. There are many JDK distributions available, but for this example, we’ll use the Azul Zulu OpenJDK distribution. We’ll assume that the workers are running Windows, so download the ZIP distribution of the JDK. At the time of writing, the file you will download is called zulu27.28.101-ca-jdk27.0.0-win_x64.zip. Rename the file to zulu27.28.101.zip before uploading it to the built-in feed.

You must now have 3 packages in the built-in feed:

Running Ant in a deployment step

Ant is run as part of a script step in an Octopus deployment. The script step will extract the Ant and JDK packages into the working directory, set the JAVA_HOME environment variable, and append both Ant and Java to the session Path variable. This allows Ant to be executed on a worker without requiring any installation of Ant or Java on the worker itself:

# 1. Define explicit working directories
# Note that the Ant and JDK packages include their own versioned subfolders, so we need to include those in the path.
# The versioned subfolders are unique to the package version, so if you update the package version, you'll need to update the path here as well.
$workDir   = Get-Location
$antBinDir = "$workDir\apache-ant\apache-ant-1.10.18\bin"
$javaDir   = "$workDir\zulu\zulu27.28.101-ca-jdk27.0.0-win_x64"

# 2. Set JAVA_HOME and explicitly append BOTH Java and Ant to the session Path
$env:JAVA_HOME = $javaDir
$env:Path = "$antBinDir;$javaDir\bin;" + $env:Path

# 3. Verify the binary actually exists where we expect it
if (-not (Test-Path "$antBinDir\ant.bat")) {
    Write-Error "Could not find ant.bat at: $antBinDir"
    Exit 1
}

# 4. Change directory to your app folder
cd antdemo

# 5. Run Ant using the call operator (&) to force PowerShell to resolve the executable path
& ant.bat compile
& ant.bat jar
& ant.bat run

The three packages (the Ant Demo application, the Ant binary distribution, and the JDK) are included as Referenced Dependencies. This ensures the packages are downloaded and extracted into the step’s working directory:

Running the deployment

At this point, you can create a release of the project and deploy it to an environment. The deployment log will show the output of the Ant commands as they are executed:

Conclusion

Executing Ant as part of an Octopus deployment is straightforward. By using the built-in feed to provide Ant and its dependencies, you can run Ant on any worker without requiring any installation of Ant or Java on the worker itself. This approach allows teams to deploy Ant applications consistently and repeatably by leveraging Octopus Deploy.

Continuous Delivery Office Hours Ep.11: Haute culture

2026-10-20

In the previous episode, we discussed modernizing legacy architecture, including the hazards of the rewrite, architectural strategies, and team design considerations.

This episode looks at “haute culture”, or high-performance organizational culture, and its profound impact on software delivery.

Watch the episode

You can watch the episode below, or read on to find some of the key discussion points.

Watch Continuous Delivery Office Hours Ep.11

Posters aren’t culture

Everyone has worked for an organization that attempted to define their identity through poster campaigns, entrance halls decorated with inspirational quotes or word clouds, and mugs adorned with the “five pillars of our culture”.

I worked for an organization that launched the RON campaign. Do it “right”, do it “once”, do it “now”. Of course, none of these happened, as the slogans bore no relation to the reality of the work.

In too many cases, there’s a systematic gap between the organization’s aspirational, publicly stated culture and employees’ lived experience. In fact, when an organization is dysfunctional, the list of values becomes an admission of exactly what is missing: “We value trust, respect, and work-life balance” means you’ll be micromanaged, treated like a child, and made to work long hours.

Meanwhile, the real culture is built from tiny interactions that reinforce what leaders value and what they don’t.

Every tiny interaction reinforces the real culture. The way your boss talks to you, whether they listen to your opinions, and how they respond when you flag a potential problem all set the scene for culture. Even when interactions aren’t aggressive, they can still stifle the crucial component of a healthy culture: information flow.

Here’s an example. You go to your boss and say, “Our test automation is missing a few really crucial areas that could cause us a problem in the future.” Your boss responds by tasking you with filling that gap. While you’re pleased to have permission to fix this, you now have a bunch of more work to juggle, and maybe it would have been better not to say anything.

As soon as people hesitate to share potential problems, you switch from fixing things before they go wrong to firefighting afterward.

Theoretical foundations

High-performing software teams understand the old models of organizational sociology. They understand Douglas McGregor’s principles of human motivation (from The Human Side of Enterprise, though more often encountered in Dan Pink’s book, Drive), and they understand Ron Westrum’s Typology of Organizational Culture.

You can use these models to shift focus to the structural mechanics of workplace culture, and retire the posters, mugs, and mousepads.

McGregor challenged the view of traditional management, which uses rewards and punishment as the tools of motivation. Instead, McGregor asserted that individuals want to do good work and are more satisfied when they deliver quality outcomes, which means they don’t need to be cajoled by management.

The perfect complement to McGregor’s views on motivation is the three categories of culture shared by Ron Westrum:

Pathological: A culture with high anxiety, information hoarding, and strict power hierarchies. Messengers are punished or otherwise discouraged from sharing uncomfortable truths.
Bureaucratic: These organizations have rigid channels, compartmentalization, and protocols, so information moves slowly along inflexible routes.
Generative: The ideal culture has optimal information flow and cross-functional collaboration. Everyone is encouraged to share risks early, without fear of repercussions.

Information flow is the signal of organizational health, with generative environments actively protecting “messengers”; people who flag potential risks and issues. This helps identify problems early and resolve them before they cause damage. Conversely, pathological leaders destroy information flow through intimidation, like an executive engaging in silent staring contests when they are told a date can’t be met unless scope is changed. This coercive dynamic works its way down the hierarchy, becoming the default mode of operation for managers and supervisors.

Suppressing information flow doesn’t change reality. Dates are missed, software ships with known faults, and the fundamentals of physics still apply. The only difference is the realization comes far later, often when it’s too late to prevent damage.

Bad news is crucial operational data, not the result of difficult or negative employees. A leader’s response to this information should be: “Thank you for bringing this up, because sharing this information will help us stop this from becoming a major mistake.”

Fixed scope and arbitrary deadlines

There’s a classic iron triangle in project management that says quality is constrained by three variables: scope, time, and cost, and you can pick any two. This idea presents a neat view of a classic problem in software engineering: the notion that fixing time, cost, and scope doesn’t work.

The reality is a little different from this picture, which leads many project managers to believe you can trade quality for reduced time and cost. The failure demand that results increases future costs and time, so it doesn’t work as a medium- or long-term strategy. Many teams have fallen into the trap of rushing to meet an arbitrary deadline, resulting in a flood of bugs and rework, which increases pressure on the next set of tasks. This cycle is destructive if repeated.

The mismanagement of software tasks, particularly the use of project management approaches designed to cajole teams into unreasonable delivery expectations, inevitably leads to reduced information flow. Project managers share the plan is at risk and are ordered to “make it happen”; developers flag that some work items won’t be completed on time and are told: “well, they have to be.” Eventually, nobody shares these risks, but they happen all the same.

Traditional project management techniques were created to surface the reality of a project, but were used in attempts to force impossible realities. Instead of being cartographers, diligently mapping the territory they explored, project managers believed they could draw the map first, then change millions of hectares of land to match what they imagined.

Feedback is oxygen

Our founder, Paul Stovell, said this to me: “Feedback is oxygen.” That’s true when you’re developing software and need to know whether what you’re building helps users achieve their goals. It’s true throughout the process, whether that’s feedback from linters, tests, security scans, or employees who have spotted trouble ahead.

While it’s true that a healthy generative culture is better for workers, it’s also better for the organization. When information flows, everyone gets better results. Even your CFO.

Happy deployments!

Continuous Delivery Office Hours is a series of conversations about software delivery, with Tony Kelly, Bob Walker, and Steve Fenton.

You can find more episodes on YouTube, Apple Podcasts, and Pocket Casts.

Controlled Delivery: A Strong Opinion

2026-10-19

Sometimes it feels like there are as many modifiers on “Delivery” as there are on a fancy coffee order, and why do they all have to start with C?

I’m here to add another to the list.

What is Controlled Delivery?

Controlled Delivery is the set of practices that ensure you’re delivering valuable changes to software behavior, not just detonating a change across an entire ecosystem. The goal of controlled delivery is to get the value of a change to the person who benefits from it. This is not about the change itself, because sometimes a change is not the point. Thinking of change as value is a mistake we all make, because that’s what we’re evaluated on, but it’s not what matters to the user.

Here are the things that we think make up Controlled Delivery

Composable content

Software isn’t a one-way flow from the maker to the user, it’s a collaborative work object, and it’s only a small part of the user’s day. As software makers, we need to give users the option to choose the parts that add value to their day and leave aside the parts that they neither need nor want. That means that our concepts of modularity and microservices can’t stay locked inside our own architecture, they have to be obvious and manipulable to the user. That’s why APIs, and now MCPs, are such a powerful concept.

From a sales and adoption perspective, of course it would be great if people used all our features all the time, but that’s not very realistic. I’d bet that you’re using less than 20% of the available features in your daily software, and still getting good value from it. And probably, you’d have an easier time using it if there were fewer options available.

Composable content is what Jordan Mallory is asking for in this 2020 post.

Big video games require a lot of expensive hardware to run them, and dedicated time to play them. Stardew Valley was a hugely successful game with objectively rudimentary graphics and skills requirements, exactly because anyone could get rewarding play out of it, even on an old cell phone.

If you’re reading articles about CI/CD, you’re probably not One Guy (™) working at a table in the corner of your bedroom, but the point remains - the value is not in what you deliver, but in what the user can do.

Mindful rollout

Change, especially rapid change, is hard for people to deal with. Alvin Toffler wrote Future Shock in 1965-1970, and it was about how much people were struggling to adapt to the rate of change they were facing. That problem is not, I’m sure you’ve noticed, going away.

That means that whenever we deliver software to our users, we’re asking them to accept change, which they don’t like. We owe it to them to make sure it’s a change that benefits them, and that it’s a good delivery.

We have a lot of very good evidence that deploying rapidly/continuously makes software development safer and more robust. Let’s keep doing that. But as a user, I would much rather have all those changes packaged up into a coherent and periodic bundle, so I only have to get my process disrupted once in a while.

How do we make sure what we’re sending out is good? We want our product to be

Safe
Compliant
Robust
Valuable

It needs to not create new problems, it needs to fit in with the existing software, it needs to operate at the scales it will face, and it needs to be a net addition to their workflow.

We use feature flags in a variety of patterns to accomplish these goals.

To make it safe, we do staged rollout or ring deployment to test on subsets of users before we push it to everyone. We also include an andon cord in case a deployment should be stopped and rolled forward.
To make it compliant, we make sure our deployment tests include legacy users and people on old hardware, as well as early adopters
To make it robust, we run shadow versions in parallel with the visible versions and blue/green overlaps
To make it valuable, we collect feedback on who uses new features, and communicate directly with them on how it works and what they need.

Many of the tools of mindful rollout already exist and are being used for load evaluation, user entitlements, or A/B testing. What makes it truly mindful rollout is that the people doing the deployment are actively monitoring and watching the changes - not just to preserve operational stability, but to understand how and why people are using the changes.

Verifiable receipt

Everything that is deployed goes through the same deterministic steps, and is recorded and hashed. That means that every change has a signature that can be traced and affirmed. That signature carries through from the initial developer change to the release on the user’s machine. No surprises, no flex. Controlled Delivery has to include knowing what actually arrived, as well as what we intended to arrive.

What isn’t Controlled Delivery?

Controlled Delivery isn’t a compliance system in itself, although it helps you do compliance. Controlled Delivery is not an unwatched automation. Controlled Delivery is not an excuse to deploy all the time.

Controlled Delivery isn’t about the software creator’s experience, it’s about the software user’s experience.

How does that fit into CI/CD?

I know a bunch of you just flinched at the thought of having to do yet another process in your SDLC. Especially one that doesn’t have a track record of success or a cool conference talk (yet). But this is actually built out of parts you probably already have, just used in a different way. Ring deployment, trunk-based development, feature flags, signed changes, those are all mature technologies with over a decade of best practices behind them. When we say Controlled Delivery, we’re inviting you to combine them in a way that works for both you and your users.

What’s my action item?

First, decide if Controlled Delivery will help you deliver your software better and more effectively. If it doesn’t meet your goals, it’s not a good tool, no matter how nifty it seems.

Then survey your SDLC and see how many of these patterns you already have in place. What can you chain together to make a continuous, predictable, sensible flow from code change to user value? What runbooks, approval gates, automations, and release rituals already exist, and could they be incorporated into Controlled Delivery?

Finally, build or buy the parts you’re missing. I can’t tell you how that tradeoff will break down. Things you build are perfectly tuned for your current processes and people, but you’ll have to maintain and update them internally forever. Things you buy will require integration and adaptation, but will be maintained by the vendor.

Controlled Delivery is part of the seamless software motion we’ve all been working toward, and I hope you see the foundations in your own work.

From copy-paste to platform thinking

2026-10-15

At Octopus Deploy, we maintain a collection of static websites we call microsites. They host public-facing content like our product documentation, our external handbook, and the blog you’re reading this article on. Contributors come from across the organization, including support, engineering, product, marketing, and our people team.

Each microsite is built on the Astro framework and lives in its own GitHub repository. For years, they were built, tested, and deployed using GitHub Actions and Octopus Deploy. The setup worked, but over time, the gap between “it works” and “it’s working well” kept growing, especially when we stepped back to consider what great software delivery looks like today.

We continuously release functionality in Octopus to help teams improve software delivery, and we wanted to bring those improvements to our microsites. Eating your own dog food and all that! We also knew the build had friction, and there were parts of GitHub Actions we wanted to improve. What started as “let’s enable ephemeral environments for the microsites” became a series of adjustments to our deployment pipeline.

They were all for the better, but along the way, we hit paper cuts, had fascinating discussions, and faced decisions that seemed simple on the surface yet quickly made us think differently on topics like where the platform team’s responsibility ends and the application team’s begins, how opinionated a shared process should be, and how much flexibility is too much.

This article anchors a series of posts that go deeper into specific pipeline improvements. Here, I want to set the scene, while the pieces that follow get into the technical detail, the decisions we made, and the rough edges we hit along the way.

Crucially, while I’ll be using our microsites to tell the story, the patterns and considerations apply well beyond static sites, and they surfaced when I worked with customers building and delivering software. If you’ve ever tried to standardize processes across multiple teams, manage shared delivery infrastructure, or define the right lines of ownership, this will likely feel familiar.

The way things were

None of what I’m about to describe was a crisis. The microsites were online, content was being published, builds and releases were functioning, and things were fine on the surface. But fine has a way of masking friction, and friction has a way of compounding in the background until someone decides to act. What started with “let’s enable ephemeral environments on the microsites” led us to look more broadly at how we build and deploy changes, and that surfaced several areas we felt could be improved.

I want to give you a peek behind the curtain at what things looked like before we started. I’m not going to cover every paper cut and rough edge here, as those get their own dedicated articles. But I want you to see that, on their own, none of these things were really that big of a deal. It was only when we stepped back and looked at the delivery cycle holistically that the case for change became clear.

The copy-paste loop

Each microsite lived in its own GitHub repository, and each repository had its own set of GitHub Actions workflows to build, test, and validate changes. We had four core GitHub Actions workflows, which at a high level achieved the following tasks:

Spellcheck (branch)
Markdown linting (branch)
Build, test, package, push the package to Octopus, and trigger the release (branch)
Build, test, package, push the package to Octopus, and trigger the release (main)

Four workflows per repo across five repos meant 20 workflow files in total. Any future microsites would only make it worse, as another repo meant another set of workflow copies to maintain. And this was just for the CI side. The idea behind this was that if a change was made to one of these workflows, it would be abstract enough to be easily copied and pasted into the same workflow file in the other microsite repositories. This pattern will be familiar to many software teams. A build process works well for a particular technology stack, so when the next application comes along using the same stack, an engineer copies the working example as a starting point. It’s pragmatic, it’s fast, and on day one, it makes complete sense.

The problem with copy-paste, even if you’re copying from a template file, is that it’s a snapshot from a point in time, not an ongoing linked relationship. The moment you paste something into a second place, you have two things to maintain instead of one. Over time, changes are made in one repo but not in the others, sometimes intentionally, sometimes not. A node version gets bumped in one workflow and forgotten in another. Someone tweaks a step while testing something and doesn’t propagate it across. Another engineer just isn’t aware of all the different applications using the same workflow, and before long, five repos that were supposed to be identical have drifted apart, and nobody has a clear picture of which one is the source of truth.

The same pattern played out for deployments. Each microsite had its own project and deployment process, defined in Octopus Configuration Language (OCL) and stored in the repository. This is great, as the deployment process is stored in code alongside the application, and benefits from all the great things we’ve defined as an industry by putting configuration in version control. For the microsites, the deployment process was identical across all five sites. Or at least it was supposed to be. Making a change meant updating one project, verifying it worked, and then manually propagating the change to the other four projects. In practice, this meant five pull requests, five reviews, and five merges.

Even though we designed variables and the deployment process to be project-agnostic, the overhead of something as small as changing the format of a Slack notification message is hard to justify and only gets worse at scale. When the overhead of making a change is too high, people stop making them. Over time, that means fewer improvements, and fewer improvements mean everything starts to feel slow and heavy. The pipeline becomes something people work around rather than something they invest in.

The deeper problem is the drift. Copy-paste gives you the illusion of consistency without the guarantee of it. It is very easy for a human to forget to update one of the files or test a change against one of the sites, and then completely forget to update the other sites. From a Platform Engineering and compliance perspective, saying “this is how we build and deploy” with confidence when operating this way is impossible.

Deployment times that test our patience

Deploying a microsite should be straightforward. At the end of the day, it is a static website; it’s not as complex as much of today’s software development and architecture. Build the site, push the files to the destination, clear the cache if needed, and send a notification. In practice, a full deployment of one of our larger microsites, like the blog or docs, would take more than 40 minutes.

The culprit was the way files were transferred to S3. The step responsible for the upload compares each file in the source against the existing files in the destination before deciding whether to copy it. For a site with thousands of images, each generating multiple derivative files during the build, the comparison loop took too long.

Alternatives were explored briefly. SFTP was considered, and questions were raised about whether the upload step could be improved or replaced with a more efficient alternative. While the answer to that was almost certainly “yes,” the deployment was working; it wasn’t a priority to dig into further, and the impression at the time was “that’s how S3 works.” When something is functioning well enough, and the path to a better solution isn’t obvious, a targeted workaround tends to win.

That workaround was a new function in the build - allow me to introduce pnpm thin. Rather than deploying the full site on every run, pnpm thin stripped out any image assets that hadn’t been modified in the last 14 days. Running pnpm thin was added to the build process (well, all 5 copies of the build processes!), and fewer files meant fewer comparisons, which brought deployment times down to around 10 minutes.

An issue with pnpm thin was the assumption it came with. It assumed the destination already contained all the images stripped during the build. For an incremental deployment to a long-running production environment, that assumption was fine. For a fresh deployment to a brand new environment, like an ephemeral environment spun up for a pull request, it wasn’t. Most of the site’s images would simply be missing.

It’s a good example of how workarounds can quietly constrain future decisions. The pnpm thin function solved the immediate problem, but it made a full, clean deployment effectively impossible without first understanding why half the images weren’t showing up.

The fading static staging environment

Each microsite had two static environments that Octopus deployed to - staging and production. Early on, staging was a genuine part of the process, proposed changes were deployed to the staging environment, and people relied on it. But over time, use faded, and the reasons why are worth understanding because they’re not unique to our microsites.

Two things eroded it. The first was contention. When someone needed to do more thorough testing, they’d ask others not to overwrite the staging environment while they worked. I’m sure you’ve seen similar messages bounce around your Slack or Teams channels:

Please don’t use the staging environment today, I’m testing out some changes I’ve been working on. Thanks heaps!

It seems like a reasonable request, but realistically, it meant everyone else had to find another way to check their changes. Local previews filled that gap, and once people found a faster workaround that didn’t require coordinating with anyone, they stuck with it. Interestingly, relying on running the sites locally introduces other pain points, which I’ll touch on below when discussing how to preview changes.

This also meant that, as someone who wanted to deploy your change to the staging environment, you felt like you had to ask around first to see if you were about to interrupt someone else. Messages like “Anyone in the blog staging environment at the moment?” weren’t unusual to see flying around Slack, though admittedly, those were more pleasant than seeing the “Who just overwrote my deployment in the blog staging environment!?” messages! Add in a globally distributed team and the friction that is time zones to the equation, and you’re in for a world of hurt.

The second was the feedback loop. Build times already stretched to around 10 minutes. A deployment to staging added more to that. When you can verify something locally in a few seconds, waiting 20 or more minutes for a staging deployment is hard to justify, especially for a content change where the diff is right there in the GitHub UI.

Delayed feedback loops are the conditions in which workarounds grow. The longer you wait for a build, a deployment, or a shared environment to free up, the more attractive any shortcut becomes. It’s a rational response to friction, and once the shortcut becomes the default, the original agreed and documented process falls out of the team’s workflow.

By the time we looked at this properly, most contributors were testing locally if they checked at all, and reviewers were reading diffs in GitHub’s portal rather than seeing changes live. The first time many changes were seen in a real hosted environment was in production.

The effort to preview changes

The staging situation pointed to a broader gap. Unless the static staging environment was used, there was no easy way for a contributor to share a live, hosted version of their change with someone else. No way for a reviewer to click a link and see the proposed change running in a real environment. To do it in staging meant:

Knowing you were all clear to use the staging environment without annoying someone else who may be testing/reviewing their change
Knowing which Octopus Deploy instance and project to go to
Having access to the target project in Octopus Deploy
Knowing how to perform a deployment to the staging environment
Knowing the URL for the staging environment to share with others

Technical contributors would often just run the site locally on their machine. Clone the repo, install dependencies, run pnpm dev, and open localhost. It’s not onerous if you know what you’re doing. But many people contributing to the microsites aren’t developers. For them, the local preview instructions in the readme present a barrier, not a solution.

For reviewers, the situation isn’t much better. To see a proposed change live, you’d need to check out the branch, follow the same local setup instructions, and run the site yourself. In practice, most reviewers looked at the diff in GitHub and called it done. That works for typo fixes or, honestly, even new documentation pages or blog posts. However, it’s less reassuring for layout changes, new components, or anything where seeing it rendered matters.

What we wanted was simple. Open a pull request, get a URL, and see your change in a real hosted environment. Ideally, one that mirrored the production infrastructure, allowing us to test changes in a production-like environment. While static website hosting is straightforward, there are nuances with different hosting options. We wanted to provide this to contributors without them needing to know anything about the underlying infrastructure, without needing access to Octopus, without needing to run anything locally. That experience didn’t exist yet, and building it was what set this whole project in motion, which admittedly was a bit of eat your own dog food when we introduced ephemeral environments in Octopus.

Organically growing infrastructure

The microsites were provisioned and were running in AWS, using S3 as the endpoint and CloudFront distributions in front of them. It worked, but they were initially provisioned and configured manually and had been left largely untouched since.

Without Infrastructure as Code (IaC), there was no reliable way to know whether the configuration of each bucket and distribution was consistent across all sites. If a change was required, it had to be made manually, one resource at a time. If something ever needed to be recreated from scratch, like deploying to a new AWS region or provisioning a fresh environment for a pull request, there was no automated way to achieve it.

We knew we wanted to move to Azure, where most of Octopus’s infrastructure lives, and that the migration was an opportunity to put the infrastructure management in a better shape. Automating the provisioning and deprovisioning of infrastructure was something we knew we had to get right, particularly if we were going to support ephemeral environments and speed up deployments.

What we changed

The pain points above are just the surface. Each one has a dedicated article that goes into the details, the decisions, the trade-offs, and the edges we hit along the way. If you’ve felt any of this in your own work, the deeper articles are worth your time.

New articles in this series are being published over the coming weeks. As each one goes live, the topics below will link through to it.

The copy-paste problem across both GitHub Actions and Octopus was solved by leaning into templating. Twenty workflow files spread across five repositories were consolidated into a set of reusable GitHub workflows. In Octopus, five individual deployment processes were consolidated into a single versioned process template that all five microsites now consume, along with templated runbooks for provisioning and deprovisioning infrastructure. Both solved the copy-paste problem, but if you read the reusable GitHub workflows article, you might come away thinking Octopus has set a pretty high bar for what templating should look like.

Slow deployments and the pnpm thin workaround that papered over them were addressed during the migration to Azure. We evaluated several hosting options before landing on Blob Storage, swapped out the file transfer tooling for AzCopy, and in doing so, made pnpm thin unnecessary. The full story is in finding the right hosting for a static site.

Ephemeral environments were the catalyst for this project, and while Octopus does much of the heavy lifting, it requires a mature foundation underneath. Every pull request now gets its own hosted environment, with a preview URL posted as a comment on the PR. Along the way, we hit some interesting edges, including managing Terraform state for short-lived environments and a subtle race condition with short-lived PRs that took a pragmatic workaround to resolve.

Two of the more interesting conversations in the project weren’t really about tooling at all. Where ownership lines fall between a platform team and the teams consuming what they build is something many practitioners wrestle with, and it came up repeatedly here. And rather than installing tools at deployment runtime - something I’ve seen a lot of teams do in the field - we took an approach of keeping workers lean with execution containers, which made deployments faster and more predictable.

Finally, not every pull request needs a full environment spun up. Based on some conversations I had at conferences and internal feedback, we made the whole thing optional using a simple GitHub PR label, without compromising branch protection rules.

Wrapping up

None of the pain points in this article were dramatic on their own. A few copied workflow files, a slow deployment, a staging environment people stopped using. But together, they made it harder to improve, harder to trust what we were shipping, and harder for contributors to see their changes before they went live.

It’s also worth thinking about what happens as these patterns scale. Five microsites is a small footprint, but the same copy-paste approach across dozens or hundreds of applications makes it close to impossible to answer simple questions like “are all our deployments following the same process?” or “has everyone picked up the latest security change?” That’s where platform thinking earns its keep. Shared templates, consistent infrastructure, and guardrails built into the process mean compliance and risk are handled by default, rather than relying on every team to remember to do the right thing based on a knowledge base article people rarely revisit.

For us, the realization was that the tooling we rely on had moved on, and our pipelines hadn’t kept up. Taking the time to step back, look at the whole delivery cycle, and bring it in line with what modern software delivery looks like today has been worth it. If some of this sounded familiar, it might be worth taking that same step back with your own pipelines.

Happy deployments!

Introducing remote MCP for Octopus Deploy

2026-10-13

Until now, connecting an agent to Octopus meant running our local Model Context Protocol (MCP) server on your machine. You had to install it on every machine, for every user, and keep every installation up to date.

There’s an easier option now. Octopus includes a built-in remote MCP server, so there’s nothing to install or maintain. Point your agent at your instance’s /mcp endpoint, and it can talk to Octopus over HTTP.

What can the remote MCP do?

The remote MCP initially supports a selected set of core Octopus features, and we’ll add more over time. Share your feedback to help us decide what comes next.

Depending on the authentication mechanism and the permissions you grant, the remote MCP can:

Navigate and orient: Find and provide details on spaces, projects, tenants, and tenant tags.
```
List the projects in the Payments space and the tenants each one deploys to.
```
Answer deployment questions: Show a pull request’s deployment status, including when it reached a tenant or environment, and describe the lifecycle phases and progression rules behind it.
```
When did PR #4821 reach the Brisbane Bank tenant, and which environment is it in now?
```
Deploy and operate: Create and deploy a release, promote a release through its lifecycle, and run runbooks. Then generate and attach release notes to a release.
```
Create a release of Payments Service, deploy it to production, then draft and attach release notes.
```
Investigate and diagnose: Search task logs, deployment processes, and variables to work out why something failed. List or filter running, queued, and failed tasks across the instance.
```
The last deployment of Payments Service to production failed. What was the error, and which step failed?
```
Audit and report: Query audit events, report on deployment health, and triage incidents by tracing what was deployed to which targets and when.
```
What changed in the Payments space in the last hour?
```
Check tenant configuration: Find variables with incomplete configuration across tenants.
```
Which tenants have missing variable values for the Payments project?
```

Get started

Octopus Cloud customers can use the remote MCP now. Point your agent at your instance’s /mcp endpoint to try it.

Octopus Server customers will get it in the upcoming 2026.3 release.

Read the remote MCP docs to learn how to connect your agent and set up authentication.

What’s next

We know that for many teams, easily connecting an agent to Octopus is only the first step. The next is governance.

The remote MCP is one part of our broader vision for agent governance. In the coming months, we’re launching:

Scoped API keys: Tighter control over what an agent can reach
OAuth for the remote MCP: A cleaner, more secure connection flow
Agent-aware policies: Visibility into whether an agent initiated a deployment or runbook run, to inform Platform Hub policies
Improved audit log: Easier filtering and viewing of audit events related to agent activity

Thank you to the 19 users who voted for and commented on remote MCP in our roadmap. You helped shape this feature.

Salesforce Deployments with Octopus

2026-10-10

Salesforce DX (Developer Experience) is a set of tools and features that bring modern, source-driven development and DevOps practices to the Salesforce platform. It allows teams to build Salesforce applications using Git-based workflows and deploy them via CI/CD pipelines.

Salesforce DX provides a command-line interface (CLI) to automate application deployments, and Octopus Deploy can integrate with it to deliver a seamless deployment experience.

In this post, you’ll learn how to deploy Salesforce applications using Octopus Deploy and the Salesforce CLI.

Prerequisites

Download the sample application from this GitHub repository. The releases provide Zip files that can be uploaded to the Octopus built-in feed:

You must install the Salesforce CLI locally by following the Salesforce CLI installation instructions.

You can create a free account on the Salesforce Developer site. This post will use a Salesforce Developer Edition account to deploy the sample application.

Log in locally

sf org login web --set-default --alias Dev

The authentication URL, which is used as a secret to log in to Salesforce, is shown with this command:

sf org auth show-sfdx-auth-url

The SFDX Auth URL is then displayed in the format force://PlatformCLI::<secret>@<hostname>.develop.my.salesforce.com. This URL is used to authenticate the Salesforce CLI with your Salesforce organization. Take note of this URL, as it must be saved as a secret in Octopus Deploy.

You can use the JWT Flow to authenticate the Salesforce CLI without requiring a web-based login. This allows deployments to be automated without user interaction. However, this post will use the web-based login for simplicity.

Deployment process

Deploying a Salesforce application is done via a script step that runs the Salesforce CLI commands.

To automate Salesforce login, the SFDX Auth URL is stored as a secret variable named Salesforce.Auth.

Then add a script step to the deployment process that runs the following commands.

You’ll make use of an Execution Container to expose the Salesforce CLI to the script step. In the Execution Container Image section, select the option Runs inside a container on a worker, and then the Build container from an inline Dockerfile option. Paste the following Dockerfile into the text box:

FROM node:22-bookworm-slim

RUN apt-get update && apt-get install -y --no-install-recommends \
    ca-certificates \
    curl \
    gnupg \
    libicu-dev \
    && rm -rf /var/lib/apt/lists/*

RUN npm install -g @salesforce/cli

Paste the following script as an inline script in the script step:

# Stop the CLI from losing its auth storage context
export SF_USE_GENERIC_UNIX_KEYCHAIN=true

# Deactivate the CLI's DNS check, which frequently fails in CI networks
export SF_DISABLE_DNS_CHECK=true
export SFDX_DISABLE_DNS_CHECK=true

# Keep telemetry off
export SF_DISABLE_TELEMETRY=true

# Enter the directory with the sample application
cd SampleApp

# Log into Salesforce using the auth URL stored in Octopus Deploy
echo $(get_octopusvariable "Salesforce.Auth") > ./authfile.txt
sf org login sfdx-url --sfdx-url-file ./authfile.txt --set-default --alias CiOrg
rm ./authfile.txt

# Perform the deployment
sf project deploy start --target-org CiOrg

Finally, add the sample application to the project as a referenced package:

Using the new component

To use the new component from the sample application, navigate to the Setup menu in Salesforce:

Open the Lightning App Builder item in the left-hand menu, and click the New button to create a new Lightning app:

Complete the wizard to create a new Lightning app:

Select the new component and drag it onto the page:

Going further

This Salesforce post describes a high-level deployment pipeline, with this diagram showing the breakdown between the CI and CD processes:

All the steps in the CD process are implemented via the sf CLI and can be automated using Octopus Deploy.

Conclusion

Octopus provides a convenient way to deploy Salesforce applications using the Salesforce CLI. The CLI handles the interactions with the Salesforce platform, while Octopus provides a user-friendly interface for managing deployments, variables, and secrets. By combining these tools, teams can implement a robust CI/CD pipeline for Salesforce applications.

Continuous Delivery Office Hours Ep.10: Modernizing legacy software

2026-10-06

In CD Office Hours episode 9, we discussed the compliance ratchet and how accelerating software development without the right practices can lead to an irreversible increase in controls. In this episode, we look at a classic software problem: the lure of the software rewrite and the inevitable hazards such endeavors bring.

When the cost to maintain the software and add new features becomes burdensome, a decision is often made to rewrite it rather than improve it “in place”. This is sometimes a valid approach, but more often it’s based on an exaggeration of how bad the code is and an understatement of the work involved.

In some cases, the qualities of the codebase that a team dislikes stem from an architectural decision they don’t understand, either because there’s no record of it or because the records aren’t put to use. In many cases, the layers of change applied to the code over time have made it messy and hard to comprehend.

When considering a big-bang rewrite, it is practically impossible to determine whether the rewrite is required or will provide a return on investment. That’s why big-bang rewrites have such a high failure rate and should be avoided.

Watch the episode

Watch Continuous Delivery Office Hours Ep.10

Legacy or heritage

The term “legacy” has become associated with old and unusable software, but more often, legacy software is the long-running backbone of an organization. It captures vast institutional knowledge and endures for so long because it works. In many cases, software inevitably becomes legacy software, as the alternative is that it fails.

That’s why we prefer to use the term “heritage” software, as it’s an artifact of special value to the organization. The code for heritage software has captured not just the essence of the solution, but hundreds or even thousands of edge cases and enhancements based on years of learning.

The hazards of the rewrite

Most codebases have parts that are untidy or don’t make sense. There’s a tipping point that makes us want to rewrite the whole thing, but this is often the wrong reaction. It’s very rare for the cost of maintenance to exceed the cost of wholesale replacement.

When teams consider a big-bang rewrite, they tend to estimate the task based on the obvious use cases. That means the new software is naturally cleaner, because it doesn’t handle any of the less obvious problems. When the new software version goes live, the team begins rediscovering the many edge cases that must be handled.

By the time these edge cases have been incorporated into the software, it has started to look complicated once more, because the complexity came from the domain rather than a careless implementation. The team may find more graceful ways to handle edge cases, but by this time, the rewrite will have vastly exceeded all estimates of effort and expense.

When the rewrite is complete, the organization will effectively be “back to square one”, which means they will have fallen behind the competition. That means the anticipated cost of maintenance and new features must be substantially lower to allow the software to catch up and pass competitor offerings.

Essentially, wholesale rewrites should be avoided; a different approach is needed.

Architectural and team strategies

The alternative to the big-bang rewrite is to identify a specific component to replace. You might take a calculation routine and move it out of a monolith into a service, creating the missing tests and refining the routines as you extract it. The result is a new, highly maintainable component and a slightly smaller monolith that calls it rather than doing the work itself.

This is the strangler fig pattern, named for the plants that cheat the competition for sunlight by growing high up on a host tree, eventually sending down their own roots and often remaining after the host tree has died and rotted away. In the same way, the heritage software can continue to support users while an increasing number of components are rewritten and deleted from the monolith.

You can use both domain-driven design and team topologies to inform your gradual rewrite. If you can identify a seam that would carve off a meaningful part of the domain and have a team that can own the domain and the component that serves it, you can create a meaningful interface for the software and improve the organization’s communication structure.

Combining the strangler fig pattern with architectural and team design results in teams with deep knowledge of their specific areas and the ability to move with relative independence. The number of teams you have can be instructive when considering how far you want to break down a monolith into cohesive components.

Wholesale rewrites invite disaster, but working in small steps and considering organizational design as well as architectural design is the path to success.

Happy deployments!

Continuous Delivery Office Hours is a series of conversations about software delivery, with Tony Kelly, Bob Walker, and Steve Fenton.

You can find more episodes on YouTube, Apple Podcasts, and Pocket Casts.

Configuring generic OIDC provider for authentication

2026-10-05

The use of OpenID Connect (OIDC) has gained popularity as a standard for authentication and authorization. Octopus Deploy supports using OIDC for integrating with External Feeds, Accounts, and as an authentication provider. In this post, I will cover how to configure an OIDC provider as an authentication mechanism for Octopus Deploy. This post uses Auth0 as the OIDC provider.

Setting up Auth0

To get started, you’ll need to configure an Application in Auth0.

Create an Auth0 application

Auth0 makes the process of creating an Application pretty painless:

After logging in, expand the Applications category within the Auth0 navigation
Click on Applications
Click Create Application
Give the Application a name (eg., Octopus Deploy)
Choose Regular Web Application
Click Create

Configure the Auth0 application

Once the Application has been created, there are a couple of settings that need to be configured so it will work with Octopus Deploy:

Navigate to the Settings tab on your newly created Application
Scroll down to the Application URIs section
In the Allowed Callback URLs, enter the following: https://<your Octopus Deploy Server URL>/api/users/authenticatedToken/GenericOidc, for example:
```
https://shawnsesna.octopusdemos.app/api/users/authenticatedToken/GenericOidc
```
(Optional) In the Allowed Logout URLs enter the following: https://<your Octopus Deploy Server URL>/app#/users/sign-out, for example:
```
https://shawnsesna.octopusdemos.app/app#/users/sign-out
```
Click Save

Before navigating to Octopus Deploy, record the values of Domain, Client ID, and Client Secret. These values are needed to configure OIDC authentication in Octopus Deploy.

Configure OpenID Connect in Octopus Deploy

Configuration of OIDC authentication can be completed in just a few minutes:

Navigate to Configuration (cog) in Octopus Deploy
Click on Settings -> OpenID Connect
Enable the integration by ticking the Is Enabled checkbox
Set Username Claim Type to name
Set Display Name to something meaningful (eg. Auth0)
Set Issuer to https://<Domain value from Auth0>/ Note the trailing slash
Set Client ID to the Client ID value from Auth0
Set Client Secret to the Client Secret value from Auth0
(Optional) Tick Allow Auto User Creation to automatically create an Octopus user account when a new user logs in using OpenID Connect
Click Save

Configuration is now complete! Users will now see the OpenID Connect login option when signing into Octopus Deploy.

Including roles from Auth0

Unlike other providers such as Microsoft Entra or Okta, Auth0 does not include role assignments by default. Instead, you must insert a step into the process after login, but before the token is issued.

Create an Auth0 role

If you don’t already have roles in Auth0, creating a role in Auth0 is a straightforward process:

Expand the User Management section and click Roles
Click the + Create Role button
Give the role a Name and Description
Click on the Users tab and add some users to the role

Create an Auth0 Actions Trigger

Auth0 provides a mechanism for inserting the role information into the OIDC token called an Action. An Action can be added to a Trigger such as the post-login, which is executed after the user logs in, but before the token is issued.

Expand the Actions section and click Triggers
Under Sign Up & Login, choose the post-login trigger
The process will consist of two steps: Start and Complete. Click on the + button next to Add Action and select Create Custom Action
Give the Action a name (eg., Include Roles)
For this example, leave the Runtime as the recommended Node 22 value
Update the code to the following
```
exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://shawnsesna.octopusdemos.app';
  const roles = event.authorization?.roles ?? null;


  api.idToken.setCustomClaim(`${namespace}/roles`, roles ?? []);
};
```
This code inserts a JSON array payload containing assigned roles into the issued token. In this case, ${namespace}/roles acts as the key with the roles array as the value. The namespace value is important, as this is what Octopus needs to determine where to look for role assignments. In the above example, the namespace value is https://shawnsesna.octopusdemos.app/roles. The namespace can be whatever you want; it doesn’t have to be the URL to your Octopus instance.
Click Deploy to save the Action to the Library.
Navigate back to Triggers
Under Sign Up & Login, choose the post-login trigger
Your newly created Action will now be listed; click and drag the Action and drop it between Start and Complete
Click Apply

Auth0 is now configured to include role assignments with the OIDC token. This will allow you to add an Auth0 role as an external role to an Octopus Team.

Update the OpenID Connect Octopus configuration

Now that roles are included within the token, you’ll need to update the OpenID Connect configuration in Octopus to be able to “see” them.

Navigate to Configuration (cog) in Octopus Deploy
Click on Settings -> OpenID Connect
Update Role Claim Type to the key from the JSON. In the above example, this value is https://shawnsesna.octopusdemos.app/roles
Click Save

Octopus now knows where in the token to locate role membership. Assigning the name of the role to an Octopus Deploy Team will grant anyone who has the role within their token access to the resources that the Team has been granted, removing the need to add individual users to the Team.

Troubleshooting roles

OIDC token exchange takes place server-to-server, making the ability to see what was included in the JSON Web Token (JWT) difficult. Fortunately, there is an easy way to pass the token to jwt.io for debugging purposes.

In Auth0, navigate to your Application
Scroll to the Applications URIs section
Add https://jwt.io to the Allowed Callback URLs
Open a new browser window (Incognito/InPrivate is best to ensure cache doesn’t interfere) and go to:

https://<Your Auth0 domain>/authorize?client_id=<Your Client ID>&response_type=id_token&redirect_uri=https://jwt.io&scope=openid%20profile%20email&nonce=12345

You will be prompted to log in to Auth0, then redirected to https://jwt.io. Jwt.io will automatically decode the returned JWT so you can see what is included. Below is an example:

Decoded payload

{
  "https://shawnsesna.octopusdemos.app/roles": [
    "Demo-Argo-CD-Apps"
  ],
  "nickname": "joe.dirt",
  "name": "joe.dirt@fake.com",
  "picture": "https://s.gravatar.com/avatar/30daab2c90a676d8ab323d0eab8c8f45?s=480&r=pg&d=https%3A%2F%2Fcdn.auth0.com%2Favatars%2Fjo.png",
  "updated_at": "2026-09-17T19:04:13.380Z",
  "email": "joe.dirt@fake.com",
  "email_verified": true,
  "iss": "https://[Your Auth0 domain]/",
  "aud": "<Your Client ID>",
  "sub": "<Your User ID>",
  "iat": 1789671854,
  "exp": 1789707854,
  "sid": "<Your SID>",
  "nonce": "12345"
}

From our example, you can see that the key https://shawnsesna.octopusdemos.app has been assigned the value of the roles the user joe.dirt@fake.com belongs to: Demo-Argo-CD-Apps. The user joe.dirt@fake.com will gain access to any resource where the Octopus Deploy Team has included the external role Demo-Argo-CD-Apps.

Conclusion

This post covered how to add Auth0 as a generic OpenID Connect authentication provider for Octopus Deploy. Some of the steps were specific to Auth0; however, the overall instructions will work for any OpenID Connect provider.

Happy deployments!

Build your own Octopus dashboards with llms.txt and an AI coding agent

2026-10-02

The built-in Octopus dashboard shows you which releases are deployed to each environment. When you manage deployments across many tenants and teams, you might want a more focused view. Which tenants are 2 releases behind? Which approvals are holding up the Payments team? How far has a release progressed across environments and tenants?

You can build these views with the Octopus REST API, but first you need to understand its endpoints, request bodies, and deployment step properties. Octopus’s llms.txt file brings that information together in a format AI coding agents can read and understand.

For this blog post I gave the file to a coding agent and asked it to:

Create realistic test data for a multi-tenant company with several teams
Build custom dashboards for those teams
Visualize release progress in a new and interesting way

Everything below ran against a local Octopus install. I used Claude Code, gave it the URL of the llms.txt file, an agent API key, and the prompts quoted throughout this post.

What is llms.txt

llms.txt is a convention for publishing a plain Markdown file at /llms.txt that condenses information about a website or a collection of documents into a single file. This can also work similarly for API documentation. In essence, it fills the same role for agents that a well-written README does for people.

Octopus serves its own file at https://your-octopus-server/llms.txt. As of the time of this writing the file is about 400 KB of Markdown and has 5 sections:

Section	What it contains
Authentication	API keys, the `X-Octopus-ApiKey` header, cookie login, and cross-site request forgery (CSRF) protection
Space selection	The 2 URL prefix forms, `/api/Spaces-1/...` and `/api/spaces/default/...`
Endpoints	Documented routes grouped by resource, with query parameters, request body type, and response type
Types	One line per type listing its properties and their child types
Steps and their properties	Every `ActionType` with its `Octopus.Action.*` property keys, defaults, and allowed values

A typical endpoint line then looks like this:

- `POST /deployments` - Create a Deployment | Prefixes (pick one): `/{spaceId}`, `/spaces/{spaceIdentifier}` | Body: CreateDeploymentCommand → DeploymentResource

And the matching type line describing the underlying types:

CreateDeploymentCommand: SpaceId (string), ReleaseId (string), ChannelId (string), DeploymentProcessId (string), EnvironmentId (string), TenantId (string), ForcePackageDownload (boolean), ...

Together, these lines give the agent an endpoint and the fields for its request body. It can search for POST /deployments, find the matching type definition, and construct a request.

The Steps section is particularly useful. To build a deployment process through the API, for example, the agent needs to know that a script step uses the ActionType value Octopus.Script and stores its script in Octopus.Action.Script.ScriptBody. The Steps section provides these property keys alongside the API information derived from our existing Swagger docs.

Why is this useful? The llms.txt file gives agents a succinct overview of everything available in the Octopus API, making it easy to build:

Custom views ands dashboards
Automation scripts
Custom integrations with Octopus

Part 1: Seeding realistic data

First, I wanted to fill my Octopus instance with data. I started with an almost empty space: one project, 3 environments, no tenants, no targets. The prompt was:

Use the Octopus API to create test data. Projects with deployment processes, fake targets, project variables, tenants, and anything else you can think of. Make the projects look realistic.

The agent fetched llms.txt, searched the sections it needed, and wrote a small Python helper for calling the API securely (to avoid pasting the API key in the agent’s logs):

def call(method, path, body=None):
    req = urllib.request.Request(BASE + "/" + SPACE + path, data=json.dumps(body).encode() if body else None, method=method)
    req.add_header("X-Octopus-ApiKey", KEY)
    req.add_header("Content-Type", "application/json")
    with urllib.request.urlopen(req) as r:
        return json.loads(r.read().decode())

The agent created a fictional company called Harborline, with 5 teams running a platform for retailers. Each retailer is represented as a separate tenant. It then seeded the instance with the deployment processes, runbooks, variables, deployment targets, etc.

How the llms.txt file helped

Here are some examples of where llms.txt was useful for my agent:

Space prefixes. The agent could understand the Spaces scoping concept and apply the correct URL prefixes to the API calls, like /api/Spaces-1/....
Deployment process authoring. Keyed step properties like Octopus.Action.TargetRoles, Octopus.Action.RunOnServer, and Octopus.Action.Manual.ResponsibleTeamIds were documented in the file and the agent used those to create the deployment processes.
Backdating releases. CreateReleaseCommand has an optional Assembled field. The agent used it to spread 31 releases across August and September so the dashboards would have history to show.
Breadth of the API. As Octopus Deploy is an API-first product, the agent was able to understand what Octopus is and what it offers just by reading the available API endpoints.

While the text file gave the agent enough ground to start, there were still issues where it had to make requests to the API first to understand the right shape of things. The agent worked through these issues by making API requests and reading back the detailed error and validation messages.

Part 2: Custom dashboards

One of the best scenarios for using the Octopus REST API directly is creating customized dashboards tailored to your specific requirements. This is much easier to achieve now that you can just point your coding agent to the llms.txt and ask it to build it for you.

Keep the API key out of the browser

To avoid embedding your API key into the dashboard, you can use a small proxy script. The proxy serves the static HTML and forwards requests under /api/ to Octopus, adding the API key header. This gives the browser a single origin for both the page and its API requests, solving Cross-Origin Resource Sharing (CORS) issues.

Here’s is an example that forwards a request:

def proxy(self):
    req = urllib.request.Request(OCTOPUS_URL + self.path)
    req.add_header("X-Octopus-ApiKey", API_KEY)
    with urllib.request.urlopen(req) as r:
        body = r.read()
    self.send_response(200)
    self.send_header("Content-Type", "application/json")
    self.end_headers()
    self.wfile.write(body)

Now here are some examples of the dashboards you could build.

The tenant rollout board

The first dashboard is a matrix. Tenants are rows, grouped by any tenant tag set. Projects are columns, grouped by team. Each cell shows the release a tenant is running in the selected environment, and how many releases behind the newest one it is.

The board uses these endpoints:

Endpoint	Used for
`GET /dashboard?showAll=true`	Current deployment per project, environment, and tenant, plus projects, tenants, and environments in one call
`GET /projects/{id}/releases`	The newest release per project and per channel, to work out how far behind a tenant is
`GET /tagsets/all?scopes=Tenant`	Tag sets for grouping and filtering
`GET /tenants/variables-missing`	Tenants that cannot be deployed to because a required variable has no value
`GET /interruptions?pendingOnly=true`	Deployments paused for approval

The board calculates how far behind a tenant is in its channel, such that a tenant on the latest hotfix isn’t flagged as behind the mainline.

The summary tiles highlight where a release manager needs to act. In this example, 51 tenant deployments are behind the latest release in their channel, and 5 tenants have missing variables. Selecting Only tenants with a problem narrows the board to the affected tenants.

The team health board

The second dashboard groups work by team, with one card for each. Each card starts with deployments waiting for approval and tasks that failed in the last 24 hours. Every item links to its task in Octopus, so you can go back to the Octopus UI at any point.

Below these items, a table shows each project’s releases across environments. Version labels like 2026.3.3 ×5 summarize tenanted deployments. The footer shows target health by environment, and a banner at the top of the dashboard shows active or upcoming deployment freezes.

Endpoint	Used for
`GET /dashboard?showAll=true`	Current deployments and the project group for each project
`GET /interruptions?pendingOnly=true`	Pending approvals
`GET /tasks?states=Failed,TimedOut&fromCompletedDate=...`	Failures in the last 24 hours
`GET /machines/all`	Target health and deactivated targets
`GET /teams/all`	Mapping project groups to the team that owns them
`GET /deploymentfreezes`	Active and upcoming freezes

The agent sorted the cards by an attention score: 3 points per failure, 2 per pending approval. The team with the highest score appears at the top left.

Part 3: A release flow diagram

And for the last one, just for fun, I asked the agent:

Use the API via llms.txt to create one other custom dynamic HTML representation of Octopus data in a creative way, perhaps a visualization.

The agent chose a Sankey diagram, which uses ribbons to show connections between groups. Here, the ribbons connect a project’s releases to their current environments and the tenants or tenant groups they serve.

Ribbon width represents the number of tenants. You can color the ribbons by release to follow a version across the diagram, or by deployment state to highlight failures and pending approvals.

With this you could easily create interactive charts that help you analyze a complex matrix of deployments to spot trends and anomalies.

Try it yourself

You will need a publicly accessible instance of Octopus, an agent API key, and a coding agent that can fetch URLs and run scripts.

Open https://your-octopus-server/llms.txt (or https://your-octopus-server/api/experimental/llms.txt) in a browser to confirm your version serves it.
Give your agent the URL and an API key with permissions scoped to a test space. Ask it to fetch the file before doing anything else.
Start with a read-only task, like “list every tenant that is more than one release behind in Production.” Check the answer against the portal.
Move on to writing the real code. When the agent makes a mistake, the API response will explain why. Use this loop to build the functionality you want.

Keep the API key on the server side. If you build dashboards, create a service account, and put a proxy between the browser and Octopus, like the one above. Never paste the key into the page source. If you are using an external authentication provider, you could also extend this to use a proper authentication mechanism rather than just an API key, though the implementation could become quite complex.

Happy deployments!

The Future of Platform Engineering report

2026-10-01

We're excited to announce the release of the 2026 Future of Platform Engineering report. The report examines why organizations adopt platforms, what shapes their decisions along the way, and what high-performing platform teams do differently.

Platform Engineering has moved from a frontier practice to a mainstream industry standard. It's now an established discipline with recognizable patterns and a maturing body of evidence. The report draws on primary survey data from 379 technical platform practitioners worldwide, and a review of the current literature to establish where the discipline now stands.

A consistent theme runs through the findings, separating platforms that succeed from those that struggle. The decisions and practices around the technology determine success: how adoption is managed, how clearly the strategy is set, and how engaged the leadership is.

Why teams actually build platforms

Organizations adopt platforms primarily for automation and efficiency purposes. Developer experience is still a consideration, but less of a priority for most. When they explain why the initiative was funded, automation comes first. This was a consistent finding in our previous report, the 2025 Platform Engineering Pulse report.

:::figure

:img{ src="/blog/img/future-of-platform-engineering/benefits-reasons.png" alt="Top 10 reasons for adopting platforms" loading="lazy" } :figcaption[Top 10 reasons for adopting platforms (multi-select)]

:::

The motivation behind platform adoption is important as it shapes how success is measured. A platform funded for efficiency reasons and later judged on developer experience will look like a failure that isn't one. Teams that name their primary motivation early have a clearer basis for knowing whether the platform worked.

The organizational constraint to success is strategy

Struggling teams most often report a lack of clear strategy as their obstacle, ahead of the technical complexity of building a platform.

Organizations that predominantly build their platform features from scratch are also the most likely to report this gap. Of respondents building from scratch, 57.9% also cite a lack of a clear strategy as an obstacle. While this may suggest that teams are building without a plan, many engineers build to work out a problem, which makes the build a method rather than a problem. This would explain why these two often turn up together.

:::figure

:img{ src="/blog/img/future-of-platform-engineering/obstacles-build-buy.png" alt="Heatmap of obstacles by dominant build approach" loading="lazy" } :figcaption[Build-versus-buy feature implementation due to a lack of a clear strategy and technical complexity. Heatmap showing the percentage of respondents selecting the obstacle by dominant build approach.]

:::

A result that caught us off guard

Among teams reporting mandatory adoption, 62.2% achieved most of their goals (high-performers). For respondents reporting optional platform adoption, this sits at roughly 27.5%.

This was an unexpected finding. Industry advice that comes up again and again in Platform Engineering is, don't force adoption, treat the platform like a product, and let it earn its users. We assumed that optional adoption would track more with high-performing teams and strong outcomes, but we found the opposite.

:::figure

:img{ src="/blog/img/future-of-platform-engineering/goals-adoption-strategy.png" alt="Goal delivery by adoption strategy" loading="lazy" } :figcaption[Goal delivery by adoption strategy]

:::

The tension here is real, but it doesn't mean that everyone else is doing it wrong. It's two different questions getting two different answers. Mandatory adoption is the stronger signal for whether a platform delivers on the goals it set. Optional adoption speaks to something else entirely: a platform that earns its place because developers choose it rather than because they're asked to, which is a success worth having in its own right.

Mandatory adoption also doesn't move on its own. In the network analysis, it clusters with stronger leadership direction, higher job satisfaction, and greater confidence in budget safety, and those measures correlate with one another about as much as each correlates with goal delivery. Mandatory adoption without the leadership engagement and budget security is unlikely to produce the same result. What appears as a decision about adoption is usually a decision about how much of the organization is behind the platform.

Who's actually getting value from AI?

Teams reporting the most positive impacts from AI were the platforms offering features we classified as advanced, like ephemeral environments, cost control, and code coverage. Adopting these features actually shifted platforms from no AI impact to a positive AI impact on software delivery speed and stability. The difference was in which capabilities a platform had, not how many it had.

:::figure

:img{ src="/blog/img/future-of-platform-engineering/ai-impact-features-software.png" alt="Features ranked by AI impact on software delivery speed and stability" loading="lazy" } :figcaption[Features ranked by AI impact on software delivery speed and stability]

:::

That is consistent with how DORA described AI in 2025, as an amplifier of the system it enters. Where the foundations are solid, the gains compound, and where they aren't, the friction is amplified instead. Teams on mature, well-designed platforms get more out of AI than teams with ad hoc setups.

What this means for platforms

The patterns associated with successful platform teams emerged in organizational decisions: how clearly the strategy is set, how engaged the leadership is, and how adoption is handled. This is an encouraging result. The platforms that deliver well are the ones where people agreed what the platform was for and committed to it.

Platform Engineering is maturing, and the patterns are becoming clear enough to learn from. Read the report for the full analysis, including how teams measure success and what high-performing teams do differently.

Happy deployments!

Octopus Approvals

2026-09-29

Octopus Approvals is a lightweight approval workflow that lets users gate deployments to environments that are sensitive to change. For customers that can’t justify the cost of a full ITSM implementation, it provides approval gating to ensure the right people review before a deployment progresses to the specified environments. This allows deployments to progress safely and satisfies standard compliance requirements.

The current landscape

Manual interventions were initially built to provide the ability to pause a deployment at crucial points to let a human review the state before progressing. We’ve seen customers build a makeshift approval system by stitching together a couple of manual intervention steps. This works for basic use cases but not particularly well at scale and has enforcement gaps.

The next step up is to use ITSM providers like SNOW and JSM. These are perfect for those in highly regulated industries with complex requirements. If you have strict redeployment processes or need to configure a subset of approvers, then that is still the right solution for you; we are not trying to replace these providers.

Why we’ve built Octopus Approvals

Not everyone needs a full ITSM change management system, but many still want to know that a release has the buy-in of key stakeholders before it goes out the door. Octopus Approvals have been designed for customers occupying the middle ground, with more complex approval requirements than manual interventions can meet, but who can’t yet justify the cost of a full ITSM implementation.

Our aim with Octopus Approvals is to bridge this chasm as your compliance requirements grow and help you reach the next level. Octopus Approvals occur before deployment begins; approval is not a step that can be skipped, and it won’t take up a spot in your task queue until it has been approved. Within Approvals, you can explicitly set the parameters required to approve a deployment, including preventing the deployment creator from approving and specifying how many people must approve and from which team(s).

Octopus Approvals walk-through

I want to set up an approval rule requiring at least two team members to approve a deployment before it goes to production. This applies across all projects in my team’s ownership, but only for production; I don’t want to slow down deployments to non-production environments.

Approvals are set at a space level; a single approval rule can span multiple projects. I’m going to use tags to determine which projects and environments are affected, enabling a more dynamic selection. Any new projects tagged as owned by my team will automatically have this rule applied.

When a project owned by Fire & Motion has a deployment created for a production environment, the task will wait for all required approvals. Change requests can be reviewed and approved from the deployment task and the change request tab within the approvals page. Once all required approvals have been received, the deployment will continue.

Each release requires only one approval; redeployments of the same release to the same environment do not require another approval. This ensures that rollbacks to approved versions are not blocked.

For scheduled deployments, an approval will be available as soon as the deployment is created, so you can schedule a deployment outside working hours but approve it before you clock off. This ensures that deployments stay within the approved change windows, but the checks can happen when it’s practical for the team.

Rejected change requests

If any approver rejects the change request, the deployment will not proceed and will be marked as failed. You can not revive a rejected change request; you’ll need to create a new deployment, which will create a new change request. You can use your normal process to identify failed deployments, or set up a Subscription to be notified of change request status.

Reviewing and approving change requests

Change requests can be viewed on the Approvals page. From here, you can see who approved the deployment and when, along with deployment details. Approvals and changes to rules can also be tracked via the audit page; there are ‘Approval Rule’ and ‘Server Task Approval’ document types that the audit page can be filtered by.

Notifications

The same event types used to filter the audit page can also be used to set up targeted notifications. Using our subscriptions feature, you can subscribe to notifications about rule changes to help ensure your team remains compliant. Notifications can be sent via email, Slack, Teams or webhook. Note the below screenshot is the first iteration of our Slack integration, we are currently working on providing a more actionable message.

We will be releasing a separate blog post detailing how you can use subscriptions and webhooks to receive more targeted notifications, so that users who need to approve the deployment are the ones who receive the notification. Subscribe to our newsletter to get this in your inbox.

Known limitations

Any of the required approvers are counted towards the total. If you specified two teams within the approvers, any two approvals across those teams will suffice.
This cannot be used to automate your approval process.
Approvals only work for deployments; this functionality is not available for runbooks.
Approvals, unfortunately, cannot be used to finally get your mother-in-law’s approval.

Octopus Approvals is now available as a Public Preview for cloud customers and in the 2026.3 server release.

Happy deployments!

Inside Platform Engineering with Kian Rogerdi

2026-09-25

If you’ve got the best engineers in the world building the greatest product nobody uses, what was the point? That’s a core question that was lingering in my mind in this episode of Inside Platform Engineering, with Kian Rogerdi. Kian has spent over 20 years in software, the last 10 of them in leadership, running cloud engineering, SRE, and Platform Engineering departments at companies ranging from startups to big enterprises.

What stood out to me most was how much of this conversation ended up being about mindset rather than tooling. In fact, it’s been a common theme in many conversations I’ve had on Inside Platform Engineering, and I’m seeing it as a crucial element in successful platform teams. We didn’t talk much about specific platforms or products. We talked about how easy it is for a platform team to lose sight of who they’re serving, and what that looks like when it goes wrong.

Watch the episode

You can watch the episode with Kian below.

Inside Platform Engineering with Kian Rogerdi

Business value is the point

Kian’s framing is simple, but as a technologist, can be easy to lose sight of. Everything a platform team does only matters if it’s actually helping someone else move faster and safer. He pointed out that plenty of teams still measure themselves on technical excellence alone, building the most secure, most powerful, most elegant system, without asking whether anyone’s using it or whether it’s solving a real problem. Product teams sorted this out years ago because they have a customer staring back at them. Platform teams don’t get that same forcing function, since their customers are internal, which is exactly why it’s harder and why it gets missed. That mindset needs to be a deliberate choice from day 1 when forming a platform team, backed by sensible success metrics to help platform teams showcase their value.

Treat your internal teams like customers

This idea of treating internal teams as real customers has come up in previous conversations, even even as far back as Inside Platform Engineering episode 001 with Luke Philips. Kian leaned on Team Topologies, and it’s worth a read if you haven’t. His point was that platform teams are supposed to reduce cognitive load for stream-aligned teams, but that only works if you’re listening to those teams the way a product team listens to its customers. He talked about embedding platform engineers with the teams they serve, just to watch what actually happens, which templates get ignored, which pipelines get quietly replaced with something homegrown. I really love this take, and I’ve seen versions of this myself, where teams don’t abandon your tooling because they’re difficult, they abandon it because it doesn’t solve their problem.

It reminds me of when I was in a consultative role as a DevOps Engineer, and we were a little too on the reactive side where we were waiting for customers to come to us when they needed help. We decided to flip the model on its head, and asked to sit in with our customers’ developers on their daily standup. We weren’t in every standup, just one or two a week. Just doing this paved the way for a much better way of working with their teams. We could ask questions like “why are you doing it that way” or suggest “we can make that a lot easier”, and because we were in the room, they would ask for our opinion on the topics of discussion in that meeting. Dev and Ops coming together, who would have thought! I see this same pattern as crucial for platform teams, who need to spend time with the teams they’re trying to enable.

Enablers, not gatekeepers

Speaking of enabling, Kian described a pattern he’s seen play out at companies he’s worked at, where a platform team that starts dictating instead of enabling, vetoing decisions, and effectively becomes a gate that other teams have to get through. He drew a clear line around genuine compliance requirements in regulated industries like fintech or healthcare, which are legitimately non-negotiable, but said everything beyond that is a red flag. He also noted this tends to get worse as companies scale, because politics creeps in and platform work becomes a source of power over other teams rather than a service to them. The fix, in his words, isn’t complicated; it’s remembering the purpose. It just takes deliberate effort to keep remembering it.

Happy deployments!

Inside Platform Engineering is a series of conversations with Matt Allford and a guest, bringing their own experience and perspective from the world of Platform Engineering.

You can find more episodes on YouTube.

Continuous Delivery Office Hours Ep.9: The compliance ratchet

2026-09-22

In the last episode, we talked about AI efficiency and effectiveness. That meant thinking not just as a beneficiary user but also as an end user. In this episode, we bring the authority to bear when we discuss the compliance ratchet. It turns out that there is an equal and opposite reaction in software, just like physics. If you speed up your software delivery velocity without the right practices in place, you encounter trip hazards that cause your organization to tighten controls.

The most dangerous part of this reaction is that compliance controls are added very easily, but are difficult or impossible to remove. That means you can trigger a one-way ratchet that permanently hampers your software delivery performance.

At the moment, it’s common for teams to use AI to increase the volume and pace of their software development. If this results in outages or high-profile bugs, compliance controls are slapped on the team. This often pushes the pace of change back to pre-AI levels, preventing any return on the AI investment.

Watch the episode

Watch Continuous Delivery Office Hours Ep.9

Balance the AI investment

One of the mistakes of introducing AI coding tools is expecting immediate gains. This puts pressure on teams to produce more changes and discourages them from introducing the pipelines and practices that will unlock the velocity and safety of sustainable high-performance software delivery.

On top of balancing the need for enabling practices, it’s also crucial to balance where you apply AI. If you only use AI to increase coding speed, the increased change volume will be absorbed by downstream bottlenecks. That means you need to consider where the investment has the greatest impact on the end-to-end flow of value, rather than speeding up individual stages and pushing more work into queues for review, approval, deployment, and feedback.

Unlock the ratchet

The controls you have in place for software delivery were likely created for a different time. They accrue as a result of organizational trauma: a bad deployment during a peak period means a 3-month deployment freeze, or a bad dependency means every change needs a senior developer review. Even if the team has learned from those mistakes, the controls remain.

Now might be a good time to revisit your path from a developer’s laptop to production, documenting each control and deciding whether it’s still necessary, and whether there’s a better way to manage the controls you decide to keep, optimizing for both speed and stability. Each past decision made on the assumption that there was a trade-off between velocity and safety should be reconsidered to find a way to achieve both. Automated validation is often faster and more repeatable than manual validation, so you likely have a way to achieve both easily. Replacing manual stages with automation provides far better control than adding additional slow checks.

Direction often beats speed

If you’ve been hanging around in software development for any length of time, you’d think all people cared about was speed. This is one of the great distractions of the past 3 decades. Teams adopted Agile for speed, they adopted DevOps for speed, and now they’re buying AI coding tools for speed. As described in The Bullseye Model, the ultimate goal isn’t speed, but a combination of speed and direction. When you aren’t sure what users want, delivering software versions early and often helps you discover their needs and what works. Ultimately, though, you’re trying to hit the bullseye with perfect software, and that means direction is at least as important as speed, perhaps more so.

All of these insights point to a necessary shift in software delivery; one that is long overdue. For a long time, we’ve treated technical practices as optional, but with the velocity and scale of modern software, that’s no longer true. We’ll be talking more about this in the future.

Happy deployments!

Continuous Delivery Office Hours is a series of conversations about software delivery, with Tony Kelly, Bob Walker, and Steve Fenton.

You can find more episodes on YouTube, Apple Podcasts, and Pocket Casts.

Let's not water down the terms Continuous Integration and Continuous Delivery

2026-09-08

One of the most perplexing discussions I’ve had in recent times was about CI/CD. I’ve earned my CI/CD scout badge at this stage in my career, so the confusion caught me off guard. This post briefly sets out what Continuous Integration (CI) and Continuous Delivery (CD) mean and addresses the most common misconceptions in the discussion.

My point isn’t just semantic. These terms carry decades of hard-won engineering practice, and when we let their meaning drift or decay, we lose crucial wisdom.

Continuous Integration

Continuous Integration is well named compared to many concepts in our industry. The term “integration” refers to merging your changes into the main branch in version control, and the term “continuous” means you do it often. When Kent Beck popularized the term in Extreme Programming Explained (1999), he set an upper limit of a day. After 26 years of progress, you should expect to be doing it far more frequently than that.

You might understand the concept better if we look at examples that don’t fit the definition. If you have code on your machine that’s more than a day old, you’re not practicing Continuous Integration. If you have a branch that’s more than a day old, you’re not practicing Continuous Integration. It doesn’t matter how often you merge from main into your branch, because main is completely unaware of changes, like yours, that haven’t been merged yet. That means you have diverging software versions, and at some point, you have to make them all converge.

Continuous Delivery

Continuous Delivery is an approach focused on delivering all changes to users quickly, safely, and sustainably. You keep your code in a deployable state at all times and reject the idea of separate integration, testing, and hardening phases. There are specific technical practices involved here because you need a deployment pipeline that reduces risk and increases your confidence that the software version works.

At this stage in our industry’s history, almost everything involved in answering the question “Is this deployable?” should be automated as part of the deployment pipeline. A decade ago, perhaps, you could reasonably list a few stages that were economically unviable for automation. The scale and pace of modern software delivery mean this is rarely the case now.

The simple test is to ask, “Is the software deployable?” If you can’t answer this question every day, you’re not doing Continuous Delivery. In their book on Continuous Delivery (2010), Dave Farley and Jez Humble detail the principles and practices that let you answer this question, and the research has increased our confidence that this is what good software delivery looks like.

Misconceptions

Let’s turn our attention to where the conversation left the trail.

CI doesn’t just mean automated builds

One of the most common sources of confusion is that CI just means automated builds and tests. While it’s difficult to practice Continuous Integration without automation, the crucial property of Continuous Integration is that all changes are in a shared mainline, not on developer machines or in long-lived branches. Having more than 3 branches or keeping branches open for more than a day slows delivery throughput and makes the software less stable, as reinforced by long-running research.

There’s a human process at the heart of CI: each developer chooses to commit their changes frequently to main. Without people deciding to do this, there is no CI.

CI doesn’t allow feature branching

There’s a misconception that you can do CI and choose a branching strategy, like feature branches. Any branching strategy that keeps a change out of main for more than a day cannot be called CI. You may still choose to use feature branches despite the drawbacks, but you have to stop calling it Continuous Integration, as you aren’t continuously integrating all changes.

CD doesn’t mean Continuous Deployment, though it can

CD means “Continuous Delivery”. It means your software is deployable at all times, and you can test this daily by asking, “Can we deploy the software?” If you don’t have a way to answer the question confidently, you’re not doing Continuous Delivery. You may choose to deploy every validated software version automatically, which is Continuous Deployment, or you may need to be more tactical about when you deploy. Either is fine.

For both Continuous Delivery and Continuous Deployment, you need high levels of automation and sufficient risk coverage within that automation so you know you can deploy. Continuous Delivery should mean you can deploy at the press of a button, and Continuous Deployment removes the requirement to press the button.

You can’t do CD without CI

Some folks were confident that you can do Continuous Delivery without doing Continuous Integration, but the literature on this is very clear. Farley and Humble explicitly include Continuous Integration as a required practice. There’s a whole chapter dedicated to it (p. 55 of Continuous Delivery) that adequately explains how it should work and why it’s not optional.

CI/CD isn’t vague or open to interpretation

Another claim that came up more than once was that CI/CD is vague, open to interpretation, or lacks the detail on “how” you should apply the approach. This does a disservice to those who conscientiously captured the approach, whether that’s Kent Beck describing Continuous Integration in Extreme Programming Explained (1999) or Farley and Humble detailing both Continuous Integration and Continuous Delivery in their book Continuous Delivery (2010).

Resist the diffusion

There is a constant temptation in the tech industry to allow semantic diffusion to erode our progress. When we package up a cartload of wisdom into a term, we have to resist the diffusion that follows when people oversimplify our term, remove crucial parts of the whole, or try to brand something with the label that pushes us backward.

We have a history of giving up on these battles, as we seem to have done with Agile and DevOps. These terms had an important meaning that represented a significant step forward for our industry, and losing our energy in their defense lets the perpetual “Late Majority” and “Laggards” (from Crossing the Chasm) drag us all back into their old ways.

CI and CD deserve better.

Debunking the hotfix pipeline myth

2026-08-27

Hotfix pipelines are like an extended warranty; they make sense in principle, but in reality, they aren’t necessary. And just like an extended warranty, you spend a lot of money (and time) building a hotfix pipeline that you should use only rarely. This article will first walk through the fundamental flaws of hotfix pipelines. Then it will explain why it is better to focus on improving the standard Production deployment pipeline.

Defining hotfix pipelines

Hotfix pipelines are a “fast lane” to the normal Production deployment pipeline. Their purpose is to skip specific steps to get changes into Production as soon as possible. Typically, they are:

Production deployment pipeline: Development → Test → Staging → Production
Hotfix pipeline: Staging → Production

They exist because of this scenario:

A critical bug appears in Production hours or days after a deployment.
A rollback is impossible, as that will cause more problems than it solves.
There is work in flight in lower environments.
The hotfix pipeline skips the lower environments.

The core idea behind hotfix pipelines is that they allow normal work to continue while providing a path to fix a critical bug as soon as possible. Someone, either within the development team or the business, determines that a bug is important enough to fix and can skip use the hotfix pipeline.

Hotfixes in the real world

From experience, hotfix pipelines are created in response to a suboptimal Production deployment pipeline. There is a step, or several steps, that either add little value or take so much time that everyone is fine skipping them when certain conditions are met.

I experienced a suboptimal process before joining Octopus Deploy. Before Octopus Deploy, I was a software engineer for almost 15 years. This was a deployment process at a company I worked for before we fully automated it (using Octopus Deploy, of course!).

Four environments: Development, QA, Integration, and Production.
Shared database for the same application for all in-flight work.
The build server only monitored the main branch.
The build server automatically deployed to Development and QA.
Deploying to Integration and Production used different tooling and was a mix of manual and automated.

As you can see, deploying to Integration and Production was completely different from Development and QA. Some notable new steps include placing code build artifacts in “hot folders” to automatically deploy code, placing database delta scripts in designated network folders, and hand-typing instructions for the Web Admins and DBAs.

Deployments to Production took hours due to missing database and configuration changes, and occasional failures to update a server with the latest code. Because deployments to Production took hours and were error-prone, the application I was responsible for deployed new functionality and most bug fixes to Production once a quarter. Those deployments were always off-hours.

Integration was slightly better; we could deploy to that in the middle of the day, but it was still just as error-prone. We didn’t want to deal with that headache. Integration was often updated only days before a Production deployment. As a result, Integration and Production were almost always running the same version. This created a clear hotfix path for us.

Generally, but not always, hotfixes could be placed into one of four buckets. In each case, we could run the proposed fix in Integration before Production.

Fix the issue by changing a record in the database to “trick” the code into the right path.
Solve the problem by making a change to the database schema or a stored procedure. Sometimes it was as simple as adding an index.
Make a configuration change, either in a web.config file or the operating system host.
If it required a code fix, we could configure the build server to create the build artifacts but not deploy to Development and QA. We’d copy the artifacts to the “hot folders” for a deployment to Integration.

The common workflow when a bug was reported was for the on-call engineer to triage it. Once they isolated the root cause, they’d pair with a DBA or Web Admin until the issue was resolved. While issues were resolved, it led to other problems.

Database schema hotfix changes were rarely “copied down” to lower environments. The delta in the database schema between Dev/QA and Integration/Production was significant.
Configuration changes sometimes didn’t make it into version control. The next deployment to Integration and Production would often overwrite the hotfix, requiring another hotfix.
Because of the once-a-quarter releases, finding an appropriate point in time in version control that just had what was in Integration/Production took a lot of effort.

Impact of automation on hotfix pipelines

Automating a terrible process doesn’t make it any less terrible. The core problems must be addressed. Our core problem was two different processes to deploy software from Development through to Production. Those two processes were required because the build server was used for deployments and shared application database. The build server lacked the appropriate RBAC and configuration controls to satisfy security and audit requirements. The shared database encouraged the merging of unfinished code.

Using a combination of local database development, git, Redgate’s tooling, Octopus Deploy, and Azure DevOps (or Visual Studio Team Services as it was called back then), we rebuilt the entire deployment pipeline.

All changes, code, and database are made in a branch.
Changes are merged to the main using a Pull Request.
Azure DevOps / VSTS builds the code and packages database changes.
Octopus + Redgate deploys those build artifacts to Development.
Automated Verification, then Octopus + Redgate, promotes those artifacts to QA.
QA verifies.
Promote those artifacts to Integration using Octopus + Redgate.
Final sign-off.
Promote those artifacts to Production using Octopus + Redgate.

Rebuilding the deployment pipeline had numerous benefits.

Consistent deployments: No more surprises when deploying to Integration and Production, as it was the same process for Development and QA
Eliminated post-deployment emergency fixes: Automation stopped the dumb mistakes that led to many hotfixes.
Reduced manual work: No one had to copy files to specific network folders and write up instructions.
Increased release cadence: Production deployments increased from once a quarter to once a week.
Smaller changeset: Instead of dozens or 100s of changes, each deployment had fewer than a dozen. That meant there was a lower chance that something could go wrong.

The most surprising thing to us was the more tolerant users. When it took two or three months to get a bug fix into production, users would classify most bugs as high/must-fix because they couldn’t wait that long. With the new pipeline, unless the bug was critical, most users were willing to wait a day or two for a fix. With smaller change sets, the number of critical bugs dropped significantly.

While we were deploying once a week, we still had major features that would take over a month to develop. All that work would occur in a branch. When we merged in those major changes, it would sometimes take a week or two to fully test it (our actual average was deploying every 10 days). During that time, there was “no clear path to production” for hotfixes.

For major features, we’d often do a few deployments to Integration as a final test with Production-like data.
Once major features were pushed to Integration, there was no easy way to roll back those changes.
We used a Service-Oriented Architecture (SOA) to achieve loose coupling, but there was still some coupling. Whenever anyone rolled back Integration to match Production, other applications would break because they were expecting a specific version.

Because we knew there was a chance of bugs after deploying a major feature to Production, we would implement a merge freeze, except for critical bugs, for a week after the Production deployment.

The merge freeze was the best solution we could come up with at the time. We looked into creating a hotfix pipeline, but with deployments to Production occurring once a week (or so), we kept running into the same roadblocks:

How do we qualify a bug to justify using the hotfix pipeline?
What if a pending change is in Integration?
How do we configure the build server to tell Octopus to push to Integration instead of Development?
How do we know which branch would be in Production when another bug occurred with a hotfix pipeline?

The decision tree of if/then/elseif/else for when to use a hotfix pipeline became extremely confusing. In addition, fewer critical bugs were released. The work to create a hotfix pipeline for my team was de-prioritized. Until I left, I never saw that becoming a priority. Every once in a while, when we had a merge freeze, someone would bring it up. But it was more of a passing comment. Not a dictate to make a change.

Hotfixes don’t fit in modern software delivery

The story from above took place over 10 years ago. It involved deploying .NET applications to static environments hosted by Windows Servers. There were many Continuous Delivery techniques we didn’t implement at the time. In addition, many technologies and techniques have been introduced.

Below are the core principles every software delivery pipeline should follow. See Continuous Delivery and Achieving Continuous Delivery with TPF, and Trunk-Based Development for more details.

The main branch must always be in a deployable state.
Create the build artifacts from the main branch once and promote them through the necessary environments to production.
How you deploy to Production should be exactly the same as how you deploy to Development, Testing/QA, and Staging/Integration.
Automate as much testing as possible, including unit testing, integration testing, and post-deployment smoke and soak tests.
Store environment configuration in version control and use that to keep all environments similar. Compute resources and external access can differ by environment.
Separate deploying new code from releasing new functionality by using feature flags.

With those core principles in mind, the delivery pipeline is the following:

Make any changes in a short-lived branch.
Checking in changes to a branch creates a pre-release artifact and deploys to an ephemeral environment or a static Development environment.
Merge those changes into the main branch via a pull request.
The pull request should also be verified on an ephemeral environment or a static PR environment.
After merging into the main branch, create the release artifacts.
Promote those release artifacts through any static testing environments (Test, QA, Staging, Pre-Production, etc.) to Production.
Once a feature is ready, enable the new functionality for a subset of users in Production via feature flags. Start with internal teams, then slowly add users until you have enabled it for all users.

With the appropriate guardrails around the main Production deployment pipeline, a hotfix pipeline for just Staging → Production raises a lot of questions.

Branching and Deploying
- Will the hotfix branch use an ephemeral environment for testing before going to Staging?
- How will the build server know to skip the Test environment and move to Staging → Production?
- What will the version number be for the hotfix release? If Production is 2026.8.1, does that mean the hotfix is 2026.8.1-Hotfix, 2026.8.1.1, or 2026.8.1.1-hotfix?
- The main branch is supposed to represent production. How will the appropriate hotfix be communicated to the rest of the engineering team?
- When will the hotfix changes merge into the main branch? How much of a delta is there between what is in the main branch and production? Can the fix even be merged into the main branch without serious modifications?
Testing and Risk
- What is preventing the main branch from being deployed to Production?
- If there is new functionality that’ll likely have many edge cases and potentially show-stopping bugs, why wasn’t it behind a feature toggle?
- Were there changes already in Staging that were overwritten by the hotfix? Will that impact other teams or applications?
- What steps and tests are being skipped in the Test environment?
- How much time is really being saved by skipping the Test environment?
- What if the hotfix requires a hotfix? How long is it acceptable to block the normal pipeline from deploying to Staging → Production?
- How often is the hotfix pipeline tested and verified?

Hotfix pipelines no longer make sense

All of the challenges listed above are solvable with enough time and money. But to quote Ian Malcolm from Jurassic Park, “Your scientists were so preoccupied with whether they could, they didn’t stop to think if they should.”

To put it bluntly:

Is it worth spending time to work through all those issues to create a hotfix pipeline?
How often do you need to push a hotfix?
If it is a regular occurrence, is the hotfix process masking a suboptimal process like the one I described earlier?

The time spent creating a hotfix pipeline is better spent making the primary software delivery pipeline as efficient as possible. A good goal is to take less than an hour from pull request acceptance to being ready to deploy to Production. That includes builds, testing, linting, scanning, deploying to lower environments, and verification.

Achieving that requires addressing some hard problems:

If the main branch is regularly in an undeployable state, what testing and verification should be moved earlier in the pipeline to ensure it is always in a deployable state?
Is the branching strategy Trunk Based Development or GitHub Flow (not to be confused with GitFlow)? If not, why not? Even the creator of GitFlow has said not to use it for most applications.
Showstopping bugs, ones that typically require a hotfix, are typically the result of new features and functionality. How can Feature Flags be introduced into the pipeline to separate deploying new code from releasing new features?
If manual review and approval processes are the primary bottleneck, which steps in that process are prime candidates for automation to speed up approvals?

The primary advantage of focusing on the items above is that they have a net positive for any change. New features, security patches, and bug fixes will be deployable faster.

**Disclaimer:*- The one hour is a goal to aim for. It isn’t a hard rule. One hour for some applications, like monoliths, is impossible. That doesn’t mean you shouldn’t try. Small improvements add up over time. Improving a monolith’s pipeline from one day to two hours is a huge accomplishment.

Configuring Octopus Deploy

By this point, you might be asking yourself, how does this impact my configuration of Octopus Deploy?

Unfortunately, lifecycles (and channels) are among the most misconfigured constructs within Octopus Deploy. To make onboarding easier, the default lifecycle is built using conventions. If you were to create Development, Test, Staging, and Production environments, the default lifecycle automatically becomes:

Development → Test → Staging → Production

That default lifecycle encourages bad behavior, necessitating a hotfix lifecycle.

It doesn’t represent how developers work in branches. Because it includes Production, it has to represent the main branch. But it also includes Development. To get feedback, developers are forced to use their local machine or merge unfinished changes into main.
With unfinished changes in the main branch, it is currently undeployable. It could remain there for days and sometimes weeks.
Enforcing SemVer versioning rules becomes nearly impossible. For example, releases that are not ready for Production typically receive a pre-release tag because the lifecycle includes Development and Production; that rule cannot exist.
There isn’t a clear path to push a fix to Production. To prevent that from happening, teams will implement merge freezes for a period of time after a major release (like I did at a previous job). Or create a hotfix lifecycle that skips Development and Test.

The root cause of that is having the static Development environment included in the same lifecycle as Production. Development is for unfinished changes, Production is for finished changes. A Production lifecycle must never include Development.

If a static Development environment is required, my recommended lifecycles are:

Default: Development
Release: Test → Staging → Production

**Disclaimer:*- The release lifecycle should include all static testing environments required to reach Production. You might only need Test → Production, or Staging → Production. I included Test → Staging → Production because, as an industry, we have coalesced around four environments.

The subsequent Project Channels are:

Default (uses the default lifecycle or an ephemeral environment): build artifacts require a pre-release tag and can only be created from non-main branches.
Release (uses release lifecycle): build artifacts cannot have a pre-release tag and can only come from the main branch.

GitHub Actions (or really any build server) doesn’t make dynamically selecting channels based on branches any easier. They require using a hard-to-decipher if/then/else command in the build definition. For example, ${{ github.ref == ‘refs/heads/main’ && vars.OCTOPUS_RELEASE_CHANNEL || vars.OCTOPUS_DEFAULT_CHANNEL }}.

Running multiple versions in Production

Occasionally, REST APIs and other backend services must run multiple versions in Production for backward compatibility. For the recommendations below, my example application has three versions: v1.x, v2.x, and v3.x.

The main branch represents the latest version (v3.x)
Separate branches for each version (v1.x and v2.x)
Each version branch is treated like a “trunk”
- Changes are made in short-lived branches that were branched off the version branch.
- Merging into those version branches requires a pull request.

Within Octopus, you’ll only need one lifecycle:

Release: Test → Staging → Production

But the Project will have four Channels:

Default
- Uses an ephemeral environment
- Build artifacts require a pre-release tag and can only come from non-version or main branches.
vCurrent
- Uses release lifecycle
- Build artifacts cannot have a pre-release tag
- Build artifacts must come from the main branch
- Build artifacts version must be <= 3.x
V2
- Uses release lifecycle
- Build artifacts cannot have a pre-release tag
- Build artifacts must come from the v2 branch
- Build artifacts version must be between 2 and 2.999999
V1
- Uses release lifecycle
- Build artifacts cannot have a pre-release tag
- Build artifacts must come from the v1 branch
- Build artifacts version must be between 1 and 1.999999

Ephemeral environments make this significantly easier, as you can spin up a sandbox for a change for any version and verify it before merging into the appropriate branch. If you cannot use ephemeral environments, I’d recommend setting up a couple of static development environments and configuring a lifecycle that lets you deploy to any of them. The downside is that a person must determine which static development environment to use.

Conclusion

A Production incident is not the time to improvise a deployment pipeline. Steps shouldn’t be skipped to “go faster.” All too often, a “simple change” that isn’t properly vetted causes a bigger issue. But that is essentially what a hotfix pipeline is designed to do. It skips important steps in the normal Production deployment pipeline to save time. To resolve a Production incident, you want a well-tested and well-used pipeline, so you know you aren’t introducing even more risk. The time required to create and improve a hotfix pipeline is better spent improving the Production deployment pipeline. Once the Production deployment pipeline takes less than an hour to be ready for deployment to Production, the need for a hotfix pipeline will be all but eliminated.