# Push a repository back to GitHub

Copy every push of a repository here to a GitHub repository through {{product}}'s GitHub App, with no token stored.

This sets up a [push mirror](configure-a-push-mirror.md) whose credential is the GitHub App
installation instead of a token: each push asks GitHub for a token for that one repository. Use it,
for example, for a repository that moved here from GitHub and that GitHub should keep receiving.

## Prerequisites

- Permission for `git:ConfigurePushMirror` on the repository and for `git:ConnectGithub`.
- A GitHub account connected to your organization whose installation covers the target repository
  on GitHub; see [Connect a GitHub account](connect-github.md). The target repository exists on
  GitHub.
- The repository here is not a mirror. A mirror follows GitHub and is refused with 409
  `A mirror follows GitHub; it does not push back`; stop mirroring first (see
  [Import a repository](import-a-repository.md)).

## Set it up

Replace repo-id with the repository's id here, installation-id with the
installation's `id` from `dcloud git github list-installations`, and `example-org/my-app` with the
target's owner and name on GitHub.

**CLI**
```sh
dcloud git github set-push-back repo-id \
  --installation installation-id --repository example-org/my-app
```

**API**
```http
PUT /git/api/github/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/push-back
{ "installation": "0b8f3c2d-4e5a-4b6c-8d7e-9f0a1b2c3d4e", "repository": "example-org/my-app" }
```

The answer carries the repository's `id` and the `url` of the target's page on GitHub. Setting it
replaces any push mirror the repository had, and the first push is queued at once.

The request is refused with:

- 404 `Not found` when your organization has no repository with that id.
- 404 `Installation not found` when your organization has no installation with that id.
- 404 `The installation does not cover example-org/my-app; add it on GitHub first`.
- 409 `The installation is suspended on GitHub`.
- 502 when GitHub could not be asked.

## Result

From now on it behaves as any push mirror: branches and tags are pushed after every push here,
fast-forward only, and nothing is deleted on GitHub. The repository's **Settings** → **Mirroring**
page (which needs `git:GetRepository`) shows it under **Push mirror**, with **Copies to** and
**Last push**, and offers **Push now** and **Stop copying** (which need
`git:ConfigurePushMirror`); see [Configure a push mirror](configure-a-push-mirror.md). If the
installation is disconnected later, pushes fail with
`The GitHub App installation is no longer connected to this organization`.

## Related

- [Connect a GitHub account](connect-github.md)
- [Configure a push mirror](configure-a-push-mirror.md) with a token instead.
- `git.github.set-push-back`
