Integrations and repositories

Source-built applications (kind: Application) need three things on a fresh installation before the first deploy:

The GitHub integration configured on the installation — once by the operator. Two modes are supported: a GitHub App (recommended) or a Personal Access Token.
Your own user connection to GitHub — once per Flui user. In App mode you install the App on your account/org; in PAT mode you paste your own classic PAT.
The specific repository imported into your Flui account.

The CLI covers all of it under the integration and repo topics. The dashboard exposes the same flows under Apps → Repositories → GitHub setup. CatalogApps (kind: CatalogApp) skip every step — they pull a pre-built image from a public registry, with no source repo on the install side.

Choosing a mode

	GitHub App	Personal Access Token
Identity used to talk to GitHub	Bot identity owned by the App	Your own user
Per-user setup	Install the App on your account / org	Paste a classic PAT
Webhooks for deploy-on-push	Yes, registered with the App	Yes, the PAT grants `admin:repo_hook`
Org policies that block PATs	Unaffected	May block the PAT entirely
Container registry (GHCR)	Needs a separate per-user PAT (see GHCR PAT)	The same PAT covers cloning and pulling images
Recommended for	Teams, multi-user installations	Single-user / self-hosted dev

GitHub App is the recommended path. The PAT mode is an escape hatch for solo deployments and environments where creating a GitHub App is impractical.

Setup (operator, once per installation)

`flui integration setup github`

Interactive setup that walks the operator through either mode end to end. Admin-only.

flui integration setup github
flui integration setup github --headless     # print URLs instead of opening a browser

If the integration is already configured the command asks before overwriting — use flui integration reset github first if you want a clean slate.

GitHub App branch (recommended)

The command builds a GitHub App manifest, opens GitHub with the App name and all the permissions pre-filled, and waits for you to confirm. As soon as you click Create, GitHub redirects back to the API, which exchanges the temporary code for the final App credentials and stores them automatically.

You will be asked for:

Field	Notes
App name	Must be unique across GitHub. Defaults to `flui-<hostname>`.
Flui public URL	Base URL of this Flui API as reachable from `github.com`. Callback, manifest redirect and (if enabled) webhook URL are all derived from this. For local development behind a tunnel, use the tunnel URL.
Enable webhooks for deploy-on-push?	Off by default. Turn on if you want a push to trigger a deploy.
Allow install on other accounts / organizations?	Off by default (only the owner account can install). Turn on if Flui needs repos under multiple accounts or orgs.

After confirmation the credentials (App ID, slug, Client ID, Client Secret, Webhook Secret, private-key PEM) are persisted in Flui — no copy-paste required.

Personal Access Token branch

The command opens GitHub’s token-creation page pre-filled with the required scopes, then validates the token against GitHub before saving it. The validator surfaces missing scopes inline so you know exactly what to re-check.

Scopes requested:

repo — clone and push private repositories
workflow — commit .github/workflows/flui.yml on first deploy
user:email — identify the user
admin:repo_hook — register webhooks for deploy-on-push
write:packages, read:packages, delete:packages — push, pull, and clean up images on GHCR

The same token covers both the repository side and the GHCR side — there is no separate GHCR step in PAT mode.

Classic PATs only — fine-grained PATs cannot grant admin:repo_hook yet, which Flui needs to register webhooks.

Equivalent dashboard flow

Open Apps → Repositories → GitHub setup in the dashboard for the same two-card picker (App via manifest, or PAT). The dashboard polls the API in the same way and the resulting configuration is identical. A “I already have a GitHub App” disclosure under the App card lets you plug in pre-existing App credentials instead of running the manifest flow.

User connection

`flui integration connect github`

In App mode, opens the browser to install the Flui GitHub App on your account or org and waits for the local callback. The same round-trip also performs the OAuth grant your user needs to commit .github/workflows/flui.yml on first deploy.

flui integration connect github
flui integration connect github --headless     # print URL instead of opening a browser

If the integration is not configured yet, the command exits with a friendly hint pointing at flui integration setup github instead of the raw API error.

In PAT mode this command currently targets the App install endpoint and therefore reports the integration as not configured. The operator’s own PAT is saved at setup time; additional users in PAT mode connect their token from the dashboard wizard (Apps → Repositories → GitHub setup → PAT card).

Flag	Effect
`--headless`	Print the install URL instead of opening one. Useful over SSH.

The callback uses the same port range as flui auth login (8899, falling back through 8900–8910).

`flui integration list`

Lists the third-party integrations configured for your account and whether each is currently connected. Includes the GHCR PAT state in App mode.

flui integration list

Only github is supported today; the topic is shaped to accept more providers later.

Status and health

`flui integration status github`

Shows the active mode (App or PAT), runs a live health check against GitHub, and prints your own user connection state.

flui integration status github

