> ## Documentation Index
> Fetch the complete documentation index at: https://help.dsalta.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Octopus Deploy

> Deployment automation — users, targets, events & access

<Tabs>
  <Tab title="Overview">
    Connect Octopus Deploy with an API key and your instance URL to sync users with their roles and status, spaces, teams, projects, environments and deployment targets, and the audit events, and run access reviews. Read-only. Data feeds into your Access accounts, Inventory and Changes pages.

    <Info>
      **Read-only access.** DSALTA only reads data from this integration. It never creates, modifies, or deletes anything in your environment, and every remediation step is performed by your team directly in the third-party product.
    </Info>

    <Info>
      **What you'll see.** The Access page lists the **users** of the one Octopus Deploy **instance** whose URL you enter, across all of its spaces and teams. Each row shows the user's display name (or their username, or their email address), their email, the user roles their teams grant them (as the instance names them, for example **Project Deployer**) — or, when no team grants a role, the names of their teams other than the built-in **Everyone** team, or **Member** — and the date the account was created. Service accounts, including the built-in **octoadmin** account, and users without an email address are left out. A user the instance has deactivated is shown as **Inactive**; everyone else is shown as **Active**. Octopus Deploy reports no per-user MFA state, so the **MFA** column is blank (shown as a dash).
    </Info>

    <Note>
      DSALTA collects this integration's data when you connect it — you can refresh it at any time with **Sync from integrations** on the **Integrations** page. The compliance checks below re-run once a day at 02:00 America/New\_York.
    </Note>

    ## What DSALTA reads

    DSALTA reads the Octopus Deploy user roster — names, usernames, emails, team-derived roles, active state and creation dates — which appears on your **Access** page; your instance's **spaces**, **teams** (member count, and whether the team is built in) and, in each space, the **projects** (description and disabled state), **environments** (description) and **deployment targets** (roles, health, environment count and disabled state), which appear on your **Inventory** page; and the instance's **audit events**, which appear on your **Changes** page. Each event arrives as a change that has already happened — status **Deployed**, the event message as the title, the user and how they authenticated in the description, priority always **Low** because Octopus attaches no severity to an audit event, the event category as the type, and the space the event belongs to as the environment (or **Octopus Deploy** for an instance-wide event). Events raised by the **system** user or by a service account — such as the hourly token exchanges and node churn on Octopus Cloud — are filtered out so the page shows what people and API keys did. Up to 500 events are read per sync, in the order Octopus returns them, with no date window. Projects, environments and deployment targets appear once you have created them. Deployments, releases and per-user API keys are not read, and the API-key hint and IP address on each event are dropped.

    It calls these Octopus Deploy endpoints on your instance (for example `yourinstance.octopus.app`):

    * `/api/users/me`
    * `/api/users`
    * `/api/teams/all`
    * `/api/scopeduserroles`
    * `/api/userroles/all`
    * `/api/spaces/all`
    * `/api/{spaceId}/projects/all`
    * `/api/{spaceId}/environments/all`
    * `/api/{spaceId}/machines/all`
    * `/api/events`

    Every request is a read. DSALTA has no code path that creates, modifies, or deletes anything in your Octopus Deploy environment.

    ## Troubleshooting

    <AccordionGroup>
      <Accordion title="The connection is rejected">
        A wrong **Instance URL** — a Cloud instance name that does not exist answers Octopus's **Instance Not Found** page, and a server that redirects is reported rather than followed — an expired or deleted key, or a key created by a user who cannot list users: the key inherits its creator's permissions, and DSALTA treats an empty user list as a rejected connection. Create the key as the subscription owner or an **Octopus Manager**. DSALTA keeps only the host of the URL you paste and always connects over HTTPS; a bare name such as `acme` becomes `acme.octopus.app`.
      </Accordion>

      <Accordion title="The connection stopped working">
        Every Octopus Deploy API key expires — 180 days by default, 366 days at most — and the connection fails on that day. Create a new key with the furthest expiry the picker allows, then disconnect and connect again, and plan a rotation. Octopus also deactivates a Free Octopus Cloud instance after 60 days without a deployment or runbook run. Note that disconnecting permanently deletes the data already collected from Octopus Deploy.
      </Accordion>

      <Accordion title="Inventory has spaces and teams but no projects, or Changes is short">
        Teams, roles, spaces, projects, environments, deployment targets and events are read best-effort after the user roster: a failure on one of those calls leaves that part of the page empty without failing the sync. Projects, environments and targets appear once created, and the Changes page holds at most 500 events per sync and omits events raised by the system user or a service account. Click **Sync from integrations** on the **Integrations** page to retry.
      </Accordion>
    </AccordionGroup>

    <AccordionGroup>
      <Accordion title="How do I check whether the connection is healthy?">
        Open **Integrations** in the DSALTA sidebar, stay on the **Connected** tab, and click **Manage** on the integration's card. Open the **Status** tab: it shows either **Connected and working properly** or **Connection issues detected**.

        Use the **Status** tab, not **Overview** — Overview always reports **Connected** regardless of the real state.
      </Accordion>

      <Accordion title="A check shows Failed and nothing changed on my side">
        On an integration-powered check, **Failed** normally means DSALTA was blocked rather than that you are non-compliant. Open the test, go to **Source Data**, and read the result code: **403** is a missing permission, **428** is a setting DSALTA still needs, **500** is a failure on DSALTA's side.

        A real compliance gap shows **207** and leaves the test looking **Completed**. See [Understanding Test Results](/guides/compliance/test-results).
      </Accordion>

      <Accordion title="Data looks out of date">
        Compliance checks re-run once a day at 02:00 America/New\_York. To refresh sooner, open **Integrations → Connected** and click **Sync from integrations** at the top right — it refreshes every connected integration at once.
      </Accordion>

      <Accordion title="How do I repair a broken connection?">
        There is no Reconnect, Repair or Refresh Token button. The only repair available is to disconnect and connect again.

        <Warning>
          **Disconnecting is destructive and cannot be undone.** DSALTA removes the access records, inventory, vulnerabilities, code changes, incidents and device records collected from this integration, and deletes the test results tied to the connection. Export anything you still need as audit evidence first — see [Integration errors](/troubleshooting/integration-errors).
        </Warning>
      </Accordion>

      <Accordion title="Configure scope will not let me change anything">
        That is expected. **Configure scope** is read-only — it shows what DSALTA is permitted to read, and has no Save action. To change what DSALTA can see, change the permissions on the credential in the third-party product, then disconnect and connect again.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="How to connect">
    An Octopus Deploy API key created by an administrator together with your instance URL. Read-only.

    **Before you begin**

    * An Octopus Deploy administrator — the key inherits its creator's permissions, and a base user's key cannot list users.
    * Your instance URL, for example `https://yourinstance.octopus.app` — it is part of the connection and cannot be derived from the key.

    You will need:

    | Field | Where to find it | Example |
    | - | - | - |
    | **Instance URL** | Your browser's address bar while signed in to the instance | `https://yourinstance.octopus.app` |
    | **API key** | Profile image → **Profile → My API Keys → New API key** | `API-…`, shown once |

    <Steps>
      <Step title="Start in DSALTA">
        Open **Integrations** in the DSALTA sidebar, find **Octopus Deploy**, and click **Connect** to open the connect panel.
      </Step>

      <Step title="Sign in to your instance as an administrator">
        Sign in at `https://{yourinstance}.octopus.app` (or your self-hosted server) as the subscription owner or an **Octopus Manager**. Note the full instance URL from the browser: it is part of the connection.
      </Step>

      <Step title="Create an API key">
        Click your profile image → **Profile** → **My API Keys** → **New API key**. Enter a purpose, choose read-only access if the selector is offered — otherwise the key is created with the same permissions as your user account — and set the expiry to the furthest date the picker allows. Click **Generate new** and copy the key.

        <Warning>
          **Copy the key now.** Octopus stores only a one-way hash of the key and cannot show it again; if it is lost, create a new one.
        </Warning>

        <Info>
          Every key expires — 366 days at most — and the connection stops working on that day, so plan a rotation.
        </Info>
      </Step>

      <Step title="Connect Octopus Deploy">
        Return to the connect panel, paste the instance URL and the API key, and click **Connect**.
      </Step>
    </Steps>

    <Check>
      DSALTA validates the pair when you click **Connect**, by reading the key's own user record on your instance and listing the first page of users with it, and rejects a key that returns no users. On success the integration moves to the **Connected** tab, and **Manage → Status** reads **Connected and working properly**. Checks begin reporting after the first sync.
    </Check>

    <Warning>
      **If the connection is rejected.** An invalid or expired key, a wrong instance URL, or a key whose user cannot list users.

      The on-screen message is generic — see [Connection error messages](/troubleshooting/connection-error-messages).
    </Warning>
  </Tab>

  <Tab title="Automated checks">
    Each check below re-runs once a day, at 02:00 America/New\_York, while this integration is connected. Click any check for step-by-step remediation guidance.

    | Check | Severity | What it verifies |
    | - | - | - |
    | [User access to Critical System should be valid](/integrations/octopus-deploy/user-access-to-critical-system-should-be-valid) | Info | Checks that everyone with Octopus Deploy access is an active employee on the People page. |
    | [Offboarded users should not have active access](/integrations/octopus-deploy/offboarded-users-should-not-have-active-access) | High | Checks that offboarded employees no longer have active Octopus Deploy access. |
  </Tab>

  <Tab title="Useful links">
    | Topic | Link |
    | - | - |
    | Setup | [How to create an Octopus Deploy API key](https://octopus.com/docs/octopus-rest-api/how-to-create-an-api-key) |
    | Remediation | [User roles](https://octopus.com/docs/security/users-and-teams/user-roles) |
    | General | [Getting started with Octopus Cloud](https://octopus.com/docs/octopus-cloud/getting-started-with-cloud) |
    | DSALTA | [Connection error messages](/troubleshooting/connection-error-messages) |
  </Tab>
</Tabs>