Git Authentication
GitHub
GitLab
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.
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
kubefirst needs the following scopes or scopes groups:
| Scope | Score Permission | kubefirst Usage |
|---|---|---|
| repo | Full access to public & private repositories | Creating 2 repositories on cluster creation & manage repositories related to your cluster with Atlantis |
| workflow | Add & update GitHub Actions workflow files | Creating workflows that will help manage your cluster and repositories |
| write:packages | Upload & publish packages in GitHub Packages | Creating application packages (ex.: metaphor) |
| admin:org | Fully manage the organization | Managing users and accesses with Infrastructure as Code using Atlantis & Vault |
| admin:public_key | Fully manage public keys | Needed for the kubefirst admin kbot user to take action in the repositories we created for you |
| admin:repo_hook | Full access to repository hooks | Creating hooks for Atlantis to subscribe to some GitHub events (i.e., comments, pull requests...) |
| admin:org_hook | Full access to organization hooks | This is will be removed soon (see #2180) |
| user | Grants read & write access to profile info | Retrieving the user profile to display in the console UI & let the user validate the used token |
| delete_repo | Delete repositories | Deleting repositories managed by Infrastructure as Code with Atlantis |
| admin:ssh_signing_key | Full control of public user SSH signing keys | This is will be removed soon (see #2180) |
You can read more about the scopes in the GitHub documentation.
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.
kubefirst uses a GitLab token to authenticate with the GitLab 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 GitLab repositories and updating GitLab repository webhook URL.
kubefirst issue GitLab Tokens at the beginning of the installation using GitLab device login flow.
GitLab Token Scopes
kubefirst uses the following scopes to provision the kubefirst platform:
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, create groups, 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 GitLab Token
There are different ways to create a GitLab 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 GitLab token. You can login into your GitLab 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 GITLAB_TOKEN.
If you never connected to GitLab using SSH before, be sure to add it to the known host using the command ssh-keyscan gitlab.com >> ~/.ssh/known_hosts to ensure you won't get a ssh: handshake failed: knownhosts: key is unknown error.