Deploy multi-file Hub workflows (#3128)
* feat(hub): deploy canonical workflow bundles Keep CLI deployment aligned with Hub's authored bundle boundary so validation and activation receive the same deterministic source files. Public documentation now teaches that boundary as the only configuration format. * test(hub): assert validation diagnostics directly * refactor(hub): deepen HTTP client module * feat(hub): validate named agent configurations * docs(hub): align Claude mode example
This commit is contained in:
Mohamed Boudra
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Hub quickstart
|
||||
description: Sign in, connect GitHub, register a daemon, and get an agent starting from a mention.
|
||||
description: Connect Hub, create a project, and run a workflow from a GitHub comment.
|
||||
nav: Quickstart
|
||||
order: 61
|
||||
category: Hub
|
||||
@@ -8,105 +8,96 @@ category: Hub
|
||||
|
||||
# Hub quickstart
|
||||
|
||||
From an empty Hub to an agent that starts when someone mentions it.
|
||||
## 1. Connect GitHub and a daemon
|
||||
|
||||
## 1. Sign in
|
||||
|
||||
Open your Hub and sign in. Your connections, daemons, and projects all live inside one organization. [Hosted](/docs/hub/hosted) and [self-hosting](/docs/hub/self-hosting) cover how you get that first account.
|
||||
|
||||
## 2. Connect GitHub
|
||||
|
||||
Open **Connections** and connect GitHub. Choose the account or organization whose repositories you want to use.
|
||||
|
||||
The connection appears with a generated slug like `yourname-github`.
|
||||
|
||||
## 3. Register a daemon
|
||||
|
||||
On the machine that will run agents:
|
||||
Open **Connections** in Hub and connect the GitHub account or organization whose repositories you use. On the machine that will run agents:
|
||||
|
||||
```sh
|
||||
paseo hub login https://your-hub.example.com
|
||||
paseo hub connect
|
||||
```
|
||||
|
||||
Approve the CLI login in the browser. `connect` selects that active login's origin and enrolls the daemon using the stored organization credential. The CLI login and daemon relationship remain separate identities. See [Daemons](/docs/hub/daemons).
|
||||
Approve the browser login. See [Daemons](/docs/hub/daemons) for the separation between your CLI login and the daemon relationship.
|
||||
|
||||
## 4. Create a project
|
||||
## 2. Create a project
|
||||
|
||||
Open **Projects → New project**. On its **Configuration** tab, pick a repository and choose **Use for configuration**. Hub now reads `.paseo/hub.yml` from that repository's default branch.
|
||||
Open **Projects → New project**. In **Configuration**, choose the repository that will hold the configuration and select **Use for configuration**.
|
||||
|
||||
## 5. Commit the configuration
|
||||
## 3. Add the bundle
|
||||
|
||||
Add `.paseo/hub.yml` to that repository:
|
||||
Create these files:
|
||||
|
||||
```text
|
||||
.paseo/
|
||||
├── hub.yml
|
||||
└── workflows/
|
||||
└── github-help.yml
|
||||
```
|
||||
|
||||
`.paseo/hub.yml` names project-wide resources:
|
||||
|
||||
```yaml
|
||||
project: your-project
|
||||
|
||||
environments:
|
||||
- name: dev
|
||||
dev:
|
||||
kind: daemon
|
||||
daemon: my-daemon
|
||||
cwd: /Users/you/code/your-repo
|
||||
|
||||
triggers:
|
||||
- name: mention
|
||||
on: github.issue_comment
|
||||
max_runtime: 2h
|
||||
filters:
|
||||
repo: yourname/your-repo
|
||||
contains: "@paseo"
|
||||
from_users: [your-github-login]
|
||||
steps:
|
||||
- id: work
|
||||
environment: dev
|
||||
max_runtime: 90m
|
||||
idle_timeout: 10m
|
||||
agent:
|
||||
provider: codex
|
||||
mode: full-access
|
||||
prompt:
|
||||
- text: |
|
||||
Someone asked for help.
|
||||
|
||||
Call hub.finish_execution when the step is complete.
|
||||
- text: |
|
||||
<user-prompt>
|
||||
${{ paseo.prompt }}
|
||||
</user-prompt>
|
||||
agents:
|
||||
codex:
|
||||
provider: codex
|
||||
mode: full-access
|
||||
```
|
||||
|
||||
`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.
|
||||
`.paseo/workflows/github-help.yml` contains one trigger and its ordered steps:
|
||||
|
||||
The prompt names the Hub tool the agent should call, and keeps the triggering message in its own `<user-prompt>` block. This step grants no reply capability, so it only finishes. [Tell the agent which tool to call](/docs/hub/workflows#tell-the-agent-which-tool-to-call) covers replying to a person.
|
||||
```yaml
|
||||
name: github-help
|
||||
on: github.issue_comment
|
||||
max_runtime: 2h
|
||||
filters:
|
||||
repo: yourname/your-repo
|
||||
contains: "@paseo"
|
||||
from_users: [your-github-login]
|
||||
steps:
|
||||
- id: work
|
||||
environment: dev
|
||||
max_runtime: 90m
|
||||
idle_timeout: 10m
|
||||
agent: codex
|
||||
prompt:
|
||||
- text: |
|
||||
Complete this request and call hub.finish_execution when done.
|
||||
|
||||
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.
|
||||
<user-prompt>
|
||||
${{ paseo.prompt }}
|
||||
</user-prompt>
|
||||
```
|
||||
|
||||
## 6. Push
|
||||
`daemon` is the daemon slug shown by Hub. `cwd` is a directory on that machine. `${{ paseo.prompt }}` is the normalized request text after the provider marker and declared input headers are removed.
|
||||
|
||||
Push to the default branch. Hub fetches the file at that commit, validates it, and activates it. The **Configuration** tab shows the active revision and the last sync.
|
||||
Workflow files are discovered as direct `.yml` children of `.paseo/workflows/`. You do not list them in `hub.yml`.
|
||||
|
||||
If the file is invalid, Hub records the failure and keeps the previous revision active.
|
||||
## 4. Validate and deploy
|
||||
|
||||
To inspect the authenticated organization's projects and deploy the file directly, run:
|
||||
Push the files to the configuration repository's default branch. Hub fetches the complete bundle at that commit, validates it, and activates a revision. A failed sync leaves the previous revision active.
|
||||
|
||||
You can validate or deploy the same local bundle from its project root:
|
||||
|
||||
```sh
|
||||
paseo hub projects
|
||||
paseo hub deploy --dry-run
|
||||
paseo hub deploy
|
||||
paseo hub deploy -p your-project --dry-run
|
||||
paseo hub deploy -p your-project
|
||||
```
|
||||
|
||||
`--dry-run` sends the same YAML, project, and partial bundle to Hub's validator without recording or activating a revision. Deploy reads `.paseo/hub.yml` in the current directory; pass a path for another file, or `-p, --project <slug>` to override the file's project metadata. Origin and credential precedence are in [Configuration](/docs/hub/configuration).
|
||||
Dry-run performs the same discovery and server-side validation without recording or activating a revision. See [Configuration](/docs/hub/configuration) for credentials, diagnostics, and GitHub sync.
|
||||
|
||||
## 7. Trigger it
|
||||
## 5. Trigger it
|
||||
|
||||
Comment on an issue in that repository, from the account you listed in `from_users`:
|
||||
Comment from the account in `from_users`:
|
||||
|
||||
```text
|
||||
@paseo have a look at this
|
||||
```
|
||||
|
||||
Open the project's **Activity** tab. You should see the event received and routed, and an execution in **Executions**. The agent itself appears in the Paseo app on that machine.
|
||||
Open the project's **Activity** tab to see routing and execution. If nothing runs, use the [Activity checklist](/docs/hub/activity).
|
||||
|
||||
If nothing happened, [Activity](/docs/hub/activity) has the checklist.
|
||||
|
||||
Before enabling the example for broader use, read [Hub security](/docs/hub/security) for trigger allowlists, host boundaries, provider-native controls, and output authority.
|
||||
Before widening the allowlist or granting write authority, read [Hub security](/docs/hub/security).
|
||||
|
||||
Reference in New Issue
Block a user