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.

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.

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.

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.

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.

For those who have accepted that you can move fast without breaking things, a second myth is emerging: The myth of speed.

When you look at teams that deploy frequently with short lead times, you’ll find they are generally more successful than those who work in larger batches. This checks out when you consider the additional work large batches cause. There’s also a benefit to the automation you introduce to achieve higher throughput.

But if you think speed alone is driving the success of these teams, their products, or the organization’s market share, you’re making a common mistake.

You can develop a better understanding of the broader factors that contribute to success using the Bullseye Model, which captures the nuance of product velocity.

A quick archery lesson

Many sports present a target with a bullseye, but we’ll use archery as an example today.

When you practice shooting a bow, your goal isn’t to hit the bullseye (though that will become the goal later). Instead, you should develop consistency so your arrows land in a tight group. Until you can consistently group your arrows, any bullseye you hit is chance, not skill.

Much of the skill in archery comes from the discipline of form. You have to develop consistency in where you place your feet, how you hold your body, the way you draw the bow, and how smoothly you release the string. You repeat this by making very deliberate moves many times over, working through a checklist in your mind each time, until it becomes automatic.

Once you’ve developed these skills, missing the bullseye becomes part of the feedback loop. When you know you’ve got all the movements right, you’re able to attribute any drift to other sources. You can now adjust your aim to compensate for the many variables, like wind speed, moisture in the air, and distance, and you develop a feeling for when you’ve damaged an arrow and need to repair it.

If you were betting on an archer based on scores, you’d likely pick the left-hand target. You now know that, over the course of a whole competition, the right-hand target was made by the archer more likely to win. When an archer can group their arrows in a tight bunch, they can move that group closer to the bullseye and achieve far higher scores than those hitting the target randomly.

Why speed isn’t enough

Let’s return to the topic of building software. We need to establish why speed alone isn’t a sufficient strategy. If you’ve been following the research, you’ll be familiar with the insight that deploying more often with short lead times makes your team, software product, and organization more successful (source: DORA). Interpreting this as “speed equals success” is a simplification of the true picture.

Many teams and organizations are working hard to improve their software delivery performance without realizing a crucial element is missing from their approach. Alongside the smooth flow of changes, you need to develop a deep understanding of the user, their goals, and what’s causing them problems and friction.

The research captures this in a construct called “user-centric focus,” and the Bullseye Model is how you navigate it.

The bullseye sits at the center of the target. It represents an absolutely perfect product-market fit for your software product. If you imagine the best product your customers could ever want, that’s the bullseye. Except you can’t imagine it, which is why you need to apply the Bullseye Model.

Product velocity

There are infinite paths for developing a software system. The two most interesting are where you are now compared to the ideal product you could build. The concept of the ideal product is asymptotic, but it’s better, faster, safer, and cheaper than your competitor’s products.

To map product velocity, you need to know your starting point. What you’ve built likely isn’t the absolute best product, so your customers’ needs are not fully met. Your starting point will be somewhere other than the bullseye. It may be close to the gold circle, or it could be wallowing in the very edge of the last white one.

From this starting point, you create a roadmap, which is your hypothesis about what will make your software look more like the ideal product. Each roadmap entry is another arrow hitting the target, and each time you shoot an arrow, you have the opportunity to observe where it landed.

The line between the starting point and the new arrow has a distance and direction. This is your vector, telling you whether you’re heading in the right direction and how quickly. You have to watch both, as only a careless organization celebrates speed without paying attention to direction.

The direction of the vector tells you how well your roadmap is servicing the hunt for the ideal product. If the vector points to the bullseye, your assumptions were perfect. More often, you’ll find you’re making less efficient moves.

When you move away from the bullseye, your hypothesis is invalid, and you need to adjust course. You might back up and try a different approach (returning to the previous starting point), or incorporate feedback that changes the outcome (continue from where your arrow landed, hoping to flip the loss to a gain).

When speed does matter

On the Bullseye Model, speed refers to how quickly you can prepare and shoot each arrow. We can apply the lessons from the research here, as we don’t want throughput (lots of arrows) without stability (hitting the target).

Speed does matter, but it’s not the goal. Your ultimate aim is to reach the bullseye, but being able to smoothly and quickly deliver arrows creates more opportunities to check your vector and adjust course. Crucially, when you start trending away from the center, you can rapidly reverse course without over-investing in the wrong approach. You might start building an “offline mode” only to discover users are confused by how you’ve implemented it, or that they don’t value the idea at all and would prefer to be notified when they are back online.

Any speed you have in excess of your ability to check your vector and change course is wasted, as it’s as likely to move you rapidly away from the bullseye as it is to move you closer. You need to develop feedback cycles in concert with your software delivery throughput, while maintaining stable operations.

Moving in the right direction is the primary concern and high-throughput is a valuable way to check your vector more often.

AI makes deployment pipelines crucial

The introduction of AI-assisted software development means teams have the potential to increase their throughput. There are preconditions for this to be true: the techniques and practices described in Continuous Delivery, as evidenced by research programs like DORA.

When you increase change throughput, you must adapt to this rate of change in other areas, or queues will eat all your gains. Manual stages in your deployment pipeline need refinement. You may automate, augment, or prioritize them, but leaving them as they were before AI-assisted development is not an option.

Deployment governance has become crucial in regulated organizations and those working at scale, as fragmented governance processes will result in a total loss of all return on your AI investments. Your default path to production must be the easiest, safest, and most compliant way to deliver changes, with no exceptions or expediting.

The Bullseye Model also reminds you that the rate at which you can collect and absorb feedback is a crucial consideration of how quickly you can introduce changes. If you can’t tell if a change is moving you toward the ideal product, you’re simply spinning out of control.

While our competitors are counting token use, pull requests, or lines of code, the thing that we should focus on above all else is how rapidly we are closing the gap between where our product is today and the ideal product described in our roadmap.

Happy deployments!

There are many things I like about ephemeral environments, and I think they add significant value to the software development lifecycle. However, I have recently been asked a few times whether ephemeral environments can be skipped as part of the PR process. Once was at NDC Sydney, where I gave a talk on Ephemeral Environments, and another was by a colleague who regularly works on these microsites internally.

I sat down to think about this, and refactored the GitHub workflow to accommodate the request.

Why skip ephemeral environments?

Ephemeral environments are valuable, but as I learned through these recent conversations, they’re not always required. Our ephemeral environment process for microsites, which creates an Azure Storage account with Terraform and then deploys the website package to the target storage account, can take 5 to 9 minutes.

Our GitHub repositories have protections on the main branch, and in addition to a required review, we have checks that must pass before the PR can be merged. Some of those checks check spelling and Markdown syntax, but another checks that the build process completed successfully. Part of that build triggers the ephemeral environment deployment in Octopus Deploy, so deploying the ephemeral environment can delay the build’s completion.

Another reason that came up in a community discussion was the issue of busy repositories and the amount of infrastructure that may be provisioned when environments are spun up for each PR. Especially if those environments have high costs, there could be real cost implications at scale. Though I’d also argue that there are other factors to investigate, like the duration of opened PRs, to see if optimizations can be made elsewhere.

The common thread across all these scenarios is that the decision to deploy an ephemeral environment is contextual; it depends on the nature of the change and the needs of the people reviewing it. Rather than removing ephemeral environments from the process entirely, what I needed was a way to make them optional on a per-PR basis, with minimal friction for the developer raising the PR.

It turned out that GitHub’s PR labels were the perfect tool for the job.

Skipping ephemeral environments with a PR label

The original GitHub workflow file only had one job. All steps were within the single job, and the required checks for the GitHub repo were configured to verify a successful run of this single job before allowing the PR to be merged.

While you can make steps in a workflow conditional, the more I looked at it, the more I realized it made sense to break the workflow into multiple jobs to achieve different outcomes.

• build — always runs on every PR. It installs dependencies, builds the site, runs tests, packages the artifact, and uploads it for use by subsequent jobs.
• deploy-ephemeral — picks up the artifact from the build job, pushes it to Octopus Deploy, creates the ephemeral environment, and deploys the release. This is the job we want to make optional.
• pr-ready — a lightweight gate job that acts as the required status check for the main branch. It verifies that build succeeded and that deploy-ephemeral either succeeded or was deliberately skipped.

The key to making deploy-ephemeral optional is a single if: condition on the job:

deploy-ephemeral:
  runs-on: ubuntu-latest
  needs: build
  if: ${{ !contains(github.event.pull_request.labels.*.name, 'skip-ephemeral') }}
  ...

This checks whether the PR has a label named “skip-ephemeral”. If the label is present, the entire job is skipped. If it isn’t, the job runs as normal. Adding the label to a PR before opening it is all that’s needed to skip the deployment to the ephemeral environment.

But by breaking the workflow into two jobs, I introduced another problem I needed to solve.

Using a gate job to keep branch protection intact

Previously, the required check on the main branch pointed directly at the single build job, and if it passed, the PR could be merged. With the refactored workflow, I couldn’t configure the required check to check the status of deploy-ephemeral anymore, because that job might be intentionally skipped. A skipped job registers as a failed required check in GitHub, which would block the PR from merging even when everything went exactly as intended.

I needed a reliable way to signal whether the overall workflow succeeded or failed, regardless of whether the ephemeral deployment ran. That’s where the pr-ready gate job comes in.

The pr-ready job runs after both build and deploy-ephemeral, and uses if: always() to ensure it runs regardless of what happened upstream. Inside the job, a single step checks two conditions:

• build must have succeeded, as there’s no scenario where a failed build should result in a mergeable PR
• deploy-ephemeral must have either succeeded or been deliberately skipped. A failure in the deployment job should still block the merge, but a skip should not

If either of those conditions isn’t met, the step runs exit 1, which fails the job and blocks the PR from merging. The required check on main now checks the pr-ready job rather than either of the other two, so it always has a clear, predictable result to work with.

pr-ready:
  runs-on: ubuntu-latest
  needs: [build, deploy-ephemeral]
  if: always()

  steps:
    - name: Verify required checks
      run: exit 1
      if: >-
        needs.build.result != 'success' ||
        (needs.deploy-ephemeral.result != 'success' &&
        needs.deploy-ephemeral.result != 'skipped')

Making it simple to use

I wanted to make it as easy as possible for developers to skip an ephemeral environment, should they want to. When creating a PR, all they need to do is add the label skip-ephemeral to the PR. When the PR is opened, the GitHub workflow will start, read the labels assigned to the PR, and skip the deploy-ephemeral job. The build still runs as expected, and the pr-ready job will execute, which is the job being tracked by required checks for PRs.

It’s worth noting that the label needs to be present before the workflow triggers. If you open a PR without the label and the workflow starts running, adding the label mid-run won’t affect that run. The label state is read from the event payload when the workflow was triggered. If you push a subsequent commit, the workflow will re-trigger and read the current label state at that point, so the skip will take effect from your next push onwards.

One change, every team benefits

One of the things I enjoy about working with a Platform Engineering mindset is that the improvements I make to shared infrastructure benefit everyone who relies on it. In this case, I was responding to a request from one of our application teams, but because our microsite build process is templated and shared across multiple teams, the change I made is immediately available to every team using the same workflow. At the same time, the platform team can also decline a feature request. If skipping ephemeral environments conflicted with the organization’s risk, compliance, or deployment policies, we could simply choose not to implement it, and every team consuming the shared workflow would remain compliant by default.

This is the value of treating your pipelines as shared, versioned infrastructure rather than copies of a golden template. When every team has its own copy of a pipeline, improvements stay local to the team, making it harder for the platform team to push changes out. When teams consume a shared workflow, a single change propagates everywhere, everyone benefits, and the platform team can focus on building improvements rather than coordinating rollouts.

Wrapping up

Ephemeral environments are a powerful tool for reviewing changes in a real environment before they’re merged, but there are scenarios where developers may want to skip the ephemeral environment process. It’s not something I’d lean towards myself, and I definitely wouldn’t make that the default behavior.

By breaking the workflow into separate jobs and using a simple-to-use PR label as a condition, it’s possible to make the ephemeral environment deployment optional without compromising the integrity of the build process or the branch protection rules that rely on it.

Happy deployments!

In 2024, we launched the Octopus Deploy App in the GitHub Marketplace. It has been widely adopted, unsurprisingly, as it is the most seamless way to connect Octopus Deploy and GitHub. At launch, however, it did not support self-hosted Octopus Server customers.

This means until now, if you self-host your Octopus instance and you integrate with GitHub, you’ve been doing it with Personal Access Tokens (PATs). PATs work, but they’ve never been ideal for a critical integration like this, suffering from a number of problems:

• Someone leaves the team and their PAT goes with them
• A token quietly expires at 2am and a deployment falls over
• PATs are user-scoped, long-lived, and often have more permissions than they strictly need

We’ve received plenty of feedback requesting support for the Octopus Deploy App for GitHub from our self-hosted customers, and we’re happy to say that as of release 2026.2 it’s available.

What’s shipping

GitHub Connections are now available for self-hosted Octopus Deploy. You can install the Octopus Deploy App for GitHub, connect it to your self-hosted instance, and use it anywhere the product currently requires GitHub credentials.

Under the hood, GitHub Connections use OpenID Connect (OIDC) to exchange a signed token from your Octopus instance for a short-lived GitHub token, scoped to the repositories you’ve granted the app access to. There are no long-lived secrets to store, rotate, or leak. The permissions are managed in GitHub against the app installation, not against a user account. When someone leaves the team, nothing breaks.

What about Octopus instances behind a firewall?

This is the part that took the most thought.

OIDC requires GitHub to fetch the public signing keys from your Octopus instance to verify the tokens it issues. That works fine on Cloud, and it works fine on a self-hosted instance that’s reachable from the public internet. It doesn’t work if your instance lives behind a corporate firewall, on a private network, or otherwise isn’t reachable from github.com, and this is true for many self-hosted installs.

