The AWS Well-Architected framework recommends staggered deployments, noting that:

These techniques contribute to safer and more reliable software deployment and release processes.

In the previous post, you created a project that used a Claude agent step to categorize commits.

In this post, you will create a sample project that demonstrates a progressive rollout through multiple production environments.

Return to the series index.

Prerequisites

• An Octopus Cloud account. If you don't have one, you can sign up for a free trial.
• The Octopus AI Assistant Chrome extension. You can install it from the Chrome Web Store.

:::div{.hint} The Octopus AI Assistant will work with an on-premises Octopus instance, but it requires more configuration. The cloud-hosted version of Octopus doesn't need extra configuration. This means the cloud-hosted version is the easiest way to get started. :::

Creating the project

Paste the following prompt into the Octopus AI Assistant and run it to create a sample project with a progressive rollout:

Create a new progressive deployment project called "18. Progressive rollout".

The resulting project models a gradual production rollout by promoting the same release through progressively larger slices of production.

The AI Assistant creates a lifecycle with the environments Prod 10, Prod 50, and Prod 100. The lifecycle captures the different stages of the rollout as a percentage of production traffic, enforces the deployment order, and has the project deploy a release to each environment in turn.

How the progressive rollout works

The project creates a custom lifecycle called Progressive with four phases:

• Development
• Prod 10
• Prod 50
• Prod 100

Each lifecycle phase targets a single environment, and the project uses a runbook to explicitly trigger the next deployment after the current one succeeds.

The deployment process starts with a Deploy App step that simulates deploying an application by printing Deploying app to the task log. It is followed by a Simulate Failure step that acts as a validation gate. This step checks the prompted variable Project.SimulateFail, and if it is set to True, the deployment exits with an error and the rollout stops.

If the validation step succeeds, the process runs a community step template called Run Octopus Deploy Runbook. This step starts a runbook named Deploy Release to promote the current release to the next environment. This works around a limitation where Octopus prevents a deployment to the next environment until the current one is complete, so you cannot trigger a deployment to Prod 50 while the Prod 10 deployment is still running. By having a runbook trigger the deployment after a short delay, we can be sure the current deployment has completed before the next one starts.

The Run Octopus Deploy Runbook step is configured to run in the Prod 10 and Prod 50 environments. It dynamically chooses the next environment with the following logic:

• When the current environment is Prod 10, it triggers a deployment to Prod 50
• When the current environment is Prod 50, it triggers a deployment to Prod 100

The step also passes the current release ID into the runbook as the prompted variable Project.Release.Id, ensuring the same release is promoted through each stage of the rollout.

The runbook itself contains a single Sleep step that waits for 60 seconds before using the Octopus API to create the next deployment. This pause allows the current deployment to complete before the next rollout stage begins.

In practice, the rollout looks like this:

• You create a release and deploy it to Development
• You promote the release to Prod 10
• The Run Octopus Deploy Runbook step automatically starts the Deploy Release runbook
• The runbook waits 60 seconds and then creates a deployment of the same release to Prod 50
• When the Prod 50 deployment succeeds, the same pattern is used to create the final deployment to Prod 100
• If there are any failures, the rollout stops

Customizing the rollout

The Deploy Release runbook initiates a deployment to the next production environment after a short delay. This may be customized to instead schedule a deployment at a specific time, which allows the rollout to be paused for a longer period of time before continuing. You could, for example, only roll out to 100% of production traffic during off-peak hours, or after the release has been validated in Prod 50 for a full day.

You may also consider preventing release progression if a deployment fails. This ensures that a failed release cannot be promoted to the next environment until the issue is resolved. A blocked release will also prevent any scheduled deployments from taking place.

Comparing tenants and environments

This example used environments to represent progressive rollouts. It is also possible to use tenants to represent progressive rollouts. However, there are benefits to using environments:

• Environments are easier to visualize in the Octopus UI
• Lifecycles enforce the progression of releases through environments, which in turn progressively advance the rollout
• The ability to block release progression after a successful deployment is only available for environments, not tenants

For these reasons, environments are the recommended approach for modeling progressive rollouts in Octopus.

What just happened?

You created a sample project with:

• A custom lifecycle called Progressive that promotes releases through Development, Prod 10, Prod 50, and Prod 100
• A scripted deployment process that simulates an application deployment and then validates the result before continuing
• A prompted variable that can intentionally fail the validation step to stop the rollout
• A community step template that runs a Deploy Release runbook to promote the same release to the next production environment
• A runbook with a delayed API call that chains the rollout from Prod 10 to Prod 50, and then from Prod 50 to Prod 100

What's next?

The next step is an example of blue/green deployments.

For most teams, centralizing audit logs in the same SIEM tool they already watch is more than an added advantage, it is a compliance requirement, and "audit log to SIEM" stays a busy search term precisely because so many tools make it harder than it should be.

In this guide you will stream Octopus audit events into Grafana Cloud over OpenTelemetry, query them with LogQL, and fire a Slack alert the moment something is deleted.

Because the transport is OpenTelemetry, you can take what you learn here and stream the same events to any OpenTelemetry destination, whether that is Datadog, Honeycomb, Elastic, or a self-hosted collector."

Where Octopus audit data lives

Octopus gives you three ways to reach audit data, and it helps to know which one you are reaching for.

• The Audit tab (Configuration, then Audit) is the in-product view. It is great for browsing individual events, filtering by user or date, and expanding a single change to see exactly what was modified.
• The Audit Stream pushes those same events out to an external system as they happen. This is the path this article covers. It supports OpenTelemetry (OTLP) alongside direct integrations for Splunk and Sumo Logic.
• Compliance Reports, also in Platform Hub, are the purpose-built path for Governance, Risk, and Compliance (GRC) reporting. If your primary need is producing GRC evidence rather than raw log search, that is where to look. It complements the streaming setup here rather than replacing it.

In other words, the Audit tab and Audit Stream give you the raw events, and Compliance Reports streamline the reporting on top.

Architectural overview

Before we hop into a demo, It is worth getting a grasp on how this will all work.

Fundamentally, Octopus emits audit events over OTLP. A collector receives them and forwards them to Grafana Cloud, where they land in Loki and become queryable in Explore. From there, an alert rule watches for events and notifies Slack.

:::figure

:img{ src="/blog/img/stream-audit-logs-to-grafana-cloud/architecture-diagram.png" alt="A diagram showing Octopus using OLTP to ngrok, which fronts Grafana Alloy and Grafana Cloud." loading="lazy" }

::figcaption[Octopus streams over OTLP, Grafana Alloy forwards to Grafana Cloud, and Loki becomes the searchable, alertable home for your audit trail.]

:::

Prerequisites

• An Octopus instance with the Audit Stream available.
• A free Grafana Cloud account.
• Grafana Alloy, the OpenTelemetry Collector distribution Grafana recommends, running as the receiver and forwarder.

You might ask, "why put a collector in the middle instead of pointing Octopus straight at Grafana Cloud?" Simple. For reliability and control.

The collector batches records, holds the Grafana Cloud credentials in one place, and gives you a single spot to add processing or route to a second backend later. It also keeps Octopus configuration simple: Octopus only ever talks to the collector.

Step 1: Set up the Grafana Cloud destination

A free tier Grafana Cloud account includes 50 GB of log ingestion per month with 14 days of retention, which is plenty for an audit trail demo.

Once your stack exists, open the connection details for the OTLP endpoint. In the Grafana Cloud portal, go to your stack and find the OpenTelemetry tile, or open the stack's OTLP connection page directly.

:::figure

:img{ src="/blog/img/stream-audit-logs-to-grafana-cloud/grafana-otlp-connection-details.png" alt="Grafana OLTP connection details page" loading="lazy" }

::figcaption[The OTLP connection page gives you the gateway endpoint and your instance ID. Generate an API token here to get the third value.]

:::

You are after the following three values:

• OTLP Endpoint, something like https://otlp-gateway-prod-us-west-0.grafana.net/otlp. The region in that hostname will match your stack.
• Instance ID, a numeric value such as 1714216. This is the username half of the credentials.
• API Token. Click Generate now, give the token a name like octopus-audit-stream, keep the default scopes (which include logs:write), and create it. Copy the token, it is shown only once. This is the password half.

Logs sent over OTLP land in Loki. Grafana Cloud promotes the OpenTelemetry service.name resource attribute to the Loki stream label service_name, which is how you will find the data later. Octopus sets this to Octopus Deploy, so your query will start with {service_name="Octopus Deploy"}.

Step 2: Configure the OpenTelemetry collector (Grafana Alloy)

In Grafana Alloy, create the configuration file. It does three jobs: receive OTLP from Octopus, batch the records, and export them to Grafana Cloud with basic authentication.

cat > config.alloy <<'EOF'
// 1. Receive OTLP over HTTP (Octopus sends http/protobuf) and gRPC.
otelcol.receiver.otlp "octopus" {
  http {
    endpoint = "127.0.0.1:4318"
  }

  grpc {
    endpoint = "127.0.0.1:4317"
  }

  output {
    logs = [otelcol.processor.batch.default.input]
  }
}

// 2. Batch records before export to reduce request volume.
otelcol.processor.batch "default" {
  output {
    logs = [otelcol.exporter.otlphttp.grafana_cloud.input]
  }
}

// 3. Authenticate to Grafana Cloud with the stack instance ID and API token.
otelcol.auth.basic "grafana_cloud" {
  username = "YOUR_INSTANCE_ID"
  password = sys.env("GRAFANA_CLOUD_API_TOKEN")
}

// 4. Export to the Grafana Cloud OTLP gateway. Logs land in Loki.
otelcol.exporter.otlphttp "grafana_cloud" {
  client {
    endpoint = "https://otlp-gateway-prod-us-west-0.grafana.net/otlp"
    auth     = otelcol.auth.basic.grafana_cloud.handler
  }
}
EOF

Walking through the two values that matter most:

• The exporter endpoint is the OTLP gateway from your connection details
• The otelcol.auth.basic block is the authentication. Grafana Cloud expects HTTP Basic auth where the username is your instance ID and the password is the API token. Replace YOUR_INSTANCE_ID with the numeric instance ID, and keep the token out of the file by reading it from an environment variable.

Start Alloy with the token in the environment:

export GRAFANA_CLOUD_API_TOKEN='glc_your_token_here'
alloy run config.alloy --storage.path=./alloy-data

Alloy logs that it is listening. You should see the OTLP servers come up:

level=info msg="Starting GRPC server" component_id=otelcol.receiver.otlp.octopus endpoint=127.0.0.1:4317
level=info msg="Starting HTTP server" component_id=otelcol.receiver.otlp.octopus endpoint=127.0.0.1:4318

Confirm the receiver accepts data before wiring up Octopus:

curl -sw "\nHTTP %{http_code}\n" -X POST http://127.0.0.1:4318/v1/logs \
  -H "Content-Type: application/json" \
  -d '{"resourceLogs":[{"scopeLogs":[{"logRecords":[{"body":{"stringValue":"hello"}}]}]}]}'

A HTTP 200 means Alloy took the record. If it also reached Grafana Cloud, you will see it in Explore in a moment.

Expose the collector so Octopus can reach it

Octopus Cloud needs a public URL to send to. For a local test, ngrok is the quickest way to expose the Alloy HTTP receiver, the same technique the Octopus and Elastic walkthrough uses:

ngrok http 4318

ngrok prints a public HTTPS URL such as https://4202-12-17-71-220.ngrok-free.app. That, with /v1/logs appended, is what Octopus will target. In a permanent deployment you would run Alloy on a host Octopus can reach directly and skip the tunnel.

Step 3: Point Octopus at the collector

In Octopus, go to Configuration > Audit, and click Stream Audit Log. Choose OpenTelemetry as the provider.

:::figure

:img{ src="/blog/img/stream-audit-logs-to-grafana-cloud/octopus-audit-stream-providers.png" alt="Octopus audit stream providers" loading="lazy" }

::figcaption[Octopus supports OpenTelemetry, Splunk, and Sumo Logic out of the box. OpenTelemetry is the one that keeps you vendor-neutral.]

:::

Fill in the OpenTelemetry fields:

• OpenTelemetry Endpoint URL: Your collector's log endpoint, which is the ngrok URL with /v1/logs on the end, for example https://4202-12-17-71-220.ngrok-free.app/v1/logs.
• OTLP Protocol: HTTP/protobuf.
• Secret: Leave this empty. Authentication to Grafana Cloud is handled by the collector, so Octopus does not need to send any token. This is exactly why the collector sits in the middle.

:::figure

:img{ src="/blog/img/stream-audit-logs-to-grafana-cloud/octopus-audit-stream-otel-config.png" alt="Octopus audit stream OTel config" loading="lazy" }

::figcaption[The endpoint points at the collector, the protocol is HTTP/protobuf, and no secret is needed because the collector authenticates to Grafana Cloud.]

:::

Click Save.

The Stream Audit Log button now shows a green check, which means the stream is active and new events will flow. Historical events are not backfilled, only events from this point forward are streamed.

:::figure

:img{ src="/blog/img/stream-audit-logs-to-grafana-cloud/octopus-audit-stream-active.png" alt="Octopus audit stream active" loading="lazy" }

::figcaption[A green check confirms the stream is live.]

:::

Step 4: Generate events and verify in Grafana Cloud

Trigger a few audited actions so there is something to see. Anything that creates, modifies, or deletes a resource works. For this walkthrough, create an environment, edit it, then delete it. Each of those is a separate audit event.

Now open Explore in Grafana Cloud, select your logs data source, and run:

{service_name="Octopus Deploy"}

The events arrive within seconds.

:::figure

:img{ src="/blog/img/stream-audit-logs-to-grafana-cloud/grafana-explore-audit-events.png" alt="Explore audit events in Grafana" loading="lazy" }

::figcaption[Octopus audit events in Grafana Cloud. The expanded record shows a deleted environment, the Category label, and the exact field-level differences.]

:::

Expand a record and you will see the labels Octopus attaches to every event. These are what make the data useful:

• service_name = Octopus Deploy
• event_name = octopus.audit
• Category = Created, Modified, or Deleted
• Username = the account that made the change
• IpAddress = where the request came from
• SpaceId and the resource ID, such as EnvironmentId
• severity_text = Information

Those labels let you slice the audit trail without parsing message text. If you want every change a specific person made? Filter on Username. And if you want only deletions? Filter on Category:

{service_name="Octopus Deploy"} | Category=`Deleted`

That single query is the foundation of the alert you are about to build.

Step 5: Sending Slack alerts

A searchable audit trail is useful but an audit trail that pages you when something sensitive happens is better. Grafana Alerting has a native Slack integration, so no extra service is needed.

First, create the Slack contact point. In Slack, add an Incoming Webhook for the channel you want, a channel like #grc is a natural home for this.

In Grafana, go to Alerts & IRM > Alerting > Contact points then add a contact point, choose Slack, and paste the webhook URL. Keep that URL secret, anyone who has it can post to your channel.

:::figure

:img{ src="/blog/img/stream-audit-logs-to-grafana-cloud/grafana-slack-contact-point.png" alt="Grafana Slack contact point" loading="lazy" }

::figcaption[Creating the Slack contact point. With a webhook URL, you can leave the recipient and token fields empty.]

:::

Next, create the alert rule. Point it at your logs data source and use a query that counts delete events over a short window. Group the count by the labels you want in the alert, so they survive the aggregation and can be used in the message:

sum by (Category, Username, IpAddress, SpaceId, EnvironmentId) (
  count_over_time({service_name="Octopus Deploy"} | Category=`Deleted` [5m])
)

Add a threshold condition of is above 0, so the rule fires whenever a deletion shows up. Give the rule a label like team = grc and route that label to your Slack contact point in the notification policy.

Set the rule's summary annotation to reference those labels, so the Slack message names the event rather than showing [no value]. Grafana exposes the query's labels as $labels:

Octopus audit alert: {{ $labels.Category }} event by {{ $labels.Username }} from {{ $labels.IpAddress }}

:::figure

:img{ src="/blog/img/stream-audit-logs-to-grafana-cloud/grafana-alert-rule-detail.png" alt="Grafana alert rule detail" loading="lazy" }

::figcaption[The alert rule counts Octopus delete events and fires when the count goes above zero.]

:::

Delete an environment to test it. Within an evaluation cycle the rule moves to Firing, and the instance shows its destination is the Slack contact point.

:::figure

:img{ src="/blog/img/stream-audit-logs-to-grafana-cloud/grafana-alert-instances.png" alt="Grafana alert instances" loading="lazy" }

::figcaption[One firing instance, labelled team=grc, routed to the Slack contact point.]

:::

A message lands in your channel naming the event, the user, and the source IP.

:::figure

:img{ src="/blog/img/stream-audit-logs-to-grafana-cloud/slack-grc-alert.png" alt="Slack GRC alert" loading="lazy" }

:::

Use any backend

The reason to do this over OpenTelemetry rather than a proprietary integration is portability. Nothing in the Octopus configuration is Grafana-specific. Octopus speaks OTLP to a collector, full stop.

To send the same audit stream to Datadog, Honeycomb, Elastic, or a self-hosted backend, you change the collector's exporter and leave everything else alone. The receiver stays the same, the Octopus Audit Stream config stays the same, additionally you can fan out to two destinations at once by listing two exporters.

That is the whole point of standardizing on OpenTelemetry.

Your audit trail, wherever you watch it

Octopus has been recording who did what since long before you turned this on. The work here was not generating the data, but moving it to where your team looks. Because the transport is OpenTelemetry, that move is a single endpoint away from any SIEM tool you run.

If you want to try it, spin up a free Grafana Cloud account and read the Audit Stream documentation for the exact fields.

If your focus is governance and compliance reporting, look at Compliance Reports.

Happy deployments!

• The challenges of maintaining collections of MCP servers.
• Why simple tools can lead to higher token usage.
• Introducing the Octopus Easy Mode MCP server.
• Demonstrating how the Octopus Easy Mode MCP server can be used to expose runbooks as MCP tools.

All examples in this post are copy and paste prompts, so you will have a working MCP server executing runbooks in 30 minutes.

:img{ src="/blog/img/mcp-easy-mode/diagram.png" alt="Architecture diagram" }

Introduction

