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

# Git

> Connect, update, and review the repository that stores your context files

Git connects a repository to your project so admins can update the live context and edit files through the [File Explorer](https://docs.getnao.io/nao-agent/chat/admin/file-explorer.md).

> [!NOTE]
>
> **Live context** is the version of the files currently used by the agent. **File Explorer** gives each user a separate, editable Git worktree. Updating one does not overwrite the other.

## Connect a repository from the UI

To connect a repository to this project, open **Settings** → **Git** and follow these steps. If your self-hosted deployment already manages the repository, see [Deployment-managed repositories](#deployment-managed-repositories) instead.

**1. Configure the provider - once per deployment**

Register a **GitHub OAuth App** or **GitLab OAuth application**, set the credentials on the server, and restart nao:

* GitHub: `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET`
* GitLab: `GITLAB_CLIENT_ID`, `GITLAB_CLIENT_SECRET`, and `GITLAB_REDIRECT_URI=https://<your-nao-host>/api/gitlab/callback`
* Self-hosted GitLab: also set `GITLAB_BASE_URL`

A GitLab OAuth application must allow these scopes:

* `api`
* `read_user`
* `openid`
* `email`
* `read_repository`
* `write_repository`

**2. Connect the repository - once per project**

Choose GitHub or GitLab and select the repository that contains the project's context files. Connecting it does not overwrite the live context or push changes. Only a project admin can disconnect it.

**3. Connect your account - once per person**

Authorize nao with your personal GitHub or GitLab account. nao uses your permissions when it pulls the repository, commits changes, and opens pull or merge requests.

> [!WARNING]
>
> After upgrading to a version that includes the new GitLab repository scopes, existing GitLab users must disconnect and reconnect GitLab once. Otherwise, GitLab can reject pulls, commits, or pushes because the existing token does not include repository read/write access.

## Pull the latest live context

Project admins can open **Settings** → **Git** and click **Pull latest** to update the files used by the agent from the repository's configured branch. This works with GitHub and GitLab repositories connected in the UI and with deployment-managed repositories on self-hosted deployments.

The pull is fast-forward only. nao stops without replacing the live context when:

* The live branch and remote branch have diverged.
* Local changes in the live checkout would be overwritten.
* The live checkout's `origin` does not match the connected or deployment-managed repository.
* The configured branch or project subfolder is invalid.

After a successful pull, the agent uses the updated files. Clean File Explorer worktrees are also updated automatically when it is safe to do so. User branches, commits, and uncommitted changes are never overwritten.

## Review pull history

**Settings** → **Git** shows previous pulls with their status, time, commit, and changed files. Each changed file includes its additions and deletions. Click a file to open the diff in File Explorer.

Opening a diff may require File Explorer to catch up:

* If the worktree is clean, nao can switch it to the default branch automatically.
* If commits need to be fetched, nao asks you to confirm and **Update File Explorer**.
* If the worktree has local changes, commit or discard them before continuing.

See [Keep File Explorer up to date](https://docs.getnao.io/nao-agent/chat/admin/file-explorer.md#keep-file-explorer-up-to-date) for details.

## Deployment-managed repositories

Self-hosted deployments can configure the repository directly with environment variables by setting `NAO_CONTEXT_SOURCE=git` and the few remaining environment variables. See [Deployment-managed context files](https://docs.getnao.io/nao-agent/self-hosting/context-source.md#git-managed-context).

> [!NOTE]
>
> In this mode, **Settings** → **Git** shows a read-only summary of the deployment-managed repository rather than the connection wizard, because the source is controlled by the environment and not the UI. Editing in the File Explorer still works. See [Deployment-managed context files](https://docs.getnao.io/nao-agent/self-hosting/context-source.md).

## Troubleshooting

### Repository origin does not match

**Pull latest** only updates a live checkout whose `origin` matches the repository shown in **Settings** → **Git**. Update the deployment or project configuration so both point to the same repository, then retry.

### The configured context subfolder is invalid

For deployment-managed monorepos, `NAO_CONTEXT_GIT_SUBPATH` must name an existing directory in the configured branch, and that directory must contain a tracked `nao_config.yaml`. Correct the subpath or add the config file, redeploy, and retry.

### GitLab rejects the credential

For a repository connected in the UI, confirm the GitLab OAuth application allows `read_repository` and `write_repository`, then disconnect and reconnect the user's GitLab account. For a deployment-managed repository, verify that `NAO_CONTEXT_GIT_TOKEN` or `NAO_CONTEXT_GIT_SSH_KEY` is valid and can access the repository.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.