> ## Documentation Index
> Fetch the complete documentation index at: https://getfloo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# github

> CLI reference: floo apps github — manage GitHub integration for auto-deploy

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

## connect

Connect a GitHub repo to an app for auto-deploy. Opens browser to install the GitHub App if not already installed. Triggers an initial deploy after connecting.

```bash theme={null}
floo apps github connect owner/repo --app my-app
```

### Flags

| Flag               | Description                                                                                                | Default |
| ------------------ | ---------------------------------------------------------------------------------------------------------- | ------- |
| `--app APP`        | App name or UUID                                                                                           | —       |
| `--branch BRANCH`  | Branch to deploy from                                                                                      | `main`  |
| `--skip-env-check` | Skip environment variable validation                                                                       | —       |
| `--no-deploy`      | Connect without triggering an initial deploy                                                               | —       |
| `--no-browser`     | Error cleanly if the GitHub App is not installed instead of opening a browser. Required for agents and CI. | —       |

### Agent / CI usage

In `--json` mode, `--no-browser` is implied — the CLI never tries to open a browser. If the Floo GitHub App is not yet installed on the org, connect fails with `GITHUB_APP_NOT_INSTALLED` and a human needs to install it once from:

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

After install, the agent can retry `connect` and subsequent pushes deploy automatically.

### Examples

```bash theme={null}
# 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

# Connect without deploying
floo apps github connect myorg/my-app --app my-app --no-deploy

# Agent / CI: fail cleanly if the GitHub App is not installed
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

```json theme={null}
{
  "success": true,
  "data": {
    "repo_full_name": "myorg/my-app",
    "default_branch": "main",
    "status": "connected",
    "deploy_triggered": true
  }
}
```

***

## disconnect

Disconnect a GitHub repo from an app.

```bash theme={null}
floo apps github disconnect --app my-app
```

### Flags

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

### JSON output

```json theme={null}
{
  "success": true,
  "data": {
    "app": "my-app",
    "status": "disconnected"
  }
}
```

***

## status

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

```bash theme={null}
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

```json theme={null}
{
  "success": true,
  "data": {
    "repo_full_name": "myorg/my-app",
    "default_branch": "main",
    "status": "connected",
    "connected_at": "2026-02-18T10:30:00Z"
  }
}
```

***

## Errors

| Code                              | Meaning                                                                                              |
| --------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `NOT_AUTHENTICATED`               | Run `floo auth login` first                                                                          |
| `APP_NOT_FOUND`                   | No app with that name or ID                                                                          |
| `GITHUB_APP_NOT_INSTALLED`        | Install the floo GitHub App first. Browser will open automatically.                                  |
| `GITHUB_REPO_NOT_IN_INSTALLATION` | The GitHub App is installed but does not have access to this repo. Update app permissions in GitHub. |
| `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`.                               |