Model Context Protocol (MCP) servers are the new AI layer specifically designed to support agentic workflows. The protocol has gained an enormous amount of support, and it is reasonable to expect that major software vendors will provide an MCP server. Exposing a combination of MCP servers to your AI harness allows you to complete complex tasks while leaving decisions about which service to call to the AI. Agentic workflows are very much founded on the idea that LLMs can ground themselves with trusted, external sources of truth, use tools to interact with the world, and consume feedback to make decisions about how to complete a task.

Challenges with MCP servers

However, maintaining collections of MCP servers is a non-trivial challenge. End users have to maintain a list of servers, which is challenging to standardize across an organization, and with the added complexity of embedding credentials in the mcp.json file. Like any desktop software, local MCP servers also need to be kept up to date, while remote MCP servers must be hosted and maintained by a dedicated team.

Exposing a collection of general-purpose tools to an LLM also increases token use. LLMs are quite capable these days of reasoning about how to complete a task, but this comes at the cost of lengthy chain-of-thought reasoning as the LLM works out how to combine otherwise disparate tools.

And there will always be gaps in MCP server coverage. A server may not be available, network security rules may prevent access, or the task to be automated may be too complex and bespoke for an LLM to reliably complete.

Octopus Easy Mode MCP server

The Octopus Easy Mode MCP server is a community project that takes a different approach to traditional MCP servers by exposing runbooks as MCP tools. This allows any process that can be automated with a runbook to be executed by an LLM, which has a number of benefits:

• One MCP server can execute any process that can be automated with a runbook.
• Octopus orchestrates complex processes as a series of deterministic steps.
• Token count is reduced as the LLM can delegate the execution of complex processes to the Octopus server, rather than having to generate all the steps itself.
• Octopus provides security and auditing features, making it possible to restrict and trace the LLMs actions.
• There is no longer any specialized knowledge required to create an MCP server – anyone who can create a runbook can expose it as an MCP tool.

In this post, you'll learn how to use the Octopus Easy Mode MCP server to expose a runbook as an MCP tool and then use that tool to automate a process.

Prerequisites

• An Octopus Cloud account. If you don't have one, you can sign up for a free trial.
• The Octopus AI Assistant Chrome extension. You can install it from the Chrome Web Store.

:::div{.hint} The Octopus AI Assistant will work with an on-premises Octopus instance, but it requires more configuration. The cloud-hosted version of Octopus doesn't need extra configuration. This means the cloud-hosted version is the easiest way to get started. :::

Creating the runbook

The first step is to create a runbook that will be exposed as an MCP tool. In this example, you'll create a runbook that will print the current date and time.

Run the following prompt in the Octopus AI Assistant:

Create a project called "Easy Mode MCP" and then:
* Add a runbook description
* Add a runbook called "Get Current Time".
* The runbook must have a single script step that echoes the current time with the PowerShell command `Get-Date`. 
* Create a single environment called "MCP". Do not create any other environments.
* Configure the runbook to only run in the MCP environment.

:img{ src="/blog/img/mcp-easy-mode/ai-assistant-icon.png" alt="AI Assistant Icon" loading="lazy" }

:img{ src="/blog/img/mcp-easy-mode/ai-assistant.png" alt="AI Assistant Interface" loading="lazy" }

This prompt creates a project to host the runbooks used by the Easy Mode MCP server. It then creates a runbook that you'll call from an MCP client.

Run the MCP Server

The easiest way to run the Octopus Easy Mode MCP server is to use the Docker image. The following mcp.json file can be used to configure the server:

{
  "servers": {
    "easymode": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", 
        "--rm", 
        "-i",
        "--pull=always",
        "-e", "EASY_MODE_MCP_TRANSPORT=stdio", 
        "-e", "EASY_MODE_MCP_AUTH_TYPE=none", 
        "-e", "EASY_MODE_MCP_OCTOPUS_URL=https://yourinstance.octopus.app", 
        "-e", "EASY_MODE_MCP_OCTOPUS_API_KEY=API-APIKEYGOESHERE", 
        "-e", "EASY_MODE_MCP_OCTOPUS_SPACE_ID=Spaces-##", 
        "ghcr.io/octopussolutionsengineering/octopuseasymodemcp:latest"],
      "timeout": 600000
    }
  }
}

Replace the following values in the mcp.json file:

• EASY_MODE_MCP_OCTOPUS_URL with the URL of your Octopus instance.
• EASY_MODE_MCP_OCTOPUS_API_KEY with an API key that has access to the runbook you created.
• EASY_MODE_MCP_OCTOPUS_SPACE_ID with the ID of the space that contains the runbook you created.

Now run the prompt from your chat client:

Get the current time

:::div{.hint} Your MCP client may be able to return the date and time without needing to call an MCP server. If so, you can force the LLM to call the Easy Mode MCP server with the prompt Get the current time from the easymode mcp server. :::

The MCP server will create a new snapshot of the runbook, run it, and return the result.

Importantly, you did not have to instruct the LLM to run a runbook. The Easy Mode MCP server does not require the end user to know that they are running runbooks, or even that the server is backed by Octopus. The runbooks are exposed directly as tools.

You can see this by asking the LLM to list the available tools from your chat client:

List the available tools

Passing parameters to the tool

Prompted variables are treated as parameters to the tool. For example, you can create a runbook that takes a name as a parameter and returns a greeting.

Run the following prompt in the Octopus AI Assistant:

Create a runbook called "Greet User" in the "Easy Mode MCP" project and then:
* Add a runbook description
* Add a single prompted variable called "Name" with the description "The name of the user to greet" and set the default value to "World".
* Scope the "Name" variable to the "Greet User" runbook.
* Add a single script step that echoes "Hello, #{Name}!".
* Configure the runbook to only run in the MCP environment.

Restart the MCP server to pick up the new tool, and then run the following prompt from your chat client:

Greet the user "Finn"

:::div{.hint} The process of restarting the MCP server is different with each client. Visual Studio Code allows you to restart the MCP server by clicking the "Restart" link above the MCP server when editing the mcp.json file:

:img{ src="/blog/img/mcp-easy-mode/vs-code-mcp-json.png" alt="VSCode mcp.json" loading="lazy" } :::

The MCP client is smart enough to know the name Finn must be passed to the Name variable in the Greet User runbook, and the MCP server will return the greeting.

Adding elicitation

Elicitation is the process of asking the user for information that is required to complete a task. The Octopus Easy Mode MCP server supports elicitation by adding manual intervention steps to a runbook.

Run the following prompt in the Octopus AI Assistant:

Create a runbook called "Welcome User" in the "Easy Mode MCP" project and then:
* Add a runbook description
* Add a single manual intervention step called "Ask for Name" with the instruction "Please enter your name" and the prompt "What is your name?".
* Add a single script step that echoes "Hello, #{Octopus.Action[Ask for Name].Output.Manual.Notes}!".
* Configure the runbook to only run in the MCP environment.

Restart the MCP server to pick up the new tool, and then run the following prompt from your chat client:

Welcome the user

You will be asked to enter your name and The MCP server will then return the greeting.

:::div{.warning} Not all MCP clients support elicitation. This post was tested with Visual Studio Code and the GitHub Copilot Chat extension. :::

You can automatically add generated notes to the manual intervention by setting EASY_MODE_MCP_AUTO_POPULATE_INTERVENTION_NOTES to True:

{
  "easymode": {
    "type": "stdio",
    "command": "docker",
    "args": ["run",
      "--rm",
      "-i",
      "--pull=always",
      "-e", "EASY_MODE_MCP_TRANSPORT=stdio",
      "-e", "EASY_MODE_MCP_AUTH_TYPE=none",
      "-e", "EASY_MODE_MCP_OCTOPUS_URL=https://yourinstance.octopus.app",
      "-e", "EASY_MODE_MCP_OCTOPUS_API_KEY=API-APIKEY",
      "-e", "EASY_MODE_MCP_OCTOPUS_SPACE_ID=Spaces-##",
      "-e", "EASY_MODE_MCP_AUTO_POPULATE_INTERVENTION_NOTES=True",
      "ghcr.io/octopussolutionsengineering/octopuseasymodemcp:latest"],
    "timeout": 600000
  }
}

The content placed into the notes section can be defined with the EASY_MODE_MCP_AUTO_POPULATE_INTERVENTION_NOTES_VALUE environment variable:

{
  "easymode": {
    "type": "stdio",
    "command": "docker",
    "args": ["run",
      "--rm",
      "-i",
      "--pull=always",
      "-e", "EASY_MODE_MCP_TRANSPORT=stdio",
      "-e", "EASY_MODE_MCP_AUTH_TYPE=none",
      "-e", "EASY_MODE_MCP_OCTOPUS_URL=https://yourinstance.octopus.app",
      "-e", "EASY_MODE_MCP_OCTOPUS_API_KEY=API-APIKEY",
      "-e", "EASY_MODE_MCP_OCTOPUS_SPACE_ID=Spaces-##",
      "-e", "EASY_MODE_MCP_AUTO_POPULATE_INTERVENTION_NOTES=True",
      "-e", "EASY_MODE_MCP_AUTO_POPULATE_INTERVENTION_NOTES_VALUE=Your custom note",
      "ghcr.io/octopussolutionsengineering/octopuseasymodemcp:latest"],
    "timeout": 600000
  }
}

:::div{.hint} Setting the EASY_MODE_MCP_AUTO_POPULATE_INTERVENTION_NOTES environment variable to True allows you to run runbooks that contain manual intervention steps without any user interaction. This is useful for MCP clients that do not support elicitation or for automating processes that require manual intervention. :::

Practical examples

Here are some practical Runbooks that you might expose to an MCP server.

Creating cloud resources

A common scenario for DevOps teams is to provision new cloud resources. This is often done with a combination of Terraform and Octopus.

Run the following prompt in the Octopus AI Assistant:

Create a runbook called "Create EC2 Instance" in the "Easy Mode MCP" project and then:
* Create a feed called "Docker Hub" pointing to "https://index.docker.io" using anonymous authentication.
* Add a runbook description
* Add a Terraform Apply step to the runbook called "Create EC2 Instance" with the following configuration:
```
# A mocked Terraform configuration simulating the construction of an EC2 instance
output "ec2_instance_id" {
  value = "i-1234567890abcdef0"
}
```
* Use the "Hosted Ubuntu" worker pool.
* Configure the Terraform step to use the execution container image "octopusdeploy/worker-tools:6.6.4-ubuntu.22.04" from the "Docker Hub" feed
* Add a step to run a script that writes `Your instance is #{Octopus.Action[Apply a Terraform template].Output.TerraformValueOutputs[ec2_instance_id]}` as a highlight.
* Configure the runbook to only run in the MCP environment.
* The runbook must be untenanted.

Restart the MCP server to pick up the new tool, and then run the following prompt from your chat client:

Create a new EC2 instance

Debugging a Kubernetes application

In this example, we'll imagine that a support team needs to restart a Kubernetes application. The runbook will delete the pod, triggering a restart.

Run the following prompt in the Octopus AI Assistant:

Create a runbook called "Restart K8s Web App" in the "Easy Mode MCP" project and then:
* Define the first step as a kubectl script step to the runbook called "Restart K8s Web App"
* Use the "Hosted Ubuntu" worker pool.
* Configure the kubectl step to use the execution container image "octopusdeploy/worker-tools:6.6.4-ubuntu.22.04" from the "Docker Hub" feed
* Add a script that checks for a pod called "my-web-app-pod", and if it exists, deletes it. If the pod doesn't exist, the script should write a message to the log and exit successfully.
* Use client side apply in the Kubernetes step (the mock Kubernetes cluster only supports client side apply).
* Disable verification checks in the Kubernetes steps (the mock Kubernetes cluster doesn't support verification checks).
* Enable retries on the K8s deployment step.
* Define the second step as a Slack notification step to the runbook called "Notify Slack" that sends a message to the channel "#k8s-notifications" with the message "The K8s Web App has been restarted." using the web hook url "https://mockslackwebhook.octopusdemos.com/".
* Configure the runbook to only run in the MCP environment.
* The runbook must be untenanted.

---

Create a token account called "Mock Token".

---

Create a feed called "Docker Hub" pointing to "https://index.docker.io" using anonymous authentication.

---

Create a Kubernetes target with the tag "Kubernetes", the URL https://mockk8s.octopusdemos.com, using the health check container image "octopusdeploy/worker-tools:6.5.0-ubuntu.22.04" from the "Docker Hub" feed, using the token account, and the "Hosted Ubuntu" worker pool. Scope the target to the "MCP" environment.

Restart the MCP server to pick up the new tool, and then run the following prompt from your chat client:

Restart the Kubernetes Web App

What is neat about this example is that we have captured a lot of business logic in the runbook. The pod to be deleted is defined, eliminating the need for the end user to know which pod to delete. The Slack notification step is also defined, so the team is notified when the pod is restarted.

While this logic could be captured in an LLM skill, you can imagine how many tokens would be required for the LLM to reason about the steps to restart a Kubernetes application and send a Slack notification. By exposing the process as a deterministic set of steps in a runbook, the LLM only needs to know that a tool exists to restart the Kubernetes application, and it can delegate execution of that process to the Octopus server.

Bootstrapping a new project

Here is an example where we create a runbook to call the AI Assistant to create a new Terraform project. The Octopus - Prompt AI step allows you to run the same prompts you have been typing into the AI Assistant directly from a runbook.

Run the following prompt in the Octopus AI Assistant:

Create a runbook called "Create new Terraform project" in the "Easy Mode MCP" project and then:
* Define the first step as an "Octopus - Prompt AI" step
* Set the prompt to "Create a new Terraform project with the following name: #{ProjectName} in the #{Octopus.Space.Name} space." and enable auto approve.
* Add a prompted variable called "ProjectName" with the description "The name of the new Terraform project" and scope it to the "Create new Terraform project" runbook.
* Configure the runbook to only run in the MCP environment.
* The runbook must be untenanted.

You will need to create an API key for the "Octopus - Prompt AI" step and define it in the Project.Octopus.Api.Key variable.

Restart the MCP server to pick up the new tool, and then run the following prompt from your chat client:

Create a new Terraform project called "My New Project"

A new project will be created in the same space as the runbook to deploy a sample Terraform configuration.

You're now chaining AI agents:

1. The MCP client calls the Easy Mode MCP server
2. The Easy Mode MCP server calls a runbook
3. The runbook calls the AI Assistant to create a new Terraform project
4. The AI Assistant calls an LLM to create a new Terraform project

Governance and compliance

Because the Easy Mode MCP server is backed by Octopus, it inherits all the governance and compliance features of Octopus.

You get audit logs showing what was run, when, and a persistent log of all the output:

:img{ src="/blog/img/mcp-easy-mode/audit-logs.png" alt="Audit Logs" loading="lazy" }

These logs can optionally be sent to an external log aggregation service, such as Splunk or Datadog, for long-term retention and analysis.

The runbooks can be subject to Platform Hub policies, and can consume process templates.

Runbook events can trigger webhooks to notify external systems of runbook execution.

All credentials are centrally managed and can be sourced from external secret management systems, such as HashiCorp Vault.

Octopus provides a robust platform with proven governance and compliance features, all of which are now available to AI agents through the Easy Mode MCP server.

Difference between the Easy Mode MCP server and the Octopus MCP server

Octopus provides a general purpose MCP server that allows MCP clients to execute common Octopus operations, such as creating releases, deploying releases, running runbooks, getting deployment logs, etc.

The Octopus MCP server is more than capable of running runbooks, but it does not inherently know about the existence of runbooks, nor does it have a reason to link a runbook to a specific task.

For example, to run the "Get Current Time" runbook, you would write a prompt like this:

Run the runbook "Get Current Time" in the "Easy Mode MCP" project in the "MCP" environment in the "Default" space.

This command queries the space to get the space ID, the project to get the project ID, and the runbook to get the runbook ID. It then runs the runbook and returns the result. It then executes the runbook and returns the result.

In Claude Code, this was the token usage:

Usage by model:
    claude-haiku-4-5:  549 input, 17 output, 0 cache read, 0 cache write ($0.0006)
       claude-opus-5:  16 input, 1.5k output, 157.8k cache read, 12.7k cache write ($0.1956)

Running the same runbook with the Easy Mode MCP server, the token count is significantly lower:

Usage by model:
    claude-haiku-4-5:  521 input, 14 output, 0 cache read, 0 cache write ($0.0006)
       claude-opus-5:  4 input, 145 output, 29.0k cache read, 5.0k cache write ($0.0497)

By directly exposing runbooks as tools, the Easy Mode MCP server provides a more efficient way for LLMs to execute runbooks, reducing token usage and improving performance.

Conclusion

The Easy Mode MCP server provides a simple way for AI agents and MCP clients to execute Octopus runbooks as tools. This means AI-based workflows gain the scale, reliability, auditability, governance, and convenience of Octopus. And because most of the work is performed by Octopus, AI agents reduce their token use by offloading the execution of complex processes to Octopus.

So teams make a pragmatic choice: stay on Octopus Server and deal with the cloud migration later. But by extension then they continue to manage Octopus upgrades and operating system patching too; and have to accept they won't have access to new Octopus features as they come out.

We've watched this play out with a number of large enterprises. One of them is a major global financial services institution in the middle of a significant undertaking: migrating over a decade's worth of legacy deployment infrastructure to Octopus. Thousands of pipelines and years of accumulated configuration. A migration that is touching nearly every team in the organization.

Going straight to Octopus Cloud is the obvious goal — less infrastructure to manage, no platform to maintain. But it's being blocked by a straightforward problem: Octopus Cloud has no way to reach the systems that matter most—their internal Artifactory instance, and their GitHub Enterprise server and other internal systems. In a regulated environment, asking the security team to open inbound ports to a third-party SaaS platform isn't a conversation that team wants to have.

Enter the Octopus Connection Agent, available from July 2026.

How it works

The Connection Agent is a lightweight Docker container you run inside your own network. When it starts, it opens a secure, outbound-only connection to your Octopus Cloud instance over port 443—the same port used for standard HTTPS traffic.

:::figure

:img{ src="/blog/img/connection-agent-architecture/img-connection-agent-architecture.png" alt="Connection Agent architecture" loading="lazy" }

:::

Because the connection is initiated from inside your network, nothing needs to change on your firewall. No inbound rules. No VPN. No publicly accessible endpoints for your internal systems. The agent authenticates using a private key, and Octopus proxies traffic through it to reach whatever internal resources you need.

The financial services institution in this story ran the Connection Agent as a Kubernetes pod inside their own cluster—fitting naturally into the container infrastructure they already operated. After completing the registration step, the logs confirmed what they'd been waiting for:

[10:55:05 INF] Registering Connection Agent with Octopus instance URL: https://{instance}.octopus.app/api/connectionagent/registrations
[10:55:05 INF] Successfully registered Connection Agent

Within a single maintenance window, their Octopus Cloud instance was reprovisioned, and traffic began flowing through the agent to their internal GitHub Enterprise server. Artifactory followed shortly after. The only firewall edit required: outbound port 443 access to their Octopus Cloud instance and to Octopus's authentication service.

From blocker to enabler

Once the Connection Agent is running, they can get on with populating Octopus Cloud, skipping an entire phase of infrastructure work—requesting and configuring firewall ports—and instead focusing on what actually matters, getting thousands of pipelines migrated and teams deploying to production.

That's not a small thing as every migration carries risk. And adding yet more company infrastructure configuration steps into the mix—in this case extra firewall rules—doesn't actually move the migration forwards, it only further compounds the risk. By using the Connection Agent, the company removes that risk entirely.

Security by design

For teams in regulated industries, security isn't a checkbox—it's a constraint that shapes every decision. The Connection Agent was designed with that in mind.

All connections are outbound-only. The agent initiates the connection; Octopus never reaches into your network. Authentication uses JWT-signed private keys. You can configure ALLOWED_IP_RANGES to lock down exactly which internal hosts the agent can access, so you define the boundary explicitly rather than leaving it open-ended.

At this early stage, we support the publicly accessible Certificate Authorities (CAs). Though if your internal systems use certificates issued by an internal certificate authority—common in financial services—then for now you can use those internal certificates and CAs by setting --ignore-certificate-validation-errors for a given internal domain.

So if you need to pin specific CAs or certificates, let us know!

What's more, if you need redundancy, you can run multiple agents across different Kubernetes clusters.

What's supported

The Connection Agent currently supports:

• Git repositories (e.g. GitHub Enterprise, Bitbucket)
• SMTP servers
• External feeds:
  • Artifactory Generic Feed
  • Azure Container Registry
  • Docker Container Registry
  • GitHub Repository Feed
  • Helm Feed
  • Maven Feed
  • NPM Feed
  • NuGet Feed
  • OCI Container Registry

Support for additional resource types is in active development. Early adopters are working directly with the team to shape what comes next, which means real customer use cases are driving the roadmap.

Action: We would love to hear what other connectors would help. You can share them with us here.

Getting started

The Connection Agent is available as a Docker image on Docker Hub and is limited to a maximum of 5 connections i.e. 5 internal resources as of this writing.

Full documentation can be found here.

If you're on Octopus Server and a connectivity gap is what's been keeping you from moving to cloud, or if you're already on Octopus Cloud and working around the lack of access to your internal systems, talk to your account team as this is the piece that was missing.

Happy deployments!

There were 1 billion commits in 2025. Now, it's 275 million per week, on pace for 14 billion this year if growth remains linear (spoiler: it won't.)

