<!-- Source: https://console.uubright.com/docs/repositories/ -->
# Work with repositories

Give a task a repository to work in. In host mode you can pick a checkout that's
already on your server, or add a repository by its clone URL. Either way, every
task gets its own branch and workspace, so your original checkout is never changed.

## Use a checkout already on the server

**Settings → Setup check** lists the repositories you committed to most recently,
wherever they are, with the identity and push access each uses; **Add** there adds
one in a click. See [Setup check](https://console.uubright.com/docs/setup-check/).

1. Select **New**, then **Repository task**.
2. Use **Find a repository on this server** and search by name or path. It opens automatically when you have no saved projects; otherwise, expand it to find another checkout.
3. Select the checkout. It's saved as a project for future tasks.
   **＋ Add a project…**, the last choice in every **Project** list, opens the same finder.
4. Describe a small task, including how Claude should check its work, and start it.

### What the task gets

Each task gets a separate [Git worktree](https://git-scm.com/docs/git-worktree) on a
new branch, `ccr/SESSION_ID`. It starts from the project's base branch as `origin`
has it now, not from whatever branch your checkout is on:

1. uuBright Console asks `origin` for its default branch (for example `develop`) and
   fetches just that branch into `origin/develop`, waiting up to 20 seconds.
2. The task's branch starts from `origin/develop`, and pull requests target `develop`.

Your checkout is never changed: no branch is checked out, local branches such as
`develop` aren't updated, and the task branch isn't set to track anything. Only the
remote-tracking branch (`origin/develop`) moves, as it would with `git fetch`.

If `origin` can't be reached, the task starts from the last fetched `origin/develop`
(or, with none, the local default branch) and shows a warning in its activity. A
checkout with no `origin` remote starts from its committed `HEAD`, also with a warning.

The fetch never waits for input: Git and SSH can't prompt for a password or
passphrase, and SSH runs in batch mode unless you set your own `core.sshCommand` or
`GIT_SSH_COMMAND`. Use credentials that work without a prompt, such as a key in a
running agent. If another fetch is updating the same branch at that moment, the
task retries once.

| Stays in your original checkout | Available in the task |
|---|---|
| Uncommitted, staged and untracked changes | Everything committed on the base branch |
| Ignored files, such as `.env` and `node_modules` | Shared Git history and repository config |

### Choose the base branch

To start from a branch other than `origin`'s default, open **Setup for this project**
in the new-task form, enter a **Base branch** and select **Save setup**. A task created
through the [API](https://console.uubright.com/docs/api/#start-a-task) can name its own `baseBranch`, which wins over the
project's. A named branch that exists on `origin` is fetched the same way; otherwise
a local branch, tag or commit by that name is used as it is.

The task's **Details** show the branch and commit it started from. Claude is told the
base, and `REPO_BASE_BRANCH` holds it in the task's environment, so pull requests it
opens, and those opened from the app, target that branch.

Install dependencies and add environment files in the task's workspace if it needs
them. A repository needs at least one commit before a task can start in it.

Stop and Resume keep the same worktree and conversation.

> [!WARNING]
> **Deleting a task deletes its worktree, including uncommitted task files.**
> Commit or copy anything you want to keep first. The original checkout and the
> task's branch remain.

Worktrees separate files, not permissions: a task can still read anything your
server user can.

### Change where uuBright Console looks

By default uuBright Console discovers repositories under `~/src` (on a Mac also `~/code`,
`~/Projects`, `~/Developer` and `~/GitHub`), and two levels deep in other common
folders: `~/Developer`, `~/Projects`, `~/code`, `~/src`, `~/workspace` and `~/repos`.
Folders that don't exist are skipped quietly. Select **Rescan repositories** after
adding a checkout.

**Desktop and Documents.** On Linux, `~/Desktop` and `~/Documents` are searched
too, two levels deep. On a Mac, reading them makes macOS ask for permission, so
uuBright Console doesn't look there by itself: in the finder, choose **Look in Desktop and
Documents** on that Mac. It explains the prompt first, then macOS asks once; uuBright Console
remembers the choice. If you said no, allow it later in **System Settings → Privacy
& Security → Files and Folders**. To add just one folder there instead, use **Choose
folder…** in the Mac app, or type its path. macOS may still ask once when uuBright Console first
works in a folder on the Desktop or in Documents.

To scan other folders instead, set absolute paths in `server.env` and [restart the
service](https://console.uubright.com/docs/operations/#restart-the-service). They replace all of the folders above:

```sh
CCR_CLOUD_REPO_ROOTS='/home/ubuntu/src:/srv/projects'
```

Discovery works offline and stays fast on large servers. It searches the configured
folders three directory levels deep and the common folders two, returning up to 100 matching repositories and visiting up to
3,000 directories within an eight-second time limit. Typing a name or path searches
the server again after a short pause; it can find repositories beyond the initial
100 results. **Load more repositories** adds the next page without clearing your
search or previous results. Search is case-insensitive. If the scan is incomplete, the UI says so;
use a more specific search or narrower discovery roots. It skips hidden folders, dependency and build folders
(such as `node_modules`, `vendor`, `target`, `dist` and `build`), the Mac's `Library`, media and `Applications` folders,
and symlinked directories, and it doesn't check for uncommitted changes.

### Add a repository by path

A checkout outside the search folders can be added by its path: in **Find a
repository on this server**, type it under **Or add a repository by path**, for
example `~/work/my-repo` (`~` is the server user's home folder), and select **Add**.
In the Mac app connected to This Mac, **Choose folder…** opens the system folder
dialog instead and adds the folder you pick, checked the same way.
When nothing is found, the finder names the folders it searched.

The server checks the path before saving it as a project:

- It needs host mode and the server owner token. A paired phone picks from the
  repositories found instead.
- The folder must exist and be a Git checkout's top folder, not a subfolder.
- Symlinks are resolved first, and the real folder is what's checked and saved, so a
  link can't later point the project somewhere else.
- Outside the search folders, the folder must belong to the server user, and it can't
  be the home folder itself or `/`.

Tasks for a saved project keep working if you change `CCR_CLOUD_REPO_ROOTS` later; the
same checks run again each time a task starts.

### Search and paging
Repository browsing uses a snapshot with a five-minute idle expiry, sorted by name across all roots.
**Load more repositories** reads the next page from that snapshot without
rescanning or running Git on earlier pages. Checkouts created after the snapshot
appear when you select **Rescan repositories**. Active reads extend its lifetime. If it expires, searches refresh automatically;
Load more restarts from a fresh first page instead of mixing two lists. Discovery snapshots are held only in server memory.

Search matches checkout names and paths relative to each configured root, so a
root folder name or username does not match every repository. You can also enter
an absolute path or a `~/` path. Server searches are cancelled when superseded;
metadata is cached for that snapshot and inspected with at most four concurrent
Git operations. Cached searches do not wait for another directory scan. The eight-second
traversal and 3,000-directory limits bound snapshot discovery; Git metadata is
read only for the requested page, with a timeout per command.

## Prepare each task with a setup script

Every task starts from a clean checkout, so dependencies and generated files aren't
there yet. Give the project a setup script, and each new task runs it in its
workspace before Claude starts.

1. In **New → Repository task**, select the project.
2. Open **Setup for this project**, enter the script (for example `npm ci`) and any
   environment variables as `NAME=value` lines, then select **Save setup**.

The script runs once per task, as the server user, with the task's workspace as the
current folder. Its output appears in the task's activity. If it fails or runs longer
than 15 minutes, Claude starts anyway and the activity says why; a failed setup runs
again when you resume the task. Changing the setup affects new tasks only.

Keep secrets out of setup variables: anyone with the access token can read them.
Names that uuBright Console, Claude Code, Git or the system rely on, such as `PATH`,
`ANTHROPIC_*`, `GIT_*` or `NODE_OPTIONS`, are refused. Dependency caches shared
between tasks aren't available yet.

## Add a repository by URL

Use this for a repository that isn't on the server yet, or in
[Docker mode](https://console.uubright.com/docs/docker/), which always clones.

1. Select **New**, then **Repository task**, then **+ Add by URL**.
2. Enter a project name and the clone URL.
3. Select **Check access & save project**.

Choose the URL form that matches the credential your server already has:

| Credential on the server | Clone URL |
|---|---|
| SSH key | `git@github.com:OWNER/REPO.git` |
| HTTPS credential helper | `https://github.com/OWNER/REPO.git` |

An SSH key doesn't authenticate an HTTPS URL, and the reverse is also true.

### What the access check tells you

The check runs as the server user, without prompts and with time limits. It never
clones or pushes. Each result is reported separately:

| Result | Meaning |
|---|---|
| Repository readable | A read-only Git request to this exact URL succeeded. |
| Git commit identity | Git has an author name and email for commits. |
| GitHub API | `gh api user` works. Needed only for GitHub API and pull request actions. |
| Push access | Not verified. Nothing is written. |

The result is a snapshot. If credentials change, add the repository again to rerun
the check. In Docker mode the check runs inside the session image, not on the host.

## Set up GitHub access

Only do this if a check fails or you need GitHub API actions. Run these **on the
server, as the service user**:

```sh
npm run github                                         # diagnose identity, API login and SSH
npm run github -- --repo git@github.com:OWNER/REPO.git # check one exact URL
npm run github -- --setup --protocol ssh              # print SSH setup steps
```

`--setup` only prints steps. It never creates keys, logs in or changes Git
configuration. A few things to know:

- Verify a new Git host's fingerprint once in the server terminal; unattended
  checks can't answer that prompt.
- A forwarded SSH agent disappears when your SSH login ends. Use credentials that
  stay available on the server.
- Set a commit identity if the check reports none:

  ```sh
  git config --global user.name "Your Name"
  git config --global user.email "you@example.com"
  ```

See [Command line](https://console.uubright.com/docs/cli/#npm-run-github) for every option.

## Next steps

- [Run and control tasks](https://console.uubright.com/docs/tasks/)
- [Troubleshooting](https://console.uubright.com/docs/troubleshooting/#repositories)
