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. Open Repositories on this server and search by name or path.
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 on a new branch, ccr/SESSION_ID, created from the checkout's committed HEAD. ccr-cloud doesn't fetch first.

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.

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:

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.

#Add a repository by URL

Use this for a repository that isn't on the server yet, or in Docker mode, 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:

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:

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:

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:

  SHELLCopy

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

See Command line for every option.

#Next steps

• Run and control tasks
• Troubleshooting

Edit this page on GitHub ↗