Documentation

Source-of-truth docs, references, plans, and product material across Harbor surfaces.

Docs / Flows And Authoring
Flows And Authoring

Harbor Port And Hub Authoring

Create Harbor integrations that are:

portsauthoringhub
Source: HARBOR_PORT_ACTION_AUTHORING.md

Harbor Port And Hub Authoring

Goal

Create Harbor integrations that are:

  • capability-based
  • reviewable
  • safe to host in Dock / Hub
  • usable by operators and agents without exposing raw secrets

This document is the shared workflow for Codex, OpenClaw, and human contributors when adding:

  • a new Harbor http_api port design
  • new Harbor action drafts under a port
  • a Dock / Hub integration manifest

What a Harbor Port is

A Harbor Port is the service connection boundary.

For the current MVP, most new third-party integrations should start as:

  • kind: "http_api"

That means:

  • Harbor stores the hidden auth token locally in Harbor Node
  • Harbor exposes only safe metadata publicly
  • Harbor Actions are the callable surface
  • Dock / Hub can distribute the safe template, but never the credential

Port worksheet

Before authoring actions or a Dock entry, collect this worksheet:

Safe metadata

  • label
  • description
  • baseUrl
  • authMode
  • authHeaderName
  • authTokenPrefix
  • category
  • tags
  • publisher.slug
  • publisher.name

Hidden local config

  • authToken

Only Harbor Node stores the hidden value. Dock / Hub never contains it.

Action template fields

Every action template should be reduced to the current Harbor-safe fields:

  • slug
  • label
  • description
  • method
  • path
  • approvalMode
  • requestBodyMode
  • resultMode

path may be either:

  • a fixed relative path like /user/repos
  • a bounded path template like /repos/{owner}/{repo}/issues

When using placeholders, keep them explicit, named, and reviewable. Do not turn them into arbitrary full-route input.

Recommended defaults:

- none for simple GET-like actions - json for bounded JSON bodies

- json_summary for most APIs

  • requestBodyMode
  • resultMode

Action Model Inputs

Harbor's Action Model supports typed request inputs for http_api actions that need more than a fixed path.

Use it when an action needs more than a fixed path:

  • inputs.parameters for typed path and query values
  • inputs.staticQuery for safe Harbor-owned defaults

Runtime calls should then use:

  • input.path
  • input.query
  • input.body for JSON writes

Keep raw query strings out of the default model. If a provider needs complicated query grammar later, prefer computed Harbor-owned adapters over freeform transport input.

Dock / Hub manifest fields

Current Dock manifests are JSON and must match the shape in index.ts.

Each entry should contain:

  • formatVersion
  • kind
  • slug
  • title
  • summary
  • description
  • version
  • publisher
  • category
  • tags
  • compatibility
  • portTemplates
  • actionTemplates
  • workflowTemplates if safe and useful
  • helpText
  • installNotes

Safety rules

Always do

  • model a third-party service as a fixed-base Harbor Port
  • keep actions narrow and named
  • plan the full supportable API surface before writing the manifest
  • create or refresh ActionMap.md for every integration folder you touch
  • add every technically supportable action, not just the starter reads
  • send risky writes through require_approval
  • keep install notes explicit that credentials must be configured locally after import

Never do

  • create a generic arbitrary HTTP proxy action
  • put hidden config into Dock manifests
  • ask Harbor for the current token value
  • auto-publish imported actions by default
  • stop at three starter actions and call the integration complete
  • hide missing coverage behind broad categories instead of exact function names

Required outputs for every Hub integration

Every integration completeness pass must leave behind:

  • the integration JSON manifest at apps/hub/catalog/integrations/<publisher>/<slug>.json
  • ActionMap.md in the same folder
  • TechnicalLimitations.md in the same folder when exact API actions are blocked by current Harbor platform limits

If an integration folder has no ActionMap.md, treat it as unfinished starter coverage even if a manifest exists.

