using-a-git-provider-access-token.adoc

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 {prod-short} instance. If your administrator could not configure it for {prod-short} 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 {prod-short} dashboard: {prod-url}/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 {prod-short} 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 {orch-namespace} of the {orch-name} cluster of your organization’s {prod-short} 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 {orch-namespace}.

Prerequisites

• You have logged in to the cluster.

  Tip	On OpenShift, you can use the oc command-line tool to log in to the cluster: $ oc login {prod-url} --username=<my_user>

Procedure

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

   Important

   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.

   Important

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

2. Go to {prod-url}/api/user/id in the web browser to get your {prod-short} user ID.

3. Prepare a new {orch-name} 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: <{prod-id-short}_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 {prod-short} 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.

4. Visit {prod-url}/api/kubernetes/namespace to get your {prod-short} user namespace as name.

5. Switch to your {prod-short} user namespace in the cluster.

   Tip	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 {prod-short} user namespace on a command line if needed: $ oc project <your_user_namespace>

6. Apply the Secret.

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

Additional resources

• Deploying Che with support for Git repositories with self-signed certificates

• Authorizing a personal access token for use with SAML single sign-on