Using Git credentials

As an alternative to the OAuth for GitHub, GitLab, or Bitbucket that is configured by the administrator of your organization’s Che instance, you can apply your Git credentials, a credentials store and access token, as Kubernetes Secrets.

Using a Git credentials store

If the administrator of your organization’s Che instance has not configured OAuth for GitHub, GitLab, or Bitbucket, you can apply your Git credentials store as a Kubernetes Secret.

Mounting your Git credentials store as a Secret results in the Dev Workspace Operator applying your Git credentials to the .gitconfig file in the workspace container.

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

When you apply the Secret, a Git configuration file with the path to the mounted Git credentials store is automatically configured and mounted to the Dev Workspace containers in the cluster at /etc/gitconfig. This makes your Git credentials store available in your workspaces.

Prerequisites
  • An active kubectl session, with administrative permissions, to the Kubernetes cluster. See Overview of kubectl.

  • The base64 command line tools are installed in the operating system you are using.

Procedure
  1. In your home directory, locate and open your .git-credentials file if you already have it. Alternatively, if you do not have this file, save a new .git-credentials file, using the Git credentials storage format. Each credential is stored on its own line in the file:

    https://<username>:<token>@<git_server_hostname>
    Example 1. A line in a .git-credentials file
    https://trailblazer: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@github.com
  2. Select credentials from your .git-credentials file for the Secret. Encode the selected credentials to Base64 for the next step.

    • To encode all lines in the file:

      $ cat .git-credentials | base64 | tr -d '\n'

    • To encode a selected line:

      $ echo -n '<copied_and_pasted_line_from_.git-credentials>' | base64

  3. Create a new Kubernetes Secret in your user namespace.

    apiVersion: v1
    kind: Secret
    metadata:
      name: git-credentials-secret
      labels:
        controller.devfile.io/git-credential: 'true' (1)
        controller.devfile.io/watch-secret: 'true'
      annotations:
        controller.devfile.io/mount-path: /etc/secret (2)
    data:
      credentials: <Base64_content_of_.git-credentials> (3)
    1 The controller.devfile.io/git-credential label marks the Secret as containing Git credentials.
    2 A custom absolute path in the Dev Workspace containers. The Secret is mounted as the credentials file at this path. The default path is /.
    3 The selected content from .git-credentials that you encoded to Base64 in the previous step.

    You can create and apply multiple Git credentials Secrets in your user namespace. All of them will be copied into one Secret that will be mounted to the Dev Workspace containers. For example, if you set the mount path to /etc/secret, then the one Secret with all of your Git credentials will be mounted at /etc/secret/credentials. You must set all Git credentials Secrets in your user namespace to the same mount path. You can set the mount path to an arbitrary path because the mount path will be automatically set in the Git configuration file configured at /etc/gitconfig.

  4. Apply the Secret.

    $ kubectl apply -f - <<EOF
    <Secret_prepared_in_the_previous_step>
    EOF

Using a Git provider access token

If the administrator of your organization’s Che instance has not configured OAuth for GitHub, GitLab, or Bitbucket, you can 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 Kubernetes Secret in your user namespace of the Kubernetes cluster of your organization’s Che instance.

After you have applied the Secret, you can create new workspaces from a private GitHub, GitLab, or Bitbucket-server repository.

In your user namespace, you can create and apply multiple access-token Secrets per a Git provider.
Prerequisites
  • An active kubectl session, with administrative permissions, to the Kubernetes cluster. See Overview of kubectl.

  • The base64 command line tools are installed in the operating system you are using.

Procedure
  1. Copy your access token and encode it to Base64.

    $ echo -n '<your_access_token>' | base64
  2. Prepare a new Kubernetes Secret in your user namespace.

    kind: Secret
    apiVersion: v1
    metadata:
      name: personal-access-token-<your_chosen_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>
    data:
      token: <Base64_encoded_access_token>
    type: Opaque
    1 Your Che user ID. You can retrieve <che_endpoint>/api/user to get the Che user data.
    2 The Git provider name: github or gitlab or bitbucket-server.
    3 The Git provider URL.
    4 Your Git provider user ID, follow the API documentation to retrieve the user object:
    • 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 account_id value in the response.

  3. Apply the Secret.

    $ kubectl apply -f - <<EOF
    <Secret_prepared_in_the_previous_step>
    EOF