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

Prepare Hub guided self-hosting docs for the next release (#3342)

Browse Source 
* docs(hub): drop the manual auth secret from self-hosting setup

Hub generates its authentication secret on first start and stores it in the
database it is already using, so self-hosters no longer run openssl or carry
PASEO_HUB_AUTH_SECRET between restarts. The variable stays as an override for
deployments that must supply the secret from a platform secret store; Hub uses
it without persisting it, so removing it resumes the stored value.

Also corrects a claim that predates this change: rotating the secret does not
invalidate execution credentials already issued. Hub verifies those against
persisted hashes rather than the secret, so only browser sessions end.

Documentation companion to https://github.com/getpaseo/hub/pull/50.

* docs(hub): lead with the local guided setup

* docs(hub): document XDG data directory

* docs: make Hub self-hosting the quickstart
This commit is contained in:
Mohamed Boudra
2026-08-20 14:16:01 +02:00
committed by GitHub
parent c6b04f302a
commit 9163aed3f1
9 changed files with 290 additions and 315 deletions
Download Patch File Download Diff File Expand all files Collapse all files
public-docs/hub/self-hosting/github-app.md
+35 -54
View File
@@ -1,6 +1,6 @@
---
title: GitHub for Hub
description: Create the GitHub App your Hub uses, install it, and connect it to an organization.
description: Create the GitHub App your Hub uses for repository access and event triggers.
nav: GitHub App
order: 75
category: Hub
@@ -8,75 +8,56 @@ 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.
Hub talks to GitHub through a GitHub App you create and own. One App serves the Hub; each account or organization that installs it becomes a connection.
## Create the App
Open **Apps → GitHub**. Hub gives you the current callback URLs, required repository permissions, subscribed events, and the fields to copy back from GitHub. It verifies the App before saving it.
Go to **Settings → Developer settings → GitHub Apps → New GitHub App** on the account that should own it.
## Public URL requirements
Replace `hub.example.com` with your `PASEO_HUB_APP_URL`.
Repository access and installation work without a GitHub webhook. GitHub event triggers and configuration sync do not: GitHub must be able to deliver events to a public HTTPS URL.
The webhook URL must be reachable from GitHub. Keep GitHub's default SSL verification enabled; see [Provider URLs](/docs/hub/self-hosting#provider-urls).
On a local HTTP Hub, the Apps guide lets you configure repository access and explains that event setup is unavailable. Reopen Hub at its public address after setting `PASEO_HUB_APP_URL` to add the webhook secret and events.
| 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 |
GitHub uses these Hub URLs:
Repository permissions:
| Setting | Hub URL |
| ------------ | ------------------------------------------------------ |
| Homepage URL | `<PASEO_HUB_APP_URL>` |
| Callback URL | `<PASEO_HUB_APP_URL>/api/integrations/github/callback` |
| Setup URL | `<PASEO_HUB_APP_URL>/api/integrations/github/setup` |
| Webhook URL | `<PASEO_HUB_APP_URL>/webhook` |
| Permission | Access | Why |
| ------------- | ------------ | ----------------------------------------- |
| Contents | Read & write | Read the `.paseo` bundle, 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 |
Keep GitHub's SSL verification enabled.
Subscribe to events:
## Connect repositories
- Issue comment
- Issues
- Pull request review
- Pull request review comment
- Push
After Hub verifies the App, choose **Install on GitHub**. Select the account or organization and repositories the App may access.
Push is what makes configuration sync work. Without it, Hub never learns that the `.paseo` bundle changed.
Start from Hub rather than GitHub's own install button. The round trip binds the installation to the active Hub organization.
## Configure Hub
The connection appears with a slug derived from the account. An installation on `getpaseo`, for example, becomes `getpaseo-github`. Connect as many installations as the Hub organization needs.
From the App's settings page, collect:
## What the connection provides
| 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` |
- **Events:** issues, comments, reviews, and pushes from repositories the installation can see. See [GitHub triggers](/docs/hub/triggers/github).
- **Configuration sync:** a repository can hold the canonical `.paseo` bundle. See [Configuration](/docs/hub/configuration).
- **Execution credentials:** Hub mints scoped GitHub App tokens for workflow steps that explicitly request GitHub authority.
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`.
An authenticated `gh` CLI on the daemon does not configure Hub's GitHub integration. It can still serve agents outside Hub's scoped GitHub authority, subject to the daemon and provider's own environment and permission policy.
Restart Hub. GitHub should now show as **Ready** in Connections.
## Configure from environment
## Connect
Deployments that keep app secrets outside Hub can set:
Open **Connections → GitHub → Connect**. Hub sends you to GitHub to install the App, then binds the installation to your organization.
```dotenv
GITHUB_APP_ID=
GITHUB_APP_SLUG=
GITHUB_APP_CLIENT_ID=
GITHUB_APP_CLIENT_SECRET=
GITHUB_APP_PRIVATE_KEY=
GITHUB_WEBHOOK_SECRET=
```
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 private key is the contents of GitHub's downloaded PEM file. Use `GITHUB_APP_PRIVATE_KEY_PATH` instead when the deployment mounts that file.
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 the canonical `.paseo` bundle. 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.
Environment configuration takes precedence over a saved GitHub App and appears as **Managed by environment** under **Apps**. A complete environment configuration includes the webhook secret and therefore expects a public webhook origin.