Sample output (App mode):

  Instance configuration
    Mode:          github_app
    App slug:      flui-acme
    Health:        ✔ App auth ok — 2 installations

Sample output (PAT mode):

  Instance configuration
    Mode:          pat
    Health:        ✔ PAT mode enabled (per-user credentials)

  Your connection
    Authenticated: @dawit-io
    Scopes:        repo user:email admin:repo_hook write:packages …

When the health check fails (App deleted on GitHub, credentials revoked, network unreachable…) the output flags it and the dashboard shows a banner with the same information.

Reset

`flui integration reset github`

Removes the instance-wide GitHub configuration plus every per-user token and App installation Flui has on file. Useful when switching modes (App ↔ PAT) or starting over after a bad registration. Admin-only.

flui integration reset github             # type "reset" to confirm
flui integration reset github --yes       # skip the confirmation (CI / scripts)

The App on github.com is not uninstalled — uninstall it there separately if you want to clean up the GitHub side too.

After reset, run flui integration setup github to configure a fresh integration. Users will need to reconnect.

GHCR PAT (App mode only)

In App mode, the App’s bot token cannot pull container packages from ghcr.io (see community discussion #34084), so each user stores a small classic PAT scoped only for packages. In PAT mode this step is skipped — the main PAT already grants the package scopes.

`flui integration ghcr-pat set`

Saves (or replaces) the GHCR PAT for your user.

flui integration ghcr-pat set
flui integration ghcr-pat set --headless     # print the token-creation URL

The command opens GitHub’s token-creation page pre-filled with read:packages and delete:packages. Paste the token at the masked prompt and pick an expiry — Flui warns 14 days before it expires.

`flui integration ghcr-pat status`

Shows the stored token’s login, scopes, days until expiry, and the last health-check timestamp. Status values: VALID, EXPIRING_SOON, EXPIRED, INVALID, MISSING.

flui integration ghcr-pat status

`flui integration ghcr-pat revoke`

Deletes the stored PAT from Flui (does not revoke it on GitHub — do that at https://github.com/settings/tokens). After revoking, flui deploy refuses to run until a new PAT is set.

flui integration ghcr-pat revoke
flui integration ghcr-pat revoke --yes

Admin diagnostics

`flui integration installations`

Lists every GitHub App installation tracked by Flui — handy when diagnosing a stale or duplicated record. Shows the numeric installationId needed by remove-installation.

flui integration installations

`flui integration remove-installation <installationId>`

Removes an installation record from the Flui database. This does not uninstall the App on GitHub — uninstall it there first, otherwise the next webhook will re-create the record.

flui integration remove-installation 12345678
flui integration remove-installation 12345678 --yes

Flag	Effect
`-y, --yes`	Skip the confirmation prompt.

Get the ID from flui integration installations.

Repositories

`flui repo connect [<owner/repo>]`

Imports a repository into your Flui account so it can be deployed with flui deploy. Pass the full owner/repo slug, or omit it for an interactive picker over the repositories accessible through the connected integration.

flui repo connect acme/my-app
flui repo connect                              # interactive picker

The repo must be visible to whichever side is connected: the GitHub App installation in App mode, or the PAT’s permissions in PAT mode. If the picker doesn’t show it, re-run flui integration connect github (App mode — add the repo on the GitHub install page) or re-issue the PAT with broader access (PAT mode). flui deploy on an un-imported repo fails up front with Repository "<owner>/<repo>" is not connected to your account — that is the signal to run this command.

`flui repo list`

Lists the repositories already connected to your Flui account.

flui repo list
flui repo list --output json

Flag	Default	Effect
`-o, --output text\|json`	`text`	Output format.

`flui repo disconnect <owner/repo>`

Removes the repository from your Flui account. Requires admin privileges and asks to confirm; pass -y, --yes to skip the prompt. The repository on GitHub itself is untouched.

flui repo disconnect acme/my-app
flui repo disconnect acme/my-app --yes

A disconnected repo can no longer be deployed until it is connected again with flui repo connect.

First-deploy flow, end to end

For an Application repo on a fresh installation, by the operator:

flui auth login                              # OIDC against the installation
flui integration setup github                # one-time: configure App or PAT

Then by every user (in App mode):

flui auth login                              # OIDC, once per machine
flui integration connect github              # install the Flui App on your account
flui integration ghcr-pat set                # required for the cluster to pull built images
flui repo connect dawit-io/my-app            # import the repo
flui deploy                                  # build via GitHub Actions, roll out

In PAT mode the user steps collapse — the same PAT covers cloning and GHCR pulls, and for a single-user install the operator is also the user:

flui auth login
flui repo connect dawit-io/my-app
flui deploy

After the first deploy of a given repo, only flui deploy is needed for subsequent rollouts. Rotate the GHCR PAT before its expiry with another flui integration ghcr-pat set (App mode), or re-run flui integration setup github to refresh the instance PAT (PAT mode).