So we’ve added a second option. On the Signing Keys settings page, you’ll find a new Externally Hosted option. You generate your signing keys in Octopus as usual, then publish the public keys to any web host you like, such as an S3 bucket or Azure blob storage, whatever fits your infrastructure, and tell Octopus the OIDC issuer URL where GitHub can fetch them. Octopus signs tokens with that issuer URL, GitHub validates them against the published keys, and your private instance never has to take an inbound connection from the internet.

The signing keys docs walk through the options.

Getting started

GitHub Connections are available to all self-hosted customers from 2026.2. See the GitHub Connections docs for the details of how to configure the integration between Octopus Deploy and GitHub, without Personal Access Tokens.

Happy deployments!

When they actually do, the plan is typically a runbook in a wiki, or the fact that, in theory, we can always revert to the last working commit. When you run Kubernetes, Argo CD is instrumental in keeping your resources in sync.

Argo CD is good at reconciling whatever’s in your Git repo to your cluster. When a deploy goes sideways, “roll back” turns into “revert the right commit, in the right repo, without breaking the other applications syncing alongside it”, which is fine on paper and miserable in practice.

In this post, we’ll explore how to manage releases in Octopus Deploy, how it integrates with Argo CD, and discuss, as well as implement, a rollback.

What Argo CD doesn’t do (and why it matters)

Argo CD is great at one job: take whatever’s in your Git repo and reconcile a cluster to match it. It’ll show you what’s drifted, when it last synced, and which resources are unhealthy.

However, what it deliberately doesn’t do is anything above the cluster.

There’s no concept of a release. Each Application is an independent entity, and its current state is whatever commit HEAD happens to be on. If Tuesday’s image tag turns out to be a regression, your options are: revert the commit in Git and wait for the next reconcile, or open the Argo CD UI and sync to a previous revision by hand.

More importantly, the processes around what constitutes a release that can be synced are something Argo simply wasn’t built for.

How Octopus manages releases with Argo CD

A release in Octopus is a versioned snapshot of three things:

• the deployment process (the steps it runs)
• the variables those steps use, and
• the package or image versions they reference.

Once a release is created, it’s frozen. You can promote 0.0.2 through Development, then Staging, then Production, and each environment receives the same release, not whatever happens to sit at HEAD when you trigger the deployment.

With the Argo CD integration, that release model integrates into your existing GitOps setup. When you deploy a release in Octopus, you can have an Argo CD step that rewrites the image tags in your repo, commits the change with the credentials you’ve attached, then asks Argo CD to sync. Argo CD keeps doing the reconciliation while Octopus keeps the lifecycle.

Prerequisites

This tutorial assumes you have:

• A working Kubernetes cluster (any flavour)
• kubectl installed and pointed at the cluster
• The GitHub CLI (gh) installed and authenticated (gh auth login). We’ll use it to create the demo repo in one command
• An Octopus Cloud (or self-hosted) instance, with the Argo CD Gateway installed in the cluster and an Argo CD instance already registered against Octopus. If you haven’t done that yet, follow the Connecting AWS EKS Argo CD to Octopus Cloud guide first; the same flow works for any cluster.
• A Git Personal Access Token (PAT) scoped to your demo repository, Octopus will use it to push image-tag commits back

Step 1: Create the Octopus project

1. Sign in to Octopus and head to Projects > Add Project.

2. Give it a name (we’ll use argo-demo), pick Kubernetes as the deployment target, and answer Yes to Are you using Argo CD?

3. Leave the lifecycle on Default Lifecycle.

   

4. Hit Create Project.

Step 2: Add the Argo CD step

You’ll land on the Process editor.

1. Click Add Step and filter by Containers and Orchestration > Argo CD in the left sidebar. You’ll see two installed step templates:
   • Update Argo CD Application Image Tags, which updates an image tag in your manifests and commits the change for Argo CD to sync
   • Update Argo CD Application Manifests, which generate manifests from templates using Octopus variables, and commit those.

We’ll use the first one for this walkthrough.

Step 3: Set up the manifests repository

Argo CD syncs from Git, and Octopus pushes image-tag updates back to that same repo, so before either side has anything to do, we need a repository with a workload manifest in it.

We’ll keep the layout small: one Deployment, one Service, and the Argo CD Application that wires the two systems together.

argocd-octopus-demo/  
├── application.yaml      \# the Argo CD Application (apply once to the cluster)  
└── manifests/  
    └── app.yaml          \# workload Argo CD reconciles from this repo

1. Create the directory locally:

   mkdir -p argocd-octopus-demo/manifests

   cd argocd-octopus-demo

2. Write the workload manifest. We’re using nginxdemos/hello:plain-text, a tiny nginx that responds with a text page naming the pod that served the request. It’s a single-container app with no state, perfect for proving reconciliation worked end-to-end.

   cat > manifests/app.yaml <<'EOF'
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: hello
     labels:
       app: hello
   spec:
     replicas: 2
     selector:
       matchLabels:
         app: hello
     template:
       metadata:
         labels:
           app: hello
       spec:
         containers:
           - name: hello
             image: nginxdemos/hello:plain-text
             ports:
               - containerPort: 80
             resources:
               requests:
                 cpu: 25m
                 memory: 32Mi
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: hello
   spec:
     type: ClusterIP
     selector:
       app: hello
     ports:
       - port: 80
         targetPort: 80
         protocol: TCP
   EOF

3. Initialize the repo, create a public GitHub repo from it, and push the first commit:

git init -b main

git add .

git commit -m "chore: init"

gh repo create <your-org>/argocd-octopus-demo \
  --public \
  --description "Argo CD + Octopus Deploy demo manifests" \
  --source=. \
  --push

With the repo live, we can write the Argo CD Application that points at it.

Step 4: Scope the Argo CD Application with annotations

The Octopus gateway pulls the full list of Argo CD Applications from your cluster, but it doesn’t yet know which of them belong to this Octopus project. You can tell it with three annotations on the Argo Application:

• argo.octopus.com/project[.<source-name>]
• argo.octopus.com/environment[.<source-name>]
• argo.octopus.com/tenant[.<source-name>]

The .<source-name> suffix matches spec.source.name on the Application, which lets you scope different sources of a multi-source Application to different Octopus projects.

For our argo-demo project and Development environment, an annotated Application looks like this:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: argo-demo
  namespace: argocd
  annotations:
    argo.octopus.com/project.argo-demo-source: argo-demo
    argo.octopus.com/environment.argo-demo-source: development
spec:
  project: default
  source:
    repoURL: https://github.com/<your-org>/argocd-octopus-demo.git
    targetRevision: HEAD
    path: manifests
    name: argo-demo-source
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

The two annotations there tie this Application to the argo-demo Octopus project, scoped to the development environment. The suffix .argo-demo-source matches the spec.source.name field below it.

Apply it:

kubectl apply -f application.yaml

Within a few seconds, the Octopus gateway picks up the new annotations, and the Application appears in the project’s deployment preview.

Step 5: Preview the deployment

Back in Octopus, in the Process tab, click on the step you just added.

Annotations have been discovered, but flags that the source repo is missing Git credentials. Click View Applications to see what was matched.

The deployment preview opens. You should see the argo-demo application listed under the Rollback Argo CD instance, scoped to the Development environment, with the source repo URL underneath.

Step 6: Connect Git credentials

Octopus needs Git credentials so the step can push the new image-tag commit.

1. Click the Connect Git Credential dropdown next to the repo URL.

   

2. Pick Create a new Git credential (or Connect an existing Git credential if you’ve already added one to the space).

Once the credential is attached, the warning on the deployment preview clears and the source shows up as ready to update.

Step 7: Configure the step

Back on the step, fill in the rest:

The key fields:

• Step Name, leave as the default unless you have multiple Argo CD steps in one process.
• Container Images, click Add to declare which container image(s) this step should bump. You’ll point it at a package/container reference so Octopus knows which image and which feed to pull tags from.
• Git Commit Settings, the commit author/email Octopus uses when it pushes the tag update.
• Commit Message, supports Octopus variables, so something like chore: bump image to #{Octopus.Action.Package[hello].PackageVersion} is a good default.

Save the step.

Step 8: Create a release

Head to the project dashboard, and you should now see the Create Release prompt.

On the release form, give it a version (Octopus auto-suggests 0.0.1) and click Save.

Release notes are optional but recommended for anything you’d want a changelog entry for later.

Step 9: Deploy to Development

Pick Deploy to Development on the release page. Octopus kicks off the deployment, and the task log streams the three sub-steps in real time:

1. Update Argo CD Application Image Tags, Octopus rewrites the image tag in the manifest and pushes the commit
2. Triggering Argo CD application syncs, Octopus asks Argo CD to sync the Application
3. Wait for Argo CD Application Health, Octopus polls the Application until it reports Healthy

When all three turn green, you’ll see a completion line in the task log, and a Deploy to Staging… button appears at the top right, ready for the next environment in the lifecycle.

You can verify the rollout landed on the cluster side too:

kubectl -n default get deploy hello -o
jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'

Step 10: Rolling back: redeploying a previous release

The deploy half of the demo is done. The other half is the one that actually earns its keep: a release that turns out to be bad, and how Octopus takes you back to the previous one without anyone opening a terminal.

To simulate it, hit Create Release again, save as 0.0.3, and deploy it to Development. Imagine the new image is broken (regression, missing env var, whatever). To roll back, head to Releases in the project’s left sidebar.

Click 0.0.2 to open it, then look at the lifecycle table. The Development row will show its previous deployment with a Redeploy… button.

Click Redeploy…, confirm, and the same three sub-steps run again.

Octopus rewrites the image tag in Git back to the one 0.0.2 used, commits it, asks Argo CD to sync, then waits until the Application reports Healthy.

When the task completes, the project dashboard shows 0.0.2 back in Development.

When to roll back vs when to roll forward

For this demo, rolling back was a single click. That doesn’t mean rolling back is always the right call. Rollbacks have a way of failing that isn’t always talked about.

They assume the rest of the system is in a state that the old version can still talk to. Most of the time it is. Sometimes it very much isn’t.

Take, for instance, a database. If a bad release adds a new column and your users have been generating data through that path for an hour, rolling the application code back doesn’t unwind the schema or the data. The old app meets the new schema and either ignores fields it doesn’t know about (best case) or crashes on them (worst case)

Refactoring databases buys you flexibility. If schema changes go in through additive, backward-compatible migrations (add columns nullable, write to both old and new fields for a release cycle, then drop the old in a later release), rollbacks stay safe much longer.

Make rollbacks boring

If you made it this far, you’ve got the full loop: an Argo CD Application scoped to an Octopus project with annotations, a deploy that flows from a click down through Git into your cluster, and a redeploy that takes you back to a known-good release the same way.

Argo CD keeps reconciling, your manifests stay the source of truth, and Octopus wraps versioning, approvals, audit, and that redeploy button around them. The rollback nobody had tested becomes a button two engineers know how to press.

Beyond manual rollbacks, Octopus enables you to build out full lifecycles on your deployments, so this can all be automated conditionally.

Extend the pipeline to your real environments using the Argo CD integration docs, or if you don’t have an Octopus instance yet, start a free trial and run this end-to-end on your own cluster.

Even for teams that can effortlessly deploy their application code, database changes can be more stressful. Changing a schema is a high-stakes operation, and there are many ways to do it badly.

Read on to find out why database deployments are different from application deployments, and what techniques you can use to make them worry-free.

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

Why are databases different

When you change your application’s code and discover an issue, it’s trivial to revert to the previous version. In rare cases where a change affects your data, there may be cleanup to do.

You can use timestamps and a one-off process to fix those rare data-mess-up instances, but they hint at something fundamentally different about database updates. They have different levels and types of risk associated with them.

If you think backups will save you from a bad database deployment, you haven’t yet tried it. Sure, they prevent total data loss, but between your backup and your fix, the data moved. Often by a lot.

There are techniques to apply transactions from the backup up to the point of failure, but if your change caused an issue you needed to roll back, you probably don’t want to apply those transactions automatically. Welcome to the “data remediation project”.

If you added a new column or table as part of your database change and you need to roll back, you have to decide what to do with any data in those tables. Do you forget it, or do you need to keep hold of it and reapply it later when you make a new attempt to extend the schema?

Modern software teams prefer fix-forward for application issues, which are reasonably easy to roll back. Databases take rollbacks to another level.

Crucial modernization steps

Imagine you met a friend for lunch and they told you they store they application’s source code on a network share, rather than in version control. You’d think it was a joke, and when you realize it’s not, you’d form a strong opinion about the kind of sloppy outfit they must be running.

When we meet for lunch, what are you going to tell me about your database schema and static data? Please tell me it’s all in version control, not on a network share.

You should make all database changes by updating the files in version control and deploying them like you would your application code. You progress the change through environments to ensure it works, and you avoid embarrassment caused by the application failing because someone forgot to add the new column in production.

There are further choices to make, which we’ll cover next, but failing to version-control your database is unforgivable.

State-based vs migration-based approaches

On to the first choice for your database project. Do you make state-based or migration-based updates?

State-based schemas describe the desired state of the database. It will list each table with its columns, indexes, and relationships. You use a model-based tool to deploy the database, which compares your current state with the desired state and applies the changes for you.

Some state-based tools convert the differences into standard database scripts, like ALTER TABLE... scripts. Others perform migrations by creating a new table with the changes and moving the data into it. This is important if you’re using a technology like replication, which prevents the model migration mechanism from working.

The alternative to state-based database updates is migration-based updates, where you write your own ALTER TABLE scripts. You keep all your scripts in version control and use a tool that applies them in order and tracks when each was applied, preventing the same script from being applied twice to the same database.

The main difference between the two is procedural. You can code-review the migration scripts on demand, but you’ll need to review state-based migration scripts after your tools generate the implementation plan, which can make the review task more of a large batch.

Tooling and automation

