# Move a local repo to the cloud

Source: https://codeherder.com/docs/connect-a-local-repo/

Sign in from a repo you used without an account, then keep it local, move it to a cloud workspace, or keep it in sync.

You can run tasks on your own machine with no account. See [Run a task on your own machine](https://codeherder.com/docs/local-tasks/). Later you may want those tasks in a cloud workspace, where your team can see them. `ch auth login` handles that move. This page explains the choices and what each one does.

An *offline repo* is a git repository where you ran `ch` without an account, so its tasks live only on your machine.

## Sign in from the repo

Run this from inside the repo:

```
ch auth login
```

`ch login` does the same thing. CodeHerder opens your browser to sign in. After sign-in succeeds, it asks:

```
This repo works offline. What should it become?
```

If the sign-in fails, CodeHerder asks nothing. You choose one of three answers.

| Choice | What happens |
| --- | --- |
| **Keep this repo local** | Nothing moves. The repo keeps working offline. |
| **Move this repo to the cloud** | The repo’s tasks and history move to a cloud workspace. The local copy is retired. |
| **Keep this repo in sync with a cloud workspace** | The same move, but the local copy stays as a live mirror. |

You can answer up front with `--connect local`, `--connect cloud` or `--connect hybrid`. Without a terminal, `--connect` is required. CodeHerder refuses before it opens the browser if you leave it off.

## Keep this repo local

CodeHerder asks you to confirm. Without a terminal, pass `--yes`. It then adds a line to `.codeherder.env` that keeps the repo on your machine. It sends nothing to the cloud beyond the sign-in.

The command prints a `git add` and `git commit` line for that file. Commit it if you want every clone to agree. See [Project defaults for the CLI](https://codeherder.com/docs/project-config/) for what the file holds.

## Move this repo to the cloud

CodeHerder does these steps in order:

1. **Picks a workspace.** It uses `--workspace` if you pass it. Otherwise it uses the workspace named in `.codeherder.env`. Otherwise it looks for the one workspace that already holds this repo’s git URL. If none matches, you choose from a menu or create a new workspace. A group is refused, because a group never owns work.
2. **Registers the repo** in that workspace if it is missing. A checkout with no `origin` remote registers nothing.
3. **Waits for running sessions to end.** It prints “Waiting for N running session(s)…”. It never stops a session for you. Without a terminal, pass `--wait` to let it wait.
4. **Freezes the local workspace**, so no new work starts in it.
5. **Compares your definitions** with the cloud. Your workflows and stages may differ from the cloud’s copy. If so, CodeHerder shows each difference and asks “Which version stays?”.
6. **Copies your history.** Tasks, sessions and events arrive with their original ids and timestamps. This can take several batches.
7. **Retires the local workspace.** Its history now lives in the cloud.
8. **Writes the address and workspace into `.codeherder.env`.**
9. **Offers to release the imported tasks.** They arrive parked, so nothing starts by surprise. One confirm releases them all. Without a terminal, pass `--yes`. Otherwise release each one with `ch task unblock <blockerId>`.
10. **Checks that the server answers.**

CodeHerder never runs git for you. It prints a `git add` and `git commit` line for `.codeherder.env`. Commit it so every clone agrees.

```
ch auth login --connect cloud --workspace <workspaceRef> --wait
```

### If the move stops partway

Run `ch auth login` again in the same repo. CodeHerder picks up where it stopped and adds no duplicates. `ch auth status` lists an unfinished move in a table headed `PROMOTION`.

You can still back out with `--connect local`, but only while none of your history has reached the cloud. After that, finish the move.

## Keep this repo in sync

This choice does the same move, then keeps the local copy. The repo stays a live mirror of the cloud workspace instead of retiring. CodeHerder also adds a line to `.codeherder.env` that marks the repo as in sync.

- A definition file that matches the cloud’s copy is tracked from then on.
- A definition file that differs stays untouched. Settle it with `ch sync show <op>` and `ch sync resolve <op>`. See the next section.
- The mirror lives in the `.codeherder` folder. See [A repository’s project folder](https://codeherder.com/docs/project-folder/).
- CodeHerder waits about a minute for the first mirror to finish. If the local runtime is not running, it tells you to run `ch device-server --local`.

`ch auth status` shows the repo’s mode. For a synced repo it shows when the mirror last finished, or `not yet`.

## Work offline in a synced repo

In a synced repo, `ch` keeps working when the server is out of reach. Some changes wait in a queue and go out later:

- `ch task create` and `ch task edit`. You can edit the title, description, priority, due date and declared fields.
- `ch task comment`.
- `ch wiki write`.

Other changes never queue. A status move, a claim or an approval fails while you are offline. A flag with no offline base, such as `--cap` or `--base-branch`, is refused offline.

Only a connected run by a person queues changes. An agent session never does.

| Command | What it does |
| --- | --- |
| `ch sync push` | Sends edited definition files and delivers every queued change. |
| `ch sync status` | Shows what is queued, in conflict or refused. |
| `ch sync conflicts` | Lists only the changes in conflict or refused. |
| `ch sync show <op>` | Shows both versions of one change, with a diff. |
| `ch sync resolve <op> --take local` | Sends your version again. |
| `ch sync resolve <op> --take remote` | Keeps the cloud’s version and saves yours to a draft file. |
| `ch sync resolve <op> --from-file <file>` | Sends a version you merged by hand. |
| `ch sync discard <op>` | Drops the change. It writes your text to a draft file first. |

Use `ch sync --help` for the full list. `ch sync push` never runs git.

## Join from a teammate’s clone

Suppose a teammate committed a `.codeherder.env` that marks the repo as in sync. When you run `ch auth login` in your clone, you join that workspace. On a terminal, CodeHerder asks first. Without one, pass `--connect hybrid`. It sends no records. If your clone has its own offline history, that history moves first.

If you cannot read the workspace the file names, CodeHerder refuses and asks you to contact a workspace admin. It never creates a second workspace.

If no workspace you can see holds the repo, you see “No workspace you can see holds …”. Ask your teammate to add you before you create one. A new workspace is a second copy.

## Outside an offline repo

In a clone that is not offline, `--connect cloud` or `--connect hybrid` joins the clone to its workspace. It sends no records. `--connect local` does nothing.

A dev session with no task has no history to move. It stays on your machine.

## Related guides

- [Run a task on your own machine](https://codeherder.com/docs/local-tasks/): working without an account
- [Project defaults for the CLI](https://codeherder.com/docs/project-config/): the `.codeherder.env` file
- [A repository’s project folder](https://codeherder.com/docs/project-folder/): definitions and the mirror
- [Credentials and profiles](https://codeherder.com/docs/credentials/): other ways to sign in
- [Quickstart](https://codeherder.com/docs/quickstart/): set up a team from scratch