github - floo

Subcommands of floo apps github. A connected repo deploys to dev on every push to its branch.

connect

Connect a GitHub repo for auto-deploy. connect creates the named app if it does not exist and runs an initial deploy unless you pass --no-deploy. First, a human installs the floo GitHub App on the repo’s owning account and links it to your floo org; see Granting the floo GitHub App access. If either step is missing, connect opens a setup link and waits for the human to finish. Run floo init and floo preflight, then commit and push the generated configuration before connecting. The initial deploy reads the 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 the env var check for webhook deploys	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, who does two browser-only actions: install the App on the account that owns the repo, and authorize floo with GitHub through that link. An organization installation does not cover a personal-account repo, or the reverse. 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 the deploy status (--json implies --no-browser)
floo apps github connect myorg/my-app --app my-app --json 2>/dev/null | jq -r '.data.deploy_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.getfloo.app",
    "deploy": {}
  }
}

deploy is the deployment record from the API. deploy_status is live, superseded, cancelled, or failed; only live sets deployed: true and url. A failed deploy returns success: false with DEPLOY_FAILED and the same data. With --no-deploy, deployed is false and the deploy fields are omitted.

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

Show the GitHub connection: repo, branch, connected time, and what floo did with the last push.

floo apps github status --app my-app

Flags

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

my-app GitHub connection
  Repo:      myorg/my-app
  Branch:    main
  Connected: 2026-02-18T10:30:00Z
  Last push: The last push to main (3f9c2a1) at 2026-10-27 22:12 UTC created a dev deploy.
  Next:      Follow it with `floo deploys watch --commit 3f9c2a1`.

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": [],
    "last_push": {
      "at": "2026-10-27T22:12:04Z",
      "branch": "main",
      "commit_sha": "3f9c2a1e8b7d6c5f4a3b2c1d0e9f8a7b6c5d4e3f",
      "outcome": "deploying",
      "needs_action": false,
      "summary": "The last push to main (3f9c2a1) at 2026-10-27 22:12 UTC created a dev deploy.",
      "next_step": "Follow it with `floo deploys watch --commit 3f9c2a1`."
    }
  }
}

An app with no connection returns {"connected": false} as a success. last_push is null until floo receives a push for the app. The same object is on GET /v1/apps/{app_id}/github/connection.

Why a push did not deploy

floo records the last push for each app, on any branch. outcome says what happened to it:

`outcome`	What happened	Next step
`deploying`	floo created a dev deploy. A billing or config block fails that deploy with the reason.	`floo deploys watch --commit <sha>`
`coalesced`	A dev deploy was already running. floo deploys the newest commit when it finishes.	Wait, then `floo deploys watch --commit <sha>`
`not_default_branch`	The push was to a branch other than the connected branch, so dev did not deploy it. A preview deploys it if previews are on and the branch has an open pull request.	Merge it into the connected branch to deploy it to dev.
`deploy_on_push_off`	`[github] deploy_on_push = false` in `floo.app.toml`.	Set it to `true` and push again, or run `floo redeploy --rebuild`.
`repo_linked_to_several_apps`	The repo is connected to more than one floo app, so floo deployed none of them.	`floo apps github disconnect --app <name>` on every app except the one that should deploy.

needs_action is true only for deploy_on_push_off and repo_linked_to_several_apps: no push deploys until you fix them. A later push overwrites the record, so compare commit_sha with the commit you pushed. If you pushed and last_push did not change, the push did not reach this app: check the repo and branch above, then grant the floo GitHub App access. floo doctor push prints the same summary and exits 1 when needs_action is true.

setup

Mint a fresh setup link that binds the floo GitHub App installation to your floo org. Select the intended floo org first. Run it when the App was installed outside a setup link and connect fails with GITHUB_INSTALLATION_NOT_AUTHORIZED, or when an earlier setup link expired. 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, and floo links it 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 returns {"linked": true, "next": "..."}.

Granting the floo GitHub App access to a repository

Connecting a repo takes two separate operations, both required.

	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

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 personal-account repo, and the reverse. For acme/storefront, install on acme; for you/side-project, on your personal account.
Select the repository under “Repository access”. With “Only select repositories”, the repo must be 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, then re-run connect. Installing 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 reports only an existing connection, not install state, 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; no flag, token, or retry substitutes for it. When connect fails with any code above, give a human 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 in a transcript repeated attempts look like progress.

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

​Why a push did not deploy

​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

Why a push did not deploy

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