Skip to content

docs(v5.1): release notes, deployment tracking operations #524

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kriszyp merged 4 commits into from
Jun 13, 2026
+350 −16
Merged

docs(v5.1): release notes, deployment tracking operations #524

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
813890d
docs(v5.1): release notes, deployment tracking ops, deploy_component …
kriszyp Jun 10, 2026
dfdb229
style: run prettier on changed files
kriszyp Jun 11, 2026
a2d5c89
fix: remove cross-plugin MCP link that breaks Docusaurus build
kriszyp Jun 11, 2026
4e224f7
docs(5.1): expand release notes — middleware/routing, caching, LOCAL_…
kriszyp Jun 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
132 changes: 116 additions & 16 deletions reference/operations-api/operations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -577,27 +577,38 @@ Operations for deploying and managing Harper components (applications, plugins).

Detailed documentation: [Components Overview](../components/overview.md)

| Operation | Description | Role Required |
| ---------------------- | ----------------------------------------------------------------------- | ------------- |
| `add_component` | Creates a new component project from a template | super_user |
| `deploy_component` | Deploys a component via payload (tar) or package reference (NPM/GitHub) | super_user |
| `package_component` | Packages a component project into a base64-encoded tar | super_user |
| `drop_component` | Deletes a component or a file within a component | super_user |
| `get_components` | Lists all component files and config | super_user |
| `get_component_file` | Returns the contents of a file within a component | super_user |
| `set_component_file` | Creates or updates a file within a component | super_user |
| `add_ssh_key` | Adds an SSH key for deploying from private repositories | super_user |
| `update_ssh_key` | Updates an existing SSH key | super_user |
| `delete_ssh_key` | Deletes an SSH key | super_user |
| `list_ssh_keys` | Lists all configured SSH key names | super_user |
| `set_ssh_known_hosts` | Overwrites the SSH known_hosts file | super_user |
| `get_ssh_known_hosts` | Returns the contents of the SSH known_hosts file | super_user |
| `install_node_modules` | _(Deprecated)_ Run npm install on component projects | super_user |
| Operation | Description | Role Required |
| --------------------------- | ----------------------------------------------------------------------- | ------------- |
| `add_component` | Creates a new component project from a template | super_user |
| `deploy_component` | Deploys a component via payload (tar) or package reference (NPM/GitHub) | super_user |
| `package_component` | Packages a component project into a base64-encoded tar | super_user |
| `drop_component` | Deletes a component or a file within a component | super_user |
| `get_components` | Lists all component files and config | super_user |
| `get_component_file` | Returns the contents of a file within a component | super_user |
| `set_component_file` | Creates or updates a file within a component | super_user |
| `list_deployments` | Lists deployment records with optional filters | super_user |
| `get_deployment` | Fetches a single deployment record by ID; supports SSE streaming | super_user |
| `get_deployment_payload` | Returns the tarball stored for a deployment | super_user |
| `delete_deployment_payload` | Removes the stored tarball to free space | super_user |
| `add_ssh_key` | Adds an SSH key for deploying from private repositories | super_user |
| `update_ssh_key` | Updates an existing SSH key | super_user |
| `delete_ssh_key` | Deletes an SSH key | super_user |
| `list_ssh_keys` | Lists all configured SSH key names | super_user |
| `set_ssh_known_hosts` | Overwrites the SSH known_hosts file | super_user |
| `get_ssh_known_hosts` | Returns the contents of the SSH known_hosts file | super_user |
| `install_node_modules` | _(Deprecated)_ Run npm install on component projects | super_user |

### `deploy_component`

Deploys a component. The `package` option accepts any valid NPM reference including GitHub repos (`HarperDB/app#semver:v1.0.0`), tarballs, or NPM packages. The `payload` option accepts a base64-encoded tar string from `package_component`. Supports `"replicated": true` and `"restart": true` or `"restart": "rolling"`.

Additional parameters:

- `urlPath` — override the HTTP URL path the component is mounted at (e.g. `"/api/v2"`)
- `install_allow_scripts` — set to `true` to allow npm pre/post install scripts (disabled by default)

The response includes a `deployment_id` that can be used to query the deployment record:

```json
{
"operation": "deploy_component",
Expand All @@ -608,6 +619,95 @@ Deploys a component. The `package` option accepts any valid NPM reference includ
}
```

Response:

```json
{
"deployment_id": "a3f8c2d1...",
"message": "Component deployed successfully"
}
```

### Deployment Operations

Harper records every `deploy_component` call in the `system.hdb_deployment` table, capturing the full lifecycle of a deployment including phase transitions (prepare → load → replicate → restart → success/failed), per-node outcomes, and a bounded event log of install output.

### `list_deployments`

Returns a list of deployment records, newest first. All filter parameters are optional.

| Parameter | Type | Description |
| --------- | ------ | ------------------------------------------------ |
| `project` | string | Filter to a specific component project |
| `status` | string | Filter by status: `pending`, `success`, `failed` |
| `since` | number | Start of time range (Unix timestamp ms) |
| `until` | number | End of time range (Unix timestamp ms) |
| `limit` | number | Maximum number of results (default: 100) |
| `offset` | number | Pagination offset |

```json
{
"operation": "list_deployments",
"project": "my-app",
"status": "success",
"limit": 20
}
```

Response includes a `deployments` array and a `total` count. The `payload_blob` field is stripped from list responses for size; use `get_deployment_payload` to retrieve the tarball.

### `get_deployment`

Returns a single deployment record by `deployment_id`. When called on an in-progress deployment via a request that accepts `text/event-stream`, the response streams live phase events and install output as Server-Sent Events, replaying the buffered event log then tailing until the deployment reaches a terminal status.

```json
{
"operation": "get_deployment",
"deployment_id": "a3f8c2d1..."
}
```

The deployment record includes:

| Field | Description |
| -------------------- | ----------------------------------------------------------------------- |
| `deployment_id` | Unique identifier (content hash) |
| `project` | Component project name |
| `package_identifier` | Package reference or `payload` for tar uploads |
| `status` | `pending`, `success`, `failed`, or `rolled_back` |
| `phase` | Current lifecycle phase: `prepare`, `load`, `replicate`, `restart` |
| `event_log` | Bounded log of install output and phase transitions (up to 200 entries) |
| `peer_results` | Per-node outcome map for replicated deployments |
| `payload_hash` | SHA-256 hash of the deployment tarball |
| `payload_size` | Byte size of the deployment tarball |
| `started_at` | Timestamp when deployment began |
| `completed_at` | Timestamp when deployment finished |
| `user` | User who initiated the deployment |
| `rollback_of` | `deployment_id` of the deployment this rolls back, if applicable |
| `error` | Error message for failed deployments |

### `get_deployment_payload`

Returns the raw tarball for a deployment. Useful for inspecting or re-deploying a specific version.

```json
{
"operation": "get_deployment_payload",
"deployment_id": "a3f8c2d1..."
}
```

### `delete_deployment_payload`

Removes the tarball blob from a deployment record. The deployment record itself is retained; only the binary payload is deleted. Use this to reclaim storage after confirming a deployment is stable.

```json
{
"operation": "delete_deployment_payload",
"deployment_id": "a3f8c2d1..."
}
```

### `add_ssh_key`

Adds an SSH key (must be ed25519) for authenticating deployments from private repositories.
Expand Down
Loading
Loading