GitHub

Connect GitHub to clone private repositories without a pasted token. froog uses a GitHub App: you pick the account or organization and the repositories, and each sandbox gets a token that works for one hour, only for those repositories.

$ froog github connect                      # opens GitHub: install the app, pick repositories, authorize
$ froog github                              # linked accounts, and what the sandbox token reaches
$ froog github repos                        # repositories the app can see
$ froog github token-repos acme/api acme/web  # limit the sandbox token to these (none: every repository the app sees)
$ froog environment add-repo https://github.com/acme/api
$ froog github disconnect 4242              # unlink an installation (its id from froog github)

GitHub asks you to authorize the app when you install it. froog uses that only to check that you manage the installation (your own GitHub account, or an organization you're an owner of), so nobody can link an installation that isn't theirs. The connect link (froog github connect, or the dashboard's Connect button) must be opened in a browser signed in to the dashboard with the same account. Otherwise it sends you to the dashboard with an error. An install links only in the browser that started it: a GitHub callback link opened anywhere else links nothing. Uninstalling the app on GitHub unlinks it. The dashboard's Environment page has a repository picker that adds repositories from the list.

In each sandbox. A sandbox with your environment gets a git credential helper for github.com and a gh login. git clone, git push and gh work with no setup, including the environment's repos at boot. The helper asks the API for a fresh token with the sandbox's own key (POST /v1/sandboxes/{name}/github-token, action exec) when the cached one has less than 5 minutes left, so a sandbox that runs for days keeps working. The gh login holds the token from the last start: run git credential fill or start the sandbox again for a new one. A token is an installation token on your token repositories with contents, pull requests, issues and workflows (read and write) and metadata (read), as far as the app has them. It never has Administration: it can't change repository settings or register runners. With several linked accounts, git gets the token of the repository's owner. froog keeps tokens encrypted and reuses one until 10 minutes before it expires. A sandbox created with --no-environment, and every CI job, gets no GitHub token.

API: GET /github, POST /github/connect ({url}), DELETE /github/installations/{id}, GET /github/repos, PUT /github/token-repos {repos}. Reading needs account.read, changes need account.admin. Without a GitHub App on the server, these answer 404 github_not_configured, and a call for an owner with no installation answers 404 github_not_connected.