Skip to main content
Version: Next

Git Authentication

kubefirst uses a GitHub token to authenticate with the GitHub API. Tokens can be used to perform various actions on a user's behalf, such as creating, and deleting repository files. kubefirst uses a limited number of scopes (what is allowed with the issued token) to provision the kubefirst platform such as creating GitHub repositories and updating GitHub repository webhook URL.

kubefirst issue GitHub Tokens at the beginning of the installation using GitHub device login flow.

GitHub Token Scopes

kubefirst uses the following scopes to provision the kubefirst platform: GitHub Token Scopes


Those permissions are the minimum require scopes we need for the token as we need to be able to create two Git repositories, add an SSH key, and more. It is used at the cluster creation, but will also be used by Atlantis and Argo CD during your management, and workload clusters usage. We do not suggest removing some of the scopes once the management cluster is created.

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

How to create a GitHub Token

There are different ways 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.

There are other ways to create a GitHub token. You can login into your GitHub account and issue a Personal Access token following the list of scopes above. With the manually generated token, you can provide it via environment variable: export GITHUB_TOKEN.


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