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

# Connect GitHub

> Version-control your project with GitHub integration

GitHub integration is optional — your Hiveku project works fine without it. But connecting a repo gives you real version history, branches for experimenting, pull requests for review, and a full backup outside Hiveku.

## Connect a GitHub Repo

<Steps>
  <Step title="Open GitHub settings">
    In your project, go to **Settings > GitHub** and click **Connect GitHub**.
  </Step>

  <Step title="Authorize the Hiveku GitHub App">
    You'll be redirected to GitHub. Choose whether to install the app on your personal account or an organization, and which repos to grant access to.

    <Tip>
      "All repositories" is convenient but "Only select repositories" is safer if you work across multiple projects.
    </Tip>
  </Step>

  <Step title="Pick or create a repo">
    Back in Hiveku, choose:

    * **Existing repo** — pick from the list
    * **New repo** — Hiveku creates a fresh repo under the account or org you installed on
  </Step>

  <Step title="Initial push">
    Hiveku does an initial commit with every file in your project and pushes it to the `main` branch. From this point on, the repo and your project stay in sync.
  </Step>
</Steps>

## Commit Changes

You've got three ways to commit, pick whichever fits the moment.

<Tabs>
  <Tab title="Manual">
    Open the **GitHub** panel in the editor (right sidebar). You'll see a list of changed files.

    * Review the diff by clicking a file
    * Write a commit message in the input
    * Click **Commit** to commit to the current branch
    * Click **Push** to push to GitHub
  </Tab>

  <Tab title="AI-triggered">
    When the AI makes changes, it can commit them automatically. Toggle this on in **Settings > GitHub > AI Commit**. Each AI response becomes a commit with a descriptive message.
  </Tab>

  <Tab title="Auto on save">
    Toggle **Settings > GitHub > Auto-commit on save**. Every save creates (and optionally pushes) a commit. Choose between **batched** (one commit per session of edits) and **immediate** (one per save — noisy but granular).
  </Tab>
</Tabs>

## Branches

From the **GitHub** panel in the editor:

* **Switch branch** — click the current branch name and pick another
* **Create branch** — click **New branch**, name it, choose base branch
* **Merge** — open a PR from the panel and merge in GitHub
* **Delete** — right-click a branch in the list

<Info>
  Branches are a great way to experiment. Create a `feature/new-hero` branch, try a redesign, and either merge it back or throw it away — without affecting your live site.
</Info>

## Pulling Remote Changes

If you or a teammate edited files directly on GitHub (or in another Hiveku instance), pull them into your local project.

<Steps>
  <Step title="Commit first">
    <Warning>
      Pulling can overwrite unsaved local changes. Commit everything you want to keep first.
    </Warning>
  </Step>

  <Step title="Click Pull">
    In the GitHub panel, click **Pull**. Hiveku fetches the remote and merges into your current branch.
  </Step>

  <Step title="Resolve conflicts if any">
    If the same file was edited both locally and remotely, you'll see a conflict. The AI can help: *"Resolve the merge conflict in `src/page.tsx`"*.
  </Step>
</Steps>

## Commit History and Pull Requests

From the **GitHub** panel:

* **History tab** — scroll back through every commit with author, message, and timestamp
* **Pull Requests tab** — view open PRs, preview the diff, leave comments, merge when ready

Pull requests made in Hiveku appear on GitHub just like any other PR — they can use your existing review process, CI, and branch protection.

## Verifying It Works

Open your repo on github.com. You should see:

* All your project files in the file tree
* Your initial commit in the commit history
* A green status next to your account in **Settings > GitHub** in Hiveku

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authorization failed">
    The Hiveku GitHub App may not be installed, or the install was removed. Go to github.com/settings/installations, check for Hiveku, and reinstall if missing. Then try **Connect GitHub** again.
  </Accordion>

  <Accordion title="Branch conflicts on pull">
    Someone else pushed to the same branch. Resolve the conflict in GitHub's web UI or ask the AI to help locally, then pull again.
  </Accordion>

  <Accordion title="Commit isn't appearing on GitHub">
    A commit without a push only exists locally. Click **Push** in the GitHub panel. Also refresh github.com — browser caching sometimes shows stale state.
  </Accordion>

  <Accordion title="I want to disconnect">
    In **Settings > GitHub**, click **Disconnect**. Your project keeps working and the repo stays on GitHub — they just stop syncing. Reconnect any time.
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="GitHub Reference" icon="book" href="/integrations/github">
    Full reference: branch policies, PR settings, sync modes
  </Card>

  <Card title="Editor Git Panel" icon="code" href="/editor/github">
    Deep dive on the in-editor Git controls
  </Card>
</CardGroup>