BrowserStack

Custom Ocean integration

This integration was created using the custom Ocean integration framework.
Please note that:

1. This integration will not be listed in the Data sources page of your Port application, and must be installed manually using the instructions on this page.
2. This integration will not create components (e.g. blueprints, mapping, etc.) in your portal automatically, you will need to create them manually using the instructions on this page.

Port's BrowserStack integration allows you to model BrowserStack Automate test data in your software catalog and ingest it using the Ocean Custom Integration framework.

Supported resources

The BrowserStack integration can ingest the following resources into Port:

• plan - Account utilization and capacity from GET /automate/plan.json.
• project - Automate projects and team groupings from GET /automate/projects.json.
• build - Build history and pass/fail trends from builds nested in GET /automate/projects/{project_id}.json.

Entity hierarchy

The integration models this relationship in Port:

Project → Build

The plan resource is account-level utilization data and is not part of this hierarchy.

Prerequisites

To use this integration, you need:

• A BrowserStack account with access to BrowserStack Automate.
• Your BrowserStack username and access key for API authentication.

To find your BrowserStack credentials:

1. Log in to BrowserStack.
2. Go to Account settings.
3. Copy your username and access key.

Installation

The Ocean custom integration can be installed in two ways:

• Hosted by Port — Port manages the infrastructure; configure the connection in the Port UI.
• Self-hosted — Run the integration in your own infrastructure using Helm or Docker.

Choose one of the following options:

Hosted by Port

Set up in Port

1. Go to the custom data source page and open the Ocean custom integration form.
2. In the configuration form, enter the following values:
   • Identifier: browserstack-ocean.
   • Base URL: https://api.browserstack.com.
   • Authentication type: basic.
   • Username: your BrowserStack username.
   • Password: your BrowserStack access key.
3. Click Save & install.

Helm

Prerequisites

• A Kubernetes cluster - the integration's container chart will be deployed to this cluster.

• kubectl and helm must be installed on your machine. Your kubectl CLI must be connected to the Kubernetes cluster where you plan to install the integration.

Installation

1. Add Port's Helm repo and install the Ocean Custom Integration:

Replace placeholders

Remember to replace the placeholders for YOUR_PORT_CLIENT_ID, YOUR_PORT_CLIENT_SECRET, YOUR_BROWSERSTACK_USERNAME, and YOUR_BROWSERSTACK_ACCESS_KEY.

helm repo add --force-update port-labs https://port-labs.github.io/helm-charts
helm upgrade --install browserstack-ocean port-labs/port-ocean \
  --set port.clientId="YOUR_PORT_CLIENT_ID" \
  --set port.clientSecret="YOUR_PORT_CLIENT_SECRET" \
  --set port.baseUrl="https://api.port.io" \
  --set initializePortResources=true \
  --set scheduledResyncInterval=60 \
  --set integration.identifier="browserstack-ocean" \
  --set integration.type="custom" \
  --set integration.eventListener.type="POLLING" \
  --set integration.config.baseUrl="https://api.browserstack.com" \
  --set integration.config.authType="basic" \
  --set integration.config.paginationType="none" \
  --set integration.secrets.username="YOUR_BROWSERSTACK_USERNAME" \
  --set integration.secrets.password="YOUR_BROWSERSTACK_ACCESS_KEY"

Selecting a Port API URL by account region

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

Configuration parameters

This table summarizes the available parameters for the installation.

Parameter	Description	Example	Required
port.clientId	Your Port client ID		✅
port.clientSecret	Your Port client secret		✅
port.baseUrl	Your Port API URL - https://api.port.io for EU, https://api.us.port.io for US		✅
integration.config.baseUrl	The base URL of the BrowserStack API. Endpoint paths in your mapping include the /automate prefix.	https://api.browserstack.com	✅
integration.config.authType	The authentication type (use basic for BrowserStack)	basic	✅
integration.secrets.username	Your BrowserStack username		✅
integration.secrets.password	Your BrowserStack access key		✅
integration.config.paginationType	Pagination method. Use none for the default mappings on this page.	none	❌
integration.eventListener.type	The event listener type. Read more about event listeners	POLLING	✅
integration.type	The integration type (must be custom for Ocean Custom Integration)	custom	✅
integration.identifier	Unique identifier for the integration instance	browserstack-ocean	✅
scheduledResyncInterval	The number of minutes between each resync. Read more about scheduledResyncInterval	60	❌
initializePortResources	When set to true, the integration will create default blueprints and the Port app config mapping	true	❌
sendRawDataExamples	Enable sending raw data examples from the BrowserStack API to Port for testing and managing the integration mapping. Default is true	true	❌

Advanced integration configuration

For advanced configuration such as proxies or self-signed certificates, click here.

Docker

To run the integration using Docker for a one-time sync:

Replace placeholders