Whichever approach you use, tooling helps it work. Many of our customers use Redgate tools as part of their deployment process to manage database schema changes, and there’s value in leaning on a tool written by folks who care deeply about the problem and how to solve it.

Crucially, you shouldn’t make any database changes outside of tool-based automation.

Test data management

Once you’ve automated your database schema and static data, it’s worth considering your test data. When automated or manual acceptance tests fail, it’s usually because someone unwittingly messed up the data. Prior test runs often leave data in an inconsistent state, especially if a test failure halts the run.

You can resolve this issue by automating your test data setup. Not only does this make it easy to reset the data during your build and test cycle, but it also lets you provide a self-service runbook for the test team to reset the data in their test environment whenever they need to.

There’s an up-front investment in this, but I can promise that it takes fewer hours than fixing your test data a few times.

Database refactoring patterns

The final thought to ponder concerns the steps you take in changing your database schema. When you’re in the habit of deploying your database and application in the same release process, you start to depend on this change coordination.

You delete a column from the database and immediately deploy the application, with all references to the deleted column removed. It looks like it works smoothly, but it’s a trap.

Imagine you had a critical bug in the application and had to redeploy the previous version. Now you can’t, because the previous version will try to read from a column that doesn’t exist. You no longer have a quick, easy back out plan, since you have to re-add the column, and you’ll also need data to put in it.

This approach also prevents you from making seamless deployments, as even if you progressively roll out the application version, the old version will error out due to the database change. You may deploy in the opposite order, application first, then database. You’ll discover the same problem with new columns that the latest version expects to find in the database.

You need to decouple database and application deployments, and there’s a whole book on the topic, called Refactoring Databases (Ambler, Sadalage). You can start by following the expand/contract pattern, which splits updates into steps. The principle is that you don’t delete a column until the production application has no reads or writes. You add a column and don’t reference it in your code until you deploy to production.

This means you can run the current version and the new version of the software against the same database, which means you can progressively roll out the new version and redeploy the prior version without touching the database.

Databases are only as hard as you make them

The database is high-risk, which is why updating it can be scary. I hope you’ve found this post full of practical advice for making database deployments robust and stress-free.

Database deployments, like application deployments, should be a happy time. You should be celebrating the new features and enhancements you’ve delivered to your users, not biting your nails and worrying that something’s about to go horribly wrong.

Happy deployments!

That’s why the strategic partnership between Octopus Deploy and GitHub is so significant.

While many organizations view AI as a coding assistant, GitHub and Octopus are helping teams unlock something more powerful: an AI-enabled software delivery platform that connects development, deployment, operations, and most importantly governance into a single intelligent workflow.

As partners, we made steps in this direction by contributing to major innovations such as Copilot Extensions back in 2024, then Custom Agents in 2025 and now being again a launch partner for Agent Apps within GitHub.

No more context switching and more control over your agents

The launch of Agent HQ at GitHub Universe made it already possible to access coding agents from Anthropic, OpenAI, Google, Cognition and xAI directly within the GitHub interface. Because regardless of how powerful they are, more agents will not improve efficiency, but rather generate complexity and loss of control unless properly governed.

But writing code is only one part of the journey. The real challenge for enterprise teams begins after the pull request is merged:

• Understanding deployment status
• Managing complex release pipelines and troubleshooting production issues
• Coordinating multi-tenant deployments and identifying issues while operating software at scale
• Maintaining security and compliance controls

Historically, these activities have required developers to switch between multiple tools, dashboards, and operational systems. But every context switch creates friction, every disconnected workflow slows delivery or, even more importantly, delays recovery when something goes wrong.

This is precisely the problem Octopus and GitHub are solving together by bringing the Octopus Intelligence to Agent HQ . When deployment information becomes accessible through natural language, organizations can unlock knowledge that was previously only accessible to specialist teams and take action quicker when necessary, avoiding downtime.

“The future of software development won’t be shaped by any single agent, but by an ecosystem of specialized ones. Our partners are defining what that looks like by embedding Agent apps into the GitHub workflows where developers build and ship.” Mario Rodriguez, Chief Product Officer at GitHub

By combining the Octopus MCP Server with specialized skills, the Octopus Intelligence Agent enables a seamless, automated workflow. This integration allows the agent to interact directly with Octopus Deploy from the GitHub interface, surfacing key data and executing tasks as directed.

Here is an example use case for the Octopus Intelligence Agent, directly within GitHub Agent HQ:

• Show the deployment status of a PR, and when it was deployed to a specific tenant
• Investigate and diagnose why it has failed
• Use the appropriate runbook to fix the failure
• Redeploy to tenant

See it in action! The demo video below shows how the Octopus Intelligence agent helps diagnose and recover from failed tenant deployments without leaving GitHub. When reviewing a PR, you can check the deployment status across tenants, investigate failures, and trigger the appropriate runbook to fix the root cause - then redeploy directly to the affected tenant once resolved.

Demo video

Our strategic partnership

Octopus Deploy and GitHub share a long standing committed partnership, focused on shaping a best-of-breed enterprise CI/CD landscape.

GitHub is where developers collaborate, build, and innovate. Octopus is where organizations orchestrate complex deployments across hybrid infrastructure, including Kubernetes, cloud-native platforms, or legacy systems, with enterprise governance in mind.

And we are not stopping there. By aligning our GitHub and Microsoft partnerships, we are able to bring the next level of DevOps innovation to our customers.

Together, we create a connected software delivery experience that helps teams move faster and securely despite the increasing complexity.

Learn more about our partnership with Microsoft and GitHub:

Microsoft case study video

If you are interested in using Octopus together with GitHub, you can now register for a free account - the agentic features are included! Octopus Deploy can be purchased via the Microsoft Marketplace and is Azure benefit eligible.

Happy deployments!

What are superseded tasks?

A task is superseded when a newer task makes it redundant. For example, if three deployments of the same project and environment are queued, the first two are superseded once the third is queued, as the third deployment will leave the environment in the desired state.

As AI coding tools push commit and PR volume upwards, a growing queue of superseded deployments becomes more pronounced

Instead of letting those redundant tasks run to completion, Octopus can automatically cancel them to expedite the latest task. The result is faster deployments, shorter feedback cycles and less resource use.

How does it work?

When a new deployment task is queued, Octopus checks for other queued tasks that target the same project and environment. If it finds tasks that are waiting to start, it cancels them and marks them as superseded.

A few important things to note:

• Only queued tasks that are yet to start are considered for cancellation. If a task has already started executing, Octopus won’t interrupt it mid-deployment.
• Tasks with skipped steps or included/excluded targets are not considered for cancellation since it’s difficult to ensure the intended changes are still flowing through the deployment pipeline
• Superseded tasks are cancelled, not deleted. You can still see them in the task log with a clear explanation of what happened and which task superseded them.
• This applies to deployments and runbook runs where the outcome of the newer task makes the older one irrelevant.

Variation - cancel running tasks

As we were developing the Argo CD integration, we realized that Octopus could potentially have many deployments paused while waiting for pull request approval for the same project and environment. Once the latest pull request merges, the user would need to cancel the previous deployments manually.

This is why we’ve added the option to also cancel running tasks that are waiting for external events like pull request merges and manual intervention.

How do I configure this?

These settings are active by default for all new projects, you can customize the behavior for each project’s deployment process or runbook by editing their respective settings.

Learn more

For the full details on how superseded tasks work, head to the official documentation.

Happy deployments!

Most practitioners will be familiar with this. A script, a Lambda, a homegrown integration that filled a real gap at the right moment. It was built for good reasons, shipped, and is still running somewhere in your stack. Knowing when it’s time to let it go is the hard part.

That moment usually comes when your vendor catches up, and it happens much more often than most people realize.

Why do we build our own things?

A friend recently posted something on LinkedIn that grabbed my attention:

This is a story most practitioners will recognize. You’re working with a tool you depend on, but it might lack functionality for something you need to achieve today, so you build around it. A script, a wrapper, in Sam’s case, a Lambda, whatever it might be. You have a real need today, the vendor doesn’t have an answer yet, and may not for many months or years, so you solve it yourself. There’s nothing wrong with this approach; it’s pragmatic engineering, and the right call.

Vendors can’t prioritize every use case that every customer might have. Their roadmap has to serve a broad set of customers, which means your specific requirement might be well understood - and something the vendor wishes to solve - but it may not be next in line on their list of priorities. So you build something that fits your context and environment, ship it, and move on to the next problem.

Platform Engineers will recognize this

This is especially common for platform teams. They’re often the ones filling gaps across a whole stack of tools being used by hundreds or thousands of developers and application teams. Most Platform Engineers will resonate with building integrations, abstractions, and internal tooling so the rest of the organization doesn’t have to think about the seams between tools and has a great experience.

At Octopus Deploy, we see this across our customer base. One example that comes to mind is a customer who needed to ensure a specific deployment step was always present and enabled across thousands of projects. The problem will likely be familiar — developers, eager to get past a failing step and move on with their deployment, would disable or remove it entirely. In this case, skipping the step introduced a serious risk to the organization, as the step was critical to their auditing processes.

Octopus didn’t have a great built-in answer for this at the time, so the customer wrote a script that interrogated the API, identified non-compliant projects, and flagged them for manual review. It worked for the purposes it was built for, but it was reactive, needed maintenance, and relied on one or two people who understood it well enough to keep it running if something broke or needed tweaking.

We’ve since introduced Policies as part of Platform Hub, an enforcement engine that handles exactly the scenario the customer was looking for, baked into the product proactively.

In both cases I’ve shared, the build was the right call. But eventually the vendor caught up, and that changed things.

The slow drift problem

When you ship a custom solution, the problem is solved, and life moves on. But quietly over time, it becomes part of the furniture. It runs on a schedule, or it sits in a repo somewhere, and nobody questions it because it works. The person who wrote it might still be around, or they might not. Either way, the context that existed when it was built starts to fade.

Meanwhile, the vendors you depend on don’t stand still. They’re shipping new features, adapting to the market, and building capabilities based on the feedback their customers have been giving them. That script you wrote, or the Lambda you set up two years ago to solve a problem they didn’t have an answer for? There’s a decent chance you weren’t the only one with that problem to solve, and the vendor may have an answer for it now. But if you’re not paying attention to what they’re shipping, you’d never know.

The Octopus example is a good illustration of this. The API script that checked for compliant deployment steps across thousands of projects didn’t stop working, and nobody rushed to replace it. But when Policies shipped as part of Platform Hub, the situation changed. The same requirement was now handled in the product, proactively, and without the maintenance overhead. The custom solution wasn’t immediately a problem; it had just become unnecessary. Unnecessary code you’re still running, maintaining, and depending on is a cost easy to overlook because nothing is visibly broken.

This is precisely where it matters for platform teams. A platform team’s job is to make the engineering organization more effective, and that works best when the platform stays focused on the goals it is there to achieve. Taking on a custom solution to fill a vendor gap is good technical debt. It’s a conscious tradeoff, made at a specific point in time to keep the platform moving. But technical debt has a repayment point, and when a vendor ships their own solution to something you’ve been solving yourself, that’s usually the moment it arrives. Keeping the custom solution running past the point where it is needed is when good debt turns into bad debt, leaving you paying maintenance overhead and dealing with complexity that no longer needs to exist. The best platform teams recognize that moment and act on it. Let the vendor carry the maintenance burden, absorb the edge cases, and handle the support. This keeps your platform thin, lets you remove complexity, and frees your team to focus on what only you can build.

But none of this is possible if you don’t know what your vendors are shipping. The repayment moment only arrives if you recognize it, and that’s the part that’s easy to miss because keeping up with every tool in your stack, across every channel each vendor uses, can feel like a job in itself.

Staying connected without it becoming a job

You can’t spend your life reading vendor changelogs. That would be a full-time job, and you already have one. But there’s a meaningful middle ground between obsessively monitoring every release and being completely unaware, and most of the time, good vendors are trying to meet you there. At the end of the day, vendors want you to know about new features and functionality, and start using their solutions to solve the problems you have.

At Octopus, we try to surface what we’re shipping across a range of channels, and the intention is that at least one fits how you already work and where you prefer to consume content. Some examples of where we do this are:

• Monthly newsletter
• Blog
• What’s New feed
• In-app notifications
• Webinars
• Deploy on Friday
• Social media
• YouTube
• Community Slack
• Roadmap
• Press room
• Shipped (yearly online event)

Most vendors are making a similar effort. The bar for staying loosely connected is lower than it probably feels.

One approach I’ve found genuinely useful is using AI to do the monitoring for me. There are a few ways to tackle this, but I’ve been using skills in Claude for this use case. You can get Claude to help you build a skill, using the built-in skill builder by saying something like “Can you help me build a skill?”. From there, you can provide context of what you’re interested in, and provide as many resources from the vendor as you can. I specifically note that I’m usually not interested in non-product-related posts (e.g., from social media feeds), and that any duplicate items found across multiple sources should be consolidated.

Your mileage will vary depending on how the vendor provides updates and how consumable those updates are for something like a large language model. Vendors who publish structured, well-maintained feeds like a dedicated changelog page, a What’s New feed, and versioned release notes tend to work much better as sources than those whose updates are scattered across social media posts and marketing announcements. But within about 30 seconds, I can say “grab me the last month’s updates from Octopus Deploy”, and Claude uses the skill to build a response in the format I’ve specified, that I can easily scroll through. Claude is also pretty good at linking to the source if I want to explore something further.

Keeping pace

When a vendor ships a solution to something you’ve already solved yourself, moving to it is usually the right call. They’ve absorbed the edge cases, they own maintenance going forward, they’ve researched the feature’s requirements and may build something you didn’t already have, and you get to decommission something. Your team can focus on building things of value and importance to your organization, and you can push complexity down to vendors, creating a thinner platform that floats on top of the capabilities they provide.

My friend Sam was paying attention to what the vendors he uses are doing, saw the AWS announcement, and was able to decommission a custom solution in favor of AWS’s built-in solution. It’s a small habit - staying loosely connected to what the tools you depend on are shipping - but it’s what put him in a position to act when the moment arrived.

