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 apply your personal access token as a Kubernetes Secret.

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 cluster administrator permissions for the cluster on which your organization’s Che instance is running.

  • 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
  1. Generate your access token on your Git provider’s website.

  2. Encode your access token to Base64.

    If you have the base64 command-line tools installed in the operating system, you can use the command line:

    $ echo -n '<your_access_token_string>' | base64

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

  4. Get your Git provider user ID by following the Git provider’s API documentation:

    • GitHub: Get a user. See the id value in the response.

    • GitLab: List users: For normal users, use the username filter: /users?username=:username. See the id value in the response.

    • Bitbucket Server: Get users. See the id value in the response.

  5. 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-userid: '<git_provider_user_id>'(4)
        che.eclipse.org/scm-username: <git_provider_username>
        che.eclipse.org/scm-organization: <git_provider_organization>(5)
    data:
      token: <Base64_encoded_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 Your Git provider user ID.
    5 This line is only applicable to azure-devops: your Git provider user organization.
  6. Visit https://<che_fqdn>/api/kubernetes/namespace to get your Che user namespace as name.

  7. 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>

  8. Apply the Secret.

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

    $ oc apply -f - <<EOF
    <Secret_prepared_in_step_5>
    EOF
Verification
  1. Start a new workspace by using the URL of a remote Git repository that the Git provider hosts.

  2. Make some changes and push to the remote Git repository from the workspace.