Remember to replace the placeholders for YOUR_PORT_CLIENT_ID, YOUR_PORT_CLIENT_SECRET, YOUR_BROWSERSTACK_USERNAME, and YOUR_BROWSERSTACK_ACCESS_KEY.

docker run -i --rm --platform=linux/amd64 \
  -e OCEAN__EVENT_LISTENER='{"type":"ONCE"}' \
  -e OCEAN__INITIALIZE_PORT_RESOURCES=true \
  -e OCEAN__SEND_RAW_DATA_EXAMPLES=true \
  -e OCEAN__INTEGRATION__CONFIG__BASE_URL="https://api.browserstack.com" \
  -e OCEAN__INTEGRATION__CONFIG__AUTH_TYPE="basic" \
  -e OCEAN__INTEGRATION__CONFIG__PAGINATION_TYPE="none" \
  -e OCEAN__INTEGRATION__SECRETS__USERNAME="YOUR_BROWSERSTACK_USERNAME" \
  -e OCEAN__INTEGRATION__SECRETS__PASSWORD="YOUR_BROWSERSTACK_ACCESS_KEY" \
  -e OCEAN__PORT__CLIENT_ID="YOUR_PORT_CLIENT_ID" \
  -e OCEAN__PORT__CLIENT_SECRET="YOUR_PORT_CLIENT_SECRET" \
  -e OCEAN__PORT__BASE_URL="https://api.port.io" \
  ghcr.io/port-labs/port-ocean-custom:latest

Selecting a Port API URL by account region

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

Advanced integration configuration

For advanced configuration such as proxies or self-signed certificates, click here.

Set up data model

Before the integration can sync data, you need to create the required blueprints in Port. These blueprints define the data model for your BrowserStack resources.

To create the blueprints:

1. Go to your Builder page.

2. Click + Blueprint.

3. Click the {...} Edit JSON button in the top right corner of the form.

4. Copy and paste each blueprint JSON from the section below.

   Create blueprints in order

   We recommend creating blueprints in the order they appear below. Create the Project blueprint before the Build blueprint, since builds reference projects.

   Plan blueprint (click to expand)

   Account-level Automate utilization and capacity:

   {
     "identifier": "browserstackPlan",
     "title": "BrowserStack Plan",
     "description": "BrowserStack Automate plan utilization and parallel session capacity",
     "schema": {
       "properties": {
         "automatePlan": {
           "type": "string",
           "title": "Automate Plan"
         },
         "parallelSessionsRunning": {
           "type": "number",
           "title": "Parallel Sessions Running"
         },
         "parallelSessionsMaxAllowed": {
           "type": "number",
           "title": "Parallel Sessions Max Allowed"
         },
         "teamParallelSessionsMaxAllowed": {
           "type": "number",
           "title": "Team Parallel Sessions Max Allowed"
         },
         "queuedSessions": {
           "type": "number",
           "title": "Queued Sessions"
         },
         "queuedSessionsMaxAllowed": {
           "type": "number",
           "title": "Queued Sessions Max Allowed"
         }
       },
       "required": []
     },
     "mirrorProperties": {},
     "calculationProperties": {},
     "aggregationProperties": {},
     "relations": {}
   }

   Project blueprint (click to expand)

   Automate projects used to group builds by team or product:

   {
     "identifier": "browserstackProject",
     "title": "BrowserStack Project",
     "icon": "Team",
     "description": "A BrowserStack Automate project",
     "schema": {
       "properties": {
         "groupId": {
           "type": "number",
           "title": "Group ID"
         },
         "userId": {
           "type": "number",
           "title": "User ID"
         },
         "subGroupId": {
           "type": "number",
           "title": "Sub Group ID"
         },
         "createdAt": {
           "type": "string",
           "format": "date-time",
           "title": "Created At"
         },
         "updatedAt": {
           "type": "string",
           "format": "date-time",
           "title": "Updated At"
         }
       },
       "required": []
     },
     "mirrorProperties": {},
     "calculationProperties": {},
     "aggregationProperties": {},
     "relations": {}
   }

   Build blueprint (click to expand)

   Test builds with pass/fail status and a relation to their parent project:

   {
     "identifier": "browserstackBuild",
     "title": "BrowserStack Build",
     "icon": "Pipeline",
     "description": "A BrowserStack Automate test build",
     "schema": {
       "properties": {
         "duration": {
           "type": "number",
           "title": "Duration (seconds)"
         },
         "status": {
           "type": "string",
           "title": "Status",
           "enum": ["running", "done", "timeout", "failed"],
           "enumColors": {
             "running": "blue",
             "done": "green",
             "timeout": "orange",
             "failed": "red"
           }
         },
         "buildTag": {
           "type": "string",
           "title": "Build Tag"
         },
         "framework": {
           "type": "string",
           "title": "Framework"
         },
         "createdAt": {
           "type": "string",
           "format": "date-time",
           "title": "Created At"
         },
         "updatedAt": {
           "type": "string",
           "format": "date-time",
           "title": "Updated At"
         }
       },
       "required": []
     },
     "mirrorProperties": {},
     "calculationProperties": {},
     "aggregationProperties": {},
     "relations": {
       "project": {
         "title": "Project",
         "target": "browserstackProject",
         "required": false,
         "many": false
       }
     }
   }

