# Configure a push mirror

Copy every push to a remote outside {{product}}, such as a GitHub repository kept as a second copy.

A push mirror sends the repository's branches and tags to the remote after every push, merge,
edit in the Deutsche Cloud Console or import: for example to a GitHub repository you can still build from
when Deutsche Cloud itself is unavailable. The examples use the repository id
`5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60`; replace github-token with your token.

## Prerequisites

- Permission for `git:ConfigurePushMirror` on the repository. It is a separate action from
  `git:UpdateRepository`, because it sends code outside Deutsche Cloud.
- In the Deutsche Cloud Console, also `git:GetRepository` to open the repository's settings (without it the
  page is not found).
- A token allowed to push to the remote. On GitHub: a fine-grained token for that one repository
  with write access to **Contents**.
- The remote URL is https, has no credentials, query or fragment in it, and its host resolves to a
  public address. Otherwise the call is refused with 400 and the reason, for example
  `only https:// sources can be imported` or `that address is not reachable from here`.
- In the Deutsche Cloud Console, the repository is not archived, and it is not itself a pull mirror: on a
  repository that follows a source, **Settings** → **Mirroring** shows the push mirror only once
  one is set, so set it with the CLI or API there.

## Configure it

**Console**
1. In the repository, choose **Settings**, then **Mirroring**.
2. Under **Push mirror**, choose **Set up** (**Change** when one is already set).
3. For **Repository URL**, enter the remote's https URL, without credentials.
4. For **Token**, enter the token.
5. Choose **Save and push**. The first push of everything is queued at once.

**CLI**
```sh
dcloud git repositories set-push-mirror 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 \
  --url https://github.com/acme/app.git --token github-token
```

**API**
```http
PUT /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/push-mirror
{ "url": "https://github.com/acme/app.git", "token": "github_pat_EXAMPLE" }
```

The token is stored encrypted and never shown again. Setting a push mirror again replaces the URL
and the token.

## Result

The repository's **Mirroring** page shows **Copies to** and **Last push** (**Pushed** or
**Failed**, with the time). The mirror only fast-forwards and never deletes anything on the
remote. If a branch there moved on its own (someone pushed a fix to GitHub while Deutsche Cloud was
down), that branch is not overwritten: `pushMirror.lastStatus` becomes `failed`, `rejectedRefs`
lists it and `lastError` reads
`the remote has commits this repository does not (<refs>): push them here first`. Push that
commit here (fetch it from the remote, merge, push), and the next push catches the mirror up. A
remote that cannot be reached or refuses the token is also recorded as `failed`, with git's error,
and the push is tried again later.

## Push now or stop

- **Push now**, `POST …/push-mirror/sync` or `dcloud git repositories sync-push-mirror` queues a push
  now (202). On a repository without a push mirror it is refused with 409
  `This repository has no push mirror`.
- **Stop copying**, `DELETE …/push-mirror` or `dcloud git repositories remove-push-mirror` stops it;
  the Deutsche Cloud Console asks **Stop copying pushes?** first. The remote keeps what it has.

## Related

- [Import a repository](import-a-repository.md) as a mirror, the opposite direction.
- [Push a repository back to GitHub](push-back-to-github.md) through the GitHub App, with no
  token stored.
- `git.repositories.set-push-mirror`
