github - floo

Manage GitHub integration for auto-deploy on push. These are subcommands of floo apps github.

connect

Connect a GitHub repo for auto-deploy. The command creates the named app if it does not exist and triggers an initial deploy unless you pass --no-deploy. A human must install the floo GitHub App on the repo’s owning account and authorize floo in a browser. When the App is missing, connect opens a setup link and waits for the human to finish; that link connects the installation to your floo org. Run floo init and floo preflight, then commit and push the generated configuration before connecting. The initial deploy reads the already-pushed branch, so connecting first can deploy incomplete source or configuration.

floo apps github connect owner/repo --app my-app

Flags

Flag	Description	Default
`--app APP`	App name or UUID	inferred from config
`--branch BRANCH`	Branch to deploy from	`main`
`--skip-env-check`	Skip environment variable validation	off
`--no-deploy`	Skip the initial deploy; the first deploy runs on your next push to the connected branch. `floo redeploy` cannot start the first deploy.	off
`--no-browser`	Print the setup link and numbered instructions, then exit if the GitHub App is missing. Required for agents and CI; implied by `--json`.	off

Agent / CI usage

Run connect with --no-browser (implied by --json) and relay the printed setup link to a human. Two browser-only actions are required: authorize floo with GitHub through that link, and install the App on the account that owns the repo. Each account needs its own installation; an organization installation does not cover a personal-account repo, or vice versa. If the App was installed outside a setup link, run floo apps github setup --no-browser and relay its link. Re-run connect after the human finishes.

Examples

# Connect a repo (triggers initial deploy)
floo apps github connect myorg/my-app --app my-app

# Connect a specific branch
floo apps github connect myorg/my-app --app my-app --branch develop

# Agent / CI: relay the setup link to a human if the App is missing
floo apps github connect myorg/my-app --app my-app --no-browser

# Agent workflow: connect and extract status (--json implies --no-browser)
floo apps github connect myorg/my-app --app my-app --json 2>/dev/null | jq -r '.data.status'

JSON output

{
  "success": true,
  "data": {
    "connected": true,
    "app": "my-app",
    "repo": "myorg/my-app",
    "branch": "main",
    "deployed": true,
    "deploy_status": "live",
    "url": "https://my-app-dev.on.getfloo.com",
    "deploy": {}
  }
}

The deploy object contains the deployment record returned by the API. With --no-deploy, deployed is false and deployment fields are omitted; the first deploy runs on your next push to the connected branch.

disconnect

Disconnect a GitHub repo from an app.

floo apps github disconnect --app my-app

Flags

Flag	Description
`--app APP`	App name or UUID

JSON output

{
  "success": true,
  "data": {
    "app": "my-app",
    "status": "disconnected"
  }
}

status

Show GitHub connection status (repo, branch, connected date).

floo apps github status --app my-app

Flags

Flag	Description
`--app APP`	App name or UUID

GitHub: connected
  Repo:      myorg/my-app
  Branch:    main
  Connected: 2026-02-18 10:30

JSON output

{
  "success": true,
  "data": {
    "id": "connection-id",
    "app_id": "app-id",
    "skip_env_var_check": false,
    "preview_enabled": true,
    "preview_ttl_hours": 72,
    "connected_at": "2026-02-18T10:30:00Z",
    "repo_full_name": "myorg/my-app",
    "default_branch": "main",
    "installation_id": 123456,
    "services": []
  }
}

setup

Mint a fresh setup link to link or re-link the floo GitHub App installation to your floo org. Run it when the App was installed outside a setup link and connect fails with GITHUB_INSTALLATION_NOT_AUTHORIZED. A human opens the link and authorizes floo with GitHub; floo links an installation that login can access, or shows a picker if several are available. If none is installed, the page asks the human to install the App on the repo’s owning account; floo links it automatically when GitHub reports the installation.

floo apps github setup
floo apps github setup --no-browser

Flags

Flag	Description
`--no-browser`	Print the link instead of opening a browser. Required for agents and CI; implied by `--json`.

JSON output

{
  "success": true,
  "data": {
    "setup_url": "https://api.getfloo.com/...",
    "next": "floo apps github connect <owner>/<repo>"
  }
}

