Integrations and repositories

Source-built applications (kind: Application) need four one-off connections on the installation before the first deploy:

The Flui GitHub App registered on GitHub and configured in Flui itself — once per installation, by the operator.
The same App installed on the GitHub account or organisation that owns the repositories — once per user/org, by every Flui user.
The specific repository imported into your Flui account.
A GHCR PAT stored in Flui — once per user, used to pull container images from ghcr.io (GitHub App and OAuth tokens cannot read container packages — see community discussion #34084).

The CLI covers all four under the integration and repo topics. CatalogApps (kind: CatalogApp) skip every step — they pull a pre-built image from a public registry, with no source repo on the install side.

Creating the Flui GitHub App

This is the one-time setup done by the operator who runs the installation — not by every user. Skip ahead to Install the App on your account if the App is already created and registered in Flui.

1. Register the App on GitHub

Open https://github.com/organizations/<your-org>/settings/apps/new if the App will be owned by an organisation (recommended for managed deployments — the app appears to users as the org’s app, and ownership can be transferred between admins). For a self-hosted install only used by a single operator, https://github.com/settings/apps/new on a personal account is fine.

Fill the registration form like this:

Field	Value
GitHub App name	Anything human-readable. The slug is derived from this and used in install URLs — pick something stable.
Homepage URL	The dashboard URL of the installation (e.g. `https://app.example.com`).
Callback URL	`https://<api-host>/api/v1/repositories/github-app/user-callback` — see the note on timing below.
Webhook URL	`https://<api-host>/api/v1/repositories/github-app/webhook`.
Webhook secret	Generate a random string (≥32 chars). Keep it — Flui needs the same value during `setup-github-app`.
Identifying and authorizing users	Tick Request user authorization (OAuth) during installation. This is what makes `flui integration connect github` cover the OAuth grant in the same browser round-trip — without it, you would need a separate dashboard step.

Permissions to grant (Repository permissions):

Contents: Read & write
Actions: Read & write
Workflows: Read & write
Metadata: Read
Packages: Read & write
Pull requests: Read & write

Subscribe to events:

Installation
Installation repositories
Workflow run
Push

Set “Where can this GitHub App be installed?” to Only on this account for now. You will flip it later once the App is verified working end to end.

Click Create GitHub App. On the next page:

Note the App ID (top of the page).
Note the Client ID (same section).
Click Generate a new client secret under Client secrets. Copy it now — it is only shown once.
Click Generate a private key under Private keys. A .pem file downloads — keep it for setup-github-app.

A note on the Callback URL

The Callback URL on the App must match — character for character — the URL Flui will pass as redirect_uri in the OAuth flow. That URL comes from setup-github-app and lives on whatever domain the API is served at.

If you do not yet have the final API hostname (you are still on a *.nip.io or staging domain), it is fine to set a temporary Callback URL now, get the rest of the flow working, then update both the App registration on GitHub and the Flui-side setup-github-app configuration once the final hostname is in place. The same applies to the Webhook URL. Keeping the two ends in sync is the only requirement; the value itself can change as often as the hostname does.

2. Register the App in Flui

The credentials gathered above (App ID, slug, Client ID, Client Secret, Webhook Secret, private key PEM, callback URL) get stored in Flui through flui integration setup-github-app — see the Admin-only commands section below.

3. Open the App to users

Once setup-github-app is done and a first test install on the operator account works, flip the App’s “Where can this GitHub App be installed?” setting from Only on this account to Any account. The button is under Advanced → Danger zone → Make public (see Modifying a GitHub App registration).

After this, https://github.com/apps/<slug>/installations/new will offer the user’s personal account and any org they administer as install targets — which is what flui integration connect github sends users to.

Integrations

`flui integration connect github`

Opens the browser to the Flui GitHub App install flow and waits for the local callback to confirm the connection. On the GitHub side you pick which account/org to install on and which repositories to expose to Flui. The same browser round-trip also performs the OAuth grant your Flui account needs to commit the .github/workflows/flui.yml workflow on first deploy — provided the App has Request user authorization (OAuth) during installation enabled (see Creating the Flui GitHub App).

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

Flag	Effect
`--headless`	Print the install URL instead of opening one. Useful over SSH — pair with `ssh -L 8899:localhost:8899 server` so the callback can reach the listener.

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 state of the GHCR PAT alongside the GitHub App install.

flui integration list

Only github is supported today; the topic is shaped to accept more providers later without changing the verb set.

`flui integration ghcr-pat set`

Saves (or replaces) the classic GitHub PAT Flui uses to pull container images from GHCR. Required for flui deploy to work — without it the cluster fails the image pull with ImagePullBackOff even when the build succeeded.

flui integration ghcr-pat set
flui integration ghcr-pat set --headless    # print the token-creation URL instead of opening a browser

The command opens GitHub’s token-creation page pre-filled with the expected scopes (read:packages plus delete:packages for image cleanup) and a description (Flui GHCR pull). After generating the token, paste it at the masked prompt and pick an expiry. Fine-grained PATs (github_pat_…) are also accepted as long as they grant Packages: read on the relevant org or account.

Flag	Effect
`--headless`	Print the GitHub token-creation URL instead of opening a browser.

`flui integration ghcr-pat status`

Shows the current state of the stored GHCR PAT: GitHub login it belongs to, granted scopes, days until expiry, and verification timestamps. Status values reflect a server-side health check — VALID, EXPIRING_SOON, EXPIRED, INVALID, or MISSING.

flui integration ghcr-pat status

`flui integration ghcr-pat revoke`

Deletes the stored PAT from Flui. Asks to confirm; pass -y, --yes to skip. It does not revoke the token on GitHub — do that separately at https://github.com/settings/tokens. After revoking, flui deploy will refuse to run until a new PAT is set.

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

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 the Flui GitHub App installation. If the picker doesn’t show it, re-run flui integration connect github and add the repo on the GitHub side during the install. 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.

Admin-only commands

The next three verbs are reserved for the operator who runs the installation — they manage the GitHub App on the Flui side (the credentials Flui uses to talk to GitHub, and the installation records it tracks). They are not part of the daily user flow.

`flui integration setup-github-app`

Configures the GitHub App credentials in Flui itself: App ID, slug, Client ID, Client Secret, Webhook Secret, callback URL and the path to the private-key PEM. The command is interactive; secrets are hidden during input and encrypted at rest in the database. Run it once per installation, right after registering the App on GitHub.

flui integration setup-github-app
flui integration setup-github-app --private-key-file ./flui-cloud.pem
flui integration setup-github-app --callback-url https://api.example.com/api/v1/repositories/github-app/user-callback

Flag	Effect
`--private-key-file <path>`	Path to the PEM private key, skips the path prompt.
`--callback-url <url>`	OAuth callback URL configured on the GitHub App. Defaults to `<api-url>/repositories/github-app/user-callback`.

If a configuration already exists the command asks before overwriting. This is the same channel used to rotate any of the credentials later.

`flui integration installations`

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

flui integration installations

`flui integration remove-installation <installationId>`

Removes a GitHub App 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.

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-app            # one-time: register the App's
                                             # credentials in Flui

Then by every user of the installation:

flui auth login                              # OIDC, once per machine
flui integration connect github              # install the Flui GitHub App
                                             # (and grant OAuth in the same flow)
flui integration ghcr-pat set                # save a GHCR PAT — 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

After the first deploy of a given repo, only flui deploy is needed for subsequent rollouts — the integration, the OAuth grant, the GHCR PAT, and the repo connection are already in place. Rotate the PAT before its expiry with another flui integration ghcr-pat set.