When did you last look at what your vendors have been shipping? It’s probably worth 20 minutes to find out.

Happy deployments!

Octopus Deploy has built-in integration with Argo CD. If you want to understand the technical details and setup instructions, feel free to take a look at the announcement and the documentation.

In this post, we want to focus on the “why” of the integration rather than the “how”. We have talked with several customers about the Octopus/Argo CD collaboration, and most discussions always start with similar questions:

• Why do I need Octopus if I already deploy with Argo CD?
• How does Octopus change the Argo CD experience?
• Does Octopus improve how GitOps deployments work with Argo CD?
• Is GitOps with Octopus better than GitOps with Argo CD?

If you have already adopted Argo CD and are wondering about the value of Octopus and how it supercharges your GitOps deployments, read on!

Octopus and Argo CD work together

Octopus does not change the excellent GitOps engine that Argo CD already offers. Instead, it allows you to scale Argo CD to Enterprise organizations that have special requirements regarding security, standardization, observability, etc.

The two tools work together to offer you a complete solution that is appropriate for Enterprise adoption of GitOps best practices.

GitOps standardization across your teams

Adopting Argo CD on the first team is an easy task. The problems start when Argo CD adoption grows beyond the initial phase within an organization. Can you guarantee that the second, third, fourth, and Nth teams are adopting Argo CD the same way?

Argo CD is a very flexible tool that can be used in multiple ways. This is a double-edged sword. On one hand, it means that Argo CD can cover many use cases. On the other hand, it also means that every team can deviate from the “approved” or “blessed” way if there are no guardrails in place.

The most common pattern we see is with Git commits. Argo CD is great for taking your Git changes and deploying them to a Kubernetes cluster.

This is a well-understood process and the foundation for GitOps deployments. The hidden question here is who updates the Git files? How are they updated? And when? Argo CD doesn’t really care about how a change found its way into Git. But if you are working in an organization that cares about standardization and auditing, you must know that all your teams deploy the same way.

Several times we talk with customers who say they have “standard” GitOps deployments and in reality, they do something like this:

This setup is a big problem for organizations that want to scale their Argo CD usage. If every team is doing something else you don’t really have a way to enforce best practices and security processes across your company.

Even if some teams are using the same tool such as GitHub actions or Jenkins, these tools are originally built for Continuous Integration. Abusing them for GitOps deployments presents several challenges that need workarounds and custom solutions in areas like:

• Manual approvals (especially when coupled with external systems)
• Security and access control (who can actually deploy/approve/commit)
• Correlation with artifacts and everything else that goes inside a release (auditing and security)
• Maintenance overhead and developer onboarding (solved with Octopus Platform Hub)

We talk with several organizations that tell us that they have tried to standardize on using a single solution such as GitHub actions. But even though on paper it seems like they have solved standardization with a custom script in reality:

• The “solution” is a homegrown script that nobody wants to maintain
• Because it is completely custom, it must be constantly updated and adapted to new requirements
• It can never scale to the needs of an Enterprise
• Day 2 operations are always lengthy and risky as they affect services that are already in production

This is where Octopus steps in. Octopus Deploy comes bundled with standard, preconfigured and auditable steps for changing the Git manifests that Argo CD monitors.

By adding Octopus, you enhance your GitOps deployments by enforcing a consistent approach to Git manifest management across all your teams. If you use Octopus and Argo CD you don’t need to guess what each team is doing to change their Git files. You know exactly what goes into Git, and you also have full visibility into how, when, and by whom all those changes are approved.

A big advantage of Octopus Deploy that is missing in Continuous Integration tools is the concept of the Release. Octopus knows what a release is and has a first class construct for everything that goes inside one. This allows for three significant advantages:

1. Octopus Deploy keeps a detailed record of all the files and artifacts that took part in the deployment for any release, even for past ones. This is important for auditing and security purposes. Standard Continuous Integration tools only know what is happening during the actual run
2. Octopus Deploy can easily perform rollbacks to previous releases as it has full knowledge on what needs to be done to bring things back to an earlier state. This is critical during incidents when downtime is affected and developers need to go back to the previous version as fast as possible.
3. With Octopus Deploy you can fully automate all Git commits, essentially preventing developers from making manual commits. If you know that only Octopus Deploy can commit, security controls are audits are now much easier in your organization.

This is the common theme for doing GitOps with Octopus. Octopus doesn’t replace the powerful GitOps engine that Argo CD implements. But using both tools together allows you to expand your GitOps practices in an enterprise setting that has different requirements about scale, security, compatibility, and auditing.

Application promotion between environments

At its core, an Argo CD application is a bidirectional link between a Git repository and a Kubernetes cluster. Argo CD continuously monitors the Git repository and deploys the application to the cluster. In a large enterprise, clusters are usually grouped by software release lifecycle (QA/Production/Staging).

Developer teams always want to gradually deploy their applications to a sequence of environments that starts with low-risk clusters and ends with the “production” clusters. For companies under strict regulations (e.g. financial institutions, HLS, Manufacturing controls etc.) this is an even more critical process as developers will be blocked from deploying anything to production unless it has been approved first in lower-risk environments.

Argo CD is excellent for deploying to a single Kubernetes cluster, but it doesn’t have any visibility into what this cluster represents and which “environment” it belongs to. By default, Argo CD will deploy a brand new application to a cluster, and it has no capacity to “promote” an application from a previous environment.

A very popular workaround for this problem is when teams choose a special naming convention for their Argo CD applications:

A human administrator who looks at the picture above will understand that they see a single application called “accounts” which is currently deployed to 3 different environments (qa/prod/staging). This information is only available to human users. As far as Argo CD is concerned, these are 3 different and unrelated applications.

This forces a lot of teams to create custom scripts or tools that handle the promotion of developer applications. This is problematic in so many ways:

• Different teams might create different scripts, resulting in effort duplication
• Promotion scripts are always hard to maintain and hard to adapt to new requirements
• Developers are constantly in firefight mode when deployments fail, as they do not understand the differences between environments
• Administrators cannot enforce common security policies and company guidelines across their teams

Octopus Deploy solves this problem entirely by modeling environments on top of Argo CD applications. In addition, you can model promotion processes directly into Octopus and get full visibility on which state each application is in right now. Understanding what is deployed and where the latest changes are is crucial not only during daily operations but also during incidents. Not knowing what your environments have will result in downtime when incidents happen.

Octopus environments essentially allow developers to promote their applications with less risk, higher confidence, and full visibility.

When an incident happens, all teams always ask the same 2 questions:

• What was the last change/version that was deployed in the problematic environment?
• What is the safe version that we can rollback to, and which environment has guarantees that it is safe to rollback to?

These two questions can be answered in seconds with Octopus Deploy using the environments dashboard.

Security and compliance

Deploying an application to production is always the last step in a lengthy process, which, depending on the nature of the company that uses Argo CD might take from a couple of hours to several days. Sending a new feature to production is important, but it is also critical to be able to reason about:

• How this feature was created
• Who implemented it
• Who approved it
• The security requirements it satisfies

Argo CD knows only the last part of the deployment process. It deploys an application into a Kubernetes cluster without any real knowledge of what features are contained in this release or who created it. Again, this forces a lot of teams to create ad-hoc solutions with custom scripts that function as workarounds, implementing essential enterprise requirements such as manual approvals or correlations with the Continuous Integration phase of a software release.

Octopus Deploy already has built-in support for understanding the whole picture of a software release. Octopus Deploy can also interface with external systems and artifact registries in order to create a full snapshot of the release process in a secure and auditable manner.

Deployment approvals are a critical part of the software lifecycle, especially for companies that operate under strict legislation (e.g. companies with financial or health data). Argo CD does NOT offer an approval mechanism. While it is possible to perform basic approvals with Git, enterprise organizations often want to integrate existing approval mechanisms in their GitOps workflows.

With Argo CD and Octopus Deploy, you get the best of both worlds. Argo CD implements a powerful GitOps engine, while Octopus handles all the requirements for Enterprise deployments.

Further enforcing the standardization aspect, all Octopus workflows can use Platform Hub templates that result in a secure and controlled workflow process. With Platform Hub your administrators can create and define the approved workflows for how deployment works within an organization. Developers across all teams must then use the approved workflow templates in their own projects. This avoids duplicated effort and custom/ad-hoc deployment processes that might result in downtime or failed security audits.

Developer experience and observability

Helping developers quickly and safely bring their changes to production is vital as this is the only way that new features can reach customers. The time a change needs to reach production is actually one of the DORA metrics and has a direct correlation to the performance of an organization.

While Argo CD has a comprehensive User Interface that system administrators love, developers have entirely different needs when it comes to application promotion.

Some examples of the questions that developers need to answer daily are:

• Which is the last environment that application X was deployed to?
• How many versions is “production” behind “staging” for application Y?
• What was the last software release that was deployed to environment Z?

As we explained already, Argo CD doesn’t model deployment environments. Only Octopus can map business environments (Staging/production, etc) to Argo CD applications. This way, Octopus can quickly answer all these questions in seconds instead of hours.

Octopus is also the best way to show multiple applications from different Argo CD instances in a single dashboard. This way, developers can see aggregated information across the whole organization about what their applications are doing.

The Octopus Deploy environment dashboard is a single pane of glass that can

• Aggregate applications from different Argo CD instances
• Show which environments are implemented by the different clusters
• Document deployment history on an environment level instead of individual clusters
• Help developers promote applications to different environments in a safe way
• Give an overview of the live status of applications and their logs

Blocking developers from understanding what is deployed where is a crucial problem during incidents. If developers cannot quickly determine which version is deployed in an environment and which version to rollback to, the incident will cause downtime for end users, leading to loss of business and customer dissatisfaction.

Conclusion

By adopting Octopus Deploy for your GitOps process, you can scale Argo CD across a large organization with many clusters/applications/developers. Argo CD still performs the last step of the deployment using its powerful synchronization engine, while Octopus handles all the enterprise requirements that the modern software lifecycle includes, such as approvals, auditing, and compliance.

With Octopus, all developer and operator teams have a single way to deploy to production without any custom scripts or glue code. Octopus standardizes your GitOps workflows by eliminating ad hoc solutions for manifest management that require constant maintenance and are often fragile and complex to update.

At the same time, developers get the full picture of how an application is promoted between different environments and can quickly understand where each application is deployed and what it needs to progress to the next environment. This results in less downtime, especially during incidents when understanding which applications are affecting which environments becomes time-critical.

If you want to know how Octopus can scale your Argo CD installation contact us or browse the documentation.

Happy deployments!

In a previous article, we looked at connecting an Argo CD instance running on a Self-Hosted Azure Kubernetes Service (AKS) to Octopus Deploy. While this was neat, AWS still leads the cloud infrastructure market at around 29% as of Q3 2025, according to Synergy Research Group, so if you have been wondering how to replicate that tutorial on EKS, you’re in the right place.

Why connect Argo CD on EKS to Octopus Cloud?

Running Argo CD on EKS gives you GitOps-driven deployments into Kubernetes, but Argo CD alone does not cover the full delivery picture. On the other end of that picture is Octopus, which coordinates the release process around it: approvals, environment progression, runbooks, and a single view across Kubernetes and everything else you ship.

Octopus Cloud customers get a mostly plug-and-play experience because Octopus has already configured the communication rules on its side, and the Helm commands generated by the connection wizard handle the rest (assuming no egress restrictions sit in front of the Argo CD cluster).

In our previous blog, a lot of the steps came about as a result of needing to open up certain ports in order to establish connectivity with your Octopus server; the majority of this goes away when you run in AWS and use Octopus Cloud.

Prerequisites

In order to follow along with this portion of the tutorial, you will need the following tools installed locally.

• Terraform, for provisioning ArgoCD and the Argo CD Gateway onto the cluster
• Helm, for installing the gateway chart
• kubectl, for interacting with the cluster
• ArgoCD CLI, for generating an auth token for the Octopus gateway account
• An Octopus API key, for accessing the Octopus Deploy REST API

Step 1: Provision a Kubernetes cluster

If you already have a cluster, feel free to skip to the next section. However, if you don’t, the following lines will use the EKS CLI, to create one.

To follow along, run the following commands:

Create a cluster configuration:

 cat << 'EOF' > cluster.yaml
  apiVersion: eksctl.io/v1alpha5
  kind: ClusterConfig

  metadata:
    name: basic-cluster
    region: eu-north-1

  nodeGroups:
    - name: ng-1
      instanceType: m5.large
      desiredCapacity: 10
      volumeSize: 80
      ssh:
        allow: true # will use ~/.ssh/id_rsa.pub as the default ssh key
    - name: ng-2
      instanceType: m5.large
      desiredCapacity: 2
      volumeSize: 100
      ssh:
        publicKeyPath: ~/.ssh/id_rsa.pub
  EOF

The cluster configuration above will provision two nodes with m5.large as the instance type, feel free to tweak the configuration as you see fit.

Create the cluster by running:

eksctl create cluster -f cluster.yaml --timeout 45m

NOTE: The --timeout flag here is to ensure the CLI does not timeout before the cluster is done being provisioned.

Finally, you can obtain the Kubeconfig for the cluster created by running:

eksctl utils write-kubeconfig --cluster=basic-cluster --region=eu-north-1

Step 2: Install ArgoCD

The next step is to install ArgoCD. Using the helm chart is the most straightforward means of installing.

Head back to your terminal and run the following command:

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

The output is similar to:

NAME: argocd  
LAST DEPLOYED: Fri Apr 15 14:32:08 2026  
NAMESPACE: argocd  
STATUS: deployed  
REVISION: 1  
TEST SUITE: None  
NOTES:

The command will install Argo CD into a namespace called argocd, the extra values file tacked on sets up the account Octopus will use to talk to it.

accounts.octopus: apiKey creates a dedicated octopus user in Argo CD and enables API key authentication for it, so Octopus has its own identity rather than piggybacking on admin.

