Octopus Deploy Integration
Port's Octopus Deploy integration allows you to model Octopus Deploy resources in your software catalog and ingest data into them.
Core support
The integration supports additional resources, see the ingest additional resources page for more information.
Setup
Choose your preferred installation method below. Not sure which to pick? See the installation methods overview.
The prerequisites required for installation are listed below.
-
Go to the Octopus Connectors page in Port.
-
Under
Select your installation method, chooseHosted by Port. -
Configure the
Installation parametersandAdvanced configurationas you wish (see below for details).
Installation parameters
Each integration requires specific parameters (such as an API token, a URL, etc.), as seen in Port's UI when installing it. Hover over the ⓘ icon next to each parameter to see more details about it.
Advanced configuration
- During the installation process each integration may have additional settings under the
Advanced configurationsection in Port's UI. Additionally, each integration has one or more settings that can be configured after installation. To do so, click on the integration's name in the Connectors page and navigate to theSettingtab. Hover over the ⓘ icon next to each setting to see more details about it.
Port secrets
Some integration settings require sensitive pieces of data, such as tokens. For these settings, Port secrets will be used, ensuring that your sensitive data is encrypted and secure.
When filling in such a setting, its value will be obscured (shown as ••••••••).
For each such setting, Port will automatically create a secret in your organization.
To see all secrets in your organization, follow these steps.
Port source IP addresses
When using this installation method, Port will make outbound calls to your 3rd-party applications from static IP addresses. You may need to add these addresses to your allowlist, in order to allow Port to interact with the integrated service:
- Europe (EU):
54.73.167.226,63.33.143.237,54.76.185.219 - United States (US):
3.234.37.33,54.225.172.136,3.225.234.99
-
Go to the Octopus Connectors page in your portal.
-
Select the
Self-hostedmethod. -
A
helmcommand will be displayed, with default values already filled out (e.g. your Port client ID, client secret, etc). Copy the command, replace the placeholders with your values, then run it in your terminal to install the integration.
Live event support
Currently, live events are not supported for this integration.
Resyncs will be performed periodically (with a configurable interval), or manually triggered by you via Port's UI.
Therefore, real-time events (including GitOps) will not be ingested into Port immediately.
Live events support for this integration is WIP and will be supported in the near future.
The resync interval can be configured using the scheduledResyncInterval parameter. See the optional parameters section below for more details.
Scalable mode for large integrations
If you are deploying the integration at scale and want to decouple the resync process from the live events process (recommended for large or high-throughput environments), you can enable scalable mode by adding the following flags to your Helm install command:
--set workload.kind="CronJob" \
--set workload.cron.resyncTimeoutMinutes=60 \
--set scheduledResyncInterval="'*/60 * * * *'" \
--set liveEvents.worker.enabled=true
Required parameters:
port.clientId- Your port client id (Get the credentials).port.clientSecret- Your port client secret (Get the credentials).port.baseUrl- Your Port API URL -https://api.port.iofor EU,https://api.us.port.iofor US.integration.identifier- Change the identifier to describe your integration.integration.type- The integration type.integration.eventListener.type- The event listener type.integration.secrets.octopusApiKey- The Octopus API Key, docs can be found here.integration.config.serverUrl- The Octopus host.
Optional parameters (click to expand)
integration.config.appHost(deprecated) - The host of the Port Ocean app. Used to set up the integration endpoint as the target for webhooks created in Octopus.scheduledResyncInterval- The number of minutes between each resync.initializePortResources- Default true, When set to true the integration will create default blueprints and the port App config Mapping.sendRawDataExamples- Enable sending raw data examples from the third party API to port for testing and managing the integration mapping. Default is true.integration.secrets.webhookSecret- Webhook secret for authenticating incoming events. Learn more.liveEvents.baseUrl- The base url of the instance where the Octopus integration is hosted, used for real-time updates. (e.g.https://myoctopusdeployoceanintegration.com).
Recommended resource sizes
To ensure optimal performance and avoid out-of-memory (OOM) errors, we recommend the following resources for this integration:
- CPU Limit:
800m - CPU Request:
100m - Memory Limit:
1Gi - Memory Request:
1Gi
Set resource values
helm install my-integration port-labs/port-ocean \
# ... other parameters
--set resources.limits.cpu=800m \
--set resources.limits.memory=1Gi \
--set resources.requests.cpu=100m \
--set resources.requests.memory=1Gi
- GitHub
- Jenkins
- Azure DevOps
- GitLab
- Go to the Octopus Connectors page in your portal.
- Under Select your installation method, choose your desired CI/CD platform.
- Copy the workflow and replace the placeholders with your values.
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as a GitHub Actions secret |
|---|---|---|---|
port_client_id | Your Port client ID (How to get the credentials). | ✓ | ✓ |
port_client_secret | Your Port client secret (How to get the credentials). | ✓ | ✓ |
port_base_url | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
octopus_api_key | The Octopus API Key, docs can be found here. | ✓ | ✓ |
server_url | The Octopus host. | ✓ | ✓ |
initialize_port_resources | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
integration_identifier | The identifier of the integration that will be installed. | ✗ | ✗ |
send_raw_data_examples | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Your Jenkins agent must be able to run Docker commands.
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as a Jenkins credential (Secret Text) |
|---|---|---|---|
OCEAN__ | Your Port client ID (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port client secret (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
OCEAN__ | The Octopus API Key, docs can be found here. | ✓ | ✓ |
OCEAN__ | The Octopus host. | ✓ | ✓ |
OCEAN__ | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
OCEAN__ | The identifier of the integration that will be installed. | ✗ | ✗ |
OCEAN__ | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Here is an example for a Jenkinsfile pipeline file:Jenkins pipeline (click to expand)
Prerequisites
- Your Azure Devops agent should be able to run docker commands. Learn more about agents here.
- You must have permissions to create and manage Azure DevOps variable groups for storing credentials.
Set up your credentials
- Create a Variable Group: Name it port-ocean-credentials.
- Store the required variables (see the table below).
- Authorize Your Pipeline:
-
Go to "Library" -> "Variable groups."
-
Find port-ocean-credentials and click on it.
-
Select "Pipeline Permissions" and add your pipeline to the authorized list.
-
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as an Azure DevOps pipeline variable |
|---|---|---|---|
OCEAN__ | Your Port client ID (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port client secret (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
OCEAN__ | The Octopus API Key, docs can be found here. | ✓ | ✓ |
OCEAN__ | The Octopus host. | ✓ | ✓ |
OCEAN__ | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
OCEAN__ | The identifier of the integration that will be installed. | ✗ | ✗ |
OCEAN__ | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Here is an example for a azure-pipeline.yml pipeline file:Azure pipeline (click to expand)
- Go to the Octopus Connectors page in your portal.
- Under Select your installation method, choose your desired CI/CD platform.
- Copy the workflow and replace the placeholders with your values.
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as a GitLab CI/CD variable |
|---|---|---|---|
OCEAN__ | Your Port client ID (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port client secret (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
OCEAN__ | The Octopus API Key, docs can be found here. | ✓ | ✓ |
OCEAN__ | The Octopus host. | ✓ | ✓ |
OCEAN__ | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
OCEAN__ | The identifier of the integration that will be installed. | ✗ | ✗ |
OCEAN__ | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Configuration
Port integrations use a YAML mapping block to ingest data from the third-party api into Port.
The mapping makes use of the JQ JSON processor to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API.
Default mapping configuration
This is the default mapping configuration for this integration:
Default mapping configuration (click to expand)
createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
- kind: space
selector:
query: 'true'
port:
entity:
mappings:
identifier: .Id
title: .Name
blueprint: '"octopusSpace"'
properties:
url: env.OCEAN__INTEGRATION__CONFIG__SERVER_URL + "/app#/" + .Id
description: .Description
- kind: project
selector:
query: 'true'
port:
entity:
mappings:
identifier: .Id
title: .Name
blueprint: '"octopusProject"'
properties:
url: env.OCEAN__INTEGRATION__CONFIG__SERVER_URL + "/app#/" + .SpaceId + "/projects/" + .Id
description: .Description
isDisabled: .IsDisabled
tenantedDeploymentMode: .TenantedDeploymentMode
relations:
space: .SpaceId
- kind: release
selector:
query: 'true'
port:
entity:
mappings:
identifier: .Id
title: .ProjectId + "(" + .Version + ")"
blueprint: '"octopusRelease"'
properties:
version: .Version
assembledDate: .Assembled
channelId: .ChannelId
releaseNotes: .ReleaseNotes
url: env.OCEAN__INTEGRATION__CONFIG__SERVER_URL + "/app#/" + .SpaceId + "/releases/" + .Id
relations:
project: .ProjectId
- kind: deployment
selector:
query: 'true'
port:
entity:
mappings:
identifier: .Id
title: .Name
blueprint: '"octopusDeployment"'
properties:
createdAt: .Created
deployedBy: .DeployedBy
taskId: .TaskId
failureEncountered: .FailureEncountered
comments: .Comments
url: env.OCEAN__INTEGRATION__CONFIG__SERVER_URL + "/app#/" + .SpaceId + "/deployments/" + .Id
relations:
release: .ReleaseId
project: .ProjectId
- kind: machine
selector:
query: 'true'
port:
entity:
mappings:
identifier: .Id
title: .Name
blueprint: '"octopusMachine"'
properties:
roles: .Roles
status: .HealthStatus
url: env.OCEAN__INTEGRATION__CONFIG__SERVER_URL + "/app#/" + .SpaceId + "/infrastructure/machines/" + .Id + "/settings"
isDisabled: .IsDisabled
operatingSystem: .OperatingSystem
architecture: .Architecture
statusSummary: .StatusSummary
endpointType: .Endpoint.DeploymentTargetTypeId
communicationStyle: .Endpoint.CommunicationStyle
relations:
space: .SpaceId
Mapping & selectors per resource
Use the explorer below to view sample payloads and the resulting Port entities for each resource type. For additional resources and advanced configurations, see the ingest additional resources page.
- kind: space
selector:
query: 'true'
port:
entity:
mappings:
identifier: .Id
title: .Name
blueprint: '"octopusSpace"'
properties:
url: env.OCEAN__INTEGRATION__CONFIG__SERVER_URL + "/app#/" + .Id
description: .Description
{
"Id": "Spaces-1",
"Name": "Default",
"Slug": "default",
"Description": "Description cannot be empty",
"IsDefault": true,
"IsPrivate": false,
"TaskQueueStopped": false,
"SpaceManagersTeams": [
"teams-administrators",
"teams-managers",
"teams-spacemanagers-Spaces-1"
],
"SpaceManagersTeamMembers": [],
"Icon": null,
"ExtensionSettings": [],
"LastModifiedOn": "0001-01-01T00:00:00.000+00:00",
"Links": {
"Self": "/api/spaces/Spaces-1",
"SpaceHome": "/api/Spaces-1",
"Web": "/app#/spaces/Spaces-1",
"Logo": "/api/spaces/Spaces-1/logo?cb=2024.3.10989",
"Search": "/api/spaces/Spaces-1/search"
}
}
{
"identifier": "Spaces-1",
"title": "Default",
"icon": "Octopus",
"blueprint": "octopusSpace",
"team": [],
"properties": {
"url": "https://testport.octopus.app/app#/Spaces-1",
"description": null
},
"relations": {},
"createdAt": "2024-08-22T14:27:34.746Z",
"createdBy": "zhOWp1YybWfY12bAxNz3d1ByX18iA1yT",
"updatedAt": "2024-08-22T14:27:34.746Z",
"updatedBy": "zhOWp1YybWfY12bAxNz3d1ByX18iA1yT"
}
Set up live events
This integration supports live events, allowing real-time updates to your software catalog without waiting for the next scheduled sync.
Note that different events are supported depending on the resource type.
spacesprojectsdeploymentsreleasesmachines- Hosted by Port
Live events base URL
For integrations installed using the Hosted by Port method, you can obtain the live events base URL from the Get an integration API. The response includes liveEventsUuid and liveEventsIngestHostname in the appSpec section.
Call the endpoint with your integration's identifier:
curl -X GET \
'https://api.port.io/v1/integration/<INTEGRATION_IDENTIFIER>' \
-H 'Authorization: Bearer <PORT_ACCESS_TOKEN>'
The port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters select which Port API instance to use:
- EU (app.port.io) →
https://api.port.io - US (app.us.port.io) →
https://api.us.port.io
In the response, look for the following fields under spec.appSpec:
{
"spec": {
"appSpec": {
"liveEventsUuid": "abcdefghijk",
"liveEventsIngestHostname": "ingest.ocean.getport.io"
}
}
}
Combine them to build the live events base URL:
https://<liveEventsIngestHostname>/live-events/<liveEventsUuid>
For example, with the values above, the live events base URL is:
https://ingest.ocean.getport.io/live-events/abcdefghijk
This is the same URL configured for the integration.
Monitoring and sync status
To learn more about how to monitor and check the sync status of your integration, see the relevant documentation.