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 with a token is then the way to keep a repository on GitHub.
Prerequisites
- Permission for
git:ListGithubInstallationsto open Connect GitHub and list what is connected. - Permission for
git:ConnectGithubto connect or disconnect an account. - To mirror a repository,
git:ConnectGithubandgit:CreateRepository. The mirror is a new repository and counts against your repository quota (see Quotas). - To turn shadow CI on or off,
git:UpdateRepositoryon the mirror. To open its comparison,git:GetRepositoryandci:ListRunson the repository. - A GitHub account that can install a GitHub App on the account or organization that owns the repositories.
Connect the account
- In the Git Deutsche Cloud Console, under Configuration, choose Connect GitHub.
- Choose Connect a GitHub account. GitHub's page for installing the App opens.
- On GitHub, choose the account or organization and the repositories, and install the App.
- 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.
- Back on Connect GitHub, the page reads "GitHub account connected." and lists the account with the repositories the installation covers.
Not available in CLI. Connecting goes through GitHub's install page in a browser.
Not available in API. 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 hereYour 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.
- On Connect GitHub, find the repository under its account, in the On GitHub column.
- In the Here column, choose Mirror.
- The Here column now links to the new repository.
dcloud git github list-installations
dcloud git github mirror installation-id --repository example-org/my-appPOST /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. 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 foundwhen 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 anothername. - 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.
- On Connect GitHub, in the Shadow CI column of the mirrored repository, turn on the switch.
- The column reads Runs on every push.
dcloud git github set-shadow-ci repo-id --enabledTo turn it on when you create the mirror, add --shadow-ci to dcloud git github mirror.
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
- On Connect GitHub, next to the account, choose Disconnect.
- In Disconnect this GitHub account?, choose Disconnect.
dcloud git github disconnect-installation installation-idDELETE /git/api/github/installations/0b8f3c2d-4e5a-4b6c-8d7e-9f0a1b2c3d4eAn 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 through the same App.
- Import a repository from GitHub with a token instead.
POST /git/api/github/installations/{id}/mirror