Of course, commits are only useful if they contribute to running software. The challenge for many teams is increasing deployment frequency to match commit frequency. Ideally, changes with limited risk should be deployed with as little friction as possible. But how do you determine something as abstract as a low-risk commit?

Code is just text, and LLMs are incredible at comprehending text. With the new Run Claude Agent step in Octopus, combined with Build Information, Octopus can automatically inspect commits that contribute to a deployment and make intelligent decisions at deploy time based on the commit content.

In the previous post, you created a project simulating updating an Argo CD Manifest file.

In this post, you will create a sample project that uses the Run Claude Agent step to determine if a commit is low risk and can be deployed automatically.

Prerequisites

• An Octopus Cloud account. If you don't have one, you can sign up for a free trial.
• The Octopus AI Assistant Chrome extension. You can install it from the Chrome Web Store.

:::div{.hint} The Octopus AI Assistant will work with an on-premises Octopus instance, but it requires more configuration. The cloud-hosted version of Octopus doesn't need extra configuration. This means the cloud-hosted version is the easiest way to get started. :::

Creating the project

Paste the following prompt into the Octopus AI Assistant and run it to create a sample project using the Run Claude Agent step to categorize commits:

Create a Claude project called "17. Categorize Changes"

The resulting project uses Build Information to associate commits with a package included in the deployment.

You must provide two API keys for this project to work:

1. A GitHub Personal Access Token (PAT) with repo scope saved in the Project.GitHub.PAT project variable
2. A Claude API Key saved in the Project.Claude.ApiKey project variable

The Claude step also requires the claude CLI to be installed on the worker. This can be provided by an Execution Container Image with the following inline Dockerfile:

FROM python:3.11-slim

# 1. Install prerequisites (including libicu for .NET Calamari compatibility)
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    git \
    libicu-dev \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# 2. Install the native Claude Code CLI tool 
RUN curl -fsSL https://claude.ai/install.sh | bash

# 3. Create a global symlink using the exact path from your install log
# This bypasses the $PATH profile restriction for non-interactive runners
RUN ln -sf /root/.local/bin/claude /usr/local/bin/claude

WORKDIR /app
CMD ["/bin/bash"]

:img{ src="/blog/img/octo-easy-mode-17-claude/inline-dockerfile.png" alt="Inline Dockerfile" loading="lazy" }

Categorizing commits

The prompt defined in the Run Claude Agent step is designed to categorize commits:

Your task is to rate the impact of the Git commits that contribute to the new version of the application being deployed.

The following is the list of Git commits:

#{each change in Octopus.Deployment.Changes}
#{each commit in change.Commits}
#{commit.LinkUrl}
#{/each}
#{/each}

Output a value between 1 and 10 based on the impact of the changes in the following categories:

* Security
* User Interface
* Documentation
* Business Logic
* Performance
* Code dependencies
* Code refactoring

The result must be a plain JSON blob like this:

```
{
"security": 1,
"userInterface": 4,
"documentation": 7,
"businessLogic": 3,
"performance": 1,
"dependencies": 9,
"refactoring": 5
}
```

The key to linking Build Information with the Run Claude Agent step is the Octopus.Deployment.Changes variable. You loop over every change, then over every commit in that change. The LinkUrl property is used to embed a link to the commit in the prompt.

You then use the GitHub MCP server to access the commit content:

:img{ src="/blog/img/octo-easy-mode-17-claude/github-mcp.png" alt="GitHub MCP Server" loading="lazy" }

:::div{.hint} It is best practice to use MCP servers to interact with external services over general CLI tools like curl. The tools exposed by MCP servers have limited scope, are tested, and are constrained by the provided credentials. General tools like curl can initiate literally any web request, and LLMs will often go to great lengths constructing web requests to achieve their goals.

The step also includes a range of security and compliance features to restrict the agent. :::

Demonstrating a low-risk change

Start by pushing a Build Information package to Octopus that links to a number of low-risk commits. Save the JSON blob below to a file called buildinfo.json:

{
  "BuildEnvironment": "GitHub Actions",
  "Branch": "main",
  "BuildNumber": "658",
  "BuildUrl": "https://github.com/OctopusSolutionsEngineering/Octopub/actions/runs/29776705931",
  "VcsType": "Git",
  "VcsRoot": "https://github.com/OctopusSolutionsEngineering/Octopub",
  "VcsCommitNumber": "a84a77fd046e329bb10405480486ce9c11db6074",
  "Commits": [
    {
      "Id": "a84a77fd046e329bb10405480486ce9c11db6074",
      "LinkUrl": "https://github.com/OctopusSolutionsEngineering/Octopub/commit/a84a77fd046e329bb10405480486ce9c11db6074",
      "Comment": "Accidentally improved the intern with zero tests"
    },
    {
      "Id": "bb8754a163ec1b278c4e2a3e31bcb868d5d0eb70",
      "LinkUrl": "https://github.com/OctopusSolutionsEngineering/Octopub/commit/bb8754a163ec1b278c4e2a3e31bcb868d5d0eb70",
      "Comment": "Accidentally improved Schrödinger's bug against my better judgment"
    },
    {
      "Id": "1e9e34564e7e5352e4fc168377f5dd2585a6069f",
      "LinkUrl": "https://github.com/OctopusSolutionsEngineering/Octopub/commit/1e9e34564e7e5352e4fc168377f5dd2585a6069f",
      "Comment": "Stared menacingly at the dark arts with zero tests"
    }
  ]
}

If you open the links in the LinkUrl fields, you will see that these commits are gibberish changes to a text file. They are low risk because they don't change any code that is executed in the application.

Push the Build Information package to Octopus using the octopus CLI, replacing the space name with your actual space name.

This is the Bash command:

octopus build-information upload \
  --space "Your Space Name" \
  --package-id "com.octopus:octopub-frontend" \
  --version "20260721.659.1" \
  --file "buildinfo.json" \
  --overwrite-mode "overwrite"

This is the PowerShell command:

