Improving git configuration with PAT documentation

[l0rd]

Is your enhancement related to a problem? Please describe

Making PAT work at first try is hard, that's the recurrent feedback we get from customers. I have tried to configure it for BitBucket following the documentation and spent a couple of hours to make it work.

Describe the solution you'd like

• Retrieving BB user id (for the annotation che.eclipse.org/scm-userid) is not straightforward. That's because using the curl command that is linked in the documentation fails with non-authorized. A link to the authentication for BB API should be added too.
• I initially set che.eclipse.org/scm-userid: 2 because BB user id is an integer. But the secret failed to be parsed because a string is expected. We should document that the scm-userid should be wrapped with "" or ''.
• I accidentally included a newline char in the PAT that I copied in the secret. As a result che-server thrown an Internal Server Error (java.lang.IllegalArgumentException: invalid header value:...). That was a mistake on my side but che-server should be more robust and trim blank chars at the beginning and at the end of the token string.
• I didn't know exactly what URL to use: https://{bb-host}/users/{user-slug}/repos/{repo-name}/ didn't work but https://{bb-host}/scm/~{user-slug}/{repo-name}.git. We should support both BB URL schemas.
• When using PAT and the repository is private (the default for BB), cloning fails and the workspace does not work. That's because the DevWorkspace operator is not mounting the PAT as a git-credential store and project-clone fails to git clone the repository. We should mention that PAT and git-credentials should be used together and we should document how to do that.
• After successfully setting up the PAT secret, git clone continued to fail because BB was using an untrusted SSL certificate. The article "Deploying Che with support for Git repositories with self-signed certificates" should be referenced as an "additional resource".
• The article "Deploying Che with support for Git repositories with self-signed certificates" had its problems too:
  • It's hard to find although I suspect that's one of the most read articles (admin guide -> configuring dev spaces -> configuring workspaces globally -> git with self-signed certificates...)

  • Specifying the gitTrustedCertsConfigMapName in CheCluster is redudant: we should just use labels/annotations to automatically inject the config map.
  • As some point the configmap is referenced as a secret ("All Secrets that hold certificate files...")
  • It's not clear if certs in binary format are supported or not (they are not supported but this sentence is confusing "Also, they can be encoded as binary data, for example, .cer...")
  • It doesn't mention that the certificate chain is required
  • It doesn't mention that in the githost the protocol (i.e. https) is required
  • It doesn't mention what cert should used (ingress operator or *.apps?)

Additional information

For reference this is the PAT secret that I had to use to make it work (I had to add controller.devfile.io/* labels/annotations + credentials in data) :

kind: Secret
apiVersion: v1
metadata:
  name: personal-access-token-mario-bb
  labels:
    app.kubernetes.io/component: scm-personal-access-token
    app.kubernetes.io/part-of: che.eclipse.org
    controller.devfile.io/git-credential: 'true'
    controller.devfile.io/watch-secret: 'true'
  annotations:
    che.eclipse.org/che-userid: kube:admin 
    che.eclipse.org/scm-personal-access-token-name: bitbucket-server 
    che.eclipse.org/scm-url: https://bitbucket-bitbucket.apps.mloriedo-devworkspaces.devcluster.openshift.com 
    che.eclipse.org/scm-userid: '2' 
    che.eclipse.org/scm-username: mario
    controller.devfile.io/mount-path: /etc/secret
data:
  token: ...
  credentials: ...
type: Opaque

[max-cx]

@l0rd, I'd like to work on this as a technical writer to collaborate (ideally from the very beginning) with the developer who gets assigned to work on this issue. I'd be grateful if the developer can reach out to me on Slack to mleonov before starting any work on it.

[pdfruth]

@l0rd

Making PAT work at first try is hard, that's the recurrent feedback we get from customers. I have tried to configure it for BitBucket following the documentation and spent a couple of hours to make it work.

I couldn't agree more! I have spent more than a couple hours trying to get it to work with Github Enterprise (https://github.ibm.com). I am stuck.

I have tried to follow the hints in your opening post above but trying to make it work for Github Enterprise. And in the RedHat documentation But, have been unable to get it to work.

When I try to create a new workspace, by specifying the URL of the Gir repo containing my devfile, I get the error indicating the devfile does not contain a valid apiVersion or schemaVersion.

Do you have any guidance/instructions to setting up Git provider access token secret for Github Enterprise?

[RickJWagner]

Feedback from a concerned user:
The user does not want to use a personal access token because:

• For security reasons they frequently update them
• They don't like putting them in a Secret (where admins can get at them)
  The user suggests using an ssh key as the git credential and cloning the repo via ssh as a desired alternative.
  Is this possible? Please provide feedback so the user can be notified. Thank you!

[l0rd]

* For security reasons they frequently update them

A very similar discussion happened #21291 for GitLab tokens that expire every 2 hours. Currently tokens get refreshed when the workspace is restarted but there is no mechanism to refresh the token if the workspace is running for more than 2 hours. But I agree with the user: considered their high rotation frequency, those tokens are not supposed to be used in a development environment and we should look at the alternative (using an SSH key) instead.

* They don't like putting them in a Secret (where admins can get at them)
  The user suggests using an ssh key as the git credential and cloning the repo via ssh as a desired alternative.
  Is this possible?  Please provide feedback so the user can be notified.  Thank you!

It's possible to use an SSH key to clone the workspaces (instructions to add SSH Keys in a workspace) but that currently works only for public repositories. This is something that we want to address though and this is the issue to track.

[svor]

Feedback from a concerned user: The user does not want to use a personal access token because:

• For security reasons they frequently update them
• They don't like putting them in a Secret (where admins can get at them)
  The user suggests using an ssh key as the git credential and cloning the repo via ssh as a desired alternative.
  Is this possible? Please provide feedback so the user can be notified. Thank you!

@RickJWagner I didn't find something related in the Che/DS documentation but it should be possible by following SSH flow - https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#configuring-devworkspaces-to-use-ssh-keys-for-git-operations

[svor]

docs related changes are going to be provided by eclipse-che/che-docs#2567

[max-cx]

The corresponding docs issue is RHDEVDOCS-4976.

[che-bot]

Issues go stale after 180 days of inactivity. lifecycle/stale issues rot after an additional 7 days of inactivity and eventually close.

Mark the issue as fresh with /remove-lifecycle stale in a new comment.

If this issue is safe to close now please do so.

Moderators: Add lifecycle/frozen label to avoid stale mode.

[l0rd]

/remove-lifecycle stale

[che-bot]

Issues go stale after 180 days of inactivity. lifecycle/stale issues rot after an additional 7 days of inactivity and eventually close.

Mark the issue as fresh with /remove-lifecycle stale in a new comment.

If this issue is safe to close now please do so.

Moderators: Add lifecycle/frozen label to avoid stale mode.

[max-cx]

@svor, just fyi, I removed myself as the assignee on the technical writing side because I no longer work on this project.