Deploy Hub configurations from the CLI (#2955)
* feat(cli): add Hub configuration deploy Deploy configuration bytes directly to an explicitly targeted Hub project using only caller-supplied origin and organization API key authority. * refactor(cli): name Hub deploy contracts * docs(hub): complete deploy CLI guidance * docs(hub): link deployed API references * feat(cli): bundle referenced Hub partials Send exact referenced prompt-partial content alongside YAML so Hub can resolve local includes while inline-only configurations keep the existing request shape. * fix(cli): match Hub YAML size semantics Apply the finalized Hub request limit to decoded YAML length and cover multibyte configuration payloads without changing the wire body.
This commit is contained in:
Mohamed Boudra
+10
-1
@@ -199,9 +199,18 @@ Use `PASEO_HOME` to run multiple isolated daemon instances.
|
||||
paseo hub connect <url> # Enroll this daemon with a Paseo Hub
|
||||
paseo hub status # Show the current Hub relationship
|
||||
paseo hub disconnect # End it
|
||||
paseo hub deploy [file] # Install and activate a Hub configuration
|
||||
```
|
||||
|
||||
See [Daemons in Hub](/docs/hub/daemons).
|
||||
`file` defaults exactly to `.paseo/hub.yml` relative to the current directory. Pass a file to use another path. The CLI does not search parent directories or alternate filenames.
|
||||
|
||||
Pass `-p, --project <slug>` to select the project, or add optional top-level `project` metadata to the YAML. The flag wins when both are present. Project is deployment metadata, not workflow configuration, and the YAML is sent unchanged.
|
||||
|
||||
Prompt `include` blocks are read from `.paseo/partials/` under the current directory, even when you pass an explicit configuration file. The CLI sends only the files referenced by the main YAML. Nested include-looking text inside a partial is content and is not resolved recursively. Inline-only configurations omit the partial bundle.
|
||||
|
||||
Deployment requires an explicit Hub origin and organization API key. `--hub <origin>` overrides `PASEO_HUB_URL`; `--api-key <secret>` overrides `PASEO_HUB_API_KEY`. The key's organization supplies organization scope. Durable Hub login and credential persistence are not implemented.
|
||||
|
||||
See [Daemons in Hub](/docs/hub/daemons), [Hub configuration](/docs/hub/configuration), and the [Hub public API](/docs/hub/api).
|
||||
|
||||
## Connecting to a remote daemon
|
||||
|
||||
|
||||
+30
-19
@@ -9,9 +9,16 @@ category: Hub
|
||||
# Hub public API
|
||||
|
||||
The Hub public API lets automation operate on projects and daemons in one
|
||||
organization. Set the Hub origin in `HUB_URL` below, for example
|
||||
organization. Set the Hub origin in `PASEO_HUB_URL` below, for example
|
||||
`https://hub.example.com`.
|
||||
|
||||
## API reference
|
||||
|
||||
- [Interactive API reference](https://hub.paseo.sh/api/reference)
|
||||
- [OpenAPI 3.1 document](https://hub.paseo.sh/api/openapi.json)
|
||||
|
||||
These are the canonical reference endpoints for the hosted Paseo Hub. A self-hosted Hub exposes the same `/api/reference` and `/api/openapi.json` paths on its own origin.
|
||||
|
||||
## Authentication
|
||||
|
||||
Create an organization API key from the Hub dashboard under **API keys**. Send
|
||||
@@ -38,17 +45,18 @@ Each key has one or more selectable scopes:
|
||||
API keys do not grant dashboard access. They cannot manage connections,
|
||||
projects, or organization members.
|
||||
|
||||
Missing, invalid, or revoked credentials return `401`:
|
||||
API failures use RFC 9457 problem details. Missing, invalid, or revoked credentials return `401` with `application/problem+json`:
|
||||
|
||||
```json
|
||||
{ "error": "unauthorized" }
|
||||
{
|
||||
"type": "https://hub.example.com/problems/unauthorized",
|
||||
"title": "Unauthorized",
|
||||
"status": 401,
|
||||
"detail": "Provide a valid organization API key."
|
||||
}
|
||||
```
|
||||
|
||||
A valid key without the scope required by an endpoint returns `403`:
|
||||
|
||||
```json
|
||||
{ "error": "forbidden" }
|
||||
```
|
||||
A valid key without the scope required by an endpoint returns `403` in the same format.
|
||||
|
||||
## Configuration install
|
||||
|
||||
@@ -57,7 +65,7 @@ supplied YAML after Hub validates and compiles it, then activates the new
|
||||
revision.
|
||||
|
||||
```http
|
||||
POST /api/configurations/install
|
||||
POST /api/v1/configurations/install
|
||||
```
|
||||
|
||||
Request body:
|
||||
@@ -65,12 +73,17 @@ Request body:
|
||||
```json
|
||||
{
|
||||
"projectSlug": "my-project",
|
||||
"yaml": "environments:\n - name: production\n kind: daemon\n daemon: build-server\n cwd: /workspace\ntriggers:\n - name: deploy\n on: manual.run\n max_runtime: 2h\n filters:\n from_users: [automation]\n steps:\n - id: deploy\n environment: production\n max_runtime: 90m\n idle_timeout: 10m\n agent:\n provider: opencode\n mode: full-access\n prompt:\n - text: Deploy the project"
|
||||
"yaml": "environments:\n - name: production\n kind: daemon\n daemon: build-server\n cwd: /workspace\ntriggers:\n - name: deploy\n on: manual.run\n max_runtime: 2h\n filters:\n from_users: [automation]\n steps:\n - id: deploy\n environment: production\n max_runtime: 90m\n idle_timeout: 10m\n agent:\n provider: opencode\n mode: full-access\n prompt:\n - text: Deploy the project",
|
||||
"partials": [
|
||||
{
|
||||
"path": "docs/safety.md",
|
||||
"content": "Follow the safety checklist."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The YAML must describe a valid Hub configuration. Replace the example daemon,
|
||||
working directory, and trigger values with resources in your organization.
|
||||
The YAML must describe a valid Hub configuration and its string value is limited to 1,000,000 characters. `projectSlug` is deployment metadata and determines the target project; the API key determines its organization. `partials` is optional for inline-only configurations. When the YAML uses prompt `include` blocks, send exactly one entry for each referenced file, with a path relative to `.paseo/partials/` and the file's UTF-8 content. The bundle accepts at most 100 files, each with a canonical path no longer than 512 characters and content no larger than 1,000,000 bytes; combined partial content may not exceed 5,000,000 bytes. Hub rejects missing, extra, duplicate, unsafe, or oversized entries. Replace the example daemon, working directory, and trigger values with resources in your organization.
|
||||
|
||||
On success, Hub returns `201`:
|
||||
|
||||
@@ -83,21 +96,19 @@ On success, Hub returns `201`:
|
||||
}
|
||||
```
|
||||
|
||||
Common responses are `400 {"error":"invalid_request"}` for a missing or
|
||||
malformed body, `404 {"error":"project_not_found"}` for an inactive or
|
||||
unknown project in the key's organization, and `422` for invalid YAML or an
|
||||
invalid configuration. An invalid configuration includes the provisional
|
||||
`versionId` in its response.
|
||||
Common responses are `400` for a missing or malformed body, `404` for an inactive or unknown project in the key's organization, and `422` for invalid YAML or an invalid configuration. Validation problem details include field issues. A failed install does not replace the active revision.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
curl --fail-with-body -sS -X POST "$HUB_URL/api/configurations/install" \
|
||||
-H "Authorization: Bearer $PASEO_API_KEY" \
|
||||
curl --fail-with-body -sS -X POST "$PASEO_HUB_URL/api/v1/configurations/install" \
|
||||
-H "Authorization: Bearer $PASEO_HUB_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
--data @configuration-install.json
|
||||
```
|
||||
|
||||
For a local YAML file, `paseo hub deploy [file]` calls this endpoint and preserves the file contents. See [Deploy from the CLI](/docs/hub/configuration#deploy-from-the-cli) for project precedence, flags, environment variables, and the current authentication limits.
|
||||
|
||||
## Manual run dispatch
|
||||
|
||||
`runs:dispatch` dispatches a configured `manual.run` trigger for a project.
|
||||
|
||||
@@ -8,9 +8,11 @@ category: Hub
|
||||
|
||||
# `hub.yml` reference
|
||||
|
||||
A configuration has `environments` and `triggers`. Execution fields belong to each trigger's `steps`.
|
||||
A configuration has `environments` and `triggers`. It may also include top-level `project` deployment metadata for `paseo hub deploy`. Execution fields belong to each trigger's `steps`.
|
||||
|
||||
```yaml
|
||||
project: my-project
|
||||
|
||||
environments:
|
||||
- name: development
|
||||
kind: daemon
|
||||
@@ -35,6 +37,8 @@ triggers:
|
||||
- text: ${{ paseo.prompt }}
|
||||
```
|
||||
|
||||
`project` is an optional bare project slug. The deploy CLI uses it to choose the target project when `-p, --project` is absent. The flag takes precedence over this metadata without rewriting the YAML. `project` is not available to triggers, expressions, or agents.
|
||||
|
||||
## Environments
|
||||
|
||||
| Field | Required | Notes |
|
||||
@@ -131,7 +135,7 @@ Hub counts an actual capability emission; ordinary assistant text does not satis
|
||||
|
||||
## Prompt partials
|
||||
|
||||
`include` paths are relative to `.paseo/partials/` and are resolved at the exact GitHub configuration commit. Hub stores the resolved content and SHA-256 hash in the immutable revision. Missing files, unsafe paths, symlinks, submodules, directories, and nested includes are rejected. Manual configurations cannot use repository partials.
|
||||
`include` paths are relative to `.paseo/partials/`. For GitHub configuration, Hub reads them at the exact configuration commit and stores the resolved content and SHA-256 hash in the immutable revision. For `paseo hub deploy`, the CLI reads the referenced files from the local project root and sends them in the optional `partials` bundle; the bundle path omits the `.paseo/partials/` prefix. Missing files, unsafe paths, symlinks, submodules, directories, duplicate or unexpected bundle entries, and nested includes are rejected. Manual configurations cannot use repository partials.
|
||||
|
||||
## Deadlines
|
||||
|
||||
|
||||
@@ -16,11 +16,36 @@ A configuration comes from exactly one source:
|
||||
|
||||
- **GitHub source**: one repository, the file `.paseo/hub.yml`, on the repository's current default branch.
|
||||
- **Manual source**: edited in the dashboard and saved with **Save and activate**.
|
||||
- **CLI/API install**: YAML sent explicitly with an organization API key.
|
||||
|
||||
Pick a GitHub source by choosing a repository and clicking **Use for configuration**. That syncs immediately and enables automatic deployment.
|
||||
|
||||
The path and the branch are fixed. There is no setting for either.
|
||||
|
||||
## Deploy from the CLI
|
||||
|
||||
From a project checkout, add the target project slug as optional deployment metadata:
|
||||
|
||||
```yaml
|
||||
project: my-project
|
||||
```
|
||||
|
||||
Then deploy:
|
||||
|
||||
```sh
|
||||
PASEO_HUB_URL=https://hub.example.com \
|
||||
PASEO_HUB_API_KEY=paseo_pk_... \
|
||||
paseo hub deploy
|
||||
```
|
||||
|
||||
The default path is exactly `.paseo/hub.yml` relative to the current directory. The CLI does not search parent directories or alternate filenames. Use `paseo hub deploy path/to/config.yml` for another file. The bundle root remains the current directory, so partials are always read from `.paseo/partials/` under that directory. `-p, --project <slug>` overrides the file's `project` value without changing the YAML sent to Hub.
|
||||
|
||||
For each prompt `include`, the CLI sends one `{ path, content }` entry whose path is relative to `.paseo/partials/`. It sends only files referenced by the main YAML; nested include-looking text inside a partial is not scanned. Missing, unsafe, duplicate, unreadable, non-file, or oversized inputs fail locally before the Hub request. A configuration with only inline prompt blocks sends no `partials` field.
|
||||
|
||||
Use `--hub <origin>` or `PASEO_HUB_URL` for the Hub origin, and `--api-key <secret>` or `PASEO_HUB_API_KEY` for the organization API key. A flag takes precedence over its environment variable. The key supplies organization scope and needs `configuration:install`. `project` only selects the deployment target; workflows cannot reference it.
|
||||
|
||||
Durable Hub login and credential persistence are not implemented. Supply the origin and API key for each deployment through flags or the current process environment.
|
||||
|
||||
## Sync
|
||||
|
||||
A push to the default branch of the configuration repository triggers a sync:
|
||||
|
||||
@@ -39,6 +39,8 @@ Open **Projects → New project**. On its **Configuration** tab, pick a reposito
|
||||
Add `.paseo/hub.yml` to that repository:
|
||||
|
||||
```yaml
|
||||
project: your-project
|
||||
|
||||
environments:
|
||||
- name: dev
|
||||
kind: daemon
|
||||
@@ -67,7 +69,9 @@ triggers:
|
||||
${{ paseo.prompt }}
|
||||
```
|
||||
|
||||
`daemon` is the normalized slug from step 3. `cwd` is a directory on that machine.
|
||||
`project` is the project slug from step 4. The deploy CLI reads it as deployment metadata; it does not affect workflow behavior. `daemon` is the normalized slug from step 3. `cwd` is a directory on that machine.
|
||||
|
||||
If a prompt uses an `include` block, store the file below `.paseo/partials/`. The deploy CLI bundles only the files referenced by `.paseo/hub.yml`; nested include-looking text inside a partial is not resolved.
|
||||
|
||||
## 6. Push
|
||||
|
||||
@@ -75,6 +79,16 @@ Push to the default branch. Hub fetches the file at that commit, validates it, a
|
||||
|
||||
If the file is invalid, Hub records the failure and keeps the previous revision active.
|
||||
|
||||
To deploy the file directly instead, create an organization API key with the `configuration:install` scope, then run:
|
||||
|
||||
```sh
|
||||
export PASEO_HUB_URL=https://your-hub.example.com
|
||||
export PASEO_HUB_API_KEY=paseo_pk_...
|
||||
paseo hub deploy
|
||||
```
|
||||
|
||||
The command reads exactly `.paseo/hub.yml` from the current directory. It does not search parent directories. Use `paseo hub deploy path/to/config.yml` for another file. `-p, --project <slug>` overrides the file's `project` metadata. See [Hub configuration](/docs/hub/configuration#deploy-from-the-cli) for every deploy option and the current authentication limits.
|
||||
|
||||
## 7. Trigger it
|
||||
|
||||
Comment `@paseo have a look at this` on an issue in that repository, from the account you listed in `from_users`.
|
||||
|
||||
Reference in New Issue
Block a user