Mohamed BoudraandGitHub
64058722e1
* 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.
4.6 KiB
title, description, nav, order, category
| title | description | nav | order | category |
|---|---|---|---|---|
| Hub configuration | Where a project's configuration comes from, how GitHub sync works, and how revisions activate and roll back. | Configuration | 68 | Hub |
Hub configuration
A project is configured by one versioned document. The project's Configuration tab shows the active revision, its source, and the last synchronization attempt.
Sources
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:
project: my-project
Then deploy:
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:
- Hub fetches
.paseo/hub.ymlat that exact commit. - It validates the document and resolves every repository, workspace, guild, and daemon it names.
- On success the revision becomes active.
Sync now does the same on demand.
Every attempt is recorded, including failures. The outcomes you will see:
| Outcome | What happened |
|---|---|
| Activated | Valid document, everything resolved, now serving events. |
| Invalid | The document failed validation or named something the organization can't reach. |
| Fetch failed | The file is missing, or GitHub could not be read. |
| Superseded push ignored | A newer commit already moved the branch head. |
A failed sync never replaces the active revision. A repository with a broken hub.yml keeps serving the last good one.
Revisions
Revisions are immutable and numbered per project. Rolling back selects an earlier revision and recompiles its routes. The next valid push activates again, so rollback holds only until the next push.
Switching source
Switching from GitHub to manual copies the active revision into the editor and stops syncing. Switching back means choosing a repository again.
While a project uses a GitHub source, the dashboard editor is read-only. The repository is the source of truth.
The configuration repository does not have to be the repository you watch
filters.repo can name any repository the organization has a connection for. Keeping hub.yml in a private repository while triggers watch several public ones is a common setup, because push access to the configuration repository grants access to the organization's connections.
Next: Hub workflows, then the hub.yml reference.