Open setup_url once in a browser, then run connect. Without --no-browser, the CLI opens the link, waits for the binding, and reports {"linked": true, "next": "..."}.

Granting the floo GitHub App access to a repository

Connecting a repo takes two operations. They are separate, both are required, and neither substitutes for the other.

	What it does	Where
Grant	Installs the floo GitHub App on the account that owns the repo, and selects that repo	GitHub
Bind	Records which floo org the installation belongs to	A floo-minted link

The setup link can be opened before installation; both actions require a human in a browser.

1. Grant access on GitHub

Open:

https://github.com/apps/getfloo/installations/new

Choose the account that owns the repository. GitHub scopes an installation to one account. Installing on an organization grants nothing for a repo owned by a personal account, and the reverse is equally true. For acme/storefront, the installation must be on acme; for you/side-project, it must be on your personal account.
Select the repository under “Repository access”. With “Only select repositories”, the repo must appear in that list. An installation saved with the repo unselected reports success on GitHub and still fails connect.

2. Bind the installation to your floo org

Open the setup link from connect, or mint a fresh one for an App installed outside that flow:

floo apps github setup --no-browser

Open the printed link and authorize floo with GitHub to link the installation to your floo org, then re-run connect. Installing directly from github.com without opening a setup link leaves connect failing with GITHUB_INSTALLATION_NOT_AUTHORIZED.

Which failure am I looking at?

Error	What is true	What fixes it
`GITHUB_APP_NOT_INSTALLED`	No installation on the account that owns the repo	Open the setup link, authorize floo, and install on that exact account
`GITHUB_REPO_NOT_IN_INSTALLATION`	The App is installed on the owner, but this repo is not selected	Add the repo at the installation’s settings page; the error’s `settings_url` links straight to it
`GITHUB_INSTALLATION_NOT_AUTHORIZED`	The App is installed and can see the repo, but floo has no binding	Run `floo apps github setup` and authorize floo through its link

floo apps github status --app my-app reports the connection for an app that is already connected. It does not report install state for an app that has not connected yet, so use the error code from connect to tell these three apart.

For agents

You cannot grant GitHub access. It is a browser-only action tied to a human’s GitHub permissions, and no flag, token, or retry substitutes for it. When connect fails with any code above, escalate to a human with four things: the account to install on, the repository to select, the URL, and the command to re-run. Then stop. Re-running before the human acts produces the same failure, and repeated attempts are indistinguishable from progress in a transcript.

Errors

Code	Meaning
`NOT_AUTHENTICATED`	Run `floo auth login` first
`APP_NOT_FOUND`	No app with that name or ID
`GITHUB_APP_NOT_INSTALLED`	No installation on the repo’s owning account. A human must open the setup link, authorize floo, and install the App on that account. `connect` opens the link and waits; `--no-browser` or `--json` prints the link and instructions, then exits.
`GITHUB_REPO_NOT_IN_INSTALLATION`	The App is installed on the owner but this repo is not selected. Add it at the `settings_url` in the error.
`GITHUB_ALREADY_CONNECTED`	This app already has a GitHub repo connected. Disconnect first with `floo apps github disconnect`.
`GITHUB_REPO_NOT_ACCESSIBLE`	Cannot access the repo. Check that it exists and you have permission.
`GITHUB_NOT_CONNECTED`	No GitHub repo connected. Connect one with `floo apps github connect`.
`GITHUB_INSTALLATION_NOT_AUTHORIZED`	The App is installed on the GitHub account but not linked to your floo org. Run `floo apps github setup` and authorize floo through its link.

​connect

​Flags

​Agent / CI usage

​Examples

​JSON output

​disconnect

​Flags

​JSON output

​status

​Flags

​JSON output

​setup

​Flags

​JSON output

​Granting the floo GitHub App access to a repository

​1. Grant access on GitHub

​2. Bind the installation to your floo org

​Which failure am I looking at?

​For agents

​Errors

connect

Flags

Agent / CI usage

Examples

JSON output

disconnect

Flags

JSON output

status

Flags

JSON output

setup

Flags

JSON output

Granting the floo GitHub App access to a repository

1. Grant access on GitHub

2. Bind the installation to your floo org

Which failure am I looking at?

For agents

Errors