# Import a repository

Bring a repository over from GitHub, GitLab or any https git URL, once or as a mirror that keeps following its source.

The fetch runs on the Deutsche Cloud side, so the 2 GiB limit of a single `git push` does not apply to
an import, and the size of your own connection does not matter.

## What comes over

- **History, every branch and every tag**, with their original commit ids.
- **The default branch** as the source has it.
- **Pull requests** (GitHub) and **merge requests** (GitLab): same number, title and text, state
  open, closed or merged, with a line saying who opened it there and a link. Open ones first, then
  the newest closed ones, up to 500 in all, come with the import; older ones follow in the
  background, up to `include.pullRequestLimit` (default 10,000, at most 100,000). An open one gets
  the branch `import/pr-{number}`, so it can be reviewed and merged here; the heads of all of them
  stay available as `refs/pull/{number}/head` (GitLab: `refs/merge-requests/{number}/head`).
- **Git LFS files** of every branch and tag, when the default branch's `.gitattributes` tracks
  files with LFS; the import's notes say how many (see
  [Store large files with Git LFS](use-git-lfs.md)).
- **The wiki**: GitHub and GitLab wikis are git repositories; it becomes a second repository named
  `{name}.wiki`. The API imports it unless `include.wiki` is `false`; the Deutsche Cloud Console leaves
  **Wiki** cleared unless you select it.
- **Issues and releases are not imported.** Release tags come over with the other tags.

## Prerequisites

- Permission for `git:CreateRepository` (and `git:PublishRepository` to import as public).
- In the Deutsche Cloud Console, also `git:ListRepositories` to open **Repositories** (without it the page
  shows only an access-denied notice).
- An `https://` source URL with no query, fragment or credentials in it. A host that resolves to a
  private address is refused (`… resolves to an address that is not reachable from here`). A
  GitHub URL has the form `https://github.com/{owner}/{repo}`.
- For a private source, a GitHub or GitLab token with read access to the code. A token also raises
  the source's API rate limit, which an import of many pull requests can otherwise run into.

## Import it

Replace my-repo with the new repository's name.

**Console**
1. Open **Repositories**, then choose **New repository**.
2. Under **Source**, choose **Import from a URL**.
3. For **Source URL**, enter the repository's URL, for example `https://github.com/acme/app`.
4. (Optional) For **Access token** (once the URL names a host, the label names it too, for example
   **Access token for github.com**), enter a token for a private source. A one-time import uses it and does not store it.
5. (Optional) Turn on **Keep in sync** to mirror the source, and under **Sync** choose how often:
   every 5 or 15 minutes, every hour, every 6 hours or once a day.
6. (Optional) Clear **Pull requests** to leave them behind, or select **Wiki** to bring the wiki.
7. Under **Basics**, for **Repository name**, enter my-repo, and under **Visibility**
   choose **Private** or **Public**.
8. Choose **Continue**, check the summary on the **Access** step, then choose **Import
   repository**. The repository page opens and shows the import's progress.

**CLI**
```sh
dcloud git repositories import --name my-repo \
  --source '{"url":"https://github.com/acme/app"}'
```

**API**
```http
POST /git/api/repositories/import
{
  "name": "my-repo",
  "source": { "url": "https://github.com/acme/app" },
  "token": "ghp_EXAMPLE",
  "include": { "pullRequests": true, "wiki": true },
  "mirror": { "intervalMinutes": 15 }
}
```

A token goes in `token`, never in the URL. For a one-off import it is used and not kept.

## Result

The call answers `202` at once with the new repository. `importState.status` goes `queued →
running → succeeded` (or `failed`, with the reason in `error`). Follow it with
`dcloud git repositories get-import`, which reports the status, the phase, the branches, tags and
pull requests so far, and when it started and finished. Until the import has finished, nothing can
be written to the repository. A failed import can be started again from the same source with
`dcloud git repositories retry-import` (needs `git:UpdateRepository`; pass the token again for a
private source).

## Mirror mode

With `mirror`, the repository keeps following its source:

- it fetches every `intervalMinutes` (5 to 1440, default 15);
- branches deleted at the source are deleted here;
- pushes are refused while it mirrors;
- the token is stored encrypted, because every sync needs it.

`POST /git/api/repositories/{repoId}/mirror/sync` (`dcloud git repositories sync-mirror`, needs
`git:UpdateRepository`) syncs now.
`DELETE /git/api/repositories/{repoId}/mirror` (`dcloud git repositories stop-mirror`, needs
`git:StopMirroring`) stops mirroring and leaves an ordinary repository; history, branches, tags and
pull requests stay. In the Deutsche Cloud Console, both are under **Settings → Mirroring** (**Sync now**,
**Stop mirroring**).

## Related

- [Configure a push mirror](configure-a-push-mirror.md), the opposite direction.
- [Connect a GitHub account](connect-github.md) to mirror GitHub repositories without a token.
- `git.repositories.import` · `dcloud git repositories import`
