Starting a workspace from a Git repository URL

With Che, you can use a URL in your browser to start a new workspace that contains a clone of a Git repository. This way, you can clone a Git repository that is hosted on GitHub, GitLab, Bitbucket or Microsoft Azure DevOps server instances.

You can also use the Git Repository URL field on the Create Workspace page of your Che dashboard to enter the URL of a Git repository to start a new workspace.

  • Starting a workspace using a URL from a Git service other than GitHub, GiLab, Bitbucket, or Microsoft Azure DevOps will fail.

  • If you use an SSH URL to start a new workspace, you must propagate the SSH key. See Configuring DevWorkspaces to use SSH keys for Git operations for more information.

  • If the SSH URL points to a private repository, you must apply an access token to be able to fetch the devfile.yaml content. You can do this either by accepting an SCM authentication page or following a Personal Access Token procedure.

Configure personal access token to access private repositories. See Using a Git-provider access token.
Prerequisites

  • Your organization has a running instance of Che.

  • You know the FQDN URL of your organization’s Che instance: https://<che_fqdn>.

  • Optional: You have authentication to the Git server configured.

  • Your Git repository maintainer keeps the devfile.yaml or .devfile.yaml file in the root directory of the Git repository. (For alternative file names and file paths, see Optional parameters for the URLs for starting a new workspace.)

    You can also start a new workspace by supplying the URL of a Git repository that contains no devfile. Doing so results in a workspace with Universal Developer Image and with Microsoft Visual Studio Code - Open Source as the workspace IDE.
Procedure

To start a new workspace with a clone of a Git repository:

  1. Optional: Visit your Che dashboard pages to authenticate to your organization’s instance of Che.

  2. Visit the URL to start a new workspace using the basic syntax:

    https://<che_fqdn>#<git_repository_url>

    You can extend this URL with optional parameters:

    https://<che_fqdn>#<git_repository_url>?<optional_parameters> (1)
    1 See Optional parameters for the URLs for starting a new workspace.

    You can use Git+SSH URLs to start a new workspace. See Configuring DevWorkspaces to use SSH keys for Git operations
    Example 1. A URL for starting a new workspace

    • https://<che_fqdn>#https://github.com/che-samples/cpp-hello-world

    • https://<che_fqdn>#git@github.com:che-samples/cpp-hello-world.git

    Example 2. The URL syntax for starting a new workspace with a clone of a GitHub instance repository

    • https://<che_fqdn>#https://<github_host>/<user_or_org>/<repository> starts a new workspace with a clone of the default branch.

    • https://<che_fqdn>#https://<github_host>/<user_or_org>/<repository>/tree/<branch_name> starts a new workspace with a clone of the specified branch.

    • https://<che_fqdn>#https://<github_host>/<user_or_org>/<repository>/pull/<pull_request_id> starts a new workspace with a clone of the branch of the pull request.

    • https://<che_fqdn>#git@<github_host>:<user_or_org>/<repository>.git starts a new workspace from Git+SSH URL.

    Example 3. The URL syntax for starting a new workspace with a clone of a GitLab instance repository

    • https://<che_fqdn>#https://<gitlab_host>/<user_or_org>/<repository> starts a new workspace with a clone of the default branch.

    • https://<che_fqdn>#https://<gitlab_host>/<user_or_org>/<repository>/-/tree/<branch_name> starts a new workspace with a clone of the specified branch.

    • https://<che_fqdn>#git@<gitlab_host>:<user_or_org>/<repository>.git starts a new workspace from Git+SSH URL.

    Example 4. The URL syntax for starting a new workspace with a clone of a BitBucket Server repository

    • https://<che_fqdn>#https://<bb_host>/scm/<project-key>/<repository>.git starts a new workspace with a clone of the default branch.

    • https://<che_fqdn>#https://<bb_host>/users/<user_slug>/repos/<repository>/ starts a new workspace with a clone of the default branch, if a repository was created under the user profile.

    • https://<che_fqdn>#https://<bb_host>/users/<user-slug>/repos/<repository>/browse?at=refs%2Fheads%2F<branch-name> starts a new workspace with a clone of the specified branch.

    • https://<che_fqdn>#git@<bb_host>:<user_slug>/<repository>.git starts a new workspace from Git+SSH URL.

    Example 5. The URL syntax for starting a new workspace with a clone of a Microsoft Azure DevOps Git repository

    • https://<che_fqdn>#https://<organization>@dev.azure.com/<organization>/<project>/_git/<repository> starts a new workspace with a clone of the default branch.

    • https://<che_fqdn>#https://<organization>@dev.azure.com/<organization>/<project>/_git/<repository>?version=GB<branch> starts a new workspace with a clone of the specific branch.

    • https://<che_fqdn>#git@ssh.dev.azure.com:v3/<organization>/<project>/<repository> starts a new workspace from Git+SSH URL.

    After you enter the URL to start a new workspace in a browser tab, the workspace starting page appears.

    When the new workspace is ready, the workspace IDE loads in the browser tab.

    A clone of the Git repository is present in the filesystem of the new workspace.

    The workspace has a unique URL: https://<che_fqdn>/<user_name>/<unique_url>.

Additional resources