Skip to main content
Git connects a repository to your project so admins can update the live context and edit files through the File Explorer.
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 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.
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 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.
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.

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