# Connect a GitHub account

Install {{product}}'s GitHub App on a GitHub account and mirror its repositories here, without a token to create or store.

A mirror made through the App keeps no token: each time it syncs, Deutsche Cloud asks GitHub for a
token for that one repository. A GitHub installation is connected to one Deutsche Cloud organization
at a time.

**Note:**
Until Deutsche Cloud has switched the App on, **Connect GitHub** shows **Not available yet**. A
[push mirror](configure-a-push-mirror.md) with a token is then the way to keep a repository on
GitHub.

## Prerequisites

- Permission for `git:ListGithubInstallations` to open **Connect GitHub** and list what is
  connected.
- Permission for `git:ConnectGithub` to connect or disconnect an account.
- To mirror a repository, `git:ConnectGithub` and `git:CreateRepository`. The mirror is a new
  repository and counts against your repository quota (see [Quotas](quotas.md)).
- To turn shadow CI on or off, `git:UpdateRepository` on the mirror. To open its comparison,
  `git:GetRepository` and `ci:ListRuns` on the repository.
- A GitHub account that can install a GitHub App on the account or organization that owns the
  repositories.

## Connect the account

**Console**
1. In the Git Deutsche Cloud Console, under **Configuration**, choose **Connect GitHub**.
2. Choose **Connect a GitHub account**. GitHub's page for installing the App opens.
3. On GitHub, choose the account or organization and the repositories, and install the App.
4. When GitHub asks, authorize the App for your own GitHub account. Deutsche Cloud uses this sign-in
   only to check that your GitHub account can see the installation you are connecting.
5. Back on **Connect GitHub**, the page reads "GitHub account connected." and lists the account
   with the repositories the installation covers.

**CLI:** not available. Connecting goes through GitHub's install page in a browser.
**API:** not available. Connecting goes through GitHub's install page in a browser.

Finish the steps on GitHub in the same browser you started from, within 30 minutes. If the
connection is refused, **Connect GitHub** says why, for example:

- `This connection was not started from this browser; start it again here`
- `Your GitHub account cannot see that installation, so it was not connected`
- `…'s installation is connected to another organization`: disconnect it there first.

To change which repositories the installation covers, change the App's settings on GitHub.

## Mirror a repository

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

**Console**
1. On **Connect GitHub**, find the repository under its account, in the **On GitHub** column.
2. In the **Here** column, choose **Mirror**.
3. The **Here** column now links to the new repository.

**CLI**
```sh
dcloud git github list-installations
dcloud git github mirror installation-id --repository example-org/my-app
```

**API**
```http
POST /git/api/github/installations/0b8f3c2d-4e5a-4b6c-8d7e-9f0a1b2c3d4e/mirror
{ "repository": "example-org/my-app" }
```

The new repository is private, takes the name it has on GitHub (the API and CLI accept another
`name`), and its import is queued at once (202). Branches, tags, pull requests and the wiki come over
as with any import; see [Import a repository](import-a-repository.md). After that, GitHub tells
Deutsche Cloud about every push and the mirror syncs at once; a check every minute catches a push
that was missed.

The request is refused with:

- 404 `Installation not found` when your organization has no installation with that id.
- 409 `The installation is suspended on GitHub`.
- 404 `The installation does not cover example-org/my-app; add it on GitHub first`.
- 409 `A repository named "my-app" already exists`: pass another `name`.
- 409 when your organization has reached its repository quota.
- 502 when GitHub could not be asked.

## Turn on shadow CI

Shadow CI runs the mirror's GitHub Actions workflows on Deutsche Cloud for pushes mirrored to its
default branch, beside GitHub's own runs, and compares the results. It starts with the first sync
after it is turned on (the mirror's first import is not shadowed), and the budget below can pause
it or leave a push out. A newer push replaces shadow runs that have not started yet. A shadow run
gets no secrets, and a job that deploys to an environment, asks for an OIDC token (`id-token: write`) or publishes
(for example `docker push` or `npm publish`) is not run, with the reason. Shadow runs use your
organization's runners and are billed as usual.

Replace repo-id with the mirror's repository id.

**Console**
1. On **Connect GitHub**, in the **Shadow CI** column of the mirrored repository, turn on the
   switch.
2. The column reads **Runs on every push**.

**CLI**
```sh
dcloud git github set-shadow-ci repo-id --enabled
```

To turn it on when you create the mirror, add `--shadow-ci` to `dcloud git github mirror`.

**API**
```http
PUT /git/api/github/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/shadow-ci
{ "enabled": true }
```

On a repository that is not a mirror, it is refused with 404 `Not a mirror`.

To shadow other branches, enter them in **Branches** under **Shadow CI** on the repository's
**Settings** → **Mirroring** page and choose **Save**. They replace the default branch: list it
too if it should stay shadowed. While shadow CI is on, the repository's **CI** tab offers
**Shadow CI**, which opens the comparison.

Shadow CI has a budget per calendar month (UTC), counted in the job minutes of shadow runs: 3,000
per repository and 10,000 for the organization. When a cap is reached, shadow runs pause until the
next month while the mirror keeps syncing, and the **Shadow CI** column says why, for example
`Shadow CI paused: this repository used its 3,000 runner minutes this month. The mirror keeps syncing; runs resume next month.`
A push that arrives while two shadow runs of the repository are queued, provisioning or running
is not shadowed.

## Disconnect the account

**Console**
1. On **Connect GitHub**, next to the account, choose **Disconnect**.
2. In **Disconnect this GitHub account?**, choose **Disconnect**.

**CLI**
```sh
dcloud git github disconnect-installation installation-id
```

**API**
```http
DELETE /git/api/github/installations/0b8f3c2d-4e5a-4b6c-8d7e-9f0a1b2c3d4e
```

An id your organization has no connected installation with is refused with 404 `Not found`, and
so is a second disconnect of the same installation.
The mirrors made through it stop syncing and keep what they have; their syncs fail with
`The GitHub App installation is no longer connected to this organization`. Connecting the same
installation again lets them sync again. The App stays installed on GitHub until you uninstall it
there; uninstalling it on GitHub also disconnects it here. While GitHub has the installation
suspended, the page says "suspended on GitHub" next to it, and nothing is listed, mirrored or
synced through it.

## Related

- [Push a repository back to GitHub](push-back-to-github.md) through the same App.
- [Import a repository](import-a-repository.md) from GitHub with a token instead.
- `git.github.mirror`
