jb/paseo
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Document Hub and let docs pages nest (#2864)

Browse Source 
* feat(website): nest docs pages under landable groups

The docs sidebar could already render groups from subdirectories in
public-docs, but nothing used it because every doc was a flat file, and
two things stopped it being usable.

A group had no page of its own, so its label was only a toggle and its
name came from the directory name via formatLabel. A directory's
index.md now supplies the group's label, order, and href, which makes
the group landable and lets the label be authored rather than derived.

Categories and top-level directories named the same thing, so a
categorised doc at hub/index.md produced a group nested inside its own
category. Only directories below the top level become groups now.

Also fixes two behaviours in the sidebar:

- The open/closed effect assigned containsActive on every change, so a
  group you expanded to browse collapsed the moment you navigated
  anywhere else. Navigating in now opens a group and navigating away
  leaves it alone.
- The sidebar scrolls independently of the page and never scrolled the
  active entry into view, so loading or refreshing a page far down the
  list left the sidebar parked at the top with no visible position.

The group row is a single target: it navigates and expands, and
collapses when clicked again from the page it points at. A separate
chevron button would put two actions a few pixels apart.

* docs(hub): document Hub

Adds a Hub section covering what it is, how it works, daemons,
triggers, configuration, activity, and the two ways to run it.

The section separates using Hub from running it. Overview, quickstart,
daemons, triggers, and configuration hold regardless of who operates
the deployment; the self-hosting branch owns deploying the service and
creating the GitHub, Slack, and Discord apps it talks to. That split
falls on a real seam, because those apps are exactly what a hosted Hub
would own on your behalf. Hosted is a placeholder until it ships.

Each provider gets a trigger page carrying its events, filter
semantics, and the full paseo.event.* reference for the data a prompt
can read. That data is the thing a config author actually needs and
the thing they cannot get from anywhere else.

Every YAML block was parsed against the Hub config schema rather than
eyeballed, which kept several plausible-looking things out of the
docs: worktree prNumber takes a literal number and not a merge
variable, only daemon environments run today, and github.push has no
actor so it can never satisfy the required from_users filter.

Troubleshooting moves to order 90 so it stays last.

* refactor(website): let the active docs entry scroll itself into view

The layout queried the sidebar for the active entry after every
navigation, which coupled it to when that entry mounts. A link inside a
collapsed group only mounts once the group's own effect opens it, so
the query could run against a DOM that does not contain it yet.

Moving the scroll to the entry removes the ordering question rather
than answering it, and drops the ref and the cross-component query.

Reported by Greptile on #2864. The failure it described does not
reproduce: navigating from a page outside a collapsed group into one of
its children still scrolls correctly, verified with the group confirmed
collapsed and the sidebar forced to the top. The coupling was real even
though the bug was not.

* docs(hub): stop listing BETTER_AUTH_URL as required

It falls back to PASEO_CLOUD_PUBLIC_URL, so a deployment that sets the
public origin already has a correct auth base URL. Listing it as
required made the Fly recipe look incomplete when it was not.

Moved to optional with its default, and recorded what actually breaks
without BETTER_AUTH_SECRET: the auth routes close and nobody can sign
in.

Reported by Codex on #2864, which read the same inconsistency the other
way round and proposed adding the variable to the Fly example.

* docs(hub): attach a database in the Fly recipe

The Fly section showed inline config and a secrets command, neither of
which supplied DATABASE_URL. It defaults to localhost:5432, which on
Fly reaches nothing, so the documented deployment could not start.

fly postgres attach sets DATABASE_URL as a secret, so the step is the
attach itself rather than another variable to copy.

Reported by Codex on #2864.

* docs: align Hub self-hosting contract
This commit is contained in:
Mohamed Boudra
2026-08-05 03:58:27 +08:00
committed by GitHub
parent d7f72d2805
commit dfd18a44a7
26 changed files with 1670 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
public-docs/hub/self-hosting/discord-app.md
+49
View File
@@ -0,0 +1,49 @@
---
title: Discord for Hub
description: Create the Discord application your Hub uses, connect a guild, and write Discord triggers.
nav: Discord app
order: 76
category: Hub
---
# Discord for Hub
Hub connects to Discord over the gateway with a bot you own. Unlike GitHub and Slack, Discord does not post to your Hub. Hub holds an outbound connection, so it needs no public webhook beyond the OAuth callback.
## Create the application
Go to the [Discord developer portal](https://discord.com/developers/applications) → **New Application**.
Under **Bot**:
- Add a bot and copy its token.
- Enable **Message Content Intent**. Without it the bot receives empty messages and no trigger can match.
- Server Members Intent is not needed.
Under **OAuth2**, add the redirect URL:
```text
https://hub.example.com/api/integrations/discord/callback
```
Replace `hub.example.com` with your `PASEO_HUB_APP_URL`.
## Configure Hub
| Value | Environment variable |
| -------------- | ----------------------- |
| Application ID | `DISCORD_CLIENT_ID` |
| Client Secret | `DISCORD_CLIENT_SECRET` |
| Bot token | `DISCORD_BOT_TOKEN` |
Restart Hub. Discord shows as **Ready** in Connections.
## Connect
Open **Connections → Discord → Connect**, choose the server, and authorize. Hub builds the invite with the permissions the bot needs, so you do not construct an invite URL yourself.
The connection appears with a slug derived from the guild name.
Because Hub holds one gateway connection for the whole deployment, one bot serves every organization and guild you connect.
Now write a trigger: [Discord triggers](/docs/hub/triggers/discord).
public-docs/hub/self-hosting/github-app.md
+80
View File
@@ -0,0 +1,80 @@
---
title: GitHub for Hub
description: Create the GitHub App your Hub uses, install it, and connect it to an organization.
nav: GitHub App
order: 74
category: Hub
---
# GitHub for Hub
Hub talks to GitHub through a GitHub App you own. One App serves your whole Hub; each account or organization that installs it becomes a connection.
## Create the App
Go to **Settings → Developer settings → GitHub Apps → New GitHub App** on the account that should own it.
Replace `hub.example.com` with your `PASEO_HUB_APP_URL`.
| Setting | Value |
| ------------------ | ---------------------------------------------------------- |
| Homepage URL | `https://hub.example.com` |
| Callback URL | `https://hub.example.com/api/integrations/github/callback` |
| Setup URL | `https://hub.example.com/api/integrations/github/setup` |
| Redirect on update | on |
| Webhook URL | `https://hub.example.com/webhook` |
| Webhook secret | a value you generate |
Repository permissions:
| Permission | Access | Why |
| ------------- | ------------ | ----------------------------------------- |
| Contents | Read & write | Read `.paseo/hub.yml`, let agents push |
| Issues | Read & write | Read comments, add reactions |
| Pull requests | Read & write | Read review comments, let agents open PRs |
| Metadata | Read | Required by GitHub |
Subscribe to events:
- Issue comment
- Issues
- Pull request review
- Pull request review comment
- Push
Push is what makes configuration sync work. Without it, Hub never learns that `.paseo/hub.yml` changed.
## Configure Hub
From the App's settings page, collect:
| Value | Environment variable |
| ------------------------- | -------------------------- |
| App ID | `GITHUB_APP_ID` |
| The slug in the App's URL | `GITHUB_APP_SLUG` |
| Client ID | `GITHUB_APP_CLIENT_ID` |
| A generated client secret | `GITHUB_APP_CLIENT_SECRET` |
| A generated private key | `GITHUB_APP_PRIVATE_KEY` |
| The webhook secret | `GITHUB_WEBHOOK_SECRET` |
The private key downloads as a PEM file. Pass its contents in `GITHUB_APP_PRIVATE_KEY`, or its path in `GITHUB_APP_PRIVATE_KEY_PATH`.
Restart Hub. GitHub should now show as **Ready** in Connections.
## Connect
Open **Connections → GitHub → Connect**. Hub sends you to GitHub to install the App, then binds the installation to your organization.
Start from Hub, not from GitHub's own install button. GitHub only calls the setup URL when an installation is created or changed, so installing directly can leave you on a settings page with nothing bound.
The connection appears with a slug derived from the account: an installation on `getpaseo` becomes `getpaseo-github`. That slug is how configuration names this connection.
Connect as many installations as you need. A personal account and several organizations can coexist in one Hub organization.
## What the connection gives you
- **Events.** Comments, issues, and reviews from every repository the installation can see. See [GitHub triggers](/docs/hub/triggers/github).
- **Configuration sync.** Any repository in the installation can hold `.paseo/hub.yml`. See [Configuration](/docs/hub/configuration).
- **Tokens.** Scoped, per-execution GitHub credentials.
Which repositories the installation covers is a GitHub setting. Change it on GitHub, not in Paseo.
public-docs/hub/self-hosting/index.md
+127
View File
@@ -0,0 +1,127 @@
---
title: Self-hosting Hub
description: Deploy Paseo Hub with PostgreSQL and a public HTTPS origin, using Docker Compose or Fly.
nav: Self-hosting
order: 73
category: Hub
---
# Self-hosting Hub
Hub is a Node service backed by PostgreSQL. Connecting external providers requires a public HTTPS URL for their callbacks and webhooks.
1. Deploy Hub with [Docker Compose](#docker-compose) or [Fly](#fly).
2. Create the [GitHub App](/docs/hub/self-hosting/github-app), [Slack app](/docs/hub/self-hosting/slack-app), and [Discord app](/docs/hub/self-hosting/discord-app) you want.
3. Follow the [quickstart](/docs/hub/quickstart).
Migrations run automatically at startup. Hub does not start listening when a migration fails.
## Configuration
Hub has one public URL and one persistent application secret:
| Variable | Purpose |
| ----------------------- | ------------------------------------------------------------------ |
| `PASEO_HUB_APP_URL` | Public origin used by the dashboard, authentication, and callbacks |
| `PASEO_HUB_AUTH_SECRET` | Protects browser sessions and derives execution credentials |
| `DATABASE_URL` | PostgreSQL connection string |
Generate `PASEO_HUB_AUTH_SECRET` once and keep it across restarts:
```sh
openssl rand -hex 32
```
Changing it signs everyone out and invalidates completion credentials for executions that are still running.
Bootstrap the first owner with:
```dotenv
PASEO_BOOTSTRAP_ORGANIZATION=My organization
PASEO_BOOTSTRAP_OWNER_EMAIL=me@example.com
PASEO_BOOTSTRAP_OWNER_PASSWORD=replace-with-a-temporary-password
```
The password must be at least 12 characters. Sign in with it once, replace it in the dashboard, then remove `PASEO_BOOTSTRAP_OWNER_PASSWORD` from the deployment. Hub keeps the account and organization.
### Providers
Set the group for each provider you intend to connect. A provider with missing credentials shows as **Setup needed** in Connections.
```sh
# GitHub
GITHUB_APP_SLUG=
GITHUB_APP_ID=
GITHUB_APP_CLIENT_ID=
GITHUB_APP_CLIENT_SECRET=
GITHUB_APP_PRIVATE_KEY= # or GITHUB_APP_PRIVATE_KEY_PATH
GITHUB_WEBHOOK_SECRET=
# Slack
SLACK_APP_ID=
SLACK_CLIENT_ID=
SLACK_CLIENT_SECRET=
SLACK_SIGNING_SECRET=
# Discord
DISCORD_CLIENT_ID=
DISCORD_CLIENT_SECRET=
DISCORD_BOT_TOKEN=
```
See [GitHub](/docs/hub/self-hosting/github-app), [Slack](/docs/hub/self-hosting/slack-app), and [Discord](/docs/hub/self-hosting/discord-app) for where each value comes from.
## Docker Compose
The repository contains Hub and PostgreSQL as one Compose stack:
```sh
git clone https://github.com/getpaseo/hub.git
cd hub
cp .env.example .env
```
Set `PASEO_HUB_APP_URL`, `PASEO_HUB_AUTH_SECRET`, and the three bootstrap values in `.env`, then run:
```sh
docker compose up -d
```
The stack publishes Hub on port `3000` and stores PostgreSQL data in a named volume. The Hub image is `ghcr.io/getpaseo/hub:latest`.
When a reverse proxy terminates HTTPS, set `PASEO_HUB_TRUSTED_CLIENT_IP_HEADER` to the header carrying the original client IP.
## Fly
Clone the repository and create an app and database under names you control:
```sh
git clone https://github.com/getpaseo/hub.git
cd hub
fly apps create your-hub
fly postgres create --name your-hub-db
fly postgres attach your-hub-db -a your-hub
```
Set the application secret and bootstrap account, along with credentials for the providers you use:
```sh
fly secrets set -a your-hub \
PASEO_HUB_AUTH_SECRET="$(openssl rand -hex 32)" \
PASEO_BOOTSTRAP_ORGANIZATION="My organization" \
PASEO_BOOTSTRAP_OWNER_EMAIL=me@example.com \
PASEO_BOOTSTRAP_OWNER_PASSWORD=replace-with-a-temporary-password
```
Deploy the Dockerfile from the repository:
```sh
fly deploy -a your-hub \
-e PASEO_HUB_APP_URL=https://your-hub.fly.dev
```
Keep one machine running. Hub holds the Discord gateway connection and dispatches events to daemons, so a stopped machine misses events.
## Upgrades
Pull the new image or source and deploy it. Migrations are forward-only. Back up PostgreSQL first; it contains configuration revisions, connections, and execution history.
public-docs/hub/self-hosting/slack-app.md
+69
View File
@@ -0,0 +1,69 @@
---
title: Slack for Hub
description: Create the Slack app your Hub uses, connect a workspace, and write Slack triggers.
nav: Slack app
order: 75
category: Hub
---
# Slack for Hub
Hub receives Slack mentions over the Events API. Socket Mode is not used, so your Hub must be reachable from Slack.
## Create the app
Go to [api.slack.com/apps](https://api.slack.com/apps) → **Create New App → From a manifest**, and paste this after replacing `hub.example.com` with your `PASEO_HUB_APP_URL`:
```yaml
display_information:
name: Paseo
features:
bot_user:
display_name: Paseo
always_online: false
oauth_config:
redirect_urls:
- https://hub.example.com/api/integrations/slack/callback
scopes:
bot:
- app_mentions:read
- chat:write
- reactions:write
settings:
event_subscriptions:
request_url: https://hub.example.com/api/integrations/slack/events
bot_events:
- app_mention
interactivity:
is_enabled: false
org_deploy_enabled: false
socket_mode_enabled: false
token_rotation_enabled: false
```
## Configure Hub
From **Basic Information → App Credentials**, copy:
| Value | Environment variable |
| -------------- | ---------------------- |
| App ID | `SLACK_APP_ID` |
| Client ID | `SLACK_CLIENT_ID` |
| Client Secret | `SLACK_CLIENT_SECRET` |
| Signing Secret | `SLACK_SIGNING_SECRET` |
Restart Hub before Slack verifies the request URL. Hub needs the signing secret to answer the verification challenge.
## Connect
Open **Connections → Slack → Connect**, pick the workspace, and allow it.
Use Hub's button, not Slack's **Install to Workspace**. The install has to start from Hub so the workspace binds to your organization.
Then invite the bot to each channel it should watch:
```text
/invite @Paseo
```
Now write a trigger: [Slack triggers](/docs/hub/triggers/slack).