octopus build-information upload `
  --space "Your Space Name" `
  --package-id "com.octopus:octopub-frontend" `
  --version "20260721.659.1" `
  --file "buildinfo.json" `
  --overwrite-mode "overwrite"

:::div{.hint} In a production scenario, you would typically automate the generation of Build Information as part of your CI/CD pipeline. This ensures that the information is always up to date and accurately reflects the state of your codebase.

For the purposes of this demonstration, we are manually constructing and pushing mock Build Information to Octopus to simulate different commit scenarios. :::

When you deploy a release of the project, the steps will:

1. Print a list of the commit links
2. Run the Run Claude Agent step to categorize the commits
3. Extract the JSON blob generated by the Claude agent, and determine if any high-risk categories have a value greater than 5
4. If any high-risk categories are detected, a manual intervention step will be triggered, requiring a human to approve the deployment
5. If all categories are low risk, the manual intervention step will be skipped
6. Proceed to a mock deployment step that simulates deploying the application

Since the commits in this example are low risk, each category gets a low score:

:img{ src="/blog/img/octo-easy-mode-17-claude/claude-output.png" alt="Claude Output" loading="lazy" }

Based on these scores, the manual intervention step is skipped, and the deployment proceeds automatically.

Demonstrating a high-risk change

Save the following code to a file called buildinfo.json:

{
  "BuildEnvironment": "GitHub Actions",
  "Branch": "main",
  "BuildNumber": "658",
  "BuildUrl": "https://github.com/OctopusSolutionsEngineering/Octopub/actions/runs/29776705931",
  "VcsType": "Git",
  "VcsRoot": "https://github.com/OctopusSolutionsEngineering/Octopub",
  "VcsCommitNumber": "982860ff9295c75ea3f3f0f963b09f0db3138e4e",
  "Commits": [
    {
      "Id": "7ec4ef85a5aac729b2d3e823307cb4c4caa63d58",
      "LinkUrl": "https://github.com/OctopusSolutionsEngineering/Octopub/commit/7ec4ef85a5aac729b2d3e823307cb4c4caa63d58",
      "Comment": "Enhance URL safety and update footer links for improved security"
    },
    {
      "Id": "982860ff9295c75ea3f3f0f963b09f0db3138e4e",
      "LinkUrl": "https://github.com/OctopusSolutionsEngineering/Octopub/commit/982860ff9295c75ea3f3f0f963b09f0db3138e4e",
      "Comment": "Update dependencies and enhance project configuration for improved compatibility"
    }
  ]
}

Push the new Build Information package to Octopus using the octopus CLI commands provided earlier, replacing the space name with your actual space name.

These commits represent realistic changes that update dependencies and improve security. When you deploy a release of the project with this Build Information, the Run Claude Agent step will categorize the commits and produce a JSON blob with higher scores in the security and dependencies categories:

:img{ src="/blog/img/octo-easy-mode-17-claude/claude-output-high-risk.png" alt="Claude Output High Risk" loading="lazy" }

These score values indicate that the changes are high risk, and the manual intervention step will be triggered, requiring a human to approve the deployment before it can proceed.

What just happened?

You created a sample project with:

• Associated Build Information that links to commits in a GitHub repository
• A Run Claude Agent step that categorizes commits based on their impact
• A step that parses the JSON output from the Claude agent and determines if any high-risk categories are present
• A manual intervention step that is conditionally triggered based on the risk assessment

What's next?

The next step is an example of progressive rollouts through multiple production environments.

This is great until an auditor asks, "Who promoted this, and when?" or an incident traces back to a tag nobody meant to change.

Argo CD is excellent at keeping a cluster in sync with Git, but it has no concept of a release, i.e, no single, frozen artifact that moves from one environment to the next under policy.

In this guide, you will connect Argo CD to Octopus Deploy and turn promotion into a governed release, using the same immutable snapshot to move from Development to Production, gated by approval.

The Audit Stream and connection reuse the setup from our EKS connection walkthrough, so this article stays focused on promotion.

Why "promotion" is hard in vanilla Argo CD

Argo CD treats each Application as an independent unit. The dev install of your app and the production install are two separate Applications with no codified relationship between them. Nothing in Argo CD knows that "web in production" should receive exactly what "web in dev" was verified with.

Similarly, depending on your organization or team, promoting to an environment could mean a separate namespace or an entirely new cluster, both of which Octopus Deploy can handle.

That fragmented trail is slow and painful to reassemble at exactly the moments you need it most. Like when an auditor asks who promoted what and when, or when you are mid-incident trying to work out what changed.

Whereas, what you want is a single, frozen release that moves through environments under governance: verified once in Development, promoted unchanged to Production, with the who and when captured automatically.

That leaves two do-it-yourself options for promotion, and both are ad-hoc:

• Hand-edit the image tag in each environment's overlay folder, commit, and let Argo sync. This is fast, but there is no record of intent, no gate, and nothing stopping a typo from shipping a different tag to Production than the one you tested.
• Script a pull request per environment. This is more controlled, but now your promotion logic lives in CI YAML and shell, reinvented per team, drifting as the estate grows.

Whereas, what you want is a single, frozen release that moves through environments under governance: verified once in Development, promoted unchanged to Production, with the who and when captured automatically.

Prerequisites

This walkthrough builds on the cluster and Octopus connection from the EKS connection post. You do not need EKS specifically, but you do need these pieces in place before the promotion steps make sense:

• An Octopus Deploy instance with the Argo CD integration (Octopus Cloud or self-hosted). This is where the project, lifecycle, and release live.
• A Kubernetes cluster you can install into. A local kind cluster is enough. Because the Octopus gateway dials outbound, no ingress or public address is required.
• Argo CD running in that cluster, connected to Octopus through the gateway. If you followed the EKS connection post, reuse that same cluster and its gateway connection. If you are starting fresh, the next section installs Argo CD and registers the gateway from scratch.
• kubectl, helm, and the argocd CLI installed locally.
• A Git repository for your manifests with Kustomize overlays per environment (the demo uses a public GitHub repo), plus a Git credential in Octopus that can push to it.

The architecture setup

For this demo, we're aiming for a single Kubernetes cluster with two namespaces that serve as environments, dev and production, each with its own Argo CD Application.

Octopus owns the release and promotion process, and Git remains the source of truth, while Argo CD applies manifests to the cluster.

:::figure

:img{ src="/blog/img/promote-release-with-argo-cd-and-octopus/architecture.png" alt="How Octopus, Git, and Argo CD interact through commits." loading="lazy" }

::figcaption[Octopus commits the new image tag to the right overlay and triggers a sync through an in-cluster gateway. Argo CD pulls from Git and reconciles each namespace and Octopus never needs inbound access to your cluster.]

:::

The Octopus gateway is a small component you install in the cluster with Helm; it dials outbound to Octopus over gRPC, so nothing in your cluster needs a public address. That means this entire demo can run on a local kind cluster with no ingress.

For an in-depth look at the cluster and gateway connection, see the EKS connection post; here, we install Argo CD, register the gateway, and proceed to promotion.

Install Argo CD with a dedicated octopus account so the gateway has its own scoped identity rather than piggybacking on admin:

helm install argocd argo-cd \
 --repo https://argoproj.github.io/argo-helm \
  --create-namespace --namespace argocd --wait --timeout 10m \
 --values - << 'EOF'
configs:
  cm:
    accounts.octopus: apiKey
  rbac:
    policy.default: "role:readonly"
    policy.csv: |
      g, admin, role:admin
      p, octopus, applications, get, *, allow
      p, octopus, applications, sync, *, allow
      p, octopus, clusters, get, *, allow
      p, octopus, logs, get, */*, allow
EOF

With Argo CD running, register the instance in Octopus (Infrastructure, then Argo CD Instances, then Add Argo CD Instance), paste an auth token for the octopus account, and Octopus generates a Helm command for the gateway.

:::figure

:img{ src="/blog/img/promote-release-with-argo-cd-and-octopus/register-argo-instance.png" alt="Register an Argo CD instance" loading="lazy" }

::figcaption[Registering the Argo CD instance. The service DNS name is the in-cluster address of the Argo CD API server.]

:::

Run the generated Helm command against your cluster, and Octopus confirms the connection: the gateway registers, connects to Octopus, and connects to Argo CD.

:::figure

:img{ src="/blog/img/promote-release-with-argo-cd-and-octopus/install-gateway.png" alt="Install gateway" loading="lazy" }

::figcaption[The gateway bridges Octopus and Argo CD over an outbound connection. No inbound firewall rules required.]

:::

The gateway bridges Octopus and Argo CD over an outbound connection. No inbound firewall rules required.

Map the Applications with annotations

Octopus needs to know which Argo CD Applications belong to which project and environment. You declare that with two annotations on each Application manifest. No per-application configuration is needed in Octopus; the annotations handle the mapping.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: web-dev
  namespace: argocd
  annotations:
    argo.octopus.com/project: argo-web-promotion
    argo.octopus.com/environment: development
spec:
  project: default
  source:
    repoURL: https://github.com/your-org/gitops-web-promotion
    targetRevision: main
    path: overlays/dev
  destination:
    server: https://kubernetes.default.svc
    namespace: dev
  syncPolicy:
    automated: { prune: true, selfHeal: true }
    syncOptions: [ CreateNamespace=true ]

The argo.octopus.com/project annotation ties the Application to the Octopus project, and argo.octopus.com/environment ties it to an Octopus environment. The production Application is identical except name: web-production, argo.octopus.com/environment: production, path: overlays/production, and namespace: production.

When Octopus deploys argo-web-promotion to Development, it now knows web-dev is the Application to update; when it deploys to Production, it updates web-production.

Both overlays are simple Kustomize folders that set the image tag. This is the field Octopus will rewrite:

# overlays/dev/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: dev
resources:
 - ../../base
images:
 - name: nginx
    newTag: "1.27.0"

Building the Octopus project with a Dev to Production lifecycle

Create an Octopus project and give it a lifecycle with two phases, Development and Production. The lifecycle is what makes promotion ordered, which simply means a release must pass through Development before it can reach Production.

Then add the built-in Update Argo CD Application Image Tags step to the deployment process. For each Application matched by annotation, this step retrieves the Git location from the Application, updates the image tag in the manifests, commits the change, and triggers Argo CD to sync. Add a container image reference (the nginx image, from a Docker Hub feed) so the release knows which image to update and what version to pin.

To make the governance visible, add one more step before it: a Manual intervention step scoped to the Production environment only. That is your approval gate. It runs when promoting to Production and is skipped for Development, so it stays fast while Production stays governed.

:::figure

:img{ src="/blog/img/promote-release-with-argo-cd-and-octopus/argo-web-promotion.png" alt="Argo web promotion" loading="lazy" }

::figcaption[Two steps, one governed process. The approval runs only for Production; the image-tag update runs for any environment.]

:::

Create a release and deploy to Development

Create a release in Octopus and select the image version to promote, for example nginx:1.27.2 (a bump from the 1.27.0 currently in the overlays). This release is a frozen snapshot of the process, variables, and package versions. Once created, it is immutable: the version that goes to Production later is the exact version you are about to verify in Development, not whatever happens to sit at Git HEAD.

Deploy the release to Development. Octopus commits the new tag to the dev overlay, and Argo CD syncs the dev namespace:

Credential 'gitops-web-promotion' will be used to access the repository
Committing directly to branch for changes in this environment
Cloning repository https://github.com/your-org/gitops-web-promotion

Within seconds, the dev Application is synced and Healthy on the new tag, while Production is untouched:

$ kubectl get deploy web -n dev -o jsonpath='{..image}'
nginx:1.27.2
$ kubectl get deploy web -n production -o jsonpath='{..image}'
nginx:1.27.0

That contrast is the whole point: the release moved dev to 1.27.2, and Production still runs 1.27.0 because nothing has promoted it there yet.

Promote the same release to Production

Now promote the same release to Production. Because the process has a Production-scoped approval step, the deployment pauses and waits for a human before it touches anything.

:::figure

:img{ src="/blog/img/promote-release-with-argo-cd-and-octopus/deploy-to-production.png" alt="Promoting the release to Production with an approval step." loading="lazy" }

:::

Production promotion stops at the approval gate; the image update and sync below it are queued, not run.

Approve it, and the same flow runs against the production overlay: Octopus commits the tag to overlays/production, and Argo CD syncs the production namespace. Production now gets exactly what was verified in dev, not a freshly hand-edited value.

:::figure

:img{ src="/blog/img/promote-release-with-argo-cd-and-octopus/promotion-result.png" alt="Promotion result" loading="lazy" }

::figcaption[Promotion complete. The same release 1.27.2 that ran in Development is now live in Production.]

:::

The project dashboard shows the end state at a glance: one release, both environments, both healthy, with the live status pulled from Argo CD.

:::figure

:img{ src="/blog/img/promote-release-with-argo-cd-and-octopus/dashboard.png" alt="Project dashboard" loading="lazy" }

::figcaption[Development at 9:06 PM, Production at 9:43 PM after approval. Same release, one predictable shape.]

:::

The governance you got for free

Taking a step back, there are a few things this approach has saved you from:

• An immutable release snapshot. Release 1.27.2 pinned the exact image version. Production could only ever receive what dev verified.

• A Git commit per environment. Each promotion is a commit in your history, attributable and reversible:

07d62d8  Octopus Deploy promoted image 1.27.2   (production overlay)
28e2ace  Octopus Deploy promoted image 1.27.2   (dev overlay)
dfdadc8  Initial GitOps repo

• An approval record. Production promotion required a named human to take responsibility and proceed, captured in the deployment history.

• One view of what is running where. The project dashboard shows every environment and the release it holds, with live health from Argo CD, and you can click into any deployment to see who promoted it and when. That single pane matters more as you scale because your Argo CD Applications might be spread across many instances in different clusters, regions, or accounts, and Octopus gives you one place to see and govern all of them instead of tab-hopping between Argo CD UIs.

None of this is captured by default in the hand-edited-overlay approach. Because the Octopus release is a standard, predictable object, the same governance and policy apply no matter what sits underneath

This ties into the core Platform Hub idea: a single deployment shape and consistent governance across every stack you run.

Going from overlay edits to audited releases

Promotion should not be a YAML edit you hope you got right. With Argo CD connected to Octopus, it becomes a release you can govern.

Argo CD keeps doing what it does best: reconciling Git with your cluster, while Octopus adds a release model and an audit trail to that flow.

The bigger idea here is Platform Hub, which offers you one place to see what is running where, and the same governance and audit across every environment, cluster, and Argo CD instance you run, not just the one in this walkthrough.

If you promote Argo CD deployments by hand today, that is the gap it closes. See how Platform Hub brings your GitOps deployments under one governed roof, read Manage releases and rollbacks with Argo CD for the release mechanics, and start for free!

Joep calls the CNCF landscape a candy shop, and it's a comparison that stuck with me. Just because something's on the shelf doesn't mean it belongs in your cart, and the cost of a bad choice doesn't show up at checkout, it shows up months or years later when someone has to support it.

Watch the episode

You can watch the episode with Joep below.

Inside Platform Engineering with Joep Piscaer

The candy shop problem

Joep's argument is simple but easy to forget in practice, which is that every tool you add to your platform is a tool you now have to operate, secure, and explain to whoever inherits it. He's not against new tooling on principle, he's against choosing it reflexively because it's popular or well-marketed. His rule of thumb is that the best choice is often no choice at all, and that resisting the landscape is itself a skill worth developing, not a sign you're falling behind.

Small teams will build lean platforms

One of the more provocative points Joep made was that a platform team with a budget and an SLA will naturally start building for its own survival, not just for its users. His suggested fix leans further than most people may be comfortable with, keep the team small, ideally under eight people (this is very contextual to the organization), so there's only time for the basics. I liked how he framed a bloated platform as a freight ship rather than a speedboat. Once it's big, you can only change course by a single degree at a time, no matter how good your intentions are.

Talk to your users before you build

Joep was adamant that understanding why you're building something matters more than the build itself, going as far as to say a good developer might spend as little as 20% of their time actually writing code. The rest goes into figuring out what's actually needed. This came up multiple times throughout our conversation. His advice for platform teams is to get out of meetings and sit next to the people doing the work, which he only half-jokingly compared to Fisher-Price's old "soul-crushing meeting" toy.

:::figure

:img{ src="/blog/img/inside-platform-engineering-joep-piscaer/soul-crushing-meeting.png" alt="An image of a satirical Fisher-Price toy box parody designed by Daniel Picard." loading="lazy" }

:::

Vibe coding is changing who the platform needs to support

We spent time on how AI-assisted coding is reshaping who your platform needs to serve. Joep's read is that business users are increasingly vibe-coding their own tools because commodity software rarely fits the way their teams actually work. Once they've got something that works, they just want a URL, not a ticket in your backlog or a crash course in Kubernetes. What struck me was Joep's parallel back to Platform Engineering itself. Just as we're told to go and understand what our users actually need rather than guessing, these business users are doing exactly the same thing for themselves, they just build it rather than ask for it. The job for a platform then becomes hiding all of that complexity so those tools can be deployed simply, while staying lean, secure, and compliant underneath. Whether that's a threat to platform teams or an opportunity probably depends on how ready your platform already is to support something it didn't design.

Happy deployments!

:::div{.hint}

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.

:::

Modern multi-tenancy leans into the ease of allocating dedicated instances to customers, improving isolation, reducing the risk of data leaks, and making it trivial to charge a fair price based on use (instead of subsidizing the noisy neighbors with a volume of under-utilizers).

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.7

Moving away from tenanted applications

There are 3 primary architectural approaches to multi-tenancy.

• A shared application instance and database: Many customers are using the same running instance, with the application taking care of isolating their use and data.
• A shared application instance and a dedicated database: While customers all use the same running instance, their data is stored in a dedicated database, which the application connects to based on the tenant.
• Fully isolated infrastructure: Every tenant has a dedicated instance and database running on an allocation of compute.

The shared approach comes with many drawbacks. The application's code is more complex and requires more testing to reduce the risk of data being displayed to someone who shouldn't see it. Having a dedicated database limits the complexity and risk to the mechanism that selects the appropriate connection string.

When tenants share application instances, databases, or database servers, one tenant can disrupt service for others, for example, by running a resource-intensive operation. It's difficult to pinpoint where the increased load is coming from, and mechanisms for charging based on use often rely on proxy metrics that don't reflect actual use.

With modern hosting options, like containers, it becomes far easier to achieve high resource use at the infrastructure level, removing the need for applications to be made tenant aware. You can avoid all the complexity by giving each tenant their own application and database.

If you have a customer with high resource needs, their use doesn't slow down other customers or cause an outage. If they need a more powerful instance, they can pay to have one.

Shifting tenants to deployment-time

To make modern multi-tenancy work, you need to be able to deploy many more instances and apply the correct configuration when you do so. Modern CD tools take care of this, so you can share a single deployment process with hundreds or thousands of tenants.

When CD tools push a software version out, they can install tenant-specific instances by applying configuration variables. If you have 100 tenants, 3 environments, and 5 settings, the CD tool eliminates the need to manage 1,500 configuration files. They can also help you progressively roll out a new version based on tags so that customers can opt for early access or only the most stable versions.

Multi-tenancy has effectively shifted out of your code and is now managed by your deployment pipeline.

A tenant isn't always a customer

We often think of tenants as "customers," but they can just as easily be physical locations, like a hospital, restaurant, or retail store, that need a dedicated instance. Any time you need a dedicated instance, a tenanted deployment can provide it.

If you want to learn more, we also have a white paper on modern multi-tenancy available for download.

Happy deployments!

:::div{.hint}

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.

:::

For the system you currently work on, how many changes have passed code review but haven't been deployed and enabled for users?

The further this number is from zero, the less likely it is that coding or code review is your constraint.

The difficulty is that, within the software delivery industry, we've grown so used to certain practices that they now look like they belong. When you search for ways to improve software delivery capability, you don't see them. These practices are so deeply embedded that they are overgrown with moss and are indistinguishable from the hills.

When changes are collected in batches after code review, it proves that code review isn't your bottleneck, and coding wasn't either.

The desire for fast software delivery

Writing the code is a very small part of a long value stream. A value stream begins with an opportunity to provide something people want and ends when they get it.

Few organizations are building completely unique software. If the primary factor were speed, they would use something off-the-shelf that's "good enough". As someone has decided to spend vast sums of money creating something bespoke, you need to understand those other needs. What is it that makes it valuable enough to spend so much money on it?

To answer this question, you build the software, make sure it's releasable, and get it into the hands of the people who need to use it. Only then can you see if you're building the right thing.

The two errors

Since AI arrived, many people have proclaimed that the bottleneck has shifted from coding to code review. This isn't quite right, as coding wasn't the bottleneck in the first place (error 1), and it's not code review now (error 2). The reason we think either of these things is constraining the flow of value is that mossy hill we all stare past when we look at the mountains.

:::figure

:img{ src="/blog/img/code-review-not-bottleneck-even-with-ai/deployment-batch-size.png" alt="Chart showing 92% of teams have deployment batch sizes of more than 1 change." loading="lazy" }

::figcaption[Number of changes per deployment batch]

:::

Just 8% of teams deploy changes independently, while 92% deploy in batches. Only 8% are correct when they say the bottleneck moved from coding to code review. For the vast majority, this isn't true.

Batches are signposts

When you ask this batch size question, you peel back the moss and uncover what's beneath. This is how you find the true constraint in your value stream. You might have manual verification steps, a cumbersome change approval board meeting, or no easy way to deploy changes to development, test, and production. These are the things holding you back. Not coding and not code review.

You were likely working in batches before your AI initiative, and AI will certainly result in larger change size and larger batches if you don't pay attention to your constraints. Speeding up the coding stage only adds pressure to the real bottleneck.

Using the constraint to set the pace of your value stream will lead you to invest improvement efforts where they matter most. If you find your retrospectives fail to provide noticeable improvements, it's likely because you're missing that mossy mound. It's the reason some AI initiatives fail to deliver a return on investment, while others succeed.

But… the data

Some studies, like GitLab's 2026 AI Accountability Report, also say that bottlenecks have shifted from coding to code review, but they also overlook the mossy mound. Where they haven't captured the size or number of changes that haven't reached production users, they can't observe the true bottleneck.

Having invested in AI to increase coding speed, you'll now be tempted to invest in solving the code review problem, or to abandon it. If you're working in batches, you'll discover this makes little difference to your ability to deliver valuable software.

The reasons your organization is resisting solving the batch problem are the real problems you need to fix.

Look for the accumulation of changes throughout your process. Identify the true constraint, and apply the five focusing steps to manage it; and that includes making all other stages march at the pace of the constraint.

Happy deployments!

Prerequisites

• An Octopus Cloud account. If you don't have one, you can sign up for a free trial.
• The Octopus AI Assistant Chrome extension. You can install it from the Chrome Web Store.

:::div{.hint} The Octopus AI Assistant will work with an on-premises Octopus instance, but it requires more configuration. The cloud-hosted version of Octopus doesn't need extra configuration. This means the cloud-hosted version is the easiest way to get started. :::

Creating the project

Teams that have adopted GitOps workflows with Argo CD can use Octopus to commit changes to a Git repository to promote changes through environments. The Update Argo CD Application Manifests step in Octopus commits changes to the files referenced by an Argo CD Application.

Paste the following prompt into the Octopus AI Assistant and run it to create a sample project using the Update Argo CD Application Manifest step:

Create an Argo CD Manifest Update project called "16. Argo CD Manifest Update" with the slug "argo-cd-octopub-manifest" using a Git Connection called "Mock" with a random username and the allowed repository "https://mockgit.octopusdemos.com/*"

This prompt creates an example project called 16. Argo CD Manifest Update with the project slug argo-cd-octopub-manifest. The slug is important because it links an Argo CD Application to an Octopus project.

We then create a Git Credentials defining the credentials required to interact with a Git repository. In this example, we are using a mocked Git repository hosted at https://mockgit.octopusdemos.com. This Git repository lets us use Argo CD steps in Octopus without providing credentials or creating a repository on a platform like GitHub.

Behind the scenes, we also create a mock Argo CD Instance called Mocked Argo CD Instance:

:img{ src="/blog/img/octo-easy-mode-16-argocd-manifest-update/argo-cd-instance.png" alt="Argo CD Instance" loading="lazy" }

Typically, to create an Argo CD Instance, you must install the Octopus Argo CD Gateway in the Kubernetes cluster where Argo CD is running. This gateway then registers Argo CD Applications with Octopus and monitors the cluster for any changes.

For this demonstration, however, we register a mock Argo CD Instance and several mock Argo CD Applications. The mock Applications contain the information required for Octopus to modify the correct files in the mock Git repository during a deployment, without requiring an Argo CD cluster.

:::div{.warning} Some features of the mocked Argo CD Instance will always report errors or warnings. For example, the Gateway Connectivity tab will always report an error, because there was never a real Argo CD cluster to connect to. The manifests deployed by Octopus will always report Git drift because the Argo CD Applications are never updated to reflect the changes. And any attempt to sync Applications in Argo CD as part of the Update Argo CD Application Manifests step will fail.

These errors can be ignored or the features disabled without preventing Octopus from completing a deployment. :::

The sample step configuration

The Repository URL setting in the Update Argo CD Application Manifests step defines the Git repository that Octopus will commit to as part of the deployment. The value https://mockgit.octopusdemos.com/repo/argocd is matched to the Mock Git Credentials, providing the step with the credentials required to commit to the repository.

The Path setting, set to octopub-manifest/template/octopub.yml, defines the template file that will be read, have any binding syntax replaced, and persisted to the path defined in the Argo CD Application linked to the project and environment (how these Applications are linked is described later).

To see the contents of these files, check out the mock Git repository:

git clone https://somerandomusername@mockgit.octopusdemos.com/repo/argocd

:::div{.hint} The mocked Git repository accepts literally any username. However, commits made by unrecognized usernames are ignored. The Mock Git Connection created by the AI Assistant has unique and recognized credentials that allow Octopus to persist commits. However, the repository contents are reset periodically, so all commits are eventually reverted.

The contents of the Git repository cloned with the credentials above do not include the commits made by Octopus, as the mock Git server treats them as two separate repositories. :::

View the contents of the sample Argo CD Application:

cat argocd/octopub-manifest/octopub-development.yml

This is the example Argo CD Application manifest.

Note the repoURL field matches the Repository URL setting. The path field, set to octopub-manifest/application/development, specifies the location in the Git repository where Argo CD finds the manifest files to apply to the cluster.

Also note the annotations argo.octopus.com/project.<application name> and argo.octopus.com/environment.<application name>. These annotations link an Argo CD Application to an Octopus project and environment. The step references only Argo CD Applications that match the project's and environment's slugs. The prompt to create the project specified the slug argo-cd-octopub-manifest because this value is hard-coded in the example YAML:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: octopub-manifest-parent-development
  namespace: argocd
  annotations:
    argo.octopus.com/project.octopub-manifest-parent-development: "argo-cd-octopub-manifest"
    argo.octopus.com/environment.octopub-manifest-parent-development: "development"
spec:
  project: default
  sources:
    - name: octopub-manifest-parent-development
      repoURL: https://mockgit.octopus.com/repo/argocd
      # This is the destination folder where the template manifest files are placed
      path: "octopub-manifest/application/development"
      targetRevision: main

  destination:
    server: https://kubernetes.default.svc
    namespace: octopub-manifest-parent-development
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Display the octopub.yml file in the directory specified by the path field:

cat argocd/octopub-manifest/application/development/octopub.yml

This is the file applied by Argo CD:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: octopub-manifest-development
  namespace: argocd
spec:
  project: default
  sources:
    - name: octopub-development
      repoURL: https://mockgit.octopus.com/repo/argocd
      path: "octopub/octopub-frontend"
      targetRevision: main
      helm:
        values: |
          image:
            repository: ghcrfacade-a6awccayfpcpg4cg.eastus-01.azurewebsites.net/octopussolutionsengineering/octopub-frontend
            tag: latest
          mockBackend: true
          overrideTheme: blue

  destination:
    server: https://kubernetes.default.svc
    namespace: octopub-manifest-development
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Now display the template file defined by Path field on the Octopus step:

cat argocd/octopub-manifest/template/octopub.yml

Note that it includes the binding syntax #{Octopus.Environment.Name | ToLower} and #{Project.Frontend.Theme}:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: octopub-manifest-#{Octopus.Environment.Name | ToLower}
  namespace: argocd
spec:
  project: default
  sources:
    - name: octopub-manifest-#{Octopus.Environment.Name | ToLower}
      repoURL: https://mockgit.octopus.com/repo/argocd
      path: "octopub/octopub-frontend"
      targetRevision: main
      helm:
        # Octopus will replace the value for overrideTheme during deployment
        values: |
          image:
            repository: ghcrfacade-a6awccayfpcpg4cg.eastus-01.azurewebsites.net/octopussolutionsengineering/octopub-frontend
            tag: latest
          mockBackend: true
          overrideTheme: #{Project.Frontend.Theme}

  destination:
    server: https://kubernetes.default.svc
    namespace: octopub-manifest-#{Octopus.Environment.Name | ToLower}
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

:::div{.hint} The Project.Frontend.Theme variable is defined on the project. The Octopus.Environment.Name variable is provided as a system variable. :::

:::div{.hint} The pipe in the binding syntax #{Octopus.Environment.Name | ToLower} implements the ToLower filter. :::

The purpose of the Update Argo CD Application Manifests step is to:

• Read the template file (argocd/octopub-manifest/template/octopub.yml)
• Replace any binding syntax with the value of the associated Octopus variable (Project.Frontend.Theme and Octopus.Environment.Name)
• Commit the new file to the file of the same name (argocd/octopub-manifest/application/development/octopub.yml) referenced by the Argo CD Application linked via the argo.octopus.com/project.<application name> and argo.octopus.com/environment.<application name> annotations

This allows Octopus to inject environment-specific configuration into the files referenced by an Argo CD Application as a deployment progresses through environments:

[:img{ src="/blog/img/octo-easy-mode-16-argocd-manifest-update/diagram.png" alt="Argo CD Workflow Diagram" loading="lazy" }](/blog/img/octo-easy-mode-16-argocd-manifest-update/diagram.png)

:::div{.hint}

The Argo CD Application linked to a project and environment is not modified by Octopus. Only the files referenced by the Application are modified. Typically, these files will be plain Kubernetes manifests.

However, using the Argo CD App of Apps pattern, it is possible to modify a child Application referenced by a parent Application. This is the pattern used in this post.

:::

Performing a deployment

Create a new release for the project and deploy it to the Development environment. Note that Octopus commits a change reflecting the new value of the Project.Frontend.Theme and Octopus.Environment.Name variables replaced in the template YAML file:

:img{ src="/blog/img/octo-easy-mode-16-argocd-manifest-update/task-log.png" alt="Octopus Task Logs" loading="lazy" }

As you promote the deployment through environments, each new environment will inject a unique value for the Project.Frontend.Theme and Octopus.Environment.Name variables into the child Argo CD Application manifest.

In a production scenario, Argo CD will detect the changes and apply them to the Kubernetes cluster. Of course, in this example, there was no Kubernetes cluster, since everything is mocked, but you can still observe commits being made to the Git repository.

What just happened?

You created a sample project with:

• A mock Argo CD Instance and a number of mock Applications
• A mock Git Credentials pointing to a mock Git server
• An Update Argo CD Application Manifests step that commits a processed template file back to the mock Git repo

What's next?

The next step is an example of categorizing and summarizing Octopus deployments using AI.

It drops. Not because they forgot how to write code, but because the organization around them has a different risk tolerance. That's the part of the AI productivity conversation we're missing. We keep talking about developer velocity, but rarely talk about compliance velocity. But if you want to increase one, you have to increase the other.

It's not a code-writing problem

The constraint on large software teams hasn't been how fast engineers can write code. Most engineers could ship a weekend project to production in an afternoon. Put those same engineers inside a mid-sized or large company, and the same change takes days or weeks. That's not because the tooling is worse, but because the risk and compliance process around every change is doing exactly what it was built to do.

That's why an initiative that seeks to "generate changes faster with AI" fails to solve our problem. It was already possible to write code quickly; what we struggled with was managing the risk of shipping changes.

Every action has a reaction

This is where physics is a useful metaphor. For every increase in the volume of change, especially in a risk-averse environment, there's an equal and opposite reaction from the organization's risk and compliance functions.

Here's an example. A team is making 100 changes a day. They introduce AI and increase this to 200 changes per day, but production starts falling over twice as often, even though the change failure rate is the same. That causes risk and compliance to take an interest and introduce processes and policies to reduce the failures.

Within a few weeks, the team is back to 100 changes a day. Half of them are AI-authored, but there's no productivity gain to show for it. The system has found its new equilibrium, and it looks a lot like the old one, except for all the new processes that compliance wrapped around it.

There's a second version of this reaction, and it's less about infrastructure and more about experience. Small teams build up deep, shared context about the problem they're solving and the customer they're solving it for. Most software has many authors but one user at a time living through the whole journey. As a team grows, holding that cohesion gets harder, but at least the humans on the team still talk to each other.

Now give every one of those engineers their own AI coding assistant. Each engineer becomes far more productive individually, but each assistant has even less shared context than the humans did. The result is the same pattern: a high volume of change, but a more disjointed product experience, with the end-to-end story getting lost.

The equal-and-opposite reaction to that fragmentation is usually a heavy-handed swing back toward centralization. We saw that a decade ago, when "let every team choose its own tools" gave way to standardized platforms, because nobody could move between teams without relearning their entire stack.

These reactions are rational. They are the result of a system correcting for risk that increases faster than anyone can account for.

The one-way ratchet

There's something even more crucial than the equilibrium problem. Compliance only ever ratchets up; it never ratchets down.

Once a new rule shows up, like a mandatory review step, an extra test suite, or a new sign-off, it rarely gets removed, especially once it's on a regulator's radar. Velocity can go up and down as the team changes. Compliance doesn't work that way. It accumulates.

Imagine a team gets excited about AI and starts generating twenty changes a day instead of one per engineer. Production instability goes up. A data leak that used to happen once a year now happens twenty times. New compliance requirements get bolted on to stop the bleeding. Eventually, the team realizes the strategy isn't working and reverts to its old habits, but the compliance burden doesn't go away with them. They're now doing less, with more overhead, than when they started.

:::figure

:img{ src="/blog/img/the-compliance-ratchet/equal-and-opposite-reaction-diagram.png" alt="Diagram shows change volume increasing, then compliance overhead ratcheting up in response. This results in change volume returning to a lower volume, while the compliance overhead remains." loading="lazy" }

::figcaption[The compliance ratchet in action.]

:::

This is also how bad global solutions get applied to local problems. If one engineer had production access they shouldn't have had and made a mistake, the right fix is local: work out why they had that access and fix it. The wrong fix (but the one organizations reach for when they're not being deliberate) is global: nobody gets production access, ever, for anything. It solves the immediate problem and creates a dozen new ones.

Sometimes it goes even further than the company. A handful of businesses misuse a technology, a regulator responds with a blanket rule, and now everyone on the internet has to click through a cookie banner. That's what happens when a few actors are irresponsible with something new, whether that's self-driving cars, AI, or otherwise. Regulators aren't looking for a reason to step in, but companies force them to through irresponsible decisions.

Ship safer, not just faster

If your company has a new initiative to boost AI-driven productivity, here's the thing worth saying out loud before it starts: We already know risk and compliance will find equilibrium with whatever volume of change you produce. So plan for that from day one.

If every engineer on the team is using AI purely to generate more code, faster, you will accelerate the compliance ratchet. The healthier split is roughly half and half. Half the team should focus on how to make changes faster, and the other half on how to make those changes safer, more compliant, and less risky, with AI doing some of that work, too.

That second half of the work is genuinely interesting, and it's underrated. AI is well-suited to reasoning about risk, not just generating change. It could review a pull request and decide whether a one-line CSS tweak needs a human reviewer at all, while flagging any change that touches the payments pipeline for real scrutiny. It could review the build and decide which of the three hours of automated UI tests are relevant to a README update, rather than running the whole suite, which is what the pipeline does.

None of that reduces the volume of change getting shipped. It reduces the risk associated with it, which is what's actually been holding teams back.

The foundation of every software business is customer trust, and trust is not built by shipping more. If AI makes you ship faster without making you ship safer, you're not getting more productive, you're just winding the compliance ratchet a little tighter, and that one doesn't wind back.

If so, we're excited to share a feature we've been incubating — Feature Flags in Octopus.

Feature flags let teams control when and where new features are enabled, without needing to redeploy. You can experiment, test safely, roll back instantly, and ship continuously with confidence.

With Octopus Feature Flags you can:

• Toggle features on or off instantly — no redeployment required.
• Progressively roll out changes — deliver an upgrade to a single environment, to 10% of your tenants, or to a specific cohort of users.
• Develop on your main branch, keeping unfinished features safely hidden behind flags.

Built on OpenFeature

OpenFeature is an open standard that provides a vendor-agnostic, community-driven API for feature flagging that works with your favorite feature flag management tool or in-house solution.

When we came to build Octopus Feature Flags, we chose OpenFeature as the client SDK.

This means you get a robust, battle-tested SDK designed by the best minds in the feature flag business. More importantly, it means no vendor lock-in. If at some point you want to switch feature flag providers (we hope you never do), it's a single line of code to change the registered provider. You can even register multiple providers. And we get to contribute to a thriving project.

As OpenFeature offers SDKs for all popular programming languages, we only need to create an Octopus OpenFeature provider for each language.

Here's an example of configuring OpenFeature to use the Octopus Provider and evaluate a flag:

// configure OpenFeature to use Octopus as the feature flag provider
OpenFeature.setProvider(new OctopusFeatureProvider({ clientIdentifier: 'my-client-id' }));
const featureFlags = OpenFeature.getClient(); 

// evaluate a feature flag
const withDarkMode = await featureFlags.getBooleanValue('dark-mode', false); 

if (withDarkMode) {
    // enable dark mode option
} else {
    // light mode only 
}

Built into Octopus for seamless Continuous Delivery

Octopus Feature Flags live in Octopus projects. They're not a stand-alone product — they integrate deeply with the Octopus features you already use, like environments, tenants, and releases, and they're designed for releasing changes.

Environment targeting

Deliver a different experience in each environment. Each environment has its own feature flag settings, so you can turn a feature on in Development and Test for your team to trial, while it stays safely off in Production.

:::figure

:img{ src="/blog/img/feature-flags-public-preview/feature-flags-list.png" alt="The feature flags list in Octopus, showing flags toggled on and off per environment" loading="lazy" }

:::

Tenant rollout

Deliver an upgrade to 10% of your tenants, and dial it up from there. You can enable a flag for specific tenants, for tenants matching a tenant tag, or for a percentage of tenants. You can even exclude specific tenants; maybe your tenants represent your customers, and there are select customers you'd prefer not to include as early adopters.

:::figure

:img{ src="/blog/img/feature-flags-public-preview/feature-flag-tenants.png" alt="The tenant rollout configuration for a feature flag, with included, excluded, and percentage rollout options" loading="lazy" }

:::

Minimum version targeting

Because Octopus knows which versions of your project are deployed to each environment, you can configure a minimum version for a feature flag. The flag is enabled only after that release version (or a later one) has been deployed to the environment.

:::figure

:img{ src="/blog/img/feature-flags-public-preview/feature-flag-min-version.png" alt="The minimum version setting for a feature flag, which enables the flag only after that version is deployed" loading="lazy" }

:::

Client rollout and Segments

Release a feature to 5% of your users, or only to a chosen cohort — your staff, a geographic region, or a license type. Octopus Feature Flags support enabling a change for a percentage of your users (client rollout), or for a specific cohort via Segments.

:::figure

:img{ src="/blog/img/feature-flags-public-preview/feature-flag-segments.png" alt="The client rollout configuration for a feature flag, with a rollout percentage and key/value segments" loading="lazy" }

:::

Segments are built on top of OpenFeature's Evaluation Context concept. This lets your application pass context (for example information about the current user like geography, or license type) that feature flag providers, Octopus in this case, can use when evaluating a flag.

The following code sample demonstrates adding context values from your application code:

// values can be added at one of three different levels: global, client, or invocation

// add a value to the global context
// an example of a global context value might be if you have multiple sites, for different geographic regions
OpenFeature.setContext({ site: 'octopetshop.com.au' });

// add a value to the client context
// an example of values typically added to the client context are those associated with a specific web request, such as the user details
const client = OpenFeature.getClient();
client.setContext({ 
    email: webRequest.user.email,
    licenseType: webRequest.user.license.type 
    });

// add a value to the invocation context
// the invocation context may be used to add values specific to the flag being evaluated
// for example a pet shop may have a feature specifically for dogs, and add a context 
// value to indicate if dog food has been added to a shopping cart 
const context: EvaluationContext = {
  cartContainsDogFood: 'true',
};

const flagValue = await client.getBooleanValue('dog-profile', false, context);

Read more about how Segments are evaluated in our docs.

Supported languages

We currently have OpenFeature providers for the following languages:

• TypeScript/JavaScript (web client)
• .NET (server)
• Java (server)

If you're interested in using Octopus Feature Flags, and your language isn't currently supported, please register your interest below and tell us which language you need.

Try Octopus Feature Flags

Octopus Feature Flags are now available to Octopus Cloud customers as a Public Preview. To get access, register your interest.

Feature Flags are available in all license tiers, including the Free tier. They're currently available for Octopus Cloud only; we plan to make them available to self-hosted Octopus Server customers soon.

We've been releasing features in Octopus Deploy using Octopus Feature Flags for the past 12 months, and they've improved our ability to release progressively, and to roll back instantly, meaning our customers — that's you — experience a more stable product than ever. We would love to help you do the same for your customers.

Happy deployments!

We've migrated target tags to be managed with tag sets, which means you can now create, edit, and delete tags on your deployment targets the same way you manage tag sets elsewhere in Octopus.

What this means for those already using target tags

Target tags still work the same way for filtering deployments and scoping steps to specific targets but they're now backed by the tag set system, giving you improved tag maintenance. You can now:

• Rename a tag when your naming conventions change
• Use SingleSelect or MultiSelect tag set types to enforce data integrity.
• Improve the organization of target tags by splitting these out into different sets.

:::figure

:img{ src="/blog/img/tag-sets-new-functionality/deploy-to-tag.png" alt="Screenshot showing how to deploy to target tag" loading="lazy" }

:::

Use cases

Organize and provide context - for teams running multi-cloud infrastructure, it's common to need both the provider and the workload type when targeting deployments. For example:

• Cloud Provider (SingleSelect): aws, azure, gcp, on-premises
• Workload (MultiSelect): containerized, vm, serverless

Deploy to specific tags - trigger a runbook that restarts services only on targets tagged containerized, leaving VM-based workloads alone during an incident.

Exclude specific tags - exclude targets that are currently in use to ensure deployments don't result in downtime during high traffic periods

Deploy to tags across multiple tag sets - Deploy to targets tagged production (Tier) OR regulated (Compliance) to make sure a critical security patch reaches everything that's either customer-facing or subject to compliance requirements.

Getting started

If you're already using target tags, they've already been migrated to a new tag set 'Default Target Tags'. Head to Library > Tag Sets to see them and start managing them alongside your other tag sets. If you're setting up target tags for the first time, take a moment to think about what dimensions matter to your infrastructure; role, cloud provider, team ownership, compliance scope, and model those as separate tag sets rather than trying to pack everything into one.

Learn more

For guidance on designing tag sets, check out our documentation on tag set best practices.

For more information on deploying to, or excluding tags read more our docs.

Happy deployments!

Octopus comes in two flavours: Octopus Cloud, where we host and manage everything for you, or Octopus Server, where you install and run it on your own infrastructure.

Running an outdated Octopus Server is a quiet risk. This post covers why staying current matters, and why Octopus Cloud is worth considering if you'd rather focus on shipping software than maintaining the tool that ships it.

Below, I cover what Octopus updates actually contain, because security patches, bug fixes and more, matter just as much as new features.

Performance improvements

Performance is key not only for our customers but also for us. Every time we bake a new build internally, we test it to ensure it's not worse than the previous version. We run tests against our software, and our staff get to try it out first before it propagates upwards.

You might be asking yourself, "What does this look like?" Bob Walker, Field CTO at Octopus, covers this in a great talk, available on YouTube. The talk covers how we ship changes, who gets to test them, and when these changes land for our self-hosted customers.

If you don't already know, Octopus Cloud is one quarter ahead of Octopus Server.

So what does it look like? If the build is happy against automated tests:

• Staff - We dog food our own app, our main deploy instance is the first one that's updated
• Canary Customers (+3 days) - We deploy to a random subset of Octopus Cloud customers, about 5% of active instances, which is randomized each time
• Stable (+2 days) - We then deliver to the majority of our Cloud customers' instances
• Laggards - By this point, the release has already been running in production across thousands of instances, and we update the remaining Octopus Cloud instances
• Octopus Server - Eventually, self-hosted Octopus customers will be able to download the latest version of our software

Should you want to learn more about performance for your self-hosted instance of Octopus Server, be sure to check out the documentation on performance. We handle performance for you when you're on Octopus Cloud.

Improved compatibility & integrations

We're always ensuring Octopus remains compatible with the most popular software tools and integrations. We have documentation on compatibility that goes into detail, as well as our integrations page on our website.

By staying up to date, you ensure you are ready for whatever the world throws at you and can adopt and implement new integrations as they become available.

Bug fixes

No one likes bugs; these can be nuanced and overlooked. You can view our release notes on our website, and you can also track which version you are on and which target version you plan to upgrade to using the compare versions option.

We present information clearly about breaking changes, bugs, and more.

Quality of life tweaks

We believe in listening to our customers' feedback; it's quite important to us and one of our core values for every Octonaut at Octopus.

Our customers help us sharpen our product even further, and we often revisit features, integrations, and more to refine them and make their lives easier.

You can learn more about Octopus's core values in our handbook.

Security patches for CVEs

Everyone knows that a core part of keeping your software up to date is addressing security issues, and we publish this information in various places:

• Release notes
• Security Advisories page

We also have a Security Disclosure Policy.

Compliance

Building on security patching, you have to ask yourself: how do you remain compliant if you don't update your software regularly?

It's important that you understand and upgrade your software regularly; this isn't just an Octopus need, it's for all software. By staying up to date, you ensure your business remains compliant and that audit checks pass with flying colors.

Enhancements to existing features

Just because we've shipped a feature doesn't mean it's done and forgotten; we're always listening and looking for ways to improve what we offer.

You'll always gain by updating Octopus software, and more often than not, you'll learn about these in our blog section on our website. You can also subscribe, so you're always up to date with any new blogs that are published.

A great example of this is Platform Hub, where we are releasing this functionality to our customers. You might be asking what Platform Hub is? Check that out in this blog post. We also have a feature page, should you be interested.

New features

We love building features that make developers' lives easier.

You can see what we're up to by visiting our public roadmap, leave us a signal on what's important to you by voting, and you can also submit ideas directly to our product and engineering teams for consideration.

Staying within vendor support

Every Octopus software release receives six months of critical patches.

You can learn more about this on our blog post, where we discuss it, and in our documentation, which covers it for self-hosted Octopus customers.

Should you ever need to contact the Octopus Deploy Support Team, the team will be happy to help.

Deprecations

Occasionally, Octopus will deprecate features that will no longer be supported. These features are eventually removed.

Staying up to date means you're protected against known vulnerabilities as soon as fixes are available, and you're not carrying risks that have already been solved.

You can learn more about this in our docs.

Conclusion

The longer you leave it (not updating regularly), the more risk you carry, the more it costs to resolve when something breaks, and the longer it takes to get back on track. Staying current keeps your attack surface small.

If you prefer that Octopus handle upgrading Octopus for you, then I'd recommend Octopus Cloud. Octopus Cloud reliably hosts thousands of Octopus Deploy customers.

Octopus Cloud is the easiest way to run Octopus Deploy. It has the same software and functionality as Octopus Server, except we host it for you and we call it a Cloud instance. You don't need to download, install, or manage it yourself. You can get started with a free account to try it out.

You can learn more about its architecture in this blog post.

Happy deployments!

Don't worry about code reviews, Gene. Code reviews and approvals have always involved a lot of theater. We just need to perpetuate that illusion a little longer and keep pretending that humans are actually reviewing all that agent-generated code.

Jez is absolutely right; code reviews do involve a lot of theater. Especially now in the era of AI-generated code. In the short amount of time since this post, this trend has become more pronounced. Code review used to be considered a solid approach to ensuring quality and compliance. It just isn't anymore, and we need to be honest about its effectiveness for development teams today.

The chocolate belt wrappers

Consider the all-too-familiar process of reviewing a pull request (PR). The notification bell icon lights up, indicating that you have something to review. You open it, review the code, slap "LGTM" on it, and click "approve." It compiles. Ship it.

Now consider the scenario in which agents write the majority of the PRs. You probably know how this ends up if you've ever seen the "Job Switching" episode of I Love Lucy.

Lucy and Ethel wrapping chocolates

In the episode, Lucy and Ethel take jobs on an assembly line wrapping chocolates. Everything starts fine until then the belt speeds up. Lucy and Ethel can't keep pace, so they start hiding chocolates wherever they can. The chocolates keep coming. The wrapping of chocolates, what we call code review, becomes theater.

In our world, these chocolates are PRs, AI coding agents are the belt, and code review is Lucy, frantically trying to keep up while the quality of what's getting through drops with every passing minute. A lot of what's coming off that belt can be slop. It compiles. (Or, sometimes not.) If you're lucky, it passes your test matrix. Looking closely at the code, it looks fine until you realize the model copied a pattern from its training data that doesn't actually fit your problem. The person reviewing would likely not realize this. The reviewer would likely check whether the syntax and structure are correct, not whether the code should exist in the first place.

Agents can produce huge chunks of code in the time it takes to read this sentence. The PRs reflect this. Now consider the burden this places on a reviewer. Is it reasonable to evaluate a 40,000-line change? Does it get better if we atomize it into 4,000 tiny 10-line diffs? You can read each diff and still miss whether it's the right change. That's because you weren't part of the reasoning that produced it. You have no context whatsoever. It's like flipping to the middle of a book and claiming you know where you are in the story.

Yes, AI makes producing code much, much faster. However, reviewing that code has become much, much harder. As an industry, we tout and celebrate the speed. But we don't talk about the PRs piling up, putting everyone downstream under pressure.

The chocolate belt speeds up

If you take a look at the 2026 DORA report, 90% of developers now use AI tools at work. Developers are spending 2+ hours a day with these tools, completing 21% more tasks and merging 98% more pull requests.

With great power comes great responsibility. The average number of bugs per developer is up 54%. Faros AI's analysis of 10,000+ developers found incidents per pull request are up 242.7%. We've essentially doubled our merge rates while breaking things three times as often. We see the impact of AI-generated code in our own data, too. Our 2026 AI Pulse report found that AI reduces task hours across every part of the delivery pipeline except for code review. 72% of developers use AI to write code, but only 56% bother using it for their reviews. The chocolate belt is accelerating, and Lucy and Ethel are starting to look nervous.

To be fair, Daniel Stenberg, the creator of curl, recently noted that AI-generated contributions have gone from slop to genuinely good. Problem solved, right? Not quite. PRs are arriving faster than his team can review them. We have better chocolates, but the same belt speed problem. Our review queue is starting to resemble a backlog.

So what do we do about it? The prevailing sentiment right now is to chuck AI at the review problem, too. Make Ethel check Lucy's work. But think about that. They're standing at the same belt and they've trained on the same data. They have the same blind spots. "AI reviewed it so we're good" is the new "the dog ate my homework." Except now the dog wrote the homework, ate it, barfed it up, and gave it an A+.

That's the real takeaway from the DORA data. AI is an amplifier. It can amplify our intelligence or our stupidity. We need to be careful. Right now, a lot of us have the chocolate belt of PRs cranked up to full speed.

Enter the wrapping machine

The chocolate belt does exactly what it's supposed to do. The wrapping process (code review) is what failed. And the fix has been staring us in the face since the Continuous Delivery (CD) movement began. Our deployment pipeline is the assurance mechanism, not the human with the approve button. If quality and security requirements are missing from the pipeline as automated checks, code review will never ensure they are met. We are simply hoping that a human – somewhere in the chain – might catch the problem.

Yes, we still need people who can look at a system and say, "This is the wrong approach." That's not going away. But we're expecting that same person also to be the last line of defense against every bug and every security gap in every deployment. That was never going to work. We just didn't have a reason to admit it until now.

What's actually in the chocolate

Let's stop pretending code review is something it isn't.

Code review is great for knowledge sharing and catching design-level issues. But it's horrible at catching every bug in a 40,000-line diff. Bugs matter when code is shipping to production.

So the question we should be asking ourselves isn't "how do we make code review scale?" It's "how do we build a pipeline that can verify what it's shipping, regardless of who or what wrote the code?"

Policy-as-code is one way to get there. We write rules that define our deployment standards, and the pipeline checks every deployment against them. The developer sees what went wrong and how to fix it. There's no waiting around for someone to review a diff.

Learning to wrap chocolate

It would be foolish of me not to mention the fact that there's something a chocolate wrapping machine can't teach you. And that's the process of wrapping chocolate. In our world, that's the act of conducting a code review. It's how junior engineers develop judgment.

Mentorship comes from reading other people's code, getting feedback on your own, and absorbing the unwritten reasons behind certain decisions. That pipeline is already breaking. 73% of organizations have reduced junior developer hiring in the past two years. Junior devs dropped from 32.8% to 24.8% of Stack Overflow respondents between 2024 and 2025. If we let that continue without figuring out another way for juniors to learn, we're in trouble. We end up with a generation of engineers who can prompt effectively but can't reason about a system's design.

I'm not saying we need to remove code review. But we need to stop kidding ourselves that it's the all-seeing, all-knowing quality gate we've built it up to be.

Wrapping up

To reiterate, Jez was right. Code review has worked well enough when humans are involved in the volume of code being reviewed. It was good enough when a team merged a handful of PRs a day. However, it's not good enough when AI is generating them.

The answer isn't a better performance. It's a better pipeline. One that can prove our software works before it hits production. The CD community has been saying this for years. Most of us just didn't have a reason urgent enough to listen. But with the advent of AI and code generation, we're now compelled to.

If our quality gates live in our pipeline, it doesn't matter whether the code was written by a human, an AI, or a very determined cat walking across a keyboard.

If the quality of our code reviews is determined by a human's abilities, we're in trouble, because AI sped up the belt, and the chocolates aren't going to wrap themselves.

Happy deployments!

Return to the series index.

Prerequisites

• An Octopus Cloud account. If you don't have one, you can sign up for a free trial.
• The Octopus AI Assistant Chrome extension. You can install it from the Chrome Web Store.

:::div{.hint} The Octopus AI Assistant will work with an on-premises Octopus instance, but it requires more configuration. The cloud-hosted version of Octopus doesn't need extra configuration. This means the cloud-hosted version is the easiest way to get started. :::

Creating the project

Ephemeral environments support the creation and destruction of short-lived environments and their associated resources. These environments are often used to deploy feature-branch builds, allowing developers to interact with their work before it is merged into a mainline branch.

Paste the following prompt into the Octopus AI Assistant and run it:

Create a Kubernetes project called "K8s Web App with Ephemeral Environments", and then:
* Use client side apply in the Kubernetes step (the mock Kubernetes cluster only supports client side apply).
* Disable verification checks in the Kubernetes steps (the mock Kubernetes cluster doesn't support verification checks).
* Enable retries on the K8s deployment step.
* Add support for ephemeral environments, with the Parent Environment and Ephemeral Environment channel both called "Features"

---

Create a token account called "Mock Token".

---

Create a feed called "Docker Hub" pointing to "https://index.docker.io" using anonymous authentication.

---

Create a Kubernetes target with the tag "Kubernetes", the URL https://mockk8s.octopusdemos.com, attach it to the "Development", "Test", "Production" environments and the "Features" parent environment, using the health check container image "octopusdeploy/worker-tools:6.5.0-ubuntu.22.04" from the "Docker Hub" feed, using the token account, and the "Hosted Ubuntu" worker pool.

:::div{.hint} The document separator (---) is used to split the prompt into multiple sections. Each section is applied sequentially, which allows you to create different types of resources in a single prompt. :::

As we did in the last post, the AI Assistant creates a functional Kubernetes project pointing to a mock Kubernetes server.

We then added support for ephemeral environments, which requires:

• A parent environment called Features
• A channel that deploys to ephemeral environments, also called Features

:img{ src="/blog/img/octo-easy-mode-15-ephemeral-environments/parent-environment.png" alt="Parent Environment" loading="lazy" } :img{ src="/blog/img/octo-easy-mode-15-ephemeral-environments/channel.png" alt="Channel" loading="lazy" }

Create a new deployment of the project, select the Features channel, and define the FeatureBranch custom field to the name of a feature branch like features/font-change:

:img{ src="/blog/img/octo-easy-mode-15-ephemeral-environments/new-release.png" alt="New Release" loading="lazy" }

The value assigned to the custom field is used as the name for the new environment. Any invalid characters, like the backslash, are automatically sanitized to provide a valid environment name.

The deployment is visible in the Ephemeral Environments section:

:img{ src="/blog/img/octo-easy-mode-15-ephemeral-environments/ephemeral-environments.png" alt="Ephemeral Environments" loading="lazy" }

Because the Kubernetes step is configured to deploy resources to the namespace #{Octopus.Environment.Name | ToLower}, the ephemeral deployment creates resources in a namespace based on the ephemeral environment name, keeping it separate from the traditional deployments to the Development, Test, and Production environments.

You'll also notice that the Kubernetes target was selected for the deployment because it was attached to the parent Features environment. This demonstrates how durable Octopus resources are linked to ephemeral environment deployments.

Runbooks can be used for those scenarios where you need to provision and deprovision the environment.

Run the following prompt to add two runbooks to the project:

Create a runbook called "Provision Environment" in the project "K8s Web App with Ephemeral Environments".
Allow the runbook to be run from the "Features" environment.
Add a "Run a kubectl script" step run against the target tag "Kubernetes" and echo the text "Provisioning the environment" from a bash script.
Run the step from the "Hosted Ubuntu" worker pool.

---

Create a runbook called "Deprovision Environment" in the project "K8s Web App with Ephemeral Environments".
Allow the runbook to be run from the "Features" environment.
Add a "Run a kubectl script" step run against the target tag "Kubernetes" and echo the text "Deprovisioning the environment" from a bash script.
Run the step from the "Hosted Ubuntu" worker pool.

In the Ephemeral Environments project section, open the Settings tab, and select the new runbooks from the Provisioning runbook and Deprovisioning runbook fields:

:img{ src="/blog/img/octo-easy-mode-15-ephemeral-environments/runbooks.png" alt="Ephemeral Environments Runbooks" loading="lazy" }

Both runbooks must have a published snapshot. Open each runbook, click the Publish button, and click the Publish button again:

:img{ src="/blog/img/octo-easy-mode-15-ephemeral-environments/publish-runbooks.png" alt="Publish Runbooks" loading="lazy" }

Now, when you deploy to an ephemeral environment, the Provision Environment runbook is executed. After one week, the Deprovision Environment runbook is automatically executed, or you can manually deprovision an environment in the Ephemeral Environments section under the Overview tab:

:img{ src="/blog/img/octo-easy-mode-15-ephemeral-environments/deprovision-environment.png" alt="Deprovision Environment" loading="lazy" }

What just happened?

You created a sample Kubernetes project with:

• A channel called Features to deploy to an ephemeral environment based on a custom field value
• A Parent Environment called Features
• A Kubernetes target linked to the Features parent environment
• Two runbooks: one to provision the ephemeral environment, and another to deprovision it

What's next?

The next step is an example of deploying an Argo CD Application with a GitOps based workflow.

That means there's more art to change approvals than most people realize, and it's a threat to an organization's ability to deploy and operate software if they don't have change finesse.

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.6

Organizational trauma

Change approvals don't arrive without reason. If you have a heavyweight change approval process and frequent or extended change freezes, the chances are that they were introduced after a major incident. If you break financial software around tax year-end, banning deployments for a month before and a month after is, in theory, a reasonable resolution.

Almost every industry has a cadence it wants to protect from instability. Retail has seasonal sales events, the music industry has superstar ticket launches, and finance has a peak as the end of the tax year approaches. The goal is to make sure you can operate your business during these times.

With that goal in mind, we have to bust the myth of change approvals as the mechanism to achieve it. Attempting to protect these key moments with change freezes or cumbersome approval processes has one result: increased instability.

Heavyweight change approvals

Heavyweight change approvals make things less stable by delaying work and causing batches of unreleased changes to accumulate. Meanwhile, developers are starting new work and are losing the immediate familiarity with the oldest changes as they press ahead. One of the ways approvals gain weight is through approval chains, which we looked at in depth in the Compliance through Continuous Delivery report.

Large batches also come with admin that can introduce further problems. Testing becomes more difficult, the likelihood of merge issues increases, and pinpointing the source of a problem is far harder.

This is why the DORA research placed streamlined change approvals in their core model for software delivery. Centralized change approval boards don't work, and process is never the solution to your stability problems.

Streamlining

There are some easy ways to streamline change approvals. Most of these don't look like traditional change management, which is good because we know that doesn't work.

The first way to trim the process is to automate your verification stages. At every level of review, tasks can be automated, whether it's automatically linting and formatting code (instead of debating it), running automated builds and tests, or validating your SBOM is free from insecure dependencies.

Where you need a human review, use a peer-review process for individual changes, enforced on commit, with humans brought in only after the automated validation has passed. If you have advanced change approval needs, categorizing changes by risk lets you apply your people to the changes that most need their perspective.

You won't achieve all of this in one day. It's part of your continuous improvement process. You may improve your chances of stripping the bureaucracy if you follow the capability culture cycle pattern.

Small batches, again

If you follow industry experts or the research, you'll notice that small batches keep cropping up as the answer to many kinds of dysfunction. That's not a coincidence. Large batches cause far-reaching problems that build superlinearly as more changes collect unreleased.

Anything that causes batch size to increase, including change approvals, must be subject to fierce improvement.

Happy deployments!

:::div{.hint}

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.

:::

Securing these agents is a top concern for enterprises. One common solution to improve the security of AI agents is to run them in a sandboxed environment. In this post, I'll take a look at what it means to "sandbox" an AI agent in a production environment.

In brief

• Local AI agents are general-purpose assistants that can perform almost any action on behalf of a user.
• Local AI agents benefit from sandboxes as a countermeasure to their broad access to CLI tools, local files, and networks.
• Shared AI agents are designed for specific tasks.
• Shared AI agents should be decomposed into the agent harness and the tools called by the agent.
• The tools called by shared AI agents are typical web services.
• The term "sandbox" has little meaning for shared AI agents, as the tools can be secured with existing security policies and practices.

Distinguishing between local and shared agents

Before discussing what it means to sandbox an agent, it is important to distinguish between local and shared agents.

Local agents are the result of bespoke configuration in an individual's own workspace. It is the coding agent with a mishmash of MCP servers and personal credentials that a developer has set up to help them with their work. Or the OpenClaw style agent that runs in the background automating tasks like monitoring emails, browsing the web, or organizing files.

To use the pets/cattle analogy (where pets have names and are lovingly cared for while cattle are interchangeable), local agents are pets. Local agents must support a wide range of tasks, including code generation, running scripts, manipulating files, and answering questions. They were never intended to be distributed, and little thought is put into how they might be recreated. Each developer is responsible for their own local agent. In fact, much of the functionality provided by a local agent likely relies on MCP servers exposed by an IDE, which are not available outside a local development environment.

Shared (or managed) agents are designed to perform specialized tasks. They must be secure, testable, deployable, and supported. Shared agents will often be hosted as web applications, perhaps using protocols like the Model Context Protocol (MCP).

Local agents have unique security concerns. It is mesmerizing, and slightly horrifying, watching a local agent query the contents of your /etc/environment file to get the credentials required to execute a curl command as it doggedly attempts to upload a file to a remote server. Local agents are like sharing your keyboard with the most brilliant and amoral entity in the known universe.

Because local agents are general-purpose AI tools, they tend to have broad access to the CLI, local files, and networks. So it makes sense to run local agents in an isolated environment to distinguish between the trust granted to a user and the trust granted to the local AI agent.

Shared agents have a far narrower scope than local agents. Shared agents are designed to solve specific tasks and interact with the world through a small window. The limited scope of shared agents has implications for their security.

The focus of this post is on shared agents. This is not to diminish the security implications of local AI agents, but rather to note that shared agents, iteratively developed and deployed to a production environment, align very closely with the core functionality provided by Octopus.

But before we can understand what it means to sandbox a shared agent, we first need to understand the architecture of shared agents.

Shared agent architecture

At the heart of every AI agent is an LLM making decisions about how best to achieve its task.

For all their wonder and complexity, it is best to think of LLMs used by shared agents as string functions: the prompt string goes in, the response string comes out. (I'm going to ignore the social engineering security aspect of LLMs here, as the generated output of an LLM used by a shared agent is not typically consumed by a person.)

That is it. LLMs cannot, on their own, interact with the world. They cannot browse a web page, read a file, or save a record in a database.

Because LLMs can’t interact with the world, there is very little to contain in a sandbox.

However, this inability to interact with the world severely restricts the problems that LLMs can solve. A chatbot is about as complex a solution as you can build with an isolated LLM. To build useful AI agents, LLMs must be able to act.

This is where the concept of tool calling comes in. Tools are just a fancy way of describing code exposed to an LLM that can interact with the world. MCP is the most common interface through which LLMs learn about and execute tools.

When a tool like switch_lightbulb_on is exposed by an MCP server to an LLM, a prompt like Switch on the lights will cause a physical light bulb to turn on.

Treating the LLM and the tools it calls as separate concerns is crucial to understanding how sandboxes apply to shared AI agents.

Sandboxing the tools

There are many industry examples demonstrating the pattern where the LLM is run as a regular service while the tools called by the LLM are isolated within a sandbox environment.

:::div{.hint} Some of these quotes have been edited for clarity. :::

Claude describes the LLM as the brain and the tools as the hands of an AI agent:

The solution we arrived at was to decouple what we thought of as the “brain” (Claude and its harness) from both the “hands” (sandboxes and tools that perform actions) and the “session” (the log of session events).

Notably, in this description, the hands include sandboxes.

Red Hat describes the separation of the brain and the hands, with the hands running in a sandbox, as "the right choice for multi-tenant agent platforms and production workloads":

The agent's "brain" (reasoning and orchestration) is decoupled from its "hands" (tool execution and code). The platform orchestrates the agent loop and delegates execution to disposable, stateless sandboxes that you control. Credentials are physically separated from the execution environment, injected at the network boundary rather than stored where agent-generated code can reach them. Both the Responses API and Anthropic's Managed Agents follow this pattern, whether the sandbox runs in the provider's cloud or on your own infrastructure through self-hosted environments. This is the right choice for multi-tenant agent platforms and production workloads.

How 11x Rebuilt Their Alice Agent: From ReAct to Multi-Agent with LangGraph notes that agents work best when tools do the heavy lifting:

Tools are preferable over skills. Don't try to make your agent too smart. Just give it the right tools and tell it how to use them.

In the video Securing MCP in an Agentic World with Arjun Sambamoorthy from Cisco, Arjun describes the importance of run-time MCP security with sandboxes isolating MCP servers:

We should also sandbox and isolate MCP servers to make sure there's no crosspollination that's actually happening.

Agentic AI Safety & Security by Dawn Song describes the importance of decomposing systems to enforce the principle of least privilege:

The idea is that instead of building one monolithic agent with different components in one system, one can actually separate the overall agent system into separate components where each component can run its own, for example, container or context such that each separate component can have its own set of privileges depending on its needed capabilities and so on and hence enable and help enforce principle of least privilege.

OpenAI describes when to use a sandbox, and notes that "the sandbox stays focused on provider-specific execution":

Use sandboxes when the agent needs to manipulate files, run commands, mount a data room, produce artifacts, expose a service, or continue stateful work later.

The key split is the boundary between the harness and compute. The harness is the control plane around the model: it owns the agent loop, model calls, tool routing, handoffs, approvals, tracing, recovery, and run state. Compute is the sandbox execution plane where model-directed work reads and writes files, runs commands, installs dependencies, uses mounted storage, exposes ports, and snapshots state.

Keeping those boundaries separate lets your application keep sensitive control plane work in trusted infrastructure while the sandbox stays focused on provider-specific execution.

Azure Container Apps Sandboxes provide a managed service where:

Agents can run anything safely - an agent spawns a sandbox, executes work inside it, and returns the output with no agent host privileges required.

AWS provides the Amazon Bedrock AgentCore Code Interpreter, which similarly provides a sandbox where untrusted code is run:

With the AgentCore Core Interpreter, AI agents can write and execute code securely in sandbox environments, enhancing their accuracy and expanding their ability to solve complex end-to-end tasks.

The provided diagram clearly shows the Agent and LLM sitting outside the sandbox, and the code being executed inside it:

:img{ src="/blog/img/ai-agent-sandboxes/agentcore-code-interpreter.png" alt="AgentCore Code Interpreter Diagram" loading="lazy" }

What is clear from these examples is that the LLM is hosted separately from the tools it calls, and it is the tools that are sandboxed, as this is where the real work is done.

What even is a sandbox?

When taking the approach of sandboxing tools, the next decision is which guardrails the sandbox must provide.

At the extreme end, a sandbox provides an environment in which untrusted scripts can run. An example of this is Intel DeepMath, which is a lightweight agent that specializes in solving mathematical problems by running small, sandboxed Python scripts that support and enhance its problem-solving process:

Instead of verbose text, the model emits tiny Python snippets for intermediate steps, runs them in a secure sandbox, and folds the results back into its reasoning, reducing errors and output length.

Your local coding assistant AI agent may even have produced Python scripts to modify files in bulk or search for text.

Because you can do almost anything with a Python script, you need a robust sandbox to prevent any malicious or undesirable actions from being executed.

Running untrusted code is an extreme example, though. Most tools will be far more routine, performing deterministic actions like returning data, sending messages, triggering a workflow, approving a request, etc. Indeed, most of the tools called by a shared AI agent are just wrappers around existing APIs.

The sandbox around these tools must address the same cross-cutting concerns as any web service container, like authentication, authorization, rate limiting, PII redaction, observability, CPU and memory limits, firewalls, etc.

At this point, it may not even make sense to talk about sandboxes at all. Any modern Platform as a Service (PaaS) or orchestration platform has almost certainly addressed these common security concerns, usually without using the term "sandbox."

Do sandboxes make sense?

General-purpose local AI agents running in an individual's workspace absolutely benefit from a sandbox. The fact that a local AI agent can and will do anything you ask (and sometimes things you don't) means a specialized sandbox is a valid countermeasure.

In OpenClaw + Windows, Microsoft demonstrates how OpenClaw is prevented from making unwanted changes to the system by running it in a sandbox:

And you'll notice down here in the corner we've got lots of permissions options along with our sandbox configuration. Now, this sandbox is really interesting because this is using MXC, the Microsoft Execution Containers.

You've got full support about what files and folders you want OpenClaw to have access to, and really granular security features like clipboard access or talking to the internet itself.

OpenClaw already has a rich safety layer, and that layer is only augmented more by appropriate containment that can be managed by me or policies applied by IT.

The concept of a sandbox is also applicable for the execution of generated scripts, which administrators must assume can perform any action.

However, the concept of a sandbox is less meaningful when used to isolate specific, deterministic tools required by shared agents. The security layer built into any modern PaaS offering already supports the cross-cutting security concerns required to host web-based services, authentication and authorization policies are available on APIs exposed by tools, and individual tools can be turned on and off as needed in an MCP server.

You could make a good argument that this collection of controls effectively serves as a sandbox. For example, agent-sandbox combines existing Kubernetes features to provide an AI agent sandbox.

But using the term "sandbox" feels more like a distraction from the implementation of existing, standard security controls applied to any web service because it implies that there is some unique security layer that is specifically required to support AI agents.

Conclusion

The term sandbox is thrown around a lot these days. You don't have to look hard to find examples of AI agents going rogue and deleting files or trashing databases, and it is natural to assume that some kind of sandbox is required to rein in freewheeling AI agents.

But it is important to distinguish between general-purpose local AI agents that are incentivized to support any kind of action and specialized shared AI agents that are designed for a very specific purpose. Further decomposing shared AI agents into the agent harness and the tools highlights that it is the tools that need to be constrained. And centrally managed tools exposed as web services (with an MCP server being a specialized web server) already have a wealth of existing, comprehensive security controls available to secure them.

Enterprises should focus on constraining the tools used by shared AI agents, rather than being distracted by hype around sandboxes. Your existing best practices can be applied to centrally managed tools; there is no need to shoehorn in an additional security layer under the guise of a sandbox.

Happy Deployments!

Kubernetes's default rolling update strategy gradually deploys new pods and retires old ones, but during the swap, your service runs both versions side by side, and a regression in the new image affects every request that lands on a new pod.

Progressive delivery patterns like blue/green have long existed: you stand the new version up alongside the old, prove it's healthy on a separate preview endpoint, then flip user traffic across. Blast radius shrinks to nothing in the bad case, rollback is a single command, and your release stops being a held-breath moment.

In this post, you'll set that up with Argo Rollouts, the controller behind progressive delivery in the Argo ecosystem (which graduated from the CNCF in 2022).

What is Argo Rollouts (and why you need it)

Argo Rollouts is a Kubernetes controller and a set of CRDs that bolt blue/green, canary, and other progressive delivery strategies onto your cluster. The primary CRD is Rollout, a drop-in replacement for the standard Deployment.

You convert an existing Deployment by changing the apiVersion to argoproj.io/v1alpha1 and the kind to Rollout, then adding a strategy.blueGreen or strategy.canary block that describes how a new revision should roll out.

A major reason to reach for it is that there's no built-in way to do this kind of traffic control in Kubernetes (you can't decide where requests go independently of which pods are Ready). There's no easy rollback to the previous version once the update has started.

Argo Rollouts fills in everything around that. It plugs into ingress controllers (Traefik, ALB) and service meshes (Istio, Linkerd, SMI) for real traffic shaping. It can query metrics providers (Prometheus, Datadog, CloudWatch, New Relic) to gate promotions on hard numbers, and it tracks every revision as its own ReplicaSet, so flipping back is instant.

Prerequisites

This tutorial assumes some familiarity with Kubernetes. You'll also need:

• A working Kubernetes cluster (EKS, GKE, AKS, or local like Minikube/Kind).
• kubectl installed and pointed at the cluster (kubectl get nodes should return at least one Ready node)
• helm v3 installed
• curl for hitting the demo app

Step 1: Installing the Argo Rollouts controller

Argo Rollouts ships as a controller that runs in its own namespace, along with a kubectl plugin you'll use on your laptop to inspect and steer rollouts.

To install the controller, follow these steps:

1. Add the Argo Helm repo and install the controller:

   helm repo add argo https://argoproj.github.io/argo-helm
   helm repo update
   helm install argo-rollouts argo/argo-rollouts \
     --namespace argo-rollouts \
     --create-namespace \
     --wait
   

2. Confirm the controller pods are up:

   kubectl -n argo-rollouts get pods
   

   You should see something like:

   NAME                             READY   STATUS    RESTARTS   AGE  
   argo-rollouts-dcd465dfc-8m2ql    1/1     Running   0          79s  
   argo-rollouts-dcd465dfc-q92k4    1/1     Running   0          79s
   

Step 2: Installing the kubectl argo rollouts plugin

The controller is running, but the most ergonomic way to drive a rollout — inspecting state, setting images, promoting, rolling back — is the kubectl argo rollouts plugin. It's a separate binary that drops onto your PATH, and kubectl picks it up automatically.

To install the plugin, follow these steps:

On macOS with Homebrew:

brew install argoproj/tap/kubectl-argo-rollouts

On Linux:

curl -sLO https://github.com/argoproj/argo-rollouts/releases/latest/download/kubectl-argo-rollouts-linux-amd64
chmod +x kubectl-argo-rollouts-linux-amd64
sudo mv kubectl-argo-rollouts-linux-amd64 /usr/local/bin/kubectl-argo-rollouts

Verify it's wired up:

kubectl argo rollouts version

You should see something like kubectl-argo-rollouts: v1.8.3+.... From here on, we'll use kubectl argo rollouts ... subcommands to drive the rollout.

Step 3: Defining the Rollout

Argo Rollouts' core idea is that you swap your Deployment for a Rollout resource. The pod template inside it is identical to a Deployment's.

What changes is the spec.strategy block, which describes how a new revision should roll out.

For blue/green, you need three things:

1. A Rollout with spec.strategy.blueGreen configured
2. An active Service, which always points to whichever ReplicaSet is currently serving production traffic
3. A preview Service, which points at the new ReplicaSet before it gets promoted, so that you can test it in isolation

Argo Rollouts injects the rollouts-pod-template-hash label into each Service's selector at runtime, which is how it switches traffic without you ever editing the Services.

Write the manifest:

cat > rollout.yaml <<'EOF'
apiVersion: v1
kind: Service
metadata:
  name: rollouts-demo-active
spec:
  type: ClusterIP
  ports:
    - port: 80
      targetPort: 8080
      protocol: TCP
  selector:
    app: rollouts-demo
---
apiVersion: v1
kind: Service
metadata:
  name: rollouts-demo-preview
spec:
  type: ClusterIP
  ports:
    - port: 80
      targetPort: 8080
      protocol: TCP
  selector:
    app: rollouts-demo
---
apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
  name: rollouts-demo
spec:
  replicas: 2
  revisionHistoryLimit: 2
  selector:
    matchLabels:
      app: rollouts-demo
  template:
    metadata:
      labels:
        app: rollouts-demo
    spec:
      containers:
        - name: rollouts-demo
          image: argoproj/rollouts-demo:blue
          imagePullPolicy: IfNotPresent
          ports:
            - name: http
              containerPort: 8080
              protocol: TCP
          resources:
            requests:
              cpu: 25m
              memory: 32Mi
  strategy:
    blueGreen:
      activeService: rollouts-demo-active
      previewService: rollouts-demo-preview
      autoPromotionEnabled: false
      scaleDownDelaySeconds: 30
EOF

A few fields are worth calling out in the blueGreen block:

• activeService and previewService are the names of the two ClusterIP Services above. Argo Rollouts owns their selectors from here on; you don't edit them by hand.
• autoPromotionEnabled: false is what makes this a manual promotion. The new ReplicaSet comes up, you inspect it on the preview Service, and only then do you flip the active Service over. Set it to true (the default) and Argo will auto-promote the moment the new pods are Ready.
• scaleDownDelaySeconds: 30 keeps the old (blue) ReplicaSet around for 30 seconds after promotion, so if something goes wrong in those first few seconds, you can flip back instantly without rescheduling pods.

Apply it:

kubectl apply -f rollout.yaml

We're using argoproj/rollouts-demo,, a tiny app published by the Argo team that serves an HTML dashboard and a /color endpoint that reports which tagged image is running (blue, green, yellow, etc.). It's perfect for seeing the cutover happen in real time.

Step 4: Checking the initial state

Take a look at the rollout:

kubectl argo rollouts get rollout rollouts-demo

Output:

Name:            rollouts-demo  
Namespace:       default  
Status:          ✔ Healthy  
Strategy:        BlueGreen  
Images:          argoproj/rollouts-demo:blue (stable, active)  
Replicas:  
  Desired:       2  
  Current:       2  
  Updated:       2  
  Ready:         2  
  Available:     2  

NAME                                       KIND        STATUS     AGE  INFO  
⟳ rollouts-demo                            Rollout     ✔ Healthy  34s  
└──\# revision:1  
   └──⧉ rollouts-demo-86c957c6d6           ReplicaSet  ✔ Healthy  34s  stable,active  
      ├──□ rollouts-demo-86c957c6d6-72kjf  Pod         ✔ Running  34s  ready:1/1  
      └──□ rollouts-demo-86c957c6d6-nv3zg  Pod         ✔ Running  34s  ready:1/1

One revision, two pods, both stable and active. Both Services currently point at the same ReplicaSet hash. You can confirm with:

kubectl get svc rollouts-demo-active rollouts-demo-preview \
  -o jsonpath='{range .items[*]}{.metadata.name}{" -> hash="}{.spec.selector.rollouts-pod-template-hash}{"\n"}{end}'

Output:

rollouts-demo-active -> hash=86c957c6d6
rollouts-demo-preview -> hash=86c957c6d6

Step 5: Triggering a new version

Now let's deploy a new revision. We'll change the image tag from blue to yellow:

kubectl argo rollouts set image rollouts-demo \
  rollouts-demo=argoproj/rollouts-demo:yellow

Argo creates a new ReplicaSet (rev 2) for the yellow image and waits, because we set autoPromotionEnabled: false. The active Service still points at blue. The preview Service is re-pointed at yellow:

kubectl argo rollouts get rollout rollouts-demo

Output:

Status:          ॥ Paused
Message:         BlueGreenPause
Strategy:        BlueGreen
Images:          argoproj/rollouts-demo:blue (stable, active)
                 argoproj/rollouts-demo:yellow (preview)
Replicas:
  Desired:       2
  Current:       4
  Updated:       2
  Ready:         2
  Available:     2

NAME                                       KIND        STATUS     AGE  INFO
⟳ rollouts-demo                            Rollout     ॥ Paused
├──# revision:2
│  └──⧉ rollouts-demo-7cf9dff6bb           ReplicaSet  ✔ Healthy  38s  preview
│     ├──□ rollouts-demo-7cf9dff6bb-cbp2c  Pod         ✔ Running  38s  ready:1/1
│     └──□ rollouts-demo-7cf9dff6bb-fn2gt  Pod         ✔ Running  38s  ready:1/1
└──# revision:1
   └──⧉ rollouts-demo-86c957c6d6           ReplicaSet  ✔ Healthy  5m   stable,active
      ├──□ rollouts-demo-86c957c6d6-72kjf  Pod         ✔ Running  5m   ready:1/1
      └──□ rollouts-demo-86c957c6d6-nv3zg  Pod         ✔ Running  5m   ready:1/1

This is the heart of blue/green. The cluster is now running both versions, but only blue is serving real traffic.

Step 6: Proving the split with curl

Forward both Services to your laptop on different local ports:

kubectl port-forward svc/rollouts-demo-active 8080:80 >/dev/null 2>&1 &
kubectl port-forward svc/rollouts-demo-preview 8081:80 >/dev/null 2>&1 &
sleep 3

Hit each one using:

echo "active : $(curl -s http://127.0.0.1:8080/color)"
echo "preview: $(curl -s http://127.0.0.1:8081/color)"

Output:

active : "blue"  
preview: "yellow"

This is exactly the window where you'd run smoke tests, point a staging frontend at the preview hostname, or have Argo run an AnalysisTemplate against Prometheus.

Nothing about production traffic has changed yet.

When you're done with the port-forwards, run the following command:

kill %1 %2 2>/dev/null

Step 7: Promoting

When you're happy, flip the active Service over with one command:

kubectl argo rollouts promote rollouts-demo

Output:

rollout 'rollouts-demo' promoted

Argo updates the active Service's selector to the new ReplicaSet hash.

Subsequent requests should show production traffic is in yellow. The old blue pods stick around for scaleDownDelaySeconds (30 by default) before being torn down, which is what makes the next section possible.

Confirm the cutover by running:

kubectl argo rollouts status rollouts-demo --timeout 60s

You should see Healthy, and the Service selectors should now agree:

kubectl get svc rollouts-demo-active rollouts-demo-preview \
  -o jsonpath='{range .items[*]}{.metadata.name}{" -> hash="}{.spec.selector.rollouts-pod-template-hash}{"\n"}{end}'

Output:

rollouts-demo-active -> hash=7cf9dff6bb
rollouts-demo-preview -> hash=7cf9dff6bb

Step 8: Rolling back

If something goes wrong after the promotion (a metric tanks, you spot an error in the logs, a teammate flags a bug), undo it by running:

kubectl argo rollouts undo rollouts-demo

That brings the previous ReplicaSet back as the new "preview" and pauses, waiting for you to confirm with promote once more, which flips the active Service back to it. Because the old pods were kept warm by scaleDownDelaySeconds, this happens in seconds, not whatever your image pull time is.

Step 9: Cleaning up

Once you're done, you can tear down the demo using:

kubectl delete -f rollout.yaml
helm uninstall argo-rollouts -n argo-rollouts
kubectl delete ns argo-rollouts

How does this fit with Octopus Deploy and Argo CD

Everything we've done so far works on its own. You've got a Rollout, two Services, and a one-command promote/undo loop.

Argo Rollouts is happy to do its job at the cluster level. What it doesn't have is an opinion on how dev becomes staging and then becomes production. Who's allowed to push the button, or what the deployment history looked like six weeks ago.

This is the layer Octopus Deploy is built for. A good mental model is:

• Argo Rollouts owns the cluster-side mechanics: Which ReplicaSet is active, which is preview, when to flip, and when to scale down old pods.
• Argo CD owns the GitOps sync: The Rollout (and its Services) live in a Git repo, and the cluster state is reconciled to match.
• Octopus owns everything above that: Environments, approval gates, release lifecycles, audit trails, and the self-service UI that developers actually click on.

The promotion path between environments is described once in Octopus and reused across every service, instead of being re-encoded in each team's CI script.

Ship green, sleep through the night

If you made it this far, you've got the cluster-side mechanics of progressive delivery sorted: a Rollout flipping between active and preview Services, a manual promotion gate, and instant rollback. That's the hard, hands-on layer done.

What's missing is the orchestration above it, including environments, approvals, audit trails, and the self-service flow your developers actually click. That's where Octopus Deploy slots in, sitting on top of Argo CD and Argo Rollouts to give you a complete progressive delivery stack across every environment, not just one cluster.

Connect your Argo CD instance to Octopus and see how the whole pipeline comes together, or try Octopus free and wire it up against your own cluster.

Happy deployments!

Argo CD 3.5 introduces native, first-class mutual TLS (mTLS) support. By embedding encryption and identity verification directly into its components, it eliminates the need for running service mesh sidecars, writing custom certificate-rotation scripts, or managing complex volume projections just to make sure traffic is secure between the ArgoCD components.

Why mTLS is one step ahead of one-way TLS

Standard TLS provides one-way authentication: the client verifies the identity of the server via a certificate, but the server accepts connections from any client inside the network boundary. So far so good!

Let's take, however, the case of zero-trust architecture, where relying entirely on the network is an antipattern. If an attacker compromises a single pod within the cluster, they can potentially communicate with the repo-server without any authentication.

Mutual TLS (mTLS) addresses this by requiring both sides to authenticate before exchanging any data:

• The client verifies the repo-server certificate to ensure it is communicating with the legitimate repository management layer.
• The repo-server validates the client's certificate against a trusted Certificate Authority (CA) to confirm that the incoming connection originates from an authorized Argo CD component.

:::figure

:img{ src="/blog/img/mtls-support-argocd/blog_1.png" alt="mTLS vs TLS" }

:::

What do you gain by using mTLS:

• First and most important, you stop assuming internal cluster traffic is safe. Every internal component that needs to "talk" to the repo-server must explicitly prove its identity.
• If your environment is regulated by compliance frameworks such as SOC 2, HIPAA, and PCI-DSS, then you are already covered. Native mTLS satisfies the security requirements without adding third-party dependencies.
• By issuing different certificates to different components, you can precisely log which service initiated a connection and establish a foundation for fine-grained access controls.
• Even if an attacker gains access to a pod, they can't actually talk to the repo-server because they lack the required signed client certificate.

The pre-3.5 reality: how operators managed internal encryption

Before native support was introduced in version 3.5, achieving mTLS within an Argo CD deployment forced teams to choose between several complex architectural workarounds.

The service mesh approach

The most common pattern was transferring the encryption responsibility to an external service mesh like Istio or Linkerd. Teams would inject sidecar proxies into their Argo CD pods to intercept traffic and handle the TLS handshake transparently. This architecture was ok-ish. It worked, but if you ask operators, they would probably complain because they had to manage, upgrade, and debug an entirely separate control plane. On the other side, if secure communications is a hard-requirement, then this approach was a great implementation.

:::figure

:img{ src="/blog/img/mtls-support-argocd/blog_4.png" alt="Service Mesh Approach for mTLS in Argo CD" loading="lazy" }

:::

Manual cert-manager integration

Other teams used cert-manager to automatically provision certificates into Kubernetes Secrets, paired with custom Kustomize or Helm patches to manually map those secrets to specific paths inside the Argo deployments. The main point of failure here was certificate rotation. Coordinating pod restarts to ensure components picked up renewed certificates often required writing custom wrapper scripts or relying on auxiliary operators like Reloader, which added more moving pieces to the platform.

Static secret vaulting

In highly locked-down environments, teams synchronized certificates from external stores like HashiCorp Vault using tools like the External Secrets Operator (ESO). While this approach is very auditable-friendly, it creates a tight coupling between the secret store, the sync operator, and the GitOps controller.

In smaller companies, the fallback was often base64-encoding static, long-lived certificates directly into Kubernetes ConfigMaps or Secrets. This bypassed infrastructure overhead but required manual secret rotation which was often a manual process.

Overall, you can see the same pattern in all three approaches described above (there might be more, but they all follow the same basic principles) Internal communication security was handled as an external network problem rather than a native application capability, resulting in fragile configurations challenging to maintain.

What's new in 3.5: built-in mTLS

Argo CD 3.5 simplifies this landscape by moving the handshake, verification, and configuration logic entirely into the application. You no longer need to write complex volume mounts or alter network layers; It's as simple as provisioning a single, specifically named Kubernetes Secret to activate mTLS.

Below you can find a high-level overview of the new features:

1. Super-easy setup (auto-discovery). Argo CD automatically looks for a Secret named argocd-repo-server-mtls. When discovered, the manifests handle the internal mounting and environment configurations out of the box, eliminating manual template patching.
2. The repo-server requires self-directed communication to execute liveness and readiness probes. In a strict mTLS environment, a service can easily block its own health checks. Argo CD 3.5 addresses this by automatically generating memory-lived, ephemeral certificates dedicated exclusively to internal loopback probes, ensuring monitoring remains functional without manual intervention.
3. The feature accommodates both simple and highly complex environments. You can start with a single shared client certificate across all components and transition to unique per-component identities later without re-architecting your underlying deployment strategy.

:::figure

:img{ src="/blog/img/mtls-support-argocd/blog_2.png" alt="mTLS handshake. How Argo CD 3.5 handles authenticates connections between Argo CD components" loading="lazy" }

:::

Now let's take a more detailed look at the setup process for the shared-certificate configuration.

Getting started: the shared-certificate setup

For the majority of production deployments, a single shared client certificate used by all client components is enough and requires minimum configuration

Step 1: Generate the certificates

If you are not using an automated PKI pipeline, you can generate the required CA, server, and client certificates using standard OpenSSL commands:

openssl genrsa -out ca.key 2048
openssl req -new -x509 -days 365 -key ca.key -out ca.crt \
  -subj "/CN=argocd-internal-repo-ca"

openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr \
  -subj "/CN=argocd-repo-server"
openssl x509 -req -days 365 -in server.csr \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out server.crt

openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr \
  -subj "/CN=argocd-core-clients"
openssl x509 -req -days 365 -in client.csr \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out client.crt

Step 2: Construct the mTLS kubernetes secret

Create a secret named argocd-repo-server-mtls in your Argo CD namespace. The keys within the data block must strictly conform to the expected naming convention:

apiVersion: v1
kind: Secret
metadata:
  name: argocd-repo-server-mtls
  namespace: argocd
type: Opaque
data:
  client-ca.crt: <BASE64_ENCODED_CA_CRT>
  client.crt: <BASE64_ENCODED_CLIENT_CRT>
  client.key: <BASE64_ENCODED_CLIENT_KEY>
  server-ca.crt: <BASE64_ENCODED_CA_CRT>

If you are a CLI fan, you can generate and inject this secret directly using kubectl:

kubectl create secret generic argocd-repo-server-mtls \
  --from-file=client-ca.crt=ca.crt \
  --from-file=client.crt=client.crt \
  --from-file=client.key=client.key \
  --from-file=server-ca.crt=ca.crt \
  -n argocd

Step 3: Trigger a rolling restart

As usual, to let the services pick up the new configuration, secrets, and certificates and initialize mTLS, you need to run a rolling restart across your deployments:

kubectl rollout restart -n argocd \
  deployment/argocd-server \
  deployment/argocd-repo-server \
  deployment/argocd-application-controller \
  deployment/argocd-applicationset-controller

If you are running the application controller in a High Availability (HA) configuration, remember to target the statefulset instead:

kubectl rollout restart -n argocd statefulset/argocd-application-controller

Validating the connection handshake

Once the pods are restarted, check the argocd-repo-server logs to confirm successful initialization. You should observe log messages related to the self-generation of certificates for the internal health check as below:

Generated ephemeral health-check client certificate (CN=argocd-repo-server-health)

To verify that mTLS is now enabled, try to execute a direct gRPC or HTTP request to the repo-server from an unauthenticated pod inside the cluster. The connection should terminate immediately during the TLS handshake phase, log an untrusted client error on the server side, and prevent any data exposure.

To the contrary all internal communications to repo-server are now encrypted.

So far we have seen how easy to enable mTLS using a default approach, same client certificate across all components. This probably works for most of the production environments, but there are cases where you might want to use different certificates for different components. The following sections will show you how to do that.

Advanced configurations: per-component certificates

In enterprise environments with strict auditing requirements or multi-tenant architectures, sharing a single client certificate across all services may violate compliance rules. Argo CD 3.5 supports unique and different, per-component certificates through the following two approaches.

:::figure

:img{ src="/blog/img/mtls-support-argocd/blog_3.png" alt="Advanced Configurations: Per-Component Identities" loading="lazy" }

:::

Option A: multiple keys within a single secret

You can store all individual component certificates inside the primary argocd-repo-server-mtls secret using distinct key identifiers. This centralizes your secret management while allowing smooth delivery to each client component via volume projection patches. Check the sample yaml below. You can see that for each component we have a separate key for the client certificate (server-*, controller-*, etc.)

apiVersion: v1
kind: Secret
metadata:
  name: argocd-repo-server-mtls
  namespace: argocd
type: Opaque
data:
  client-ca.crt: <BASE64_CA_PEM>
  server-client.crt: <BASE64_SERVER_CERT_PEM>
  server-client.key: <BASE64_SERVER_KEY_PEM>
  controller-client.crt: <BASE64_CONTROLLER_CERT_PEM>
  controller-client.key: <BASE64_CONTROLLER_KEY_PEM>

Once you have added the above secret to K8s, patch the volume mount configuration of each component deployment, ensuring it maps its custom key to the filename the client expects (client.crt):

spec:
  template:
    spec:
      volumes:
      - name: argocd-repo-server-mtls
        secret:
          secretName: argocd-repo-server-mtls
          items:
          - key: server-client.crt
            path: client.crt
          - key: server-client.key
            path: client.key
          - key: client-ca.crt
            path: client-ca.crt

The main advantage of this approach is that you are still keeping all certificates in a single secret. Obviously the disadvantage is that you need to maintain explicit volume mount overrides across all components that need to talk to repo-server.

Option B: isolated secret objects per component

The second approach suggests breaking the secret configuration to individual, component-specific secrets (e.g., argocd-repo-server-mtls-server, argocd-repo-server-mtls-controller): So for each component that communicates with repo-server, you create a separate secret with the appropriate client certificate and key. For example:

apiVersion: v1
kind: Secret
metadata:
  name: argocd-repo-server-mtls-server
  namespace: argocd
type: Opaque
data:
  client.crt: <BASE64_SERVER_CERT_PEM>
  client.key: <BASE64_SERVER_KEY_PEM>

Then you need to patch again each deployment's volume specification to point to its corresponding secret:

spec:
  template:
    spec:
      volumes:
      - name: argocd-repo-server-mtls
        secret:
          secretName: argocd-repo-server-mtls-server

This is the most clear approach because you keep the secrets for each component isolated from the others. This allows you to rotate keys independently of the primary secret, which is a common practice in multi-tenant environments.

But as you know, there's no free beer. The downside (if you think of it as a downside) of this approach is that you need to maintain separate Kubernetes Secret objects for each component.

Real-world use cases

Comprehensive zero-trust layering

Native mTLS provides a critical mid-tier authentication layer that complements existing security layers. A strong and complete defense-in-depth model for Argo CD typically relies on the following layers:

1. Network policies that restrict pod-to-pod communication paths so that only valid Argo CD components can route packets to the repo-server port.
2. K8s service accounts that define exactly what an authenticated client process is allowed to execute once the connection is opened.
3. Native mTLS which is used to authenticate data exchange between services at the application layer.
4. Application RBAC which allows fine-grained access control to Argo CD resources.

Audit-ready compliance (SOC 2 / HIPAA / PCI-DSS)

When preparing for an audit, proving internal data security can be challenging when relying on third-party service meshes or complex bespoke scripts. Auditors look for easily verifiable, reproducible security controls. Pointing to a native, platform-supported configuration driven by a declarative Kubernetes Secret simplifies the compliance narrative considerably compared to explaining a custom infrastructure mesh setup.

Multi-tenant control planes

For large organizations running multi-tenant internal developer platforms (IDPs), combining per-component certificates with upstream gRPC interceptors allows cluster administrators to log, trace, and isolate internal requests precisely by team or business unit. This level of traceability is highly beneficial for forensics and chargeback metrics.

Migration patterns

Transitioning an active production cluster from a service mesh or custom cert-manager architecture to native mTLS might sound like a complex task but it can be executed with minimal risk using the following, incremental, approach:

1. You can keep your existing Root CA. Use your current certificate authority to generate the initial client certificates and keys.
2. Deploy the argocd-repo-server-mtls secret into the cluster while your existing sidecars or custom mounts are active. The presence of the secret will not change anything until a reload occurs.
3. Execute a rolling restart of all Argo CD components to pick up the new configuration.
4. Verify that the connection handshake (via the native mTLS configuration) is successful and that all internal traffic is now encrypted.
5. Once the connection is established, remove the old configuration, disable sidecar injection, etc.

Well done! – you are now using native mTLS for all internal traffic.

Architectural recommendation

This article cannot cover all the production cases out there but we can summarize the recommendations for two groups of implementations. If you are operating a small-to-medium-sized Argo CD installation looking for an immediate security upgrade with low operational friction and no specific requirement to audit individual internal component traffic streams. On the other side, if you are looking for a more robust and comprehensive security model, because, for instance, you are in a highly regulated enterprise environment, then you should consider the per-component approach that gives you the most flexibility and control.

For most teams, starting with a shared certificate configuration is the most pragmatic approach. The good (excellent) news is that if your compliance needs scale over time, migrating to separate component identities involves adjusting your manifest overlays without replacing your underlying secrets architecture.