<!-- Source: https://ccr-cloud.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

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.
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`, created from the checkout's **committed** `HEAD`.
ccr-cloud doesn't fetch first.

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

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 ccr-cloud looks

By default ccr-cloud discovers repositories under `~/src`. Select **Rescan
repositories** after adding a checkout. To scan other folders, set absolute paths
in `server.env` and [restart the service](https://ccr-cloud.uubright.com/docs/operations/#restart-the-service):

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

Discovery works offline and stays fast on large servers. It searches three
directory levels deep, up to 100 repositories and 3,000 directories, within a time
limit. It skips hidden folders, common dependency folders and symlinked
directories, and it doesn't check for uncommitted changes.

## 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 ccr-cloud, 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://ccr-cloud.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://ccr-cloud.uubright.com/docs/cli/#npm-run-github) for every option.

## Next steps

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