Using a Git-provider access token

OAuth for GitHub, GitLab, Bitbucket, or Microsoft Azure Repos needs to be configured by the administrator of your organization’s Che instance. If your administrator could not configure it for Che users, the workaround is for you to use a personal access token. You can configure personal access tokens on the User Preferences page of your Che dashboard: https://<che_fqdn>/dashboard/#/user-preferences?tab=personal-access-tokens, or apply it manually as a Kubernetes Secret in the namespace.

Mounting your access token as a Secret enables the Che Server to access the remote repository that is cloned during workspace creation, including access to the repository’s /.che and /.vscode folders.

Apply the Secret in your user namespace of the Kubernetes cluster of your organization’s Che instance.

After applying the Secret, you can create workspaces with clones of private Git repositories that are hosted on GitHub, GitLab, Bitbucket Server, or Microsoft Azure Repos.

You can create and apply multiple access-token Secrets per Git provider. You must apply each of those Secrets in your user namespace.

Prerequisites

You have logged in to the cluster.

On OpenShift, you can use the oc command-line tool to log in to the cluster:

$ oc login https://<che_fqdn> --username=<my_user>

Procedure

Generate your access token on your Git provider’s website.

Personal access tokens are sensitive information and should be kept confidential. Treat them like passwords. If you are having trouble with authentication, ensure you are using the correct token and have the appropriate permissions for cloning repositories:

Open a terminal locally on your computer
Use the git command to clone the repository using your personal access token. The format of the git command vary based on the Git Provider. As an example, GitHub personal access token verification can be done using the following command:

git clone https://<PAT>@github.com/username/repo.git

Replace <PAT> with your personal access token, and username/repo with the appropriate repository path. If the token is valid and has the necessary permissions, the cloning process should be successful. Otherwise, this is an indicator of incorrect personal access token, insufficient permissions, or other issues.

For GitHub Enterprise Cloud, verify that the token is authorized for use within the organization.

Go to https://<che_fqdn>/api/user/id in the web browser to get your Che user ID.

Prepare a new Kubernetes Secret.

kind: Secret
apiVersion: v1
metadata:
  name: personal-access-token-<your_choice_of_name_for_this_token>
  labels:
    app.kubernetes.io/component: scm-personal-access-token
    app.kubernetes.io/part-of: che.eclipse.org
  annotations:
    che.eclipse.org/che-userid: <che_user_id>(1)
    che.eclipse.org/scm-personal-access-token-name: <git_provider_name>(2)
    che.eclipse.org/scm-url: <git_provider_endpoint>(3)
    che.eclipse.org/scm-organization: <git_provider_organization>(4)
stringData:
  token: <Content_of_access_token>
type: Opaque

1	Your Che user ID.
2	The Git provider name: `github` or `gitlab` or `bitbucket-server` or `azure-devops`.
3	The Git provider URL.
4	This line is only applicable to `azure-devops`: your Git provider user organization.

Visit https://<che_fqdn>/api/kubernetes/namespace to get your Che user namespace as name.

Switch to your Che user namespace in the cluster.

On OpenShift:

The oc command-line tool can return the namespace you are currently on in the cluster, which you can use to check your current namespace:

$ oc project
You can switch to your Che user namespace on a command line if needed:

$ oc project <your_user_namespace>

Apply the Secret.
On OpenShift, you can use the oc command-line tool:

$ oc apply -f - <<EOF <Secret_prepared_in_step_5> EOF

Verification

Start a new workspace by using the URL of a remote Git repository that the Git provider hosts.
Make some changes and push to the remote Git repository from the workspace.

Additional resources