Skip to main content
Version: 2.4

Git Authentication

kubefirst needs a GitHub token to authenticate with the GitHub API. The token is used to perform various actions on a user's behalf like the cluster creation, but also by Atlantis and Argo CD during your management, and workload clusters usage.

How to create a GitHub Token

The easiest way is to start the kubefirst installer, and follow the screen instructions. It will guide you to issue a token with the list of scope described above to issue a GitHub Token using the GitHub device login flow.

You can also log in to your GitHub account and issue a Personal Access token following the list of scopes below. With the manually generated token, you can provide it via environment variable using export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxx.

tip

If you never connected to GitHub using SSH before and are creating a cluster using the CLI, be sure to add it to the known host using the command ssh-keyscan github.com >> ~/.ssh/known_hosts to ensure you won't get a ssh: handshake failed: knownhosts: key is unknown error.

GitHub Token Scopes

GitHub Token Scopes

kubefirst needs the following scopes or scopes groups:

ScopeScore Permissionkubefirst Usage
repoFull access to public & private repositoriesCreating 2 repositories on cluster creation & manage repositories related to your cluster with Atlantis
workflowAdd & update GitHub Actions workflow filesCreating workflows that will help manage your cluster and repositories
write:packagesUpload & publish packages in GitHub PackagesCreating application packages (ex.: metaphor)
admin:orgFully manage the organizationManaging users and accesses with Infrastructure as Code using Atlantis & Vault
admin:public_keyFully manage public keysNeeded for the kubefirst admin kbot user to take action in the repositories we created for you
admin:repo_hookFull access to repository hooksCreating hooks for Atlantis to subscribe to some GitHub events (i.e., comments, pull requests...)
admin:org_hookFull access to organization hooksThis is will be removed soon (see #2180)
userGrants read & write access to profile infoRetrieving the user profile to display in the console UI & let the user validate the used token
delete_repoDelete repositoriesDeleting repositories managed by Infrastructure as Code with Atlantis
admin:ssh_signing_keyFull control of public user SSH signing keysThis is will be removed soon (see #2180)

You can read more about the scopes in the GitHub documentation.

warning

Those permissions are the minimum requirement for kubefirst to function properly.

If you feel unease with that, we suggest you create a new GitHub user or organization for the sake of testing kubefirst.