The rbac block then scopes what that user can do: policy.default: "role:readonly" makes read-only the baseline for any account without an explicit grant, and the policy.csv lines grant the octopus user only the permissions it needs.

The values above become relevant once we install the Octopus Argo gateway.

What is the Octopus Argo gateway?

Simply put, the Octopus Argo gateway is a component required to establish a secure, TLS-encrypted connection between an Argo CD instance (running in a Kubernetes cluster) and the Octopus Deploy.

In contrast to self-hosted setups where you need to create firewall rules and potentially consider what certs to use to secure the communication, the Octopus Argo gateway handles it all.

Generate an authentication token

In order for the gateway to authenticate with the ArgoCD instance you just deployed, an authentication token is required. To create one, run the following commands:

Grab the auto-generated admin password:

ARGOCD_PASSWORD=$(kubectl get secret argocd-initial-admin-secret \
  -n argocd \
  -o jsonpath='{.data.password}' | base64 --decode)

Port-forward the Argo CD server to localhost:18080:

kubectl port-forward svc/argocd-server -n argocd 18080:443 &
PF_PID=$!
sleep 5

Log in as admin:

argocd login localhost:18080 \
  --username admin \
  --password "$ARGOCD_PASSWORD" \
  --insecure \
  --grpc-web

Mint a token for the octopus account:

argocd account generate-token \
  --account octopus \
  --insecure \
  --grpc-web

Be sure to copy and save the token

Clean up the port-forward:

kill $PF_PID

Step 3: Link your cluster

From here on out, installing the Octopus Argo gateway is only a few clicks.

Within the sidebar on the left side of your Octopus dashboard, click on the tab Argo CD Instances.

Within the Argo CD instance tab click on Add Argo Instance.

Up next, you should be greeted with the following menu.

Enter a name for this cluster’s connection, and if you wish you can select an environment for the ArgoCD instance. Leave the DNS name as the default unless you modified it during the Helm install.

Paste in the authentication token you generated earlier and hit next.

Select which project you would like to connect your Argo instance to and hit Configure Project.

Right after the configuration wizard, it will return a Helm install command which looks something like this.

helm install --atomic \
  --create-namespace --namespace octo-argo-gateway-eks-dev \
  --version "*.*" \
  --set registration.octopus.name="EKS-dev" \
  --set registration.octopus.serverApiUrl="https://<your-octopus-instance>.octopus.app/" \
  --set registration.octopus.serverAccessToken="<your-octopus-server-access-token>" \
  --set registration.octopus.environments="{development}" \
  --set registration.octopus.spaceId="Spaces-1" \
  --set gateway.octopus.serverGrpcUrl="grpc://<your-octopus-instance>.octopus.app:8443" \
  --set gateway.argocd.serverGrpcUrl="grpc://argocd-server.argocd.svc.cluster.local" \
  --set gateway.argocd.insecure="true" \
  --set gateway.argocd.plaintext="false" \
  --set gateway.argocd.authenticationToken="<your-argocd-token>" \
  eks-dev \
  oci://registry-1.docker.io/octopusdeploy/octopus-argocd-gateway-chart

Paste the command in your terminal and In a couple of seconds your cluster should be connected!

When do I pick Octopus Cloud over self-hosted?

If you caught our last blog on connecting an AKS cluster to a self-hosted Octopus server, you might be wondering which path fits your setup.

Octopus Cloud makes sense when you want the connection to just work. The wizard generates the Helm command, you paste a token, and you are done. If your team does not have a strong reason to run Octopus on your own infrastructure, this is a reasonable path.

Self-hosted Octopus makes sense when the answer to “can the server live in our VPC?” is “it has to.” which usually comes down to data residency rules, existing on-premises infrastructure you need to keep using, or security policies that will not let a third party hold your deployment control plane.

You pay for that control with the networking work in Shawn’s post: opening inbound ports, handling internal DNS, dealing with certs signed by your own CA, and configuring load balancers for gRPC. None of it is hard, but it is work.

Wherever your clusters live, Octopus fits

In this post, we walked through connecting an EKS cluster to Octopus Cloud.

We also looked at some of the tradeoffs between doing this in a self-hosted environment versus the cloud.

Whichever path fits your constraints, the outcome is the same. Argo CD keeps doing GitOps. Octopus handles approvals, environment progression, runbooks, and everything outside Kubernetes that you still need to ship.

Spin up a free Octopus Cloud instance and try the Argo CD integration for yourself, or book a demo if you want a walkthrough.

Happy deployments!

The best compliance teams look for ways to protect the organization and its customers from risk without overburdening teams with bureaucratic procedures. You want compliance set to maximum, and the ability to deliver high-quality, valuable software set to maximum. You don’t want some compromise between the two.

Good compliance sounds like DevOps

If you know DevOps, this will sound familiar. Traditional managers saw software delivery as a compromise between throughput (creating and improving software features) and stability (keeping everything working). They measured developers on throughput and ops teams on stability, then wondered why there was so much conflict between them.

Just as the solution to the software delivery problem was to align both teams to the shared goal of throughput and stability, you must do the same with other desirable system qualities, like security and compliance.

Rather than calling this DevSecOps or DevSecCompOps, we can call it DevOps because everything that relates to software fitness is part of DevOps.

The non-DevOps way is for stability to be an afterthought and compliance to be an ominous late reaction to an upcoming audit. The DevOps way is to make these part of the daily work, automate as much as possible, and deliver the outcome of compliance instead of the frantic output of audit theater.

It’s about being safe and secure, not looking safe and secure.

Compliance automation

You can approach compliance by copying what other organizations are doing. Most organizations have a spreadsheet with obliquely referenced requirements that developers are regularly asked to update and evidence. Who doesn’t love an ORG-05.15-ACCESS-CONTROL line item in a spreadsheet?

However, the best compliance teams I’ve worked with took a different approach. They spent more time educating developers like me about the reasons for these requirements so we could find ways to satisfy them, collect evidence, and keep customers safe.

This meant we considered compliance needs when writing features, selecting tools, or changing our process. When we looked at tools for builds, deployments, and monitoring, ease of meeting compliance needs and automation of evidence collection were part of the buying decision.

This isn’t just about making audits easy; it’s about making compliance easy, and it’s about making the desired outcomes of compliance more likely. Your toolchain can do much of the heavy lifting, leaving you to show and tell during an audit while listening out for opportunities to make things even better.

How Octopus supports easy compliance

Octopus has many features that ease your compliance burden and increase safety, from enterprise-grade access controls and audit trails to innovative automation. Let’s take a quick tour of some crucial compliance features:

• Role-based access control
• Extensive audit trails
• IT service management integrations
• Platform Hub policies and templates
• Octolint
• Runbooks

Role-based access control

Octopus Deploy has fine-grained role-based access controls (RBAC) that integrate with single sign-on (SSO) providers. You can define roles and permissions to control who can change deployment processes, runbooks, and other configurations. You can also define who can access the automation for different projects and environments.

You can use RBAC to prevent unauthorized changes and enforce segregation of duties. You can also safely create self-service actions, like letting testers deploy to the test environment or clear a web cache to speed up their testing without giving them more extensive permissions.

Extensive audit trail

Octopus automatically captures a detailed audit log for all significant system events. This includes deployments, configuration changes, user access events, and more. Octopus records every action that changes a state, including who initiated it.

These tamper-resistant audit logs let you demonstrate the changes made to applications or infrastructure. When you need to delve into the audit trail, it’s easy to filter actions by user or by a specific area in Octopus, like spaces, projects, environments, event types, and more.

IT service management integrations

Our integrations with ServiceNow and Jira Service Management remove manual hand-offs between Octopus and your IT service management (ITSM) platform. This makes it easy to ensure changes have the appropriate approval before progressing.

The integrations automatically create change requests associated with a deployment. You can block deployments until the change gets approved. This increases compliance, as no unapproved changes get deployed to production—but it does so without creating toil for the developers.

Platform Hub

Platform Hub lets you define policies that deployments must meet before they can proceed. When a deployment fails a check, Octopus blocks it and surfaces an explanation with links to your standards or internal guidance so that teams can fix the issue without a slow back-and-forth with compliance.

Process and project templates give teams a consistent starting point for pipelines. You configure sound defaults once and reuse them, which makes it easier for teams to meet policy requirements without reinventing their setup for every project.

Octolint

Octolint is a tool that scans your Octopus instance and recommends improvements to your setup. It detects potential issues such as perpetual API keys, shared Git user names, and unused deployment targets.

Instead of manually auditing for good practices, Octolint can automatically scan and report on items that need your attention.

[OctoLintDefaultProjectGroupChildCount] The default project group contains 79 projects. You may want to organize these projects into additional project groups.
[OctoLintEmptyProject] The following projects have no runbooks and no deployment process: Azure Octopus test
[OctoLintTooManySteps] The following projects have 20 or more steps: K8s Yaml Import 2

Runbooks

Financial institutions need good plans for both daily operations and emergencies. Octopus Runbooks help with this. You can turn routine and emergency operations tasks into reusable automations for things like:

• Database maintenance
• Restarting systems
• Applying urgent fixes
• Recovering backed-up data

Automated runbooks are safer and more reliable, reducing the need for broad distribution of elevated access. Runbooks in Octopus also log changes and runs to the standard Octopus audit trail. You can also use runbooks to automate compliance tasks like recovery testing, audit reporting, or probing firewall ports.

Octopus loves compliance

Octopus has many features that reduce the compliance burden and help you build security, privacy, and compliance into your DevOps process. As an organization, Octopus also maintains compliance with ISO 27001:2013, SOC 2 Type II, and SOC 3 with regular third-party audits and technical assessments for security, safety, and privacy. You can find out more about this in our trust center.

Tools that reduce the compliance burden are crucial to organizations in the financial industry or other regulated and safety-critical environments. Your toolchain can help maintain innovation and compliance just like it brings you throughput and stability.

Happy deployments!

Traditional monoliths are often described as a big ball of mud or spaghetti code due to the complicated mess of dependencies. When all the code is co-located, it’s common to find a tangled web of paths, with interfaces and facades skipped in favor of direct access to low-level functions and classes. This kind of code is hard to maintain.

Majestic monoliths are well-structured and loosely coupled, with carefully designed dependencies that are sometimes enforced by architectural tools. By making things modular, you get the benefits often associated with microservices, but without the difficulty of finding the code or the runtime complexity of distributed systems.

Microservices go a step further by physically separating parts of the system into independently deployable units. In addition to the architectural benefits, you can get faster build and test run times because you only build and test each service when it changes, which involves much less code. The trade-off is that your codebase becomes more complex, and you have to deal with versioning and issue pinpointing across all the deployed services.

So, how do you choose between these approaches?

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

Architectural decision factors

Many factors influence the decision between monoliths, microservices, and hybrid approaches. One of the most crucial is how your teams are structured and how much autonomy they need. There are different ways to design team structures, like Team Topologies, that make your teams and architecture part of the same conversation.

This is consistent with the inverse Conway maneuver, in which you structure your teams to match your target architecture. This works because Conway’s Law states that organizations design systems that mirror their communication structures. Working at the team level is more effective than creating an architectural diagram, as the structure will naturally yield the design you want.

Having a mismatch between the number of teams and the number of components can add complexity, either because too many teams are working on a single module, or you have created so many modules that there aren’t enough teams to own all the maintenance tasks associated with them. A sensible default is to match the number of teams to the number of components, ensuring sufficient autonomy for each team to work independently without overburdening them with excessive complexity.

The matching of service and team design sits between monolith and microservices, and might be described as “mescoservices” to highlight the balance they strike between the macro level of monoliths and the fine-grained level of microservices.

Another factor that can influence your decision is your deployment model. A managed software-as-a-service offering can use microservices without imposing complexity on its customers. In contrast, a self-hosted software offering may benefit from easier installation, troubleshooting, and upgrades if it uses a monolithic architecture.

Common microservice failure modes

There are several common failure modes to watch out for when moving to a microservice architecture.

Distributed monoliths look like microservices, except they have dependencies that mean you have to deploy services in a specific order. If you can’t deploy independently, you don’t have microservices. Similarly, you often find microservices at the application layer, but all sharing the same database. This prevents independent scaling of high-load services and can cause services to access data directly rather than through the appropriate service.

When you deploy large numbers of microservices, you may need to introduce rules about which services can communicate. Allowing any service to call any other service means managing a complex web of dependencies, and it starts to look a lot like the proverbial big ball of mud. This is often the result of splitting a monolith into microservices, as the old design tends to persist.

Microservices should bring a high level of team independence, allowing teams to make decisions about their own services, persistence, and deployment schedules.

Pulling microservices together

To make microservices successful, you need to establish data ownership and decide what level of data duplication is acceptable to support the business goals. For example, there’s a temptation to store a single address for a customer, but it may be a better idea to store the address immutably against events, like orders. Even if the customer moves house, the address for a past order remains the same.

Domain-driven design provides a method and a language for making decisions across service boundaries. A principal engineer or architect would usually set standards for service boundaries, contracts, and versioning to help keep services loosely coupled and independently deployable.

Fitness test

The best test of your service-based architecture is independent deployability. If each team can deploy its services without cross-team coordination, then your architecture is working. For majestic monoliths, the test is similar; teams should be able to work independently on modules they own. While deployments will be coupled through a single build and deployment pipeline, they should be able to make and commit changes independently.

Happy deployments!

According to Octopus Deploy’s AI Pulse report, 44% of developers say they’re frustrated with AI outputs that are “almost right, but not quite.”

You’ve likely experienced it yourself: a large language model generates a deployment config missing a critical variable, or suggests a step that works in staging but breaks in production. Which is why many engineers will use AI to whip up a script. Fewer will let it configure a production pipeline unsupervised.

So far in the Easy Mode series, we’ve walked through how to use the Octopus AI Assistant for specific, bounded tasks, from adding manual interventions to setting environment-scoped variables.