- Reference integrations now live under docs/PortsReference. - Start with GMAIL_PORT.md, GOOGLE_DRIVE_PORT.md, GOOGLE_CALENDAR_PORT.md, GOOGLE_SHEETS_PORT.md, BIGQUERY_PORT.md, SLACK_WEB_PORT.md, DROPBOX_PORT.md, GITLAB_PORT.md, GITHUB_PORT.md, TODOIST_REST_PORT.md, BOX_PORT.md, ASANA_PORT.md, AIRTABLE_WEB_PORT.md, and HUBSPOT_CRM_PORT.md. - Then expand into SENTRY_PORT.md, OPENAI_PORT.md, COHERE_PORT.md, CLOUDFLARE_PORT.md, VERCEL_PORT.md, FIGMA_REST_PORT.md, DIGITALOCEAN_PORT.md, NETLIFY_PORT.md, MISTRAL_PORT.md, TAVILY_PORT.md, CONFLUENCE_CLOUD_PORT.md, DISCORD_BOT_PORT.md, JENKINS_REMOTE_PORT.md, JIRA_CLOUD_PORT.md, MICROSOFT_GRAPH_MAIL_PORT.md, MICROSOFT_GRAPH_CALENDAR_PORT.md, SALESFORCE_REST_PORT.md, ZENDESK_PORT.md, and ZOOM_PORT.md.

- base URL - auth header name - auth prefix - stable paths - major resource groups - list, get, search, create, update, delete, webhook, watch, and admin operations

- supportable now in Harbor's current http_api action model - supportable now but should default to require_approval - blocked by a real Harbor platform limitation

- Do not stop at the first 3 starter actions unless the backlog explicitly says the API is deferred for now. - The default expectation is full supportable coverage for the current API surface.

- If the action is technically possible today, add it. - If it is not technically possible today, document the exact blocked function in TechnicalLimitations.md.

- Run node scripts/generate-hub-action-maps.mjs. - The map must make completeness review easy without reopening the full JSON.

- Run pnpm --filter @harbor/hub build.

  1. Choose a target API from docs/HARBOR_TARGET_API_BACKLOG_TOP_100.md.
  2. Read the official API docs and inventory the real function surface:
  3. Classify every documented function into one of these buckets:
  4. Create or reuse the local Harbor http_api port and implement all supportable actions.
  5. Only leave actions out when there is a concrete technical limitation.
  6. Add the safe integration document at catalog, typically under apps/hub/catalog/integrations/<publisher>/<slug>.json.
  7. Generate or refresh ActionMap.md.
  8. Validate and test the manifest in Harbor.
  9. Update the backlog entry status and notes.

Completeness standard

The old "first 3 to 10 actions" starter pattern is not enough for a completed Hub integration.

Use starter actions only as an initial scaffold. A finished integration pass should:

  • cover all API actions that Harbor can model today
  • use require_approval for risky writes, deletes, webhook actions, and high-impact mutations
  • leave out only actions blocked by real Harbor technical limitations
  • document those blocked actions precisely, with follow-up implementation notes

If an integration only has a few list or read actions and no ActionMap.md, treat it as starter coverage.

What to include in ActionMap.md

ActionMap.md is the fast completeness ledger for an integration folder.

It should stay simple. It does not need to repeat the whole JSON manifest.

At minimum it must include:

  • every currently implemented Harbor action for the integration
  • a simple function-to-action mapping such as create-repo -> http_api-github-rest-api.create-repository
  • one section per integration JSON in that folder when a publisher folder contains multiple manifests
  • phased planning sections for large APIs when the supportable surface is more than 33 actions
  • exact skipped or deferred function names when Harbor does not implement part of the API yet
  • clear notes for anything blocked by Harbor platform limitations

Good skipped notes are specific:

  • download-file
  • export-google-doc
  • upload-file
  • delete-message
  • watch-mailbox

Bad skipped notes are too vague:

  • file operations
  • admin stuff
  • risky writes

If the integration supports all currently possible actions, ActionMap.md should still exist and say so.

Large API phase workflow

If an API has more than 33 supportable actions, treat it as a phased integration instead of trying to build the whole surface in one pass.

Use this rule:

  • 1 to 33 supportable actions: one implementation pass is fine
  • more than 33 supportable actions: split into multiple phases
  • target a maximum of 33 actions per phase
  • keep phases balanced when possible so one phase does not carry all of the hard work

For large APIs, the first run should be a planning run only.

That planning run should:

  • read the official docs and map the full action surface
  • classify each documented function as supportable now, approval-heavy, or technically blocked
  • create ActionMap.md before the implementation passes
  • split the work into numbered phases with a reasonable number of functions per phase
  • note the intended ownership for each phase so the work can be delegated cleanly

The planning run should not stop at broad categories. It should map every known call that Harbor can support or cannot yet support.

Recommended phase sizing:

  • Phase 1: 25 to 33 actions
  • Phase 2: 25 to 33 actions
  • Phase 3: 25 to 33 actions
  • Phase 4+: use only when the API surface still exceeds the first three balanced phases

