> ## 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.

# GitHub

> Version-control your Hiveku project with GitHub

Connect your Hiveku project to a GitHub repository for version control, collaboration, and CI/CD workflows. GitHub is optional -- projects without it work fine -- but once it's connected, Hiveku treats GitHub as the source of truth for your code.

## Connect your account

<Steps>
  <Step title="Authorize GitHub">
    Go to **Settings > Integrations > GitHub** and click **Connect**. You'll be redirected to GitHub to authorize the Hiveku app.
  </Step>

  <Step title="Select a repository">
    Choose an existing repository or create a new one. Hiveku exports your current project files as the initial commit.
  </Step>
</Steps>

## The source-of-truth model

When GitHub is connected to a project:

* **GitHub is canonical.** Your repo's main and feature branches hold the authoritative version of your code.
* **The Hiveku database is a working buffer.** AI edits and editor saves write to the database first, then get committed to GitHub.
* **Every deploy reconciles against GitHub.** Before any build runs, Hiveku checks that the database matches what's on GitHub. Mismatches are surfaced as conflicts, not silently overwritten.

When GitHub is **not** connected, the database itself is the source of truth -- edits persist on save and that's the end of the story.

<Tip>
  The source-of-truth model means you can confidently edit from `git`, VSCode, GitHub.com, or another developer's checkout. Anything that ends up in GitHub will flow back into Hiveku on the next sync. Anything you edit in Hiveku will land in GitHub at the end of your session.
</Tip>

## Committing changes

Three paths exist for getting your work into GitHub:

* **Manual commit** -- open the GitHub panel in the editor, write a commit message, and click **Commit**
* **AI session end (automatic)** -- when an AI chat session finishes, every file the AI touched is batched into one commit, signed by `hiveku[bot]`, and pushed to your dev branch. Debounced \~10 seconds so back-to-back turns combine into one commit
* **External git** -- push from your laptop / VSCode / GitHub.com. Hiveku's webhook listens for pushes and syncs them into the database

All Hiveku-originated commits carry a `[hiveku]` prefix in the commit message so you can identify them in your repo history.

## Auto-deploy on push

Hiveku can automatically deploy when commits land on specific branches. Configure per-environment in **Settings > Integrations > GitHub > Auto-deploy**:

| Toggle          | What it does                                                       |
| --------------- | ------------------------------------------------------------------ |
| **Development** | Auto-deploy to the dev environment when its mapped branch advances |
| **Staging**     | Auto-deploy to staging when its mapped branch advances             |
| **Production**  | Auto-deploy to production when its mapped branch advances          |

<Info>
  **Bot commits never trigger auto-deploy.** When the AI session-end commit fires, the webhook handler sees the `[hiveku]` prefix and skips the auto-deploy step -- otherwise every AI turn would trigger N deploys. Auto-deploy only runs for pushes made from outside Hiveku (you from VSCode, an external collaborator, a GitHub Action, etc.).
</Info>

This separation matters: connecting GitHub doesn't suddenly mean every AI edit goes live. AI edits flow into GitHub automatically (auto-commit), but they only go live if you explicitly trigger a deploy from the **Deploy** dropdown -- or if a separate non-Hiveku push to the same branch trips the auto-deploy toggle.

## Branch management

| Action                           | How to                                                                                       |
| -------------------------------- | -------------------------------------------------------------------------------------------- |
| **Create branch**                | Open the branch dropdown in the editor and click **New Branch**                              |
| **Switch branch**                | Select a branch -- the editor and the project's database snap to match                       |
| **Delete branch**                | Use the trash icon in the dropdown, or delete from GitHub directly                           |
| **Map branches to environments** | In **Settings > Integrations > GitHub**, set which branch each environment auto-deploys from |

The branch you're currently editing is also the branch the auto-commit pushes to. If you're working on a feature branch in the editor, AI session-end commits go to that feature branch -- not main.

## Pre-deploy sync

Every deploy (manual or auto-triggered) starts with an incremental sync from GitHub. This guarantees that whatever Hiveku builds is what's currently on the connected branch.

If the sync detects that both Hiveku and GitHub have modified the same file since the last sync (a true conflict), the deploy is paused and you'll see a conflict notice listing the affected files. Resolve them in the GitHub panel, then retry the deploy.

<Warning>
  If you need to force GitHub to win and discard the Hiveku-side edits, the deploy dropdown offers an **Overwrite with GitHub** option. This is destructive for the listed files -- only use it when you're sure the GitHub side has the version you want.
</Warning>

## Viewing history

The **History** tab in the GitHub panel shows all commits with their messages, authors, and timestamps. `hiveku[bot]` commits are visually distinguished from your own. Click any commit to see the files that were changed.

## Disconnect

Go to **Settings > Integrations > GitHub** and click **Disconnect**. Your project files and the GitHub repository both remain intact -- only the link between them is removed. After disconnecting, the project reverts to "database is source of truth" mode, and Hiveku stops auto-committing AI edits.