Each post focused on a task where you could verify the result before it hit production. This post continues that pattern. We’ll cover how to create projects and what to do if you need to rollback a change you are not satisfied with.

What the AI Assistant does (and what we’re building)

If this is your first easy mode article, it is worth explaining what the Octopus AI assistant is and exactly what we will be building.

The Octopus AI assistant is a Chrome extension that integrates AI directly into Octopus Deploy. It can answer questions about your instance, help you build projects, and guide you through configuration, all without leaving the browser tab you are already in.

A common question users often have is “Does Octopus use my data for training?” to get that out of the way, the extension does NOT train AI models on your data.

Demo: Creating a project with the AI Assistant

In this walkthrough, we will create a project using the Octopus AI assistant and simulate responding to a request to revert a change.

Prerequisites

In order to follow along with this portion of the tutorial, you will need the following:

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

Upon installation, you should see a new icon in the bottom right.

Create a project

With the extension installed, the next step is to create a project.

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

Create a Script project called "15. Git backed Project".

Upon hitting enter, the Octopus AI assistant will process your request and generate the OpenTofu code required. This is important because using OpenTofu makes your results much more deterministic.

Many engineers have expressed doubts when using generative AI, as the results tend to vary. Generating the OpenTofu required to fulfill your requests helps the assistant achieve greater accuracy, as there is only one way to create a project via the OpenTofu provider.

Additionally, if you were to do this manually, it would take anywhere from a couple of minutes to a few minutes, depending on how many projects you intend to create and whether you need to modify an existing OpenTofu module.

Your safety net: Version-controlled projects

So far, the Octopus AI assistant has created your project. The obvious question is: what if something is wrong?

Thankfully, Octopus Deploy lets you back any project with a Git repository. When you enable this, every change to that project, whether you made it or the assistant did, becomes a Git commit.

To set this up, go to your project settings and connect a Git repository. Once connected, Octopus stores your project configuration in a .octopus folder in that repo. Deployment processes, variables, triggers, all of it lives in version-controlled files.

Now look at what happens after the AI assistant creates your project. Open the Git history for the repo. You’ll see the commits the assistant generated, and you can inspect exactly what it configured.

Clicking into any commit gives you the full diff, and if something looks off, you have two options: fix it in the next commit or revert to a known-good state. This is the same workflow you already use for application code.

This matters because you can use the assistant with more confidence, because changes are auditable, and because relying on a config-as-code approach means there is only one way to do things.

Tips for getting the most out of AI-Assisted setup

At this stage, if you’re looking to try out an AI-Assisted workflow, here are some quick tips on how to get better returns on your new workflow:

• Write short, specific prompts: The more detail you pack into a single prompt, the longer the assistant takes to process it. Keep prompts scoped to a single task.
• Include platform and environment details: The assistant produces better results when you tell it what you’re deploying to. Specify the target (Kubernetes, Azure App Service, AWS ECS), name your environments, and indicate your preferred deployment strategy (rolling, blue/green, canary) if applicable.
• Plan to customize after generation: The assistant handles straightforward project scaffolding well. Complex variable scoping, multi-tenant configurations, and custom scripts are better handled manually after the initial setup. Use the AI to get the structure in place, then fine-tune. Git tracks everything either way.

Beyond project creation, the AI Assistant can also help with troubleshooting failed deployments and surfacing best-practice recommendations.

Build Fast, Ship Safe

In this post, we used the Octopus AI Assistant to create a project from a prompt and then backed it with Git via Config as Code.

While the conversation around AI in DevOps evolves, having the ability to use it on your own terms is what makes the Octopus AI assistant a good choice for teams looking to dip their toes in the water.

If you want to try this yourself, install the Octopus AI Assistant Chrome extension and give it a shot.

Happy deployments!

A portal is the interface. It’s where a developer logs in and finds everything they need in one place, including services, pipelines, documentation, logging, observability, and ownership. They don’t necessarily need to know which tool sits behind each action, or who to ask for access. It’s a genuinely compelling end state. But it’s just that — an end state.

I see and hear about many teams trying to build the GPS before the roads exist.

A GPS is an incredible tool. It gets you where you’re going, surfaces the best route, and removes the guesswork. But if the roads aren’t there, or if they’re unpaved, inconsistently maintained, or only connected in some places, the GPS doesn’t fix that. It just navigates you into a field with more confidence, resulting in a poor user experience. The same is true of a portal sitting on top of a platform that isn’t ready to support it.

Portals have real value. But so does sequencing. Get the platform right first, and the portal becomes genuinely powerful. Rush to the portal before the foundations are solid, and you’re surfacing chaos through a clean UI.

When the portal becomes the platform team’s second job

I understand the appeal of a nice, polished developer portal. That single place where teams can go to self-service infrastructure, discover documentation, review application performance, all without filing a ticket or waiting on someone else. They provide a service catalogue, integrations across the tooling used in your platform, and get users to the desired golden paths fast.

One problem is the cost of getting to that point, and teams that don’t consider that cost and prioritize a portal before the underlying platform is ready for it can open themselves up for a world of pain. Portals are a product in their own right and will need to be either procured or built yourself, or a combination of the two. Whichever way you go, it’s going to require the usual care and feeding - engineering time, maintenance, new features and functionality, and one way or another, funding. That’s engineering time that isn’t going toward making the platform itself more reliable, more consistent, or easier to use.

I’ve spoken with Platform Engineers who have been asked to provision a portal for their platform, and go down a rabbit hole of open source solutions and evaluating commercial solutions, only to discover the portal itself is going to take more than a couple of hours a week to maintain, and that’s before you’ve written a single integration. The realization that a portal needs to be managed on top of the Platform itself is daunting to many Platform teams, who are already stretched thin.

A portal then also influences future Platform tooling choices. How hard is it to integrate new tooling with the portal? Does the new tool provide integrations or plugins out of the box, or does the platform team need to build and maintain them themselves?

The organizations that tend to get value from a dedicated portal are those operating at significant scale, with hundreds of developers and dozens of teams, and complex enough that the cost of running a portal becomes a rounding error compared to the coordination problems it solves. For most teams, that bar is higher than it looks. Are you there yet?

Start with solid foundations before you surface it

Good roads aren’t just tarmac. They have lane markings, speed limits, signs, and traffic lights. All of the things that make roads safe and predictable to navigate. A GPS doesn’t create any of that. It surfaces it. A portal works the same way. It can expose your golden paths, governance, pipelines, and self-service workflows, but it doesn’t define them for you. Get the road right first.

Your platform will consist of tens of tools, each focused on solving problems in its own domain. All of those tools can be configured and integrated in different ways to achieve the outcomes your teams need, and a lot of effort from Platform Engineering teams goes into making them work well together for the organization.

It’s also likely your developers and application teams have worked directly with the platform tools in their careers, too, and while context switching is an issue, it won’t be unfamiliar to them to move between different tools to get their work done. If you can lower the friction they have when working with the underlying platform tools, that’s a huge win, and in my opinion, it’s a signal of a successful platform foundation.

And with the rise of AI, that’s becoming even more relevant. Developers increasingly want to be met where they’re already working. That might be by providing a Command Line Interface, an API call, or an MCP server that the developer—or the agent they are using—can interact with directly. A well-structured platform exposes those interfaces. A portal is one way to surface platform capabilities, but it’s not the only way, and for many developers, it might not even be the preferred one.

You’re probably familiar with core concepts that platform teams focus on: standardization, policies and governance, self-service, and repeatable, consistent delivery across teams and environments. There’s a lot of work that goes into getting those foundations right before they are ready to be surfaced through an interface, and it doesn’t stop once they’re in place. The tools your platform is built on keep evolving. Vendors ship new features, integrations improve, and better primitives emerge. A good platform team takes advantage of that, pushing complexity back onto vendors and partners where possible, and reducing the volume of custom scripts and integrations they need to own and maintain themselves. The point is that building a platform isn’t a 12-month checkbox exercise. It’s a living thing that needs ongoing maintenance, care, and attention. New roads get built, old ones get resurfaced, and the rules of the road change over time. Your platform is no different. The tools keep evolving, your organization’s needs shift, and the work of keeping it solid never really stops.

Adding a portal to a platform will begin to expose the platform’s underlying capabilities as they stand today. If your underlying platform has a strong foundation and delivers measurable benefits to the organization, exposing its capabilities in a portal will amplify the value it already delivers, enabling developers to get faster access to what already works. But the same can be said if your underlying platform is a bit of a mess, too. A portal that surfaces an inconsistent or fragile deployment pipeline doesn’t hide the inconsistency. It just makes it more visible and more frustrating to more people.

A portal amplifies what’s already there. Make sure what’s already there is worth amplifying.

Portals have a place

When you’re working in an organization with hundreds of developers and many applications, finding the right information is hard. Even just knowing what you have in the organization can be a massive undertaking. Ask a new engineer at most organizations to find the logs for a service they didn’t build, and watch what happens. They’ll ask around, dig through wikis, search Slack, and probably end up messaging whoever seems like they might know. It works, eventually. But it shouldn’t be that hard.

Here at Octopus Deploy, where you could argue we have one core product, there are many Engineering teams, each owning different parts of the application. They all have defined software development processes, source code, internal and external documentation, and several Slack channels. Even though some of that information lives in the same tool across teams - let’s use GitHub as an example for our source code tool - there are still hundreds of repositories internally. There’s also the support and operational lens too, such as where the logs are being sent, what observability is being used by each application, where you file a bug or request a new feature, and who to contact or where to go if you need to ask a question from the team that owns the service.

Sit for a moment and ask these same questions in the context of your company, and consider how long it would take a new engineer on your team to find those answers on their own.

Service discoverability is one use case where a portal can deliver real value without a huge lift for the platform team. The information already exists in your organization; it just needs to be collated and surfaced in one place.

Once your platform foundations are solid, a portal can surface those capabilities in a way that genuinely changes how developers interact with it. Self-service workflows that are repeatable and reliable, golden paths that are well-defined and trusted, pipelines that behave consistently across teams and environments. A portal can bring all of that together in one place and make it accessible without developers needing to know what sits behind each action.

A useful question to ask yourself: if we built a portal today, what would we put in it? If the answer is “not much,” that’s a signal there’s more platform work to do first, or that your company doesn’t even need a portal to make the most of Platform Engineering. If the answer is a long list of capabilities that are already working well and delivering value, you’re probably ready.

This is where the GPS analogy comes full circle. The roads are built, the lane markings are down, and the signs are in place. Now you can hand people a GPS and trust that it will reliably navigate them to where they need to go, on the most efficient route. That’s the version of a portal worth building toward.

Roads first, GPS second. Where’s your team at?

A portal is a powerful navigation tool. But navigation only works when there’s somewhere real to go. Every organization is at a different point on this journey, and this post isn’t a rule book. Some teams genuinely are ready to invest in a portal, and for them, it will pay off. But in my experience, most teams have more platform work to do before the portal delivers on its promise.

The roads come first. The GPS comes when the roads are worth navigating.

So, where’s your team at?

Happy Deployments!

In the past, Octopus Deploy users used the Deploy a Release built-in step, the Chain Deployment step template, or the Deploy Child Octopus Deploy Project step template to solve this problem. But because they were single steps, the solutions were difficult to configure and brittle.

Platform Hub’s Process Templates solve this problem at scale. This post will walk through the new Verify Dependencies Process Template.

The use cases

I created the Verify Dependencies Process Template based on previous experience as an Octopus Deploy user. I automated the deployment of my application, including code, infrastructure, and database components. The coordination and scheduling were still manual.

Service dependencies

Before working for Octopus Deploy, I was the lead developer on a loan origination system at a bank. The loan origination system depended on multiple REST API services.

• Customer Information Service: Truth center for the customer PII data.
• Financial Service: Truth Center for the customer’s financial information.
• Credit Service: Checked the customer’s credit against the big three credit agencies.
• Collateral Service: Truth center for the customer’s collateral.
• Decision Engine Service: Rules-based engine that would auto-approve the loan or require more verification.

Each of those services was managed by a different team, which had different priorities and deployment schedules. The challenge my team ran into is that we’d make a change to our application based on functionality added in version 2.1.x of the Financial Service, but Production was running 2.0.5.

It required significant coordination and grit to ensure that all the loan origination system’s dependent services were on the correct version in Production before we deployed. There were several close calls and a few extended deployment windows.

Release orchestration

Often, a back-end service and the loan origination system were deployed on the same night. For obvious reasons, the deployment of back-end service changes occurred before the loan origination system. The low-friction and fastest solution was to schedule the back-end service’s deployment for 7:00 pm and the loan origination system for 7:30 pm.

That worked until multiple back-end services needed to be deployed on the same night. For example, the collateral service, credit service, and customer information service had changes to deploy on the same night.

• The collateral service was dependent upon the customer information service.
• The credit service was also dependent upon the customer information service.
• The collateral and credit services were not dependent upon each other.

The result was:

• Schedule the customer information service deployment for 7:00 pm
• Schedule the credit and collateral service deployments for 7:30 pm
• Schedule the loan origination system deployment for 8:00 pm

All that coordination occurred at a daily Change Approval Board (CAB) meeting at 11:00 am.

An unsolved problem

This problem is the silent killer of Continuous Delivery. As a developer, after automating my application’s deployments, I was rarely concerned about production deployments. That is because using Octopus Deploy, my application’s deployment processes were tested multiple times before Production.

What kept me up at night was post-deployment verification. Specifically, if the change depended on other back-end services. Runtime errors that appeared during specific conditions were the most frustrating. It’s easy to debug a missing endpoint or a contract change. It was maddening when all the changes were hidden in the business logic.

Leveraging a message bus wouldn’t have fixed this issue. Yes, that would’ve decoupled hard dependencies between applications. But that doesn’t account for business requirement changes that span multiple applications or services. A new rule may not impact the message contract, but the business logic can change.

