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

# GitHub Integration

> Connect GitHub and sync repositories

# GitHub Integration

Aether connects to GitHub through a GitHub App. Once installed, you can import repositories into projects, push changes back, and keep your code in sync.

## Connecting GitHub

<Tabs>
  <Tab title="Web">
    Go to **Settings > Integrations > GitHub** and click **Connect**. This opens GitHub's authorization flow where you grant Aether access to your repositories.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    aether github connect
    ```

    This opens your browser to the GitHub App installation page. Once authorized, the CLI confirms the connection.
  </Tab>
</Tabs>

## Checking Connection Status

```bash theme={null}
aether github status
```

Returns whether GitHub is connected and which account/organization is linked.

## Listing Repositories

```bash theme={null}
# List all accessible repositories
aether github repos

# Search by name
aether github repos --search "frontend"
```

This lists repositories from the GitHub account or organizations where the Aether GitHub App is installed.

## Importing a Repository

Import clones a GitHub repository into a workspace:

<Tabs>
  <Tab title="Web">
    Open a project, click **Import from GitHub**, and select the repository.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    aether github import --repo owner/repo-name --workspace <workspace-id>
    ```
  </Tab>
</Tabs>

The repository is cloned into the workspace's project directory. All branches and history are included.

<Note>
  Import has a 5-minute timeout for large repositories. If a repository exceeds this limit, consider a shallow clone or importing a specific branch.
</Note>

## Exporting Changes

After the agent makes changes, push them back to GitHub:

<Tabs>
  <Tab title="Web">
    Click **Push to GitHub** in the project view. Enter a commit message and confirm.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    aether github export --workspace <workspace-id> --commit-message "Add dark mode support"
    ```
  </Tab>
</Tabs>

Export stages all changes in the workspace, commits them with the provided message, and pushes to the linked remote.

<Note>
  Export also has a 5-minute timeout to handle large changesets or slow network connections.
</Note>

## Linking a Project to a Repository

Link an existing project to a GitHub repository without importing:

```bash theme={null}
aether github link
```

This opens an interactive selector to choose the repository. Once linked, export operations push to the linked repository.

## Unlinking a Repository

```bash theme={null}
aether github unlink --force
```

Removes the link between the project and its GitHub repository. The code in the workspace is not affected — only the remote connection is removed.

## Disconnecting GitHub

To remove the GitHub integration entirely:

```bash theme={null}
aether github disconnect --force
```

<Warning>
  Disconnecting revokes all GitHub access. Existing repository links on your projects will stop working. You will need to reconnect and re-link projects to resume syncing.
</Warning>

## Workflow Example

A typical workflow with GitHub integration:

```bash theme={null}
# 1. Connect GitHub (one-time setup)
aether github connect

# 2. Create a project and import a repo
aether project create --name "my-saas"
aether github import --repo myorg/my-saas --workspace <ws-id>

# 3. Use the agent to make changes
aether run "Add Stripe subscription billing to the settings page"

# 4. Review the changes, then push
aether github export --workspace <ws-id> --commit-message "Add Stripe billing"
```