Automated Installation

With the Octopus Argo CD Gateway being published as a helm chart, several options exist to install it through automated means:

Scripted install using the Helm CLI
Terraform
Argo CD Application

Full documentation for all available Helm values is available on GitHub.

These examples, and the Helm command provided in the Octopus Server portal, describe the minimum configuration required to install an Argo Gateway.

Scripted helm

The Octopus Server portal offers a process to aid in the creation of the required helm command to install the Gateway chart. However, it can also be scripted using a command similar to the following:

helm upgrade --install --atomic \
--create-namespace --namespace octo-argo-gateway-release-name \
--version "*.*" \
--set registration.octopus.name="<display name of gateway in Octopus>" \
--set registration.octopus.serverApiUrl="https://your-instance.octopus.app" \
--set registration.octopus.serverAccessToken="API-XXXXXXXXXXXXXXXX" \
--set registration.octopus.environments="{dev,staging,production}" \
--set registration.octopus.spaceId="Spaces-1" \
--set gateway.octopus.serverGrpcUrl="grpc://your-instance.octopus.app:8443" \
--set gateway.argocd.serverGrpcUrl="grpc://argocd-server.argocd.svc.cluster.local" \
--set gateway.argocd.authenticationToken="<Argo Api Token>" \
octo-argo-gateway-release-name \
oci://registry-1.docker.io/octopusdeploy/octopus-argocd-gateway-chart

Terraform

The Gateway helm chart can be installed via Terraform. For a minimal install the following is required.

Update the version line to the most recent tag found on dockerhub

locals {
  gatewayName          = "<display name of gateway in Octopus>"
  octopus_api_key      = "API-XXXXXXXXXXXXXXXX"
  octopus_address      = "https://your-instance.octopus.app"
  octopus_grpc_address = "https://your-instance.octopus.app:8443"
  argo_auth_token      = "<your Argo JWT>"
}

resource "helm_release" "argo_gateway" {
  name             = "octopus-argo-gateway"
  repository       = "oci://registry-1.docker.io"
  chart            = "octopusdeploy/octopus-argocd-gateway-chart"
  version          = "1.*.*"
  atomic           = true
  create_namespace = true
  namespace        = "octopus-argo-gateway-your-namespace"
  timeout          = 60

  set = [
    {
      name  = "registration.octopus.name",
      value = local.gatewayName
    },
    {
      name  = "registration.octopus.serverApiUrl"
      value = local.octopus_address
    },
    {
      name  = "registration.octopus.serverAccessToken"
      value = local.octopus_api_key
    },
    {
      name  = "registration.octopus.spaceId"
      value = "Spaces-1"
    },
    {
      name  = "gateway.octopus.serverGrpcUrl"
      value = local.octopus_grpc_address
    },
    {
      name  = "gateway.argocd.serverGrpcUrl"
      value = "grpc://argocd-server.argocd.svc.cluster.local"
    },
    {
      name  = "gateway.argocd.insecure"
      value = "true"
    },
    {
      name  = "gateway.argocd.plaintext"
      value = "false"
    },
    {
      name  = "gateway.argocd.authenticationToken"
      value = local.argo_auth_token
    }
  ]

  set_list = [{
    name  = "registration.octopus.environments"
    value = [octopusdeploy_environment.dev_env.name, octopusdeploy_environment.prod_env.id]
  }]
}

Registering a gateway in multiple spaces

From 2026.3.7755 onwards, a single gateway installation can be registered in more than one space, making the same Argo CD instance available in each of them.

By default, every registered space discovers all of the instance’s applications. To limit an application to specific spaces, use the space scoping annotation.

Using Helm values

Set registration.octopus.spaceIds and the gateway registers itself into each listed space:

--set 'registration.octopus.spaceIds={Spaces-1,Spaces-2,Spaces-3}' \

Using the REST API

You can also register an already-installed gateway in another space with the REST API by setting PreserveAuthenticationToken to true.

First, find the gateway’s client ID by getting its registration from the space it was initially installed into. The gateway ID (e.g. ArgoCDGateways-1) is shown in the URL of the Argo CD instance page in Octopus.

curl -H "X-Octopus-ApiKey: API-YOUR-KEY" \
  "https://your-octopus-url/api/Spaces-1/argocdgateways/ArgoCDGateways-1"

The response includes a ClientId value, which is used to re-register the gateway in the new space. To run the registration in a new space:

curl -X POST \
  -H "X-Octopus-ApiKey: API-YOUR-KEY" \
  -H "Content-Type: application/json" \
  "https://your-octopus-url/api/<new space ID>/argocdgateways" \
  -d '{
    "SpaceId": "<new space ID>",
    "ClientId": "<client id from the existing registration>",
    "Name": "<display name of gateway in Octopus>",
    "Environments": [],
    "PreserveAuthenticationToken": true
  }'

When PreserveAuthenticationToken is true, the response’s AuthenticationToken is null and the existing token remains valid.

Deleting a registration only removes the gateway from that space. The gateway’s authentication token stays valid while it’s registered in at least one space.

Installing as an Argo CD Application

The Octopus-Argo Gateway’s helm chart can be installed via an Argo CD Application.

The application YAML required to install the helm chart is as follows (replacing values as per previous examples):

Create the namespace

kubectl create ns octopus-argo-gateway-your-namespace

Generate Argo CD Authentication Token 2.1. Follow the instructions on the Argo CD Authentication guide 2.2. Save the token in a secret

kubectl create secret generic argocd-auth-token -n octopus-argo-gateway-your-namespace --from-literal=ARGOCD_AUTH_TOKEN=<token>

Generate Octopus Deploy Api-Key 3.1. Follow the instructions on the How to Create an API Key guide 3.2. Save the token in a secret

kubectl create secret generic octopus-server-access-token -n octopus-argo-gateway-your-namespace --from-literal=OCTOPUS_SERVER_ACCESS_TOKEN=<token>

Apply the Argo CD application (or commit this manifest to your git-ops repository already synced by Argo CD)

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  finalizers:
    - resources-finalizer.argocd.argoproj.io
  name: octopus-argo-gateway
spec:
  project: default
  source:
    repoURL: registry-1.docker.io/octopusdeploy
    chart: octopus-argocd-gateway-chart
    targetRevision: 1.23.0
    helm:
      valuesObject:
        registration:
          octopus:
            name: <display name of gateway in Octopus>
            serverApiUrl: https://your-instance.octopus.app
            serverAccessTokenSecretName: octopus-server-access-token
            serverAccessTokenSecretKey: OCTOPUS_SERVER_ACCESS_TOKEN
            spaceId: Spaces-1
        gateway:
          octopus:
            serverGrpcUrl: grpc://your-instance.octopus.app:8443
          argocd:
            serverGrpcUrl: grpc://argocd-server.argocd.svc.cluster.local
            authenticationTokenSecretName: argocd-auth-token
            authenticationTokenSecretKey: ARGOCD_AUTH_TOKEN
        autoUpdate:
          # should be disabled, otherwise the auto-update job will keep trying to update the instance, while argo cd syncs it back to original state
          enabled: false
  destination:
    server: https://kubernetes.default.svc
    namespace: octopus-argo-gateway-your-namespace

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Tuesday, July 21, 2026

Edit on GitHub