The primary reason for creating this Process Template was the lack of a better alternative. I have yet to find a solution that can handle the nuances of dependency management across applications.

A better solution with Process Templates

I’m the author of the Deploy Child Octopus Deploy Project. I created that step to address limitations in the Deploy a Release and Chain Deployment steps. At the time, working within the constraints of what was possible with a 2021 version of Octopus Deploy, I was happy with the solution.

But the solution had multiple problems.

Creating an approval workflow with that step is incredibly messy for consumers. See the approval in parent project only section in the announcement blog post as an example. A consumer has to:

• Add the Deploy Child Octopus Deploy Project for each of the dependent projects configured in what-if mode.
• Add a manual intervention step and set the instruction message using output variables from the previous step.
• Add the Deploy Child Octopus Deploy Project for each of the dependent projects configured for deployment mode. Set the version to deploy to the output variables from the previous step.

A project with five dependent projects would require 11 steps just for approval. A release manager attempting to coordinate the release of 50 applications would need a process with 101 steps!

Process Templates enabled a better solution by supporting multiple steps. As the producer of the step, I can abstract away all the complexity from the consumer. Consumers no longer have to add multiple steps for each dependent project. Nor do they have to know the correct Octostache for the output variables. Adding a new dependency is as simple as editing a JSON array.

Now consumers can focus on answering:

• Which projects are this project dependent upon?
• What is the version required for each project?
• Do you want to stop the deployment, continue the deployment, or attempt to deploy when a dependency is not in the target environment?
• If you choose to deploy, do you want to pause for approval?
• If you choose to deploy, in what order should the dependencies be deployed?

Verify Dependencies Process Template

The Verify Dependencies Process Template has three steps.

1. Check Dependencies - Loops through all the dependencies to determine if an appropriate version is in the target environment.
2. Approve Dependency Result - When configured, the Process Template pauses the deployment for verification when a dependency doesn’t have an appropriate version in the target environment.
3. Deploy Dependencies - When configured, the Process Template will initiate deployments for all the dependencies found in the Check Dependencies step.

It has the following parameters.

• Worker Pool - The worker pool to execute all the scripts in the Process Template
• Octopus Deploy API key - The API key of a service account that has permissions to view the dependent projects, and if configured, deploy those dependencies.
• Target Environment - The environment to check, and if configured, deploy the dependencies.
• Project Dependencies - A JSON array containing all the dependencies, the version pattern, and deployment order. See the section below for more details.
• Default Dependency Action - Indicates what the Process Template should do if a dependency doesn’t have the appropriate version in the target environment. The possible options are Stop, Continue, Deploy when newer matching found, and Deploy only when no matching found. Default is Stop.
• Approval requested to proceed - Determines if the Process Template should pause and wait for approval when a dependency doesn’t have the appropriate version in the target environment and the dependency action is Continue, Deploy when newer matching found, or Deploy only when no matching found. Default is Yes.
• Reuse Change Request Number in Dependencies - Tells the Process Template to re-use the ITSM change request number when initiating deployments. Only applicable when the dependency action is Deploy when newer matching found or Deploy only when no matching found. Default is No.
• Target Tenant - Only used when verifying a multi-tenanted dependency. By default, the Process Template ignores this parameter when used in a non-tenanted project. When used in a tenanted project, the Process Template uses the current tenant of the deployment.

Project dependencies

I opted for a JSON array as a parameter for dependencies. Requiring a consumer to add multiple Process Templates is an awful experience.

[
  {
    "projectName": "Spear",
    "versionPattern": ">1.0.54",        
    "deployGroup": 1,
    "promptedVariables": [
         {
             "name": "Prompted.Input.Variable",
             "value": "Dependency Checker"
         }
     ]
  },
  {
    "projectName": "TAKA",
    "versionPattern": "~2.4.0",        
    "deployGroup": 1
  },
  {
    "projectName": "TAWA",
    "versionPattern": "^4.0.0",        
    "dependencyAction": "Continue",
    "deployGroup": 2
  },
 {
    "projectName": "StoreHub",
    "versionPattern": ">1.0.3",
    "spaceName": "Default",    
    "tenantName": "Internal",    
    "deployGroup": 3
  }
]

The properties for each JSON object are:

• projectName (Required): the name of the project of the dependency.
• versionPattern (Required): the version pattern to match on. See below for more details.
• deployGroup (Optional): Projects in the same deploy group are deployed concurrently. Projects in different deploy groups are deployed sequentially. If omitted, all dependencies are deployed sequentially. See below for more details.
• spaceName (Optional): overrides the current space.
• tenantName (Optional): the name of the tenant to deploy. If not specified, during a multi-tenanted deployment, it will use the current deployment’s tenant.
• promptedVariables (Optional): an array that lets you send in prompted variable values to the dependency project. It will only work with string variable types, text, and sensitive values.
• dependencyAction (Optional): overrides the default dependency action parameter. For example, if you want to continue for a specific dependency but stop for all other dependencies. The options are:   - Stop: which will stop the deployment   - Continue: which will continue the deploy   - DeployNoMatchingInTarget: which will deploy only when no matching version in the target environment exists.   - DeployNewerMatching: which will deploy only when the source environment contains a newer matching version.

Version pattern

Versioning is the heart of the Verify Dependencies Process Template. Octopus Deploy uses SemVer for release versioning. All previous step templates were specific versions (2.2.5), the latest version (2.2.x), or a wildcard (2.2.x).

I can’t predict all the dependencies and their versioning requirements. So, I decided to implement a version pattern similar to Node.js. I modified it slightly because we support .NET and they allow Major.Minor.Patch.Build.

• Exact version: 1.2.3.4 - only version 1.2.3.4 will be accepted.
• Greater than current: >1.2.3.4 - Any version greater than or equal to 1.2.3.4 will be accepted.
• Caret range: ^1.2.3.4 - Allows minor, patch, and build updates, locking the major version. Similar to 1.x.
• Tilde range: ~1.2.3.4 - Allows patch and build updates only, locking the major and minor versions.
• Major wildcard: 2.x - Allows any version or any version within a major range.

The .Build part of the version is optional. Version patterns like 1.2.3, >1.2, ~1.2, and 2.x are accepted.

Deploy group

Earlier in this post, I discussed the deployment order of the back-end services because of these rules:

• The collateral service was dependent upon the customer information service.
• The credit service was also dependent upon the customer information service.
• The collateral and credit services were not dependent upon each other.

I wanted to make it very easy to deploy projects in a specific order. But, at the same time, allow for concurrent deployments of non-dependent projects. The deploy group property in the JSON object solves for that.

• All deployments in the group must finish before moving to the next group.
• Any projects in the same deploy group can run concurrently.
• A failure in a deploy group will prevent subsequent deploy groups from being processed.

The deploy group property is optional.

• If no projects have a deploy group in the JSON array, then deploy the projects in the order they appear in the array.
• If a deploy group appears for some objects in the JSON array, deploy those projects based on the specified deploy group. After that, deploy projects without a deploy group in the order they appear in the array.

Respecting the task cap

The ability to concurrently initiate deployments raised a major concern: the task cap. It would be very easy to consume all the available tasks quickly.

For example, you have a task cap of 10, and a deploy group with 15 projects. If all 15 projects require deployment, you could end up blocking any other deployments until those 15 are finished. Even worse, what happens if some of those 15 projects trigger a runbook during deployment?  

Before initiating a deployment, the Process Template will ensure that at least three tasks are available. It will check every five seconds until it finds at least three available tasks.

Dependency action and approvals

Every company, environment, and application is different. When deploying to a testing environment, you might only need a warning if a dependency isn’t on the correct version. But you’d want to fail the deployment if a dependency isn’t on the correct version in pre-production or Production.

The Verify Dependencies Process Template will use Octopus Deploy’s API to determine the version of each dependency in the target environment.

In the event a match doesn’t occur, the step can:

• Stop: If one or more of the dependency checks fail, it will stop and fail the deployment. This option is the default.
• Continue: Will proceed with the deployment even if the dependency check fails. Will not attempt to deploy any dependent projects.
• Deploy when newer matching found: Will always deploy the latest matching version from the previous environment.
• Deploy only when no matching found: Will trigger a deployment to the target environment only if the target environment has a matching version.

The deploy options control when a deployment will occur. Imagine a dependency with a version pattern set to >4.5.2.

• Example #1 - The latest version in Production is 4.1.2, and in Test it is 4.5.7. Deploy when newer matching found will deploy 4.5.7. Deploy only when no matching found will deploy 4.5.7.
• Example #2 - The latest version in Production is 4.5.3, and in Test it is 4.5.7. Deploy when newer matching found will deploy 4.5.7. Deploy only when no matching found WILL NOT deploy 4.5.7 because 4.5.3 in production matches the pattern >4.5.2.

It takes time to build trust in a new process. The Verify Dependencies Process Template allows you to pause the deployment and wait for a person to approve the changes.

Reusing change request numbers

The ServiceNow and Jira Service Management (JSM) ITSM integrations have led to interesting requests and use cases from our customers. One of the most common requests is the ability to create a single change request number and reuse that for all deployments in a deployment window.

The Verify Dependencies Process Template, when configured, will send the change request number from the parent project to all dependent projects when a deployment is invoked. It doesn’t matter whether the parent project created the change request or a user supplied the change request number.

There are a few limitations.

1. Projects can use different SNoW or JSM instances. The Process Template’s logic assumes that the parent project and its dependent projects all use the same ITSM instance.
2. ITSM has to be configured for the dependent projects. The Process Template cannot modify the project settings. The Process Template will never send the change request number to any project without the ITSM settings configured.

Prompted variables

It is safe to say that at least one project will require a prompted variables value to be supplied. The challenge is that each dependent project will have different prompted variable names and values. That is why the prompted variables are part of the Project Dependencies JSON array.

[
  {
    "projectName": "Spear",
    "versionPattern": ">1.0.54",        
    "deployGroup": 1,
    "promptedVariables": [
         {
             "name": "Prompted.Input.Variable",
             "value": "Dependency Checker"
         }
     ]
  },
  {
    "projectName": "TAKA",
    "versionPattern": "~2.4.0",        
    "deployGroup": 1
  }
]

The Verify Dependencies Process Template will match the provided name in the JSON array to the name or the label of the prompted variable. That is how our CLI handles it, so it makes sense to be consistent.

Permissions

The Verify Dependencies Process Template requires an API key because it invokes the Octopus Deploy API. I highly recommend using an API key from a new service account with limited permissions.

When configuring the Process Template to Stop or Continue, the recommended roles are:

• Project Viewer
• Environment Viewer

When configuring the Process Template to Deploy when newer matching found or Deploy only when no matching found, then the recommended roles are:

• Project Viewer
• Environment Viewer
• Deployment Creator

Scenarios

The combination of the chosen dependency action, the approval-required setting, and a dependency’s current state can result in 16 possible outcomes for each dependency. Below is a table I created to help keep track of the possible outcomes.

It can be hard to visualize results from a table. I set up my instance with a project that depends on these projects.

• Spear
• TAKA
• TAWA
• StoreHub - multi-tenanted

The dependency configuration is:

[
  {
    "projectName": "Spear",    
    "versionPattern": ">1.0.56",        
    "deployGroup": 1    
  },
  {
    "projectName": "TAKA",    
    "versionPattern": "~2.4.0",    
    "deployGroup": 1
  },
  {
    "projectName": "TAWA",
    "versionPattern": "^4.0.0",        
    "deployGroup": 2
  },
 {
    "projectName": "StoreHub",    
    "versionPattern": ">1.0.5",        
    "tenantName": "Internal",
    "deployGroup": 4
  }
]

Right now, only Spear doesn’t have a version in Test or Production that matches the version pattern.

Warning with approval

In this scenario, I’ve configured the Verify Dependencies Process Template parameters to be:

• Default Dependency Action: Continue
• Approval requested to proceed: Yes

The result of a deployment to the test environment was:

Turning off approval would yield the same result, but without the manual intervention step.

Stopping deployments

In this scenario, I’ve configured the Verify Dependencies Process Template parameters to be:

• Default Dependency Action: Stop
• Approval requested to proceed: Yes

The result of a deployment to the test environment was:

Deploying dependencies

In this scenario, version 1.0.56 for the Spear application exists in the testing environment.

I want to deploy that to the production environment. The parameters are updated to be:

• Default Dependency Action: Deploy when newer matching found
• Approval requested to proceed: Yes
• Reuse Change Request Number in Dependencies: Yes

The deployment to the test environment first checks for problems.

When Verify Dependencies runs in production, it will see that 1.0.56 needs to be deployed and pause the deployment waiting for approval.

After clicking the Proceed button, the deployment will begin. Note that this project also required ITSM approval before the deployment could start.

Spear also requires ITSM approval. Because of the parent project configuration, the Process Template sends that change request number to Spear’s production deployment.

Skipping unnecessary deployments

In this scenario, version 1.0.57 for the Spear application exists in the Test environment.

The version pattern is still >1.0.56, but the parameters have been changed to:

• Default Dependency Action: Deploy only when no matching found
• Approval requested to proceed: Yes
• Reuse Change Request Number in Dependencies: Yes

The parent project will not deploy Spear 1.0.57 to Production because it already has a version in Production that matches the pattern >1.0.56.

Storing dependencies JSON array outside of Octopus Deploy

One advantage of using a JSON array for the project dependencies is the ability to use a prompted variable for the Project Dependencies parameter.

You’d do that so you could initiate a deployment using a script + Octopus Deploy’s CLI. Where that JSON Array is created or stored is up to you.