5. Click Save after creating each blueprint.

Configuration

After installation, define which endpoints to sync in your integration configuration. Each resource maps an API endpoint to Port entities using JQ expressions to transform the data.

Key mapping components:

• kind: The API endpoint path, combined with your base URL to form the full request URL.
• selector.query: JQ filter to include or exclude entities. Use 'true' to sync all.
• selector.data_path: JQ expression pointing to the array of items in the response.
• port.entity.mappings: How to map API fields to Port entity properties and relations.

For more details on how the Ocean Custom Integration works, see the How it works section.

BrowserStack API reference

The full BrowserStack Automate API reference is available in the BrowserStack docs. Each mapping section below links directly to the relevant endpoint documentation.

BrowserStack API response formats:

With base URL https://api.browserstack.com, each kind includes the /automate path prefix:

kind	Response shape	data_path
/automate/plan.json	Single JSON object	[.]
/automate/projects.json	Direct array of projects	(omit)
/automate/projects/{project_id}.json	Project object with a nested builds array	.project.builds[]

Example project detail response (click to expand)

{
  "project": {
    "id": 17122553,
    "name": "Port Integration",
    "builds": [
      {
        "name": "Build 1",
        "hashed_id": "0059939e770b361b836783145d438d05f3594cb1",
        "duration": 4,
        "status": "done",
        "automation_project_id": 17122553,
        "framework": "selenium",
        "created_at": "2026-06-09T17:54:05.000Z",
        "updated_at": "2026-06-09T17:54:11.000Z"
      }
    ]
  }
}

Sync order matters

We recommend adding mappings in the order shown below. Sync projects first, then builds, so build-to-project relations resolve correctly. Sync the plan resource at any time.

To configure the mappings:

1. Go to your data sources page.

2. Find your BrowserStack integration in the list.

3. Click on the integration to open the mapping editor.

4. Add the resource mapping configurations below.

   Plan mapping (click to expand)

   API reference: GET /automate/plan.json

   resources:
     - kind: /automate/plan.json
       selector:
         query: 'true'
         data_path: '[.]'
       port:
         entity:
           mappings:
             identifier: '"browserstack-automate-plan"'
             title: .automate_plan
             blueprint: '"browserstackPlan"'
             properties:
               automatePlan: .automate_plan
               parallelSessionsRunning: .parallel_sessions_running
               parallelSessionsMaxAllowed: .parallel_sessions_max_allowed
               teamParallelSessionsMaxAllowed: .team_parallel_sessions_max_allowed
               queuedSessions: .queued_sessions
               queuedSessionsMaxAllowed: .queued_sessions_max_allowed

   Projects mapping (click to expand)

   API reference: GET /automate/projects.json

   resources:
     - kind: /automate/projects.json
       selector:
         query: 'true'
       port:
         entity:
           mappings:
             identifier: .id | tostring
             title: .name
             blueprint: '"browserstackProject"'
             properties:
               groupId: .group_id
               userId: .user_id
               subGroupId: .sub_group_id
               createdAt: .created_at
               updatedAt: .updated_at

   Builds mapping (click to expand)

   API reference: GET /automate/projects/{project_id}.json

   This mapping uses nested endpoints to fetch builds for each project.

   resources:
     - kind: /automate/projects/{projectId}.json
       selector:
         query: 'true'
         data_path: .project.builds[]
         path_parameters:
           projectId:
             endpoint: /automate/projects.json
             field: .[].id
             filter: 'true'
       port:
         entity:
           mappings:
             identifier: .hashed_id
             title: .name
             blueprint: '"browserstackBuild"'
             properties:
               duration: .duration
               status: .status
               buildTag: .tags
               framework: .framework
               createdAt: .created_at
               updatedAt: .updated_at
             relations:
               project: .__projectId | tostring

5. Click Save to apply the mapping.

Customization

If you want to test different API endpoints or explore the BrowserStack API before committing to a configuration, use the interactive builder.

The interactive builder helps you:

1. Test your BrowserStack API endpoints with live data.
2. Automatically detect the data structure and field types.
3. Generate blueprints and resource mappings tailored to your preferences.
4. Get installation commands with your configuration pre-filled.

Additional resources

• BrowserStack Automate API reference - full reference for all available endpoints and response schemas.
• BrowserStack plan API - details on utilization and capacity fields.
• BrowserStack project API - details on project list and project detail endpoints.
• BrowserStack build API - details on build list, status values, and pagination parameters.
• Ocean Custom Integration overview - learn how the Ocean Custom Integration framework works.
• Ocean Custom Integration configuration - advanced mapping options, nested endpoints, and pagination configuration.