Access private repositories with a personal access token

This page is for developers who create and use cloud development environments. To learn more about common roles and example tasks referenced in Che documentation, see Common user roles and tasks.

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

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

    Personal access tokens are sensitive information. Treat them like passwords. If you are having trouble with authentication, verify the token locally before applying it as a Secret:

    $ 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 cloning succeeds, the token is valid and has the necessary permissions.

    For GitHub Enterprise Cloud, verify that the token is authorized for use within your organization with SAML single sign-on.

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

  3. Prepare a new Kubernetes Secret.

    kind: Secret
apiVersion: v1
metadata:
  name: personal-access-token-<git_provider>
  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>
    che.eclipse.org/scm-personal-access-token-name: <git_provider_name>
    che.eclipse.org/scm-url: <git_provider_endpoint>
    che.eclipse.org/scm-organization: <git_provider_organization>
type: Opaque
stringData:
  token: <your_personal_access_token>

    where:

    che.eclipse.org/che-userid

    Your Che user ID.

    che.eclipse.org/scm-personal-access-token-name

    The Git provider name (github, gitlab, bitbucket-server, or azure-devops).

    che.eclipse.org/scm-url

    The Git provider URL endpoint, for example https://github.com or https://gitlab.com.

    che.eclipse.org/scm-organization

    Required only for Azure DevOps: your Git provider user organization, or collection if Azure DevOps Server is used.

    token

    Your personal access token.

    Example for GitHub:

    kind: Secret
apiVersion: v1
metadata:
  name: personal-access-token-github
  labels:
    app.kubernetes.io/component: scm-personal-access-token
    app.kubernetes.io/part-of: che.eclipse.org
  annotations:
    che.eclipse.org/che-userid: 1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p
    che.eclipse.org/scm-personal-access-token-name: github
    che.eclipse.org/scm-url: https://github.com
type: Opaque
stringData:
  token: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

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

  6. Apply the Secret.

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

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

If you are using Azure DevOps Server, you must also modify the workspace’s gitconfig with the following section:

    extraheader = "Authorization: Basic <base64-encoded(:personal-access-token)>"

To generate the key-value pair, use the following command:

echo -n "extraheader = \"Authorization: Basic "$(printf ":%s" <personal access token> | base64)\"

see the documentation page for more information.

The extraheader configuration is needed for remote git operations to Azure Devops Server, for example git clone. This authorization method has a higher priority over the git credentials store, and as a result, the remote operations to other Git providers will fail.
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.

Additional resources