$projectDependencies = @'
[
  {
    "projectName": "Spear",
    "versionPattern": ">1.0.56",        
    "deployGroup": 1,
  },
  {
    "projectName": "TAKA",
    "versionPattern": "~2.4.0",        
    "deployGroup": 1
  },
  {
    "projectName": "TAWA",
    "versionPattern": "^4.0.0",        
    "deployGroup": 2
  },
 {
    "projectName": "StoreHub",
    "versionPattern": ">1.0.3",        
    "tenantName": "Internal",
    "deployGroup": 3
  }
]
'@
$projectVersionToDeploy = "0.0.74"
$projectName = "Dependency Checker"
$spaceName = "Default"
$environmentName = "Test"
$apiKey = "Your API Key"
$octopusServer = "https://Octopus.YourDomain.com"

& octopus login --api-key $apiKey --server $octopusServer
& octopus release deploy --project $projectName --version $projectVersionToDeploy --environment $environmentName --variable "ProjectDependencies:$projectDependencies" --space $spaceName --no-prompt

Installing the Verify Dependencies Process Template

To install the Verify Dependencies Process Template, you’ll need to:

• Configure Platform Hub on your Octopus Deploy instance.   - Important Platform Hub is available to customers with Enterprise licenses running 2025.4 or newer.   - If you are not on an Enterprise license and wish to try out Platform Hub, reach out to sales@octopus.com.   - If you are not running 2025.4 or newer, then you can download the latest version of Octopus Deploy on our downloads page
• Copy the deploy-process-verify-dependencies.ocl from our Samples Platform Hub Library GitHub Repository to the .octopus/process-templates in your Platform Hub git repository.
• Go to Platform Hub in the Octopus Deploy UI and publish the new Process Template.

Release orchestration for a project per component

If you’ve been a long-time reader of Octopus Deploy’s blog, you likely read the blog post Better Release Management with Octopus Deploy. In that blog post, I said that a project per application component was the best solution.

For example, an application has four components, so it’d have five projects.

• Database
• Scheduling Service
• Web API
• Web UI
• Orchestration

That blog post reflected Octopus Deploy as it existed in 2021. Upon reflection, it was a bad recommendation. It significantly increases complexity for scenarios that rarely occur in the real world. In addition, we’ve added numerous features and functionality since 2021. For example, Process Templates make it easier than ever to scale complex deployment processes to 1000s of applications. With Process Template’s versioning capabilities, it is easy to push out a change that skips the deployment step if nothing has changed.

Conclusion

The Verify Dependencies Process Template demonstrates how to create robust deployment processes at scale using Octopus Deploy’s Platform Hub functionality. Unlike my Deploy Child Octopus Deploy Project, it enabled me to abstract away many decisions and complexity from consumers like you. With step templates, I’d be required to provide extensive documentation, examples, or even videos to show how to create a complex approval process. Now, consumers only need to add the template to a project and populate a few sensible parameters.

Happy deployments!

Continuous Integration is the practice of integrating code changes frequently, typically multiple times a day. This means you should check your code multiple times a day and keep your main branch deployable. Continuous Integration is a prerequisite for Continuous Delivery.

The name “Continuous Integration” provides solid hints about the crucial parts of the practice. Everyone should integrate their code into a shared branch (feature branches don’t count) and this should be done continuously, which means you’re doing it all the time; at least once a day, but ideally more often.

You’ll often speak to developers who want to stretch the definition of Continuous Integration, but you can’t escape those foundations. Merging the main branch into a long-lived branch feels like Continuous Integration, but you’ll notice no changes come back for ages until someone finally merges to main. Then you have to perform a large, complex merge, which you should avoid.

The DORA research on Continuous Delivery includes the capabilities of Continuous Integration and trunk-based development. The statistics suggest you can get similar benefits as long as you limit yourself to 3 (or fewer) short-lived branches (less than a day old).

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

The worst branching strategy

Since the ability to branch code was invented, developers have applied a great deal of creativity to how to use branches. The most common approach is feature branching, where each feature gets a branch of main that evolves separately until the feature is complete, and it’s merged back into main. Release branching allows development to continue on main by taking a cut of the main branch that will be released. This allows hotfixes to be applied to the release branch without further destabilizing it.

The utility of branching strategies is often eroded by the coordination overhead of maintaining the separate branches and merging different changes back together. The more complex the branching strategy, the more likely it is that you’ll have merge conflicts and lost bug fixes. For example, you might fix a release branch and forget to merge the fix back to main, so the next release reintroduces the bug.

This is why the worst branching strategy is Gitflow. This is a complicated branching strategy that creates dedicated branches for features, releases, and hotfixes alongside permanent main and develop branches. The overhead of Gitflow vastly outweighs its benefits.

This is where trunk-based development shines, as it removes unnecessary complexity.

The best strategy is trunk-based development

Trunk-based development is the process of making all commits directly to the main branch. This is complemented by out-of-band reviews that don’t block merging and by feature toggles that decouple deployments from releases. It should be possible to deploy your software from the main branch at all times, even if features aren’t complete.

The DORA research allows up to 3 short-lived branches, which can be useful for teams working remotely (like open-source project teams), who can use branches and pull requests to coordinate their work. Even so, the goal is to keep branches short-lived and to merge frequently.

Trunk-based development is complemented by automated builds and checks that run when code is committed to the main branch. If a problem is found during these checks, the team should prioritize the fix over other development work.

Elite performance comes from small batches

Teams with the best software delivery performance work in small steps. Trunk-based development and Continuous Integration are crucial practices for controlling batch size. Problems are discovered sooner and are easier to fix when you only have a small amount of change to reason about.

Making frequent commits makes it easy to back out a bad change. If a test fails, you can discard changes since the last commit and try again, instead of trying to debug the problem. This is especially true when using AI coding assistants or other code generation techniques.

Ultimately, for trunk-based development to succeed without friction, the entire team must be aligned on the process. It doesn’t work if only some of the team are on board.

Happy deployments!

In this post, I’ll show you how to proactively manage the risk associated with dependencies and supply chain attacks by associating Software Bill of Materials (SBOM) with deployed applications and automatically scanning those SBOMs for vulnerabilities.

You can complete the steps in this post in around 30 minutes.

Prerequisites

Sign up for a free trial of Octopus Cloud at https://octopus.com/start. The cloud-hosted version of Octopus is the easiest way to get started, as it doesn’t require any additional configuration to work with the Octopus AI Assistant.

Then install the Octopus AI Assistant Chrome extension from the Chrome Web Store.

Creating the sample application

To demonstrate the process of proactively managing and securing your application, we’ll create one of the sample applications provided by the AI Assistant.

Open the AI Assistant and click the Community Dashboards... link:

Click the Octopus Easy Mode link:

Octopus Easy Mode provides the ability to create sample projects based on best practices. We’ll create the sample Kubernetes project. Select the Kubernetes item and click the Execute button:

Once you review and approve the changes, this results in a project called My K8s WebApp being created in your space, along with all supporting resources like feeds, targets, environments, lifecycles, and accounts.

This sample project demonstrates proactive dependency management, and it starts with lifecycles and environments.

Security environment and lifecycles

The AI Assistant created four environments: Development, Test, Production, and Security.

The first three environments represent the typical infrastructure used to host application deployments. The Security environment is a specialized environment that will host our dependency scanning and vulnerability management steps:

We then have a DevSecOps lifecycle that has four phases, one for each environment. Deployments are executed automatically to the Development and Security environments. This means when a deployment to the Production environment succeeds, it automatically starts a deployment in the Security environment. This will be important later on:

The deployment process

The deployment process for the sample application involves scanning the SBOM for a given application version. The final step, called Scan for Vulnerabilities, accepts a package containing an SBOM file and scans it with an open-source dependency-scanning tool.

Notably, the steps that deploy the application (Deploy a Kubernetes Web App via YAML in this example) skip the Security environment. This means deployments to all environments perform the security scan, but deployments to the Security environment only scan the SBOM file:

The end result of this deployment process is that every deployment to every environment performs an SBOM security scan, and once a deployment to the Production environment succeeds, a deployment is immediately triggered in the Security environment.

This initial sequence of a deployment to Production followed by a deployment to Security is not particularly useful, as it is unlikely that a new vulnerability was detected in the seconds between the deployments.

However, the deployment to the Security environment can then be rerun as part of a trigger.

Rerunning the security scan as a trigger

The sample project also includes a Daily Security Scan trigger. This trigger reruns the deployment in the Security environment once per day:

This results in a daily scan of the dependencies that contributed to the version of your application in the Production environment.

This demonstrates how a Continuous Deployment (CD) tool like Octopus complements Continuous Integration (CI) tools to implement DevSecOps. Because Octopus knows exactly which versions of your applications are currently in production (as opposed to the state of a dependency lock file in Git, which may not reflect code deployed to production), it can scan application dependencies to catch vulnerabilities as soon as they are discovered.

You can then automatically respond to any vulnerability reports with custom steps like email alerts or messages sent to a chat platform, and proactively address any issues in a predictable and controlled manner.

Next steps

Scanning an SBOM for vulnerabilities is just one example of risk management that is possible once you associate SBOMs with deployed applications and create an environment where security tasks can be run.

For example, you could scan the SBOM for known dependencies, even when there is no CVE associated with them, or generate reports on outdated dependencies.

What just happened?

By following along with this post, you created a sample Kubernetes application with:

• Deployments that captured both application code and its associated SBOM
• SBOM security scanning steps
• Environments and lifecycles that support proactive security management
• A trigger that performs a daily security scan of the dependencies in your production application

This pattern allows DevOps teams to determine what dependencies were included in a deployment and use that information to respond to known dependency vulnerabilities. This workflow complements other security practices such as SAST/DAST scanning at CI-time, dependency management, and runtime scanning to decrease the risks associated with dependency vulnerabilities and supply chain attacks.

This is part 5 of the series. In the previous post, you created a project structure that supports a shared responsibility model, with multiple teams owning different stages of the deployment process.

In this post, you’ll learn about policies, which provide guardrails for projects to ensure they are compliant with organizational standards.

Prerequisites

Sign up for a free trial of Octopus Cloud at https://octopus.com/start. The cloud-hosted version of Octopus is the easiest way to get started, as it doesn’t require any additional configuration to work with the Octopus AI Assistant.

Then install the Octopus AI Assistant Chrome extension from the Chrome Web Store.

Exploring the sample policy

The mock Git repo shares sample policies that you can apply to your projects. Open Platform Hub, click Policies, and click the Manual Intervention Required policy:

This sample policy requires that any deployment include a manual intervention step. To activate the policy, it must be published and set to active:

To trigger a policy violation, you must delete the manual intervention step from the deployment process. Open the process for the K8s Web App project, delete the Manual Intervention step, and save the project:

Save the changes and deploy a release. The deployment will fail because the process doesn’t include a manual intervention step, which violates the policy you just published:

This demonstrates how platform teams can enforce organizational standards and provide guardrails for projects using policies. Policies are another example of architectural decisions shared and maintained at scale through Platform Hub to support DevOps teams.

The Suggest a fix button can be used by teams that may have encountered an error due to a policy violation. This feature scans the deployment logs, passes the content to an LLM, and provides guidance on resolving the issue:

What just happened?

At the end of this post, you have:

• Published a policy that requires all deployment processes to include a manual intervention step.
• Modified the deployment process for the K8s Web App project to intentionally violate the policy.
• Attempted to deploy a release, which failed because the deployment process violated the policy.
• Used the Suggest a fix button to resolve the policy violation.

What’s next?

Congratulations! You have completed the blog series.

By following along with the series, you have built a hands-on Internal Developer Platform (IDP) using Octopus Deploy. You have also experienced how the strong opinions baked into Platform Hub complement the traditional role of CI servers, enabling platform teams to share and maintain architectural decisions at scale.

This is part 4 of the series. In the previous post, you pushed changes to a shared process template in Platform Hub and saw how those changes were automatically consumed by the project that used the template.

In this post, you’ll build a project that supports a shared responsibility model, with multiple teams owning different stages of a deployment.

Prerequisites

Sign up for a free trial of Octopus Cloud at https://octopus.com/start. The cloud-hosted version of Octopus is the easiest way to get started, as it doesn’t require any additional configuration to work with the Octopus AI Assistant.

Then install the Octopus AI Assistant Chrome extension from the Chrome Web Store.

Updating the project structure

Open the process for the K8s Web App project. You already have the Platform PreDeploy Hook step template as the first step. This effectively means the platform team owns the start of the deployment process.

:::div{.hint} You must publish process templates before they can be used in a project. See the second post for an example of publishing process templates. :::

Add the Security PreDeploy Hook process template next. This gives the security team the opportunity to implement any security checks or processes that must be run before the deployment can proceed.

Add the Security PostDeploy Hook and Platform PostDeploy Hook process templates as the final two steps. This allows the security and platform teams to implement any checks or processes that must run after the deployment completes.

All process template steps default to the name Run a Process Template, but must have a unique name to save the process. Rename each of the process template steps under the Settings tab and define a new name in the Name field:

You must also configure the worker pool parameter for each of the process templates.

With these steps in place, you have modelled your project to support the cross-cutting concerns of both the platform and security teams. This embraces Conway’s law, which posits that organizations design systems that mirror their own communication structure. Conway’s law is sometimes seen as an unintended consequence arising in organizations, but regardless, it is a common pattern that must be supported by platform teams.

By wrapping deployment processes in shared templates like an onion, each team can own and maintain their part of the process. Combine this approach with the Git based workflows for managing changes to process templates, and using SemVer for quantifying the impact of changes to those templates, and you have a powerful combination of features that allow you to manage process templates at scale:

The onion model is just one example of how process templates can be used. You are, of course, free to create process templates defining more general deployment processes that don’t necessarily fit the pre/post-hook model. The key point is that process templates provide a powerful mechanism for sharing and maintaining architectural decisions, and Platform Hub provides strong opinions to support platform teams in managing those architectural decisions at scale.

What just happened?

At the end of this post, you have:

• Updated the project structure to support a shared responsibility model, with multiple teams owning different stages of the deployment process.

What’s next?

You are 80% done with the series. In the next and final post, you’ll explore policies, which provide guardrails for projects to ensure they are compliant with organizational standards.