Prefer resource-based phase boundaries when they are clean:

  • repositories
  • issues and comments
  • pull requests and reviews
  • users and organizations

If resource boundaries are uneven, balance phases by action count instead.

Large API execution flow

For APIs above the 33-action threshold, use this execution flow:

  1. Run a planning pass first.
  2. Write ActionMap.md with all mapped calls and numbered phases.
  3. Confirm which actions are technically blocked and move those to TechnicalLimitations.md.
  4. Delegate each implementation phase to a separate sub-agent when sub-agents are available.
  5. Keep each sub-agent responsible for one phase only.
  6. Regenerate ActionMap.md, review for completeness, and merge the results.

Each delegated phase should have:

  • a bounded write scope
  • a named list of functions to implement
  • a target action count of no more than 33
  • clear approval defaults for risky actions
  • no overlap with other phases unless explicitly necessary

This keeps very large APIs manageable and reduces merge conflict risk.

Suggested ActionMap.md phase format

For large APIs, ActionMap.md should include:

  • a planning summary
  • a full mapped inventory
  • numbered implementation phases
  • a blocked-by-technical-limitations section

Simple example:

markdown 
# Action Map

## Planning Summary

- Total mapped API functions: 112
- Supportable now: 96
- Blocked by technical limitations: 16
- Planned implementation phases: 4

## Phase 1

- `list-projects -> http_api-example.list-projects`
- `get-project -> http_api-example.get-project`

## Phase 2

- `list-tasks -> http_api-example.list-tasks`
- `create-task -> http_api-example.create-task`

## Blocked By Technical Limitations

- `upload-file`: needs multipart request body support
- `download-export`: needs binary result mode

The exact markdown format can vary, but the phase split and the function-level inventory must stay easy to scan.

What to include in TechnicalLimitations.md

Only create TechnicalLimitations.md when Harbor cannot model an API function today.

For each blocked function, document:

  • the exact API function name
  • why Harbor cannot model it with the current action system
  • the Harbor limitation involved, such as no multipart body mode or no binary result mode
  • what code or schema changes would unblock it later

Do not use TechnicalLimitations.md to justify skipping actions that are merely risky. Risk is handled by approval and policy, not by omission.

Action design rubric

Use this rubric before adding an action:

  • Is the route fixed?
  • If it has placeholders, are they few, explicit, and bounded?
  • Is the path stable and understandable?
  • Is the input bounded?
  • Is the output safe to summarize?
  • Would a mistaken call cause side effects?
  • Should it require approval?

If the answer to "Is the route fixed?" is no, do not model it as a Harbor Action yet. A bounded path template with a small explicit placeholder set can still count as fixed.

Approval guidance

Default automatic only for:

  • health/status reads
  • profile reads
  • list/read operations with bounded outputs

Default require_approval for:

  • send / post / create
  • update / patch / put
  • delete
  • admin operations
  • webhook or messaging actions
  • billing, money movement, or account changes

Note:

  • Harbor does not yet support a disabled-by-default action state in manifests.
  • If an action is technically supported, include it and control risk with require_approval plus Harbor Guard policy.

How to populate Dock / Hub today

Current Dock seed data is in:

For now, populating Dock means:

  1. adding a new integration JSON document and safe manifest
  2. letting Hub load that file and sync it into its local SQLite catalog on boot
  3. keeping install notes explicit that credentials stay local

Do not wait for HarborHub registry features before building safe template coverage.

Human operator

  • chooses target API
  • provides sandbox credentials locally
  • reviews risky actions
  • approves publish

Codex

  • maps the API to a Harbor Port worksheet
  • builds the full supportable action set
  • updates Hub seed manifests
  • generates ActionMap.md
  • documents technical blockers precisely when they exist
  • updates docs and backlog status

OpenClaw

  • researches official docs
  • proposes missing actions and completeness gaps
  • validates/tests drafts under an existing port
  • requests publish instead of self-publishing by default

Definition of done for a new integration

A new integration is ready when:

  • the port worksheet is complete
  • all currently supportable actions are implemented
  • ActionMap.md exists and matches the manifest
  • any unsupported actions are documented in TechnicalLimitations.md with exact function names and required platform changes
  • the actions validate and test
  • approval mode choices are documented
  • the Dock manifest is secret-free
  • the Hub entry can be imported into Harbor
